api · git:20261026.8d01e18 · 2026-10-26 · sha256 c65142c0007d3ea6

api git:20261026.8d01e18A

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

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_3yplhizihif3frkw/c65142c0007d3ea64cfa198c2fb7d6f68eaa412190b30126b0734b6cac9d42fc.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 不一致

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