---
name: api
description: REST/OpenAPI 设计审查。
---

# api · 审查清单

契约变更须同 PR 更新 server + client + mocks（见 `rules/execution/api.mdc`）。

## URL 与资源

- [ ] 资源名词复数、小写、kebab-case（`/users` 非 `/getUsers`）
- [ ] 嵌套 ≤2 层；深嵌套改 query 或独立资源
- [ ] 版本策略一致（`/v1/` 或 header，全项目统一）
- [ ] 幂等写操作（PUT/DELETE）语义正确

## 请求与响应

- [ ] 稳定 error code / error type（非仅自由文本 message）
- [ ] HTTP 状态码语义正确（401 vs 403、404 vs 410）
- [ ] 分页一种风格（cursor **或** offset，不混用）；列表信封见 `reference/list-pagination-contract.md`
- [ ] 日期/时间 ISO-8601；枚举与 OpenAPI schema 一致

## 安全与校验

- [ ] 写路径 auth + 输入校验
- [ ] 敏感字段不在 GET list 中过度暴露
- [ ] Rate limit / 体量限制对公开端点有考虑

## 边界与默认（二级 · `input-bounds.mdc`）

- [ ] 数值参数有文档化上下限（越界 clamp 或 4xx）
- [ ] 枚举/模式字段白名单；未知值拒绝或安全回退
- [ ] 分页 `limit` 等有上限，禁止无界拉取
- [ ] 配置类输入非法时可回退并记录，不半开服务

## 契约同步

- [ ] OpenAPI/spec 与实现同 PR 更新
- [ ] Client types / API wrapper 已跟进
- [ ] Mock/fixture enum 与 server 校验一致
- [ ] Breaking change 在 CHANGELOG 标明

## 反模式（标 High）

- 仅改后端字段名不更新 client
- 200 + `{ "error": "..." }` 代替 4xx
- 示例与 schema 不一致
- **同 method+path 重复注册**（后者被遮蔽或行为不确定）

## 路由表面（HTTP 注册）

- [ ] 应用内 `(method, normalized-path)` **无新增 duplicate**
- [ ] 框架**先注册优先**时：不同 handler 不得共用同 path（常见 bug：复制粘贴 path）
- [ ] intentional 保留的未接线路由：Growth 决策 + **契约测试清单**（CI 可读，不依赖 `.growing/` 目录存在）
- [ ] 已删除的路由族（steering/ADR）有 **禁止回退** 断言
- [ ] path/method 变更：OpenAPI · client · mocks · CHANGELOG 同 PR

## API 测试

- [ ]  happy path + 401/403/404/422 覆盖
- [ ]  contract test 或 consumer-driven test 若项目已有
- [ ]  pagination 边界（空页、末页、非法 cursor）
- [ ]  跑项目 test / `curl` 示例与 OpenAPI 一致

## 垂直切片（跨层交付）

全栈新 API 域时，在上方审查清单之外按序自检（层序见 `rules/execution/vibe.mdc` §垂直切片）：

- [ ] 契约已定再动 persistence / service
- [ ] server 与 client types / mocks **同 PR**
- [ ] 测试：happy path + 主要 4xx；域脚本 L1 绿（`rules/feedback/verify.mdc`）
- [ ] 公开行为变更已更 docs / CHANGELOG
