cm-backend-engineer git:20260709.0cf0db0A

Immutable. This exact content is served forever at /api/v1/blob/1e4031eba04661a6.

---
name: cm-backend-engineer
description: 后端 API 工程师 Skill，执行服务端 API 层开发（路由、业务逻辑、鉴权中间件、缓存、队列），自动适配语言和框架
---

# 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. 验证

```bash
# 根据项目实际命令执行
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 的接口清单、需要数据库配合的字段）