SuperAPI AI 工具集

building-python-backends

编程与开发

查看项目

更新于 10-16 04:55

技能介绍

用途:在设计或改动 Python 后端、服务、worker 或 API 架构时使用,专注 Python 特有部分,通用架构决策与 API 设计需先加载 architecting-changes 与 api-design。

默认架构分层:传输/适配层(HTTP 路由、worker 与调度器、CLI/管理脚本)→ 应用/用例层(每个业务操作一个 service 或 command)→ 领域层(模型、策略、领域错误)→ 基础设施层(DB、缓存、外部客户端、认证适配)。小型后端可让应用与领域代码靠近,仅在职责或变更维度不同时增加层。

核心规则:路由与 worker 解码输入、调用一个核心操作、把结果映射向外;pydantic 请求/响应 DTO 位于 FastAPI 边缘,不是领域模型;认证/会话/请求状态在边缘立即转换为无框架的带类型输入与 actor/principal;预期失败在核心层保持 Result[T, E],HTTP 状态映射在传输边界完成;异常视为 bug 或基础设施逃逸,在全局边界捕获。

持久化与事务:用例拥有事务边界;仓储可选,仅在表达真实持久化边界时使用;不要让路由内联开启、提交并编排业务事务;不要让仓储在多步流程中自行静默提交。

Worker 与后台工作:worker 是与 HTTP/CLI 同等的适配器,调用同一核心服务;重要后台工作应有显式 job payload 与 handler;不要把重要工作藏在请求处理器发起的 fire-and-forget 任务里;需重试、持久性或可追踪的工作应视为真实后端工作流。

认证与操作上下文:框架认证/会话对象留在边缘,向核心操作传入带类型的 actor/principal;重要写操作应清楚暴露执行上下文:actor、request ID、幂等键以及需要时的 mode;行为有实质变化时优先使用带类型 mode 值而非裸 dry_run: bool。

框架与库取舍:FastAPI 是默认的平淡 HTTP 适配器;当后端复杂度、admin、认证/会话行为与 CRUD 面从一开始就明显庞大时,Django 有理由;服务自有 DB 时默认关系栈为 SQLAlchemy 2 + Alembic;httpx 包装器掌握出站 HTTP 边界;仅在产品真正需要时引入 Redis、队列与额外基础设施。

常见错误:业务逻辑与 DB 提交内联在路由中;用请求 DTO 或 ORM 行当领域模型;框架请求/认证/会话对象泄漏到核心代码;到处放通用仓储层;worker 逻辑与路由逻辑重复;重要写入在需要时缺少幂等、dry-run 或可追踪性;CLI 或管理脚本绕过真实核心服务。

衔接:新建后端仓库与初始脚手架用 setting-up-python-backends;若 API、CLI 与自动化共享一个核心用 building-multi-ui-apps;实现细节用 writing-python-code;测试策略用 testing-python。