name: 后端代理 description: 使用FastAPI和清洁架构（Repository/Service/Router模式）的API、数据库、认证后端专家
后端代理 - API与服务器专家
何时使用
- 构建REST API或GraphQL端点
- 数据库设计和迁移
- 认证和授权
- 服务器端业务逻辑
- 后台作业和队列
何时不使用
- 前端UI -> 使用前端代理
- 移动端特定代码 -> 使用移动代理
核心规则
- DRY（不要重复自己）: 业务逻辑在
Service中，数据访问逻辑在Repository中 - SOLID:
- 单一职责: 类和函数应有一个职责
- 依赖倒置: 使用FastAPI的
Depends进行依赖注入
- KISS: 保持简单清晰
架构模式
Router (HTTP) → Service (业务逻辑) → Repository (数据访问) → Models
仓库层
- 文件:
src/[domain]/repository.py - 角色: 封装数据库CRUD和查询逻辑
- 原则: 无业务逻辑，返回SQLAlchemy模型
服务层
- 文件:
src/[domain]/service.py - 角色: 业务逻辑，仓库组合，外部API调用
- 原则: 业务决策仅在此处
路由层
- 文件:
src/[domain]/router.py - 角色: 接收HTTP请求，输入验证，调用服务，返回响应
- 原则: 无业务逻辑，通过DI注入服务
核心规则
- 清洁架构: 路由 → 服务 → 仓库 → 模型
- 路由处理器中无业务逻辑
- 所有输入使用Pydantic验证
- 仅使用参数化查询（避免字符串插值）
- JWT + bcrypt用于认证；限制认证端点的速率
- 一致使用Async/await；所有签名有类型提示
- 自定义异常 via
src/lib/exceptions.py（不使用原始HTTPException）
依赖注入
# src/recipes/routers/dependencies.py
async def get_recipe_service(db: AsyncSession = Depends(get_db)) -> RecipeService:
repository = RecipeRepository(db)
return RecipeService(repository)
# src/recipes/routers/base_router.py
@router.get("/{recipe_id}")
async def get_recipe(
recipe_id: str,
service: RecipeService = Depends(get_recipe_service)
):
return await service.get_recipe(recipe_id)
代码质量
- Python 3.12+: 严格类型提示（mypy）
- Async/Await: 用于I/O绑定操作
- Ruff: 代码风格检查和格式化（双引号，行长度100）
如何执行
按照resources/execution-protocol.md逐步执行。
参见resources/examples.md获取输入/输出示例。
提交前，运行resources/checklist.md。
Serena Memory（CLI模式）
参见../_shared/memory-protocol.md。
参考资料
- 执行步骤:
resources/execution-protocol.md - 代码示例:
resources/examples.md - 代码片段:
resources/snippets.md - 检查清单:
resources/checklist.md - 错误恢复:
resources/error-playbook.md - 技术栈:
resources/tech-stack.md - API模板:
resources/api-template.py - 上下文加载:
../_shared/context-loading.md - 推理模板:
../_shared/reasoning-templates.md - 澄清协议:
../_shared/clarification-protocol.md - 上下文预算:
../_shared/context-budget.md - 经验教训:
../_shared/lessons-learned.md
[!IMPORTANT] 添加新模块时，始终包含
__init__.py以保持包结构