> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akria.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Day 21 | 第三阶段复盘

> FastAPI 框架实战阶段总结

<Info>
  **复盘日**：恭喜你完成了第三周的学习！今天是巩固和总结的日子。我们将回顾过去 6 天学到的所有 FastAPI 知识，整理成速查表，并记录遇到的问题和解决方案。今天不只是复习，而是要彻底理解 **"如何将 FastAPI 知识应用到实际项目"**、**"如何设计可扩展的 API 架构"** 以及 **"如何为下一阶段的 Go 语言学习做好准备"**。
</Info>

## <span style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><Icon icon="clipboard-check" size={26} color="#059669" /> 复盘内容 | Review</span>

<AccordionGroup>
  <Accordion title="FastAPI 核心点回顾" icon="code">
    **Day 15 - 快速入门**：

    * FastAPI 应用初始化：`app = FastAPI(title="...", description="...")`
    * 路由定义：`@app.get("/")`、`@app.post("/")`
    * 路径参数：`@app.get("/items/{item_id}")`，`item_id: int` 自动类型转换
    * 查询参数：函数参数不在路径中，自动识别为查询参数
    * Uvicorn 启动：`uvicorn main:app --reload`
    * Swagger UI：自动生成文档，访问 `/docs`

    **Day 16 - Pydantic 数据验证**：

    * Schema 定义：继承 `BaseModel`，使用类型提示
    * Field 验证：`Field(..., min_length=3, max_length=20)`
    * 请求模型：定义前端发送的数据结构
    * 响应模型：`response_model=UserResponse` 自动过滤字段
    * EmailStr：自动验证邮箱格式（需要安装 email-validator）
    * 特殊类型：`IPvAnyAddress`、`HttpUrl`、`datetime`

    **Day 17 - 依赖注入与中间件**：

    * 依赖注入：`Depends(verify_token)` 复用逻辑
    * 依赖返回值：`current_user: dict = Depends(get_current_user)`
    * 中间件：`@app.middleware("http")` 全局处理
    * CORS 配置：`CORSMiddleware` 处理跨域请求
    * 请求耗时：中间件统计处理时间

    **Day 18 - 数据库整合**：

    * 异步引擎：`create_async_engine(DATABASE_URL)`
    * 异步会话：`AsyncSession`、`AsyncSessionLocal`
    * 模型定义：继承 `Base`，使用 `Column` 定义字段
    * 查询语法：`select(Model).where(...).offset(...).limit(...)`
    * 数据库依赖：`async def get_db(): yield session`
    * 事务控制：`await db.commit()`、`await db.rollback()`

    **Day 19 - 生产部署**：

    * 配置管理：`pydantic-settings` 读取环境变量
    * `.env` 文件：存储敏感配置（不提交到 Git）
    * Gunicorn：进程管理器，管理多个 Uvicorn Worker
    * Dockerfile：容器化应用
    * Docker Compose：编排多个服务

    **Day 20 - 综合实战**：

    * 项目结构：模块化设计，按功能拆分
    * 完整 CRUD：创建、查询、更新、删除
    * 数据验证：Pydantic 自动验证请求数据
    * 容器化部署：Docker + Docker Compose
  </Accordion>
</AccordionGroup>

***

## <span style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><Icon icon="clipboard-check" size={26} color="#059669" /> 复盘产出 | Output</span>

### 1. 第三阶段速查表

<CardGroup cols={2}>
  <Card title="FastAPI 基础" icon="code">
    ```python theme={null}
    from fastapi import FastAPI

    app = FastAPI(title="My API")

    @app.get("/")
    def read_root():
        return {"message": "Hello"}

    # 启动: uvicorn main:app --reload
    ```
  </Card>

  <Card title="Pydantic 模型" icon="database">
    ```python theme={null}
    from pydantic import BaseModel, Field

    class UserCreate(BaseModel):
        username: str = Field(..., min_length=3)
        email: EmailStr

    @app.post("/users/", response_model=UserResponse)
    def create_user(user: UserCreate):
        return user
    ```
  </Card>

  <Card title="依赖注入" icon="puzzle">
    ```python theme={null}
    from fastapi import Depends

    async def get_db():
        async with AsyncSessionLocal() as session:
            yield session

    @app.get("/items/", dependencies=[Depends(verify_token)])
    def read_items(db: AsyncSession = Depends(get_db)):
        return []
    ```
  </Card>

  <Card title="数据库操作" icon="database">
    ```python theme={null}
    from sqlalchemy.future import select

    result = await db.execute(select(User))
    users = result.scalars().all()

    db.add(new_user)
    await db.commit()
    ```
  </Card>

  <Card title="配置管理" icon="settings">
    ```python theme={null}
    from pydantic_settings import BaseSettings

    class Settings(BaseSettings):
        database_url: str
        class Config:
            env_file = ".env"

    settings = Settings()
    ```
  </Card>

  <Card title="Docker 部署" icon="docker">
    ```dockerfile theme={null}
    FROM python:3.10-slim
    WORKDIR /app
    COPY requirements.txt .
    RUN pip install -r requirements.txt
    COPY . .
    CMD ["gunicorn", "app.main:app", "-w", "4", "-k", "uvicorn.workers.UvicornWorker"]
    ```
  </Card>
</CardGroup>

### 2. 常见问题与解决方案

<AccordionGroup>
  <Accordion title="FastAPI 问题">
    **问题**：`422 Validation Error`

    **解决方案**：

    * 检查请求数据是否符合 Schema 定义
    * 检查字段类型是否正确
    * 检查必填字段是否提供

    **问题**：路由不生效

    **解决方案**：

    * 检查路由装饰器是否正确（`@app.get("/")`）
    * 检查函数名是否重复
    * 检查服务器是否重启（开发模式需要 `--reload`）
  </Accordion>

  <Accordion title="数据库问题">
    **问题**：`RuntimeError: This event loop is already running`

    **解决方案**：检查代码中是否有同步调用，确保所有数据库操作都是异步的

    **问题**：连接泄漏

    **解决方案**：确保使用依赖注入管理会话，或使用 `async with` 确保会话关闭
  </Accordion>

  <Accordion title="部署问题">
    **问题**：Docker 构建失败

    **解决方案**：

    * 检查 Dockerfile 语法
    * 检查 requirements.txt 是否存在
    * 检查依赖是否正确安装

    **问题**：容器启动后立即退出

    **解决方案**：

    * 检查启动命令是否正确
    * 检查日志：`docker logs container_name`
    * 检查环境变量是否正确配置
  </Accordion>
</AccordionGroup>

### 3. 项目重构示例

<AccordionGroup>
  <Accordion title="重构示例：Day 15 的基础 API">
    **原始版本**：

    ```python theme={null}
    @app.get("/items/{item_id}")
    def read_item(item_id: int):
        return {"item_id": item_id}
    ```

    **优化版本**（应用 Week 3 学到的知识）：

    ```python theme={null}
    from pydantic import BaseModel
    from sqlalchemy.ext.asyncio import AsyncSession
    from fastapi import Depends, HTTPException

    class ItemResponse(BaseModel):
        id: int
        name: str
        class Config:
            from_attributes = True

    @app.get("/items/{item_id}", response_model=ItemResponse)
    async def read_item(
        item_id: int,
        db: AsyncSession = Depends(get_db)
    ):
        result = await db.execute(select(Item).where(Item.id == item_id))
        item = result.scalars().first()
        if not item:
            raise HTTPException(404, "Item not found")
        return item
    ```

    **改进点**：

    * 使用异步数据库操作
    * 添加响应模型，自动序列化
    * 使用依赖注入管理数据库会话
    * 添加错误处理
  </Accordion>
</AccordionGroup>

***

## 🏆 阶段性总结

恭喜你！你已经完成了 **Project Team** 基础训练营的第三阶段。

<Info>
  **到这里你已经掌握了：**

  * ✅ FastAPI 框架基础和路由定义
  * ✅ Pydantic 数据验证和模型设计
  * ✅ 依赖注入和中间件
  * ✅ SQLAlchemy 异步数据库操作
  * ✅ 配置管理和环境变量
  * ✅ Docker 容器化部署
  * ✅ 完整的 API 项目开发能力

  **下一阶段（Week 4）将学习：**

  * Go 语言基础
  * Go 并发编程
  * Go Web 开发
  * 微服务架构
</Info>

***

## <span style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}><Icon icon="lightbulb" size={26} color="#059669" /> 学习建议</span>

<CardGroup cols={2}>
  <Card title="巩固基础" icon="book">
    * 复习本周的所有代码示例
    * 完成所有拓展任务
    * 整理个人知识库和速查表
    * 记录遇到的问题和解决方案
  </Card>

  <Card title="实践项目" icon="code">
    * 尝试开发自己的 API 项目
    * 练习数据库操作和依赖注入
    * 熟悉 Docker 部署流程
    * 研究生产环境的最佳实践
  </Card>
</CardGroup>

***

<CardGroup cols={2}>
  <Card title="上一天: 综合实战" href="/training/30daystudy/day-20">
    Day 20 | 第三阶段综合实战
  </Card>

  <Card title="下一周: Go 语言" href="/training/30daystudy/week-4">
    第 04 周 | Go 语言拓展
  </Card>
</CardGroup>