api · git:20261116.6085164 · 2026-11-16 · sha256 573432b663f0eaea

api git:20261116.6085164A

Immutable. This exact content never changes and is served at /api/v1/blob/573432b663f0eaea.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_3yplhizihif3frkw/573432b663f0eaeab0e4529c7c0d858652e29e42e5fce7d8a2b13d9d4e796072.json

Then /plugin install api@markdownregistry-3yplhizihif3frkw in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
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