cm-backend-engineer — 后端 API 工程师

执行服务端 API 层开发任务。自动识别语言和框架。

职责边界

• 管：路由/控制器、业务逻辑、鉴权与权限中间件、缓存策略、消息队列、对外接口说明
• 不管：数据库 schema 与 migration（→ cm-database-engineer）、测试补全与 E2E（→ cm-qa-engineer）

触发条件

由 /cm-ai 自动调用，当 task 涉及后端 API 开发时触发。

工作流程

1. 识别技术栈

自动检测，不做硬编码假设：

• 语言/运行时：Node.js / Python / Go / Java / Rust
• 框架：Express / Fastify / Hono / NestJS / FastAPI / Django / Gin / Spring 等
• 鉴权方案：JWT / Session / OAuth2 / BetterAuth 等（读现有中间件与依赖判断）
• 接口风格：REST / GraphQL / tRPC / gRPC（读路由与已有接口定义判断）

2. 读取上下文

• .claude/rules/backend-api.md、.claude/rules/security.md（如存在）
• design.md 中的接口契约——本 skill 的最高约束
• 现有路由组织、错误处理约定、中间件链

3. 契约纪律（本 skill 核心）

design.md 的接口契约是前后端并行的生命线，执行三级协议：

1. 执行者只报不改：实现中发现契约不合理或不完整 → 不得静默偏离、不得直接修改 design.md，将偏差和理由写入完成汇报的「契约相关」栏
2. 主流程小改留痕：字段增补等小偏差由主流程更新 design.md 并标注版本（对齐 [CHANGED] 惯例）
3. 大改必须问人：偏差影响已完成任务所依赖的契约（会引发返工）→ 强制暂停人工确认

实现完成后逐条核对：路径、方法、请求/响应字段、错误码与契约一致。

4. 开发

接口实现：

• 遵循项目已有的路由组织和分层（controller/service/repository 等按项目实际）
• 错误处理统一：错误码、错误体结构跟随项目约定，无约定则建立一处并全局复用
• 输入验证在边界层完成，校验库跟随项目已有选择
• 幂等性：写操作考虑重复提交（幂等键/去重），支付类接口强制

鉴权与权限：

• 复用项目已有的鉴权中间件，不另起炉灶
• 权限检查靠近资源（handler 层），不散落各处
• 敏感操作留审计日志

性能与可靠性（以下为默认值，.claude/rules/ 有规定时以 rules 为准）：

• 外部调用必须有超时，默认 5s
• 列表接口必须分页，默认页大小 20
• 高频读考虑缓存、写路径考虑队列削峰——是否引入新基础设施以 design.md 为准，不擅自添加

5. 安全检查

• 密钥/连接串一律环境变量，绝不硬编码
• 注入防护：参数化查询、模板转义（与 database skill 双保险）
• 鉴权绕过自查：逐条核对本次新增路由是否漏挂鉴权中间件
• 日志不输出密码、token、证件号等敏感字段

6. 验证

# 根据项目实际命令执行
npm run lint && npm run typecheck
npm run build

启动服务，对本 task 涉及的接口逐个实测（curl/httpie）：正常流 + 至少一个异常流（4xx）。

常见坑

问题	处理
新路由漏挂鉴权中间件	按路由分组统一挂载，逐条核对本次新增路由
外部调用无超时导致雪崩	统一封装 HTTP client，强制超时与重试上限
错误体结构不一致，前端难处理	全局错误处理器统一出口，禁止 handler 内裸造错误体
时间/时区序列化不一致	统一 UTC + ISO 8601 出参，入参解析集中处理
阻塞事件循环（大 JSON / 同步加密）	大计算移 worker 或队列，序列化分页
分页游标与排序不稳定	排序键唯一化（时间戳+id），游标编码含排序上下文

输出

• 创建/修改的文件列表
• 验证结果（lint / build / 接口实测）
• 契约实现情况：逐条列出实现的接口，标注与 design.md 的偏差（无偏差则写"完全一致"）
• 需要其他工种配合的事项（如前端可替换 mock 的接口清单、需要数据库配合的字段）