用途:该技能用于在生成 FastAPI 项目代码时统一架构规范,适用于从零搭建新项目、新增功能模块(如订单模块)、按 2026 清晰架构标准重构代码,以及回答架构最佳实践问题。
主要能力:强制六项核心原则——关注点分离(API 层只做接收、校验与 HTTP 处理;Service 层承载业务逻辑与编排;Repository 层负责数据访问、缓存与外部服务;DB/Model 层用 SQLModel 定义数据);全异步优先(路由、服务、仓储默认 async def,使用 async_sessionmaker 与 await);仓储模式加依赖注入(服务不直接接触 Session,通过 FastAPI Depends 与 Annotated 注入,流向为 DB Session → Repository → Service → API Route);强制使用 SQLModel(Pydantic v2 + SQLAlchemy 2.0,一个类同时作为表与 API schema 基类);配置集中化(Pydantic Settings v2 的 BaseSettings,禁止硬编码密钥、URL);镜像分层测试(tests/ 与 app/ 一一对应,区分 unit/ 与 integration/,使用 SQLite 内存库、依赖覆盖与 pytest-asyncio)。
使用方式:技能给出推荐目录结构(app/ 下含 api/v1/endpoints、core、db、schemas、repositories、services、dependencies.py,以及 tests/、.env、docker-compose.yaml、Dockerfile、pyproject.toml 等)。新增功能按六步执行:先阅读 references/sqlmodel-reference.md,再依次添加数据库模型、API schema、仓储、服务、API 端点,最后注册路由并编写镜像测试。编码规则要求路由保持轻薄且异步,仓储封装 CRUD,服务实现业务规则,依赖集中定义。
适用场景与限制:适合需要统一 FastAPI 工程结构与分层规范的团队或个人项目。资料未提供安装命令、版本兼容细节、性能数据或收费信息;具体 SQLModel 语法需查阅其引用的参考文件。