Claude Code + FastAPI 实战：用 AI 从零构建生产级 Python API

# CLAUDE.md（FastAPI 项目）

## 技术栈
- 框架：FastAPI 0.115+
- 异步 ORM：SQLAlchemy 2.0 async + asyncpg
- 数据验证：Pydantic v2
- 认证：python-jose（JWT）+ passlib（密码哈希）
- 测试：pytest + httpx（AsyncClient）
- 服务器：Uvicorn + Gunicorn

## 项目结构
app/
  main.py           # FastAPI 应用入口
  api/
    v1/
      endpoints/    # 路由处理函数
      deps.py       # 依赖注入（get_db, get_current_user）
  core/
    config.py       # 环境变量配置（使用 pydantic-settings）
    security.py     # JWT 生成/验证
  models/           # SQLAlchemy ORM 模型
  schemas/          # Pydantic 请求/响应 Schema
  services/         # 业务逻辑层（路由层不写业务逻辑）
  tests/

## API 响应规范
所有接口统一响应格式：
{"code": 0, "data": ..., "message": "success"}
错误响应：{"code": 非0, "data": null, "message": "错误描述"}

## 必须遵守
- 路由层只做参数解包和调用 service，不写业务逻辑
- 数据库操作必须使用 async/await
- 敏感字段（密码等）不能出现在任何响应 schema 中

# app/main.py
from fastapi import FastAPI
from app.api.v1 import auth, tasks
from app.core.config import settings

app = FastAPI(
    title="Task Manager API",
    version="1.0.0",
    docs_url="/api/docs",  # Swagger UI
)

app.include_router(auth.router, prefix="/api/v1/auth", tags=["认证"])
app.include_router(tasks.router, prefix="/api/v1/tasks", tags=["任务"])

# app/api/v1/deps.py - 依赖注入
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer
from app.core.security import verify_token
from app.database import AsyncSession, get_db

security = HTTPBearer()

async def get_current_user(
    token: str = Depends(security),
    db: AsyncSession = Depends(get_db),
):
    payload = verify_token(token.credentials)
    if not payload:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Token 无效或已过期"
        )
    user = await db.get(User, payload["sub"])
    if not user:
        raise HTTPException(status_code=404, detail="用户不存在")
    return user

# app/api/v1/tasks.py - 任务路由
from fastapi import APIRouter, Depends, Query
from app.schemas.task import TaskCreate, TaskResponse, TaskStatus
from app.services.task_service import TaskService
from app.api.v1.deps import get_current_user, get_db

router = APIRouter()

@router.get("", response_model=list[TaskResponse])
async def list_tasks(
    status: TaskStatus | None = Query(None, description="按状态筛选"),
    current_user = Depends(get_current_user),
    db = Depends(get_db),
):
    return await TaskService(db).list_by_user(current_user.id, status)

@router.post("", response_model=TaskResponse, status_code=201)
async def create_task(
    payload: TaskCreate,
    current_user = Depends(get_current_user),
    db = Depends(get_db),
):
    return await TaskService(db).create(current_user.id, payload)

# Dockerfile
FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt --no-cache-dir

COPY . .

CMD ["gunicorn", "app.main:app",
     "--workers", "4",
     "--worker-class", "uvicorn.workers.UvicornWorker",
     "--bind", "0.0.0.0:8000"]