FastAPI项目架构设计与工程化实践指南

1. 从零开始构建可维护的 FastAPI 项目结构

当你第一次用 FastAPI 可能把所有代码都塞进 main.py，就像我刚接触时那样。但随着功能增加，这个文件会膨胀到难以维护。我接手过的一个项目，main.py 超过 2000 行代码，光是找某个路由就要滚动半天 - 这绝对不是我们想要的结果。

1.1 模块化设计的核心原则

好的项目结构应该像乐高积木：

• 功能内聚：每个文件/模块只做一件事（路由、模型、工具函数等）
• 低耦合：模块间通过清晰接口交互，避免直接依赖内部实现
• 可扩展：新增功能时只需添加模块，无需修改现有结构

我推荐的中小型项目结构（适用于 90% 的 API 项目）：

code复制blog-api/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI 实例 & 中间件
│   ├── models.py               # 数据库模型
│   ├── schemas.py              # Pydantic 模型（请求/响应）
│   ├── database.py             # 数据库连接 & 会话
│   ├── security.py             # 认证逻辑
│   ├── exceptions.py           # 自定义异常
│   └── api/
│       ├── __init__.py
│       ├── v1/
│           ├── __init__.py
│           ├── posts.py        # 文章相关路由
│           └── users.py        # 用户相关路由

关键点：api/v1/ 这种版本目录让 API 演进更轻松，后续可以平行添加 v2 而不影响旧版本

1.2 数据库连接的最佳实践

在 database.py 中，我推荐使用 SQLModel 的异步会话（虽然示例用了同步，但生产环境更推荐异步）：

python复制# 改进版的异步数据库配置
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "postgresql+asyncpg://user:pass@localhost/dbname"

engine = create_async_engine(DATABASE_URL)
async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)

async def get_session() -> AsyncSession:
    async with async_session() as session:
        yield session

为什么选择异步？

• 避免阻塞事件循环，提升并发性能
• 与 FastAPI 的异步特性完美配合
• 现代数据库（如 PostgreSQL）都有优秀的异步驱动

2. 自动化测试：保障代码健康的唯一途径

没有测试的项目就像没有安全网的走钢丝。我曾因为一个未测试的支付接口修改，导致线上订单重复扣款 - 这个教训价值 3 小时紧急回滚和无数道歉邮件。

2.1 测试金字塔在 FastAPI 中的实践

code复制       E2E 测试 (10%)
      /           \
   API 测试      UI 测试
  (30%)         (弃用)
 /
单元测试 
(60%)

对于 API 项目，我们应该重点投入在单元测试和 API 集成测试。

2.2 使用 pytest 的黄金法则

1. 测试隔离：每个测试用例都应有独立的环境

python复制@pytest.fixture(autouse=True)
async def prepare_db():
    # 每个测试前清空并重建表
    async with engine.begin() as conn:
        await conn.run_sync(SQLModel.metadata.drop_all)
        await conn.run_sync(SQLModel.metadata.create_all)

2. 测试工厂：用工厂函数创建测试数据

python复制# tests/factories.py
def post_factory(**overrides):
    defaults = {
        "title": "Test Post",
        "content": "Content",
        "author": "test_user"
    }
    return {**defaults, **overrides}

3. 异步测试：使用 pytest-asyncio 和 AsyncClient

python复制@pytest.mark.asyncio
async def test_create_post(client):
    data = post_factory(title="紧急Bug修复")
    response = await client.post("/api/v1/posts/", json=data)
    assert response.status_code == 201
    assert response.json()["title"] == data["title"]

2.3 测试覆盖率：不要自欺欺人

安装 coverage 工具：

bash复制pip install pytest-cov
pytest --cov=app tests/

我建议至少达到：

• 80% 对于新项目
• 60% 对于遗留项目改造

警告：不要为了覆盖率而写无意义的测试！重点测试业务逻辑和边界条件

3. 容器化部署：从开发到生产的无缝衔接

Docker 不只是部署工具，它更是开发环境的救星。记得那次新同事花了三天配置本地环境？有了 Docker 后，现在只需要 3 分钟。

3.1 生产级 Dockerfile 的 7 个要点

dockerfile复制# 阶段1：构建环境
FROM python:3.10-slim as builder

WORKDIR /app
COPY requirements.txt .

# 安装构建依赖
RUN apt-get update && \
    apt-get install -y --no-install-recommends gcc python3-dev && \
    pip install --user -r requirements.txt

# 阶段2：运行环境
FROM python:3.10-slim

WORKDIR /app
COPY --from=builder /root/.local /root/.local
COPY . .

# 确保脚本可执行
RUN chmod +x /app/start.sh

# 确保用户级安装的包可用
ENV PATH=/root/.local/bin:$PATH

# 使用非root用户
RUN useradd -m appuser && chown -R appuser /app
USER appuser

# 健康检查
HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

CMD ["/app/start.sh"]

对应的 start.sh：

bash复制#!/bin/sh
uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8000} --workers ${WORKERS:-4}

3.2 多阶段构建的 3 个优势

1. 减小镜像体积：最终镜像不包含构建工具（gcc等）
2. 提高安全性：减少攻击面
3. 加速 CI/CD：可以利用构建缓存

3.3 生产环境必须的 Docker 配置

1. 资源限制：防止单个容器耗尽系统资源

bash复制docker run -d \
  --name myapp \
  --memory=512m \
  --cpus=1.5 \
  -p 8000:8000 \
  my-blog

2. 日志管理：使用 json-file 驱动并配置日志轮转

bash复制docker run -d \
  --log-driver=json-file \
  --log-opt max-size=10m \
  --log-opt max-file=3 \
  my-blog

3. 健康检查：结合监控系统自动重启不健康的容器

4. 云平台部署实战：Render 的隐藏技巧

Render 虽然免费，但有些坑我踩过之后才知道怎么避免。

4.1 部署流程的 5 个关键点

1. Procfile 的玄机：

code复制web: uvicorn app.main:app --host 0.0.0.0 --port $PORT --workers 2

2. 环境变量优先级：

• Render 仪表盘设置 > .env 文件 > 代码默认值

3. 构建缓存策略：

yaml复制# render.yaml
services:
  - type: web
    name: blog-api
    env: python
    buildCommand: pip install -r requirements.txt
    startCommand: uvicorn app.main:app --host 0.0.0.0 --port $PORT
    envVars:
      - key: DATABASE_URL
        fromDatabase:
          name: blog-db
          property: connectionString

4. 防止休眠的技巧：

• 设置每分钟的 health check 请求
• 使用免费监控服务（如 UptimeRobot）定期访问

5. 数据库连接池配置：

python复制# database.py
engine = create_async_engine(
    DATABASE_URL,
    pool_size=5,         # 连接池大小
    max_overflow=10,     # 允许超出pool_size的连接数
    pool_timeout=30,     # 获取连接超时时间(秒)
    pool_recycle=300     # 连接回收时间(秒)
)

4.2 成本优化方案

免费方案的限制：

• 512MB RAM
• 共享CPU资源
• 每月750小时运行时间

升级策略：

1. 先用免费方案验证可行性
2. 流量增长后切换到 Starter 方案（$7/月）
3. 高峰期使用自动扩展

5. 环境管理与安全防护

去年某公司因为 API 密钥泄露损失百万美元的事件还历历在目，安全无小事。

5.1 环境变量的 4 层防护

1. 开发环境：.env 文件 + gitignore
2. CI/CD 环境：GitHub Actions 的 secrets
3. 容器环境：Docker secrets 或 Kubernetes ConfigMap
4. 云平台：Render 的环境变量加密存储

5.2 敏感配置管理方案

python复制# app/config.py
from pydantic import BaseSettings

class Settings(BaseSettings):
    secret_key: str = Field(..., env="SECRET_KEY")
    database_url: str = Field("sqlite:///./test.db", env="DATABASE_URL")
    
    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"

settings = Settings()

使用 Pydantic 的 BaseSettings 优势：

• 类型检查
• 默认值设置
• 多环境源自动合并
• 文档生成友好

5.3 必须加密的数据

1. API 密钥
2. 数据库凭证
3. JWT 签名密钥
4. 第三方服务认证信息
5. 支付网关配置

永远不要在代码或版本控制中存储明文密码！使用 Vault 或云平台密钥管理服务

6. 从部署到监控的全链路实践

部署只是开始，真正的挑战在于保持服务稳定运行。

6.1 必须配置的 3 种监控

1. 应用性能监控（APM）

python复制# 安装
pip install opentelemetry-distro opentelemetry-exporter-otlp

# 初始化
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.resources import Resource

resource = Resource(attributes={"service.name": "blog-api"})
trace.set_tracer_provider(TracerProvider(resource=resource))

2. 日志聚合

python复制import logging
from opentelemetry._logs import set_logger_provider
from opentelemetry.sdk._logs import LoggerProvider

logger_provider = LoggerProvider()
set_logger_provider(logger_provider)

3. 健康检查端点

python复制from fastapi import APIRouter

router = APIRouter()

@router.get("/health")
async def health_check():
    return {
        "status": "healthy",
        "version": "1.0.0",
        "services": {
            "database": await check_db_connection(),
            "cache": await check_cache_connection()
        }
    }

6.2 告警策略配置

1. 响应时间：超过 500ms 触发警告
2. 错误率：5 分钟内 5% 错误触发警告
3. 内存使用：超过 80% 持续 5 分钟
4. HTTP 状态码：5xx 错误立即通知

6.3 性能优化技巧

1. 数据库连接池调优

python复制engine = create_async_engine(
    DATABASE_URL,
    pool_size=20,       # 常规设置
    max_overflow=10,
    pool_pre_ping=True  # 自动检查连接有效性
)

2. JWT 验证优化

python复制# 使用缓存验证过的token
from fastapi_cache import FastAPICache
from fastapi_cache.backends.redis import RedisBackend

@app.on_event("startup")
async def startup():
    FastAPICache.init(RedisBackend(redis), prefix="jwt-cache")

3. 响应压缩

python复制from fastapi.middleware.gzip import GZipMiddleware
app.add_middleware(GZipMiddleware, minimum_size=1000)

7. 持续集成与交付（CI/CD）流水线

自动化部署流程能减少人为错误，我团队通过 CI/CD 将部署时间从 2 小时缩短到 10 分钟。

7.1 GitHub Actions 完整配置

yaml复制name: Deploy to Render

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.10'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
        pip install pytest pytest-cov
    - name: Run tests
      run: |
        pytest --cov=app tests/
    
  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Render Deploy
      uses: render-actions/deploy@v1
      with:
        render-token: ${{ secrets.RENDER_TOKEN }}
        service-id: ${{ secrets.RENDER_SERVICE_ID }}

7.2 分阶段部署策略

1. 测试环境：每个 PR 自动部署

   • 地址：pr-123.your-app.render.com
   • 使用测试数据库
   • 自动运行集成测试

2. 预发布环境：main 分支合并后

   • 地址：staging.your-app.render.com
   • 克隆生产数据（脱敏后）
   • 人工验收测试

3. 生产环境：手动触发部署

   • 蓝绿部署或金丝雀发布
   • 监控关键指标 15 分钟
   • 出现问题立即回滚

7.3 数据库迁移方案

使用 Alembic 管理数据库变更：

python复制# alembic/env.py
from app.models import SQLModel
target_metadata = SQLModel.metadata

# 生成迁移脚本
alembic revision --autogenerate -m "add user table"

# 应用迁移
alembic upgrade head

重要：永远不要在迁移脚本中直接删除列，应该先标记为废弃，下个版本再移除

8. 项目优化进阶技巧

这些是我在多个生产项目中总结的实战经验，文档里找不到的干货。

8.1 依赖管理的 3 个层次

1. 基础依赖：requirements.txt

code复制fastapi==0.95.2
uvicorn[standard]==0.22.0

2. 开发依赖：requirements-dev.txt

code复制-r requirements.txt
pytest==7.3.1
httpx==0.24.1

3. 可选依赖：setup.py extras_require

python复制extras_require={
    'dev': ['pytest', 'httpx'],
    'prod': ['gunicorn', 'uvloop'],
}

8.2 性能关键路径优化

1. 路由注册优化

python复制# 不好的写法：每次导入都创建路由
from fastapi import APIRouter
router = APIRouter()

@router.get("/slow")
async def slow_route():
    ...

# 好的写法：延迟导入
def get_router():
    from .handlers import slow_route
    router = APIRouter()
    router.add_api_route("/fast", slow_route)
    return router

2. 中间件顺序原则

python复制# 从外到内的执行顺序
app.add_middleware(LoggingMiddleware)  # 最先执行
app.add_middleware(AuthMiddleware)     # 其次
app.add_middleware(GZipMiddleware)     # 最后执行

3. 响应模型优化

python复制# 避免的写法：每次请求都计算
@router.get("/posts", response_model=List[PostDetail])

# 推荐的写法：预编译响应模型
PostListResponse = List[PostDetail]
@router.get("/posts", response_model=PostListResponse)

8.3 文档生成技巧

1. 分组和标签

python复制router = APIRouter(tags=["用户管理"])

@router.post(
    "/users/",
    response_model=UserRead,
    responses={
        400: {"description": "无效输入"},
        409: {"description": "用户已存在"}
    }
)

2. 自定义文档界面

python复制from fastapi.openapi.utils import get_openapi

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="博客API",
        version="1.0.0",
        routes=app.routes,
    )
    # 自定义修改
    openapi_schema["info"]["x-logo"] = {
        "url": "https://example.com/logo.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

9. 疑难问题排查指南

当 API 出现问题时，按照这个检查清单能快速定位问题。

9.1 500 错误排查流程

1. 查看日志：docker logs <container_id>
2. 检查依赖：pip list 确认版本匹配
3. 验证环境变量：print(os.environ) 调试
4. 简化复现：用 curl 或 httpie 测试最小用例

bash复制http POST http://localhost:8000/api/v1/posts title="Test" content="Test"

5. 数据库连接：

python复制# 临时添加测试端点
@app.get("/debug/db")
async def debug_db(session: Session = Depends(get_session)):
    try:
        await session.execute("SELECT 1")
        return {"status": "ok"}
    except Exception as e:
        return {"error": str(e)}

9.2 性能问题排查工具

1. cProfile 分析

python复制import cProfile
from fastapi import Request

@app.middleware("http")
async def profile_middleware(request: Request, call_next):
    profiler = cProfile.Profile()
    profiler.enable()
    response = await call_next(request)
    profiler.disable()
    profiler.dump_stats("/tmp/profile.prof")
    return response

2. Py-Spy 实时采样

bash复制py-spy top --pid $(pgrep -f "uvicorn app.main:app")

3. AsyncIO 调试：

python复制import asyncio
asyncio.get_event_loop().set_debug(True)

9.3 常见错误解决方案

1. 数据库连接泄漏

• 症状：连接数逐渐增加直到超限
• 修复：确保每个 Session 都正确关闭

python复制# 错误示范
async def leaky_endpoint():
    session = Session()  # 不会自动关闭
    # ...

# 正确做法
async def safe_endpoint(session: AsyncSession = Depends(get_session)):
    # ...

2. 循环导入问题

• 症状：ImportError 涉及多个模块
• 修复：使用 importlib 延迟导入

python复制# 在需要时再导入
def get_router():
    from .handlers import my_handler
    router = APIRouter()
    router.include_router(my_handler)
    return router

3. 请求超时设置

python复制from fastapi import Request, HTTPException

@app.middleware("http")
async def timeout_middleware(request: Request, call_next):
    try:
        return await asyncio.wait_for(call_next(request), timeout=30)
    except asyncio.TimeoutError:
        raise HTTPException(status_code=504)

10. 项目演进与架构升级

当你的 API 开始被大量使用时，这些架构调整能让系统保持稳定。

10.1 从单体到微服务的过渡策略

1. 第一步：拆分路由

python复制# 原结构
app.include_router(posts_router, prefix="/api/v1")
app.include_router(users_router, prefix="/api/v1")

# 新结构：独立服务
# posts-service:8001
# users-service:8002

2. 共享代码管理

code复制shared/
├── models/
├── schemas/
└── utils/

3. 服务通信方案

python复制# 使用 HTTPX 进行服务间调用
async with AsyncClient(base_url="http://user-service") as client:
    response = await client.get("/api/users/me")

10.2 数据库分片实践

当单表超过 1000 万行时考虑分片：

python复制# 分片路由策略
def get_shard(user_id: int) -> str:
    return f"user_db_{user_id % 3}"  # 3个分片

# 动态创建引擎
engines = {
    "user_db_0": create_engine("postgresql://..."),
    "user_db_1": create_engine("postgresql://..."),
    "user_db_2": create_engine("postgresql://...")
}

def get_user_session(user_id: int):
    shard = get_shard(user_id)
    return Session(engines[shard])

10.3 缓存策略进阶

1. 多级缓存架构

python复制from fastapi_cache import FastAPICache
from fastapi_cache.backends.redis import RedisBackend
from fastapi_cache.backends.memory import InMemoryBackend

# 内存缓存作为一级
memory_backend = InMemoryBackend()
# Redis 作为二级
redis_backend = RedisBackend(redis_connection)

FastAPICache.init(memory_backend, prefix="1st-")
FastAPICache.init(redis_backend, prefix="2nd-")

2. 缓存失效策略

python复制@router.get("/posts/{id}")
@cache(expire=60, key_builder=lambda f, **kwargs: f"post:{kwargs['id']}")
async def get_post(id: int):
    # ...

# 更新时清除缓存
@router.put("/posts/{id}")
async def update_post(id: int):
    await FastAPICache.clear(namespace="post", key=f"{id}")

3. 缓存击穿防护

python复制from fastapi_cache.decorator import cache

@cache(
    expire=60,
    namespace="posts",
    key_builder=lambda f, **kwargs: f"post:{kwargs['id']}",
    # 只有一个请求会实际执行函数
    lock=True  
)
async def get_post(id: int):
    # 数据库查询

11. 安全加固终极指南

API 安全不是功能，而是必须的基础设施。以下配置能阻挡 90% 的常见攻击。

11.1 必须添加的 7 个安全中间件

python复制from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware
from fastapi.middleware.trustedhost import TrustedHostMiddleware
from fastapi.middleware.gzip import GZipMiddleware
from starlette.middleware.cors import CORSMiddleware

app.add_middleware(HTTPSRedirectMiddleware)  # 强制HTTPS
app.add_middleware(TrustedHostMiddleware, allowed_hosts=["example.com"])  # 主机头验证
app.add_middleware(GZipMiddleware)  # 响应压缩
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://your-frontend.com"],
    allow_methods=["GET", "POST"],
    max_age=600
)

11.2 JWT 安全增强方案

python复制from jose import jwt
from datetime import datetime, timedelta
from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def create_access_token(data: dict, expires_delta: timedelta = None):
    to_encode = data.copy()
    if expires_delta:
        expire = datetime.utcnow() + expires_delta
    else:
        expire = datetime.utcnow() + timedelta(minutes=15)  # 短期有效
    to_encode.update({"exp": expire})
    return jwt.encode(
        to_encode, 
        settings.secret_key, 
        algorithm="HS256",  # 避免使用RS256的配置复杂度
        headers={"kid": "v1"}  # 密钥版本标识
    )

11.3 速率限制实现

python复制from fastapi import Request
from fastapi.responses import JSONResponse
import redis

redis_conn = redis.Redis(host="localhost")

async def rate_limiter(request: Request, call_next):
    client_ip = request.client.host
    key = f"rate_limit:{client_ip}"
    
    # 每分钟最多60次请求
    count = redis_conn.incr(key)
    if count == 1:
        redis_conn.expire(key, 60)
    
    if count > 60:
        return JSONResponse(
            {"detail": "请求过于频繁"}, 
            status_code=429
        )
    
    return await call_next(request)

app.middleware("http")(rate_limiter)

12. 项目脚手架与模板工程

每次从零开始太浪费时间，我创建了这个模板项目，包含所有最佳实践：

code复制fastapi-template/
├── .github/
│   └── workflows/
│       ├── ci.yml
│       └── cd.yml
├── app/
│   ├── __init__.py
│   ├── api/
│   ├── core/
│   ├── db/
│   ├── models/
│   ├── schemas/
│   └── services/
├── tests/
│   ├── conftest.py
│   ├── factories/
│   └── integration/
├── .env.sample
├── docker-compose.yml
├── Dockerfile
├── Makefile
└── pyproject.toml

12.1 一键启动开发环境

bash复制make dev

这个命令会：

1. 启动 Postgres 和 Redis 容器
2. 创建虚拟环境
3. 安装开发依赖
4. 运行数据库迁移
5. 启动热重载服务

12.2 内置的实用 Makefile 命令

makefile复制.PHONY: test
test:
    pytest -xsv --cov=app --cov-report=term-missing tests/

.PHONY: lint
lint:
    ruff check app/
    black --check app/ tests/
    mypy app/

.PHONY: format
format:
    black app/ tests/
    ruff --fix app/

12.3 预配置的代码质量工具

1. Ruff：替代 flake8 + isort + autoflake
2. Black：统一的代码格式化
3. Mypy：静态类型检查
4. Pre-commit：提交前自动检查

yaml复制# .pre-commit-config.yaml
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.0.280
  hooks:
    - id: ruff
      args: [--fix]
- repo: https://github.com/psf/black-pre-commit
  rev: 23.7.0
  hooks:
    - id: black

13. 性能压测与调优实战

没有数据支撑的优化都是空谈。我用 Locust 做了系列测试，分享真实数据。

13.1 基准测试环境

• 机器配置：4核CPU / 8GB内存
• 网络延迟：<1ms (本地测试)
• 测试工具：Locust 2.15.1
• 测试场景：
  • 50 并发用户
  • 持续 5 分钟
  • 混合读写操作

13.2 优化前后对比

13.3 Locust 测试脚本示例

python复制from locust import HttpUser, task, between

class ApiUser(HttpUser):
    wait_time = between(0.5, 2)
    
    @task(3)
    def read_post(self):
        self.client.get("/api/v1/posts/1")
    
    @task(1)
    def create_post(self):
        self.client.post("/api/v1/posts/", json={
            "title": "Test",
            "content": "Content",
            "author": "tester"
        })
    
    def on_start(self):
        # 登录获取token
        res = self.client.post("/api/v1/login", json={
            "username": "test",
            "password": "test"
        })
        self.token = res.json()["access_token"]
        self.headers = {"Authorization": f"Bearer {self.token}"}

13.4 关键性能指标监控

1. Uvicorn 工作进程：

bash复制uvicorn app.main:app --workers 4 --loop uvloop

2. Prometheus 监控：

python复制from prometheus_fastapi_instrumentator import Instrumentator

@app.on_event("startup")
async def startup():
    Instrumentator().instrument(app).expose(app)

3. Grafana 仪表盘：

• 请求速率
• 错误率
• 数据库查询时间
• 内存使用情况

14. 国际化与本地化方案

当你的 API 需要支持多语言时，这个方案能优雅处理。

14.1 多语言错误消息

python复制# app/locales/en/errors.json
{
    "user_not_found": "User not found",
    "invalid_password": "Invalid password"
}

# app/locales/zh/errors.json
{
    "user_not_found": "用户不存在",
    "invalid_password": "密码错误"
}

14.2 中间件实现语言切换

python复制from fastapi import Request
from fastapi.responses import JSONResponse

@app.middleware("http")
async def i18n_middleware(request: Request, call_next):
    lang = request.headers.get("Accept-Language", "en")
    try:
        request.state.messages = load_messages(lang)
        return await call_next(request)
    except Exception as e:
        msg = request.state.messages.get(str(e), str(e))
        return JSONResponse(
            {"detail": msg},
            status_code=400
        )

14.3 日期时间本地化

python复制from datetime import datetime
from babel.dates import format_datetime

@app.get("/now")
async def current_time(request: Request):
    now = datetime.utcnow()
    lang = request.headers.get("Accept-Language", "en")
    return {
        "iso": now.isoformat(),
        "localized": format_datetime(now, locale=lang)
    }

15. 项目文档自动化

好的文档能减少 80% 的支持请求。这套方案让文档与代码同步更新。

15.1 Swagger UI 自定义

python复制from fastapi.openapi.utils import get_openapi

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    
    openapi_schema = get_openapi(
        title="博客API",
        version="1.0.0",
        routes=app.routes,
    )
    
    # 添加示例
    openapi_schema["paths"]["/posts/"]["post"]["requestBody"] = {
        "content": {
            "application/json": {
                "example": {
                    "title": "示例文章",
                    "content": "这是内容",
                    "author": "张三"
                }
            }
        }
    }
    
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

15.2 生成 Markdown 文档

python复制from fastapi.openapi.utils import get_openapi
import json

schema = get_openapi(
    title=app.title,
    version=app.version,
    routes=app.routes,
)

with open("docs/api.md", "w") as f:
    f.write(f"# {schema['info']['title']}\n\n")
    for path, methods in schema["paths"].items():
        f.write(f"## {path}\n\n")
        for method, spec in methods.items():
            f.write(f"### {method.upper()}\n\n")
            f.write(f"{spec['description']}\n\n")
            if "parameters" in spec:
                f.write("**参数**\n\n")
                for param in spec["parameters"]:
                    f.write(f"- {param['name']}: {param['schema']['type']}\n")

15.3 集成 ReadTheDocs

1. 创建 docs 目录

code复制docs/
├── Makefile
├── conf.py
└── index.rst

2. 自动生成 API 文档

python复制# conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('../'))

from app.main import app
from fastapi.openapi.utils import get_openapi

schema = get_openapi(
    title=app.title,
    version=app.version,
    routes=app.routes,
)

with open('api.json', 'w') as f:
    json.dump(schema, f)

3. 编写文档首页

rst复制.. _readme:

博客API文档
===========

.. toctree::
   :maxdepth: 2
   :caption: 目录:

   quickstart
   api

16. 团队协作规范

当多人协作开发时，这些规范能避免 90% 的合并冲突和代码混乱。

16.1 Git 分支策略

1. main：生产环境代码，只能通过 PR 合并
2. staging：预发布环境，每日自动部署
3. feature/：功能开发分支
4. hotfix/：紧急修复分支

bash复制# 功能开发流程
git checkout -b feature/user-auth
git commit -m "实现JWT认证"
git push origin feature/user-auth
# 创建PR合并到staging

16.2 代码审查清单

每个 PR