1398281322-a11y/java-backend-guardrails / skills/java-backend-guardrails/api-contract
api-contract
UnverifiedUse when defining API 接口规范, REST methods, HTTP status, 错误码, 版本, pagination, 金额单位分, 时区, Idempotency-Key, or request_id. Do not use for HMAC/replay (backend-api-security) or SQL 越权 (backend-safe-check).
接口规范
When to Invoke
新接口、前后端联调约定、开放 API、面试「REST 怎么设计」「错误码怎么定」「金额用元还是分」。
When NOT
验签防重放 → api-security。资源归属越权 → safe-check。支付回调报文 → pay-notify。幂等落库细节 → idempotent。
风险(面试考点)
方法语义(RFC 9110): GET/HEAD 安全且幂等(只读、可缓存、可重试)。PUT/DELETE 幂等但不安全。POST/PATCH 默认不幂等。GET 写库、GET 带 body、GET /order/create 都是扣分项。
业务失败也返回 HTTP 200 且 code=0,监控当成功。或反过来所有错误都 500。401 与 403 不分:没登录 vs 没权限。404 可用来隐瞒资源存在(对越权列表也返回 404,不泄露「这个 ID 存在但不属于你」)。
金额用 double:对账差一分。时间无时区:报表差一天。分页用巨大 offset:深翻页打穿。列表 null 当空数组:前端 NPE。创建成功不给 201 + Location,客户端无法跟资源。
版本:路径 /v1 或头;不兼容变更必须新版本,加字段可兼容。改金额单位、改枚举含义、删必填 = 不兼容。
Idempotency-Key(draft-ietf-httpapi):同一 key 必须返回首次结果。同一 key 不同 body → 409/422,禁止当新单。进行中的同一 key → 409,客户端等,不要再开一单。
方案选型(轻量优先)
| 项 | 默认 |
|---|---|
| URL | 复数名词 /orders/{id},动词在方法上 |
| 方法 | GET 查、POST 创建、PUT 全量幂等更新、PATCH 部分、DELETE 删 |
| HTTP | 2xx 成功(创建 201+Location;异步 202);400 参数;401 未登录;403 无权限;404 无资源;409 冲突/幂等处理中;422 语义无法处理;429 限流;5xx 服务器 |
| 业务码 | body 里 code 给业务细分;不要用 200 包装未登录 |
| 金额 | 整数 分,字段名 amountFen;禁止 float |
| 时间 | ISO-8601 带时区或统一 UTC;切日时区写进口径 |
| 分页 | 默认 id 游标;管理后台小数据可用 page;禁止 page=10000 |
| 幂等 | 写接口要 Idempotency-Key 或业务号,见 idempotent |
| 追踪 | 每个响应 requestId / traceId;5xx 不回堆栈 |
{
"code": 0,
"message": "ok",
"requestId": "…",
"data": { "amountFen": 19900, "createdAt": "2026-09-01T08:00:00+08:00" }
}
列表:items: [](空也是数组),nextCursor。枚举用字符串并文档化全集。字段命名全链路统一(对外 camelCase 或 snake_case 二选一)。
兼容:只增可选字段、不改语义、不删必填、不改类型。客户端忽略未知字段。批量写:约定「全成或全败」或逐条结果(Zalando 用 207);禁止静默丢一半。
客户端重试:只对超时/429/5xx;4xx 除 409/429 不自动重试。POST 重试必须带同一 Idempotency-Key。
反例
错误:GET /order/create?price=1.99。
正确:POST /orders,body amountFen,头 Idempotency-Key。
错误:业务库存不足返回 200 + 文案。 正确:约定业务码(如 40901)或 409,监控能扫到。
错误:page=10000&size=20。
正确:cursor + limit。
错误:同一 Idempotency-Key 换金额再打,当成第二笔。 正确:指纹不一致直接拒。
验证
- 未登录 401,越权 403,缺资源 404,可区分。
- 同一 Idempotency-Key 创建订单只有一条;换 body 被拒。
- 金额全链路整数分,对账无浮点误差。
- 空列表是
[]不是null。
评审清单
- 方法语义正确;POST 写有幂等键
- 金额分、时间带时区
- HTTP 与业务码可监控;5xx 无堆栈
- 分页不是巨大 offset
- 不兼容变更走新版本
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |