用途:按严格分层架构创建完整的 FastAPI 接口。适用场景包括从零新建 REST API 端点、为新的领域实体添加 CRUD 操作、搭建 Router→Service→Repository→Tests 全栈,以及脚手架式生成新领域模块。
主要能力与流程:在 schemas.py 中创建 Create/Update/Response 的 Pydantic 模式;在 models.py 中创建带 SoftDeleteMixin 的 SQLAlchemy 模型;在 repository.py 中实现带软删除的异步 CRUD;在 service.py 中编写业务逻辑并用 HTTPException 抛错;在 dependencies.py 中提供 get_db、get_service;在 router.py 中编写只做委托的薄端点,全部依赖通过 Depends() 注入;在 tests/ 中用 httpx AsyncClient 编写测试。完整各文件模板见 code-patterns.md。
架构:Router(APIRouter,使用 Depends、Pydantic 模式与状态码)→ Service(业务逻辑、HTTPException、校验)→ Repository(SQLAlchemy、AsyncSession、软删除)→ 数据库。
硬性规则:读用 GET,所有写操作(创建/更新/删除)用 POST;ID 通过查询参数传递(?id=xxx),不使用路径参数 /{id};Router 保持薄层,不含业务逻辑;Service 对预期错误(404、409、422)抛出 HTTPException;Repository 处理软删除,所有查询过滤 deleted_at.is_(None);除 CPU 密集型外端点均用 async def。
注意事项:端点务必设置 response_model,否则可能泄露 hashed_password、deleted_at 等内部字段;Depends() 每请求新建实例而非单例,Service 应无状态,需共享状态请用应用状态或缓存;commit 由 get_db 依赖处理,勿在 Repository 内再 commit,以免重复提交或提前提交;Pydantic 的 422 错误默认信息不透明,可覆盖 RequestValidationError 处理器返回字段级错误;创建端点需显式设置 status_code=status.HTTP_201_CREATED,删除端点设置 status_code=status.HTTP_204_NO_CONTENT。
限制:资料未提供安装命令、依赖版本、支持的 Python/FastAPI 版本及收费信息,暂未提供。