python-api-endpoint-creator

Python API 端点创建器

按照严格的分层架构模式创建完整的 FastAPI 端点。

适用场景

• 从头开始创建新的 REST API 端点
• 为新的领域实体添加 CRUD 操作
• 搭建完整技术栈：Router → Service → Repository → Tests
• 为新的领域模块搭建脚手架

流程

1. Pydantic Schemas — 在 schemas.py 中创建 Create/Update/Response
2. SQLAlchemy Model — 在 models.py 中添加 SoftDeleteMixin
3. Repository — 在 repository.py 中实现带软删除的异步 CRUD
4. Service — 在 service.py 中实现业务逻辑，并通过 HTTPException 处理错误
5. Dependencies — 在 dependencies.py 中定义 get_db、get_service
6. Router — 在 router.py 中实现精简端点，所有依赖都使用 Depends()
7. Tests — 在 tests/ 中编写 httpx AsyncClient 测试

每个文件的完整模板请参阅 code-patterns.md。

架构

Router (APIRouter)  →  Service  →  Repository  →  Database
      ↓                  ↓            ↓
  Depends()        Business logic  SQLAlchemy
  Pydantic schemas HTTPException   AsyncSession
  Status codes     Validation      Soft delete

硬性规则

• 所有变更操作都使用 POST — 读取使用 GET，创建／更新／删除使用 POST
• ID 使用查询参数 — 使用 ?id=xxx，绝不使用路径参数 /{id}
• Router 保持精简 — 只负责委派，不包含业务逻辑
• Service 抛出 HTTPException — 用于处理预期错误（404、409、422）
• Repository 处理软删除 — 在所有查询中筛选 deleted_at.is_(None)
• 所有端点都使用 async def — CPU 密集型操作除外

注意事项

• 忘记设置 response_model 会导致 API 泄露内部字段。 始终为端点设置 response_model=YourSchema。否则，FastAPI 会序列化原始返回值，其中可能包含 SQLAlchemy 模型中的 hashed_password、deleted_at 或其他内部字段。

• Depends() 会为每个请求创建一个新实例，而不是单例。 如果你的 Service 持有状态，这些状态会在请求之间丢失。Service 应保持无状态。如果需要共享状态，请使用 app state 或缓存。

• 在依赖项中执行 await db.commit()，不要在 Repository 中执行。 get_db 依赖项负责处理提交／回滚。如果还在 Repository 中提交，就会导致重复提交错误，或在所有操作完成前过早提交。

• Pydantic 默认返回的 422 错误信息不明确。 重写 RequestValidationError 处理器，返回字段级错误。默认信息只有“validation error”，无法为前端提供有用的细节。

• 创建端点缺少 status_code=201。 FastAPI 默认返回 200。为 POST 创建路由明确设置 status_code=status.HTTP_201_CREATED，并为删除路由设置 status_code=status.HTTP_204_NO_CONTENT。