fba

FastAPI 最佳架构

官方文档：https://fastapi-practices.github.io/fastapi_best_architecture_docs/

使用此技能来遵循 fba 架构和插件约定。先加载下方的必需基线，然后只加载任务所需的其他参考资料。

必需的编码基线

对于每项后端 Python 实现、修复、重构或代码审查，在处理代码前都要阅读 references/coding-style.md 和 references/naming.md。这些规则既适用于常规开发，也适用于明确提出的风格要求；用户无需重复说明。将其应用于维护中的应用代码和插件代码，包括运行时模块、实用工具及相关测试，同时保留框架要求的约定。

对于跨层功能、目录变更或 SDK 集成，在确定模块边界前还要阅读 references/development.md，然后加载特定层的参考资料。

严格遵循用户要求的范围：全面审查插件时，应覆盖该插件中所有维护的模块及受影响的测试，而不只是 API/Service/CRUD 文件。常规功能或修复并不意味着可以进行无关的全仓库清理。对于仅涉及文档的工作，加载相关文档参考资料，无需加载 Python 基线。

完成前，按照 references/coding-style.md 中的审查检查项进行检查。仅通过 Ruff 检查并不能验证函数设计、测试驱动的辅助函数提取或分层边界。

核心架构

项目采用以 API、Service 和 CRUD 为核心的分层后端架构，并将 Schema 和 Model 作为明确的数据契约：

层级	职责
API	路由处理、参数验证和响应返回
Schema	数据传输对象、请求/响应数据结构定义
Service	业务逻辑、数据处理、异常处理
CRUD	数据库操作（继承 CRUDPlus）
Model	ORM 模型（继承 Base）

开发工作流

1. 定义数据库模型（model）
2. 定义数据验证模型（schema）
3. 定义路由（router）
4. 编写业务逻辑（service）
5. 编写数据库操作（crud）

参考资料选择

任务	阅读
功能/模块开发流程、Service/CRUD 的放置、分页、缓存、Celery、国际化、代码生成	references/development.md
API 路由、依赖项、响应模式、身份验证、权限	references/api.md
Pydantic 请求/响应 DTO	references/schema.md
SQLAlchemy 模型和迁移	references/model.md
CRUD、Service、API、Schema、实体和表的前缀命名	references/naming.md
后端/前端插件开发和插件 README 文件	references/plugin.md
插件共享、公共仓库、市场 PR、子模块、更新	references/plugin-sharing.md
每项后端 Python 实现/审查：函数、私有辅助函数、测试边界、类型标注、格式化、注释、文档字符串	references/coding-style.md（必需基线）
全局设置和配置	references/config.md

插件工作

创建、审查或更新插件时：

1. 阅读 references/plugin.md，了解插件类型、结构、清单、配置、钩子、SQL 和 README 规则
2. 如果任务涉及共享、发布、更新、市场 PR、插件仓库或 Git 子模块，则阅读 references/plugin-sharing.md
3. 如果文档与实现不一致，优先依据 fastapi-best-architecture 中的源代码行为
4. 除非用户明确要求，否则不要执行 git add、commit、push 或 PR 操作

CLI

执行 fba -h 获取更多详情。