SuperAPI AI 工具集

building-backends

编程与开发

查看项目

更新于 10-16 04:55

技能介绍

用途:在设计或更改后端、服务、Worker 或 API 架构时加载,用于分层边界、事务归属与后台任务等后端专项决策。

前置:需先加载 architecting-changes 与 api-design,获取架构决策框架、边界与 API 设计原则;并通过 myai bootstrap 加载 engineering-principles。

主要能力与规则:路由与 Worker 只解码输入、调用一个核心操作、再向外映射结果,是薄适配器而非编排层。认证、会话、请求状态在边缘立即转换为无框架的类型化输入与 actor/principal,框架对象不得进入领域代码。预期失败在核心层保持 Result 类型,HTTP 状态映射只在传输边界进行;异常属于 bug 或基础设施逃逸,在全局错误边界与包装层捕获。

持久化:用例/处理器/服务拥有事务边界并决定提交或回滚;路由不得内联开启与提交业务事务;仓储可选,仅在真实持久化边界使用,多步流程中仓储不得自动提交。

Worker:与 HTTP、CLI 一样是适配器,调用同一核心服务,不得复制业务逻辑;重要后台工作需显式 job 载荷与处理器,不应藏在从请求处理器启动的 fire-and-forget 任务中;需要重试、持久性或可追踪时按真实工作流处理。

认证与上下文:重要写操作应显式暴露 actor、request ID、幂等键与模式;行为变化明显时用类型化 mode 枚举而非裸布尔。

常见错误:路由内联业务逻辑与提交、请求 DTO 或 ORM 行充当领域模型、框架对象泄漏进核心代码、到处使用通用仓储层、Worker 逻辑重复路由逻辑、重要写入缺少幂等/演练/可追踪、CLI 或管理脚本绕过核心服务。

生态示例:Python 默认 FastAPI 作 HTTP 适配器,Django 适用于后端复杂度大时;SQLAlchemy 2 + Alembic 为默认关系栈;pydantic DTO 在 HTTP 边缘转换。TypeScript/Node 默认 NestJS,Hono 用于边缘,Prisma/Drizzle 做持久化,Zod/Valibot 做校验,neverthrow 等做 Result。

交接:新仓库用 setting-up-backends,项目形态用 setting-up-projects,API 契约用 api-design,认证与加固用 security-and-hardening。