specsfy-specialist-web-api-design

Web API 设计

适用场景

• 在设计或审查面向内部或外部使用者的 HTTP、REST、JSON、webhook 或 OpenAPI 描述时使用。
• 在决定资源、方法、状态、错误、分页、幂等性、并发、身份验证和兼容性时使用。
• 如果实际契约风格尚未确认，不要将 RPC 或事件当作 HTTP 资源处理。
• 对威胁建模、凭据、滥用和信任边界，结合 $specsfy-specialist-application-security 使用。

流程

1. 了解使用者、用例、现有风格、负载、延迟、可用性、信任边界和兼容性政策。
2. 对资源、标识、关系、不变量和所有权进行建模，不要为了方便而将内部表或对象暴露为契约。
3. 定义操作、schema、header、状态和 Problem Details；使用 references/standards.md 记录每项操作的重试语义。
4. 在实现处理程序之前，设计身份验证、按资源／租户授权、幂等性、前置条件和并发。
5. 规定分页、筛选、确定性排序、限制、速率限制，以及面对可变数据时的行为。
6. 编写 OpenAPI/JSON Schema，并针对实现运行正向、负向和兼容性契约测试。
7. 定义日志、指标、关联、弃用、迁移，以及在不破坏已知使用者的情况下移除旧行为的标准。

模式

• 使用一致的 HTTP 语义和具体状态码。
• 保持错误格式稳定、可操作且不泄露信息。
• 长时间分页期间数据会变化时，使用游标。
• 必要时使用幂等键，确保创建和重试安全。
• 使用签名、时间戳、防重放和重新投递来保护 webhook。
• 避免无声的破坏性变更和语义模糊的字段。
• 不要为了方便而将持久化模型暴露为契约。

反模式

• 对所有结果都返回 200，并且只在 body 中编码失败；缓存、客户端和可观测性都会丢失协议语义。
• 超时后在没有幂等性或对账机制的情况下重复发送 POST；丢失的响应可能导致重复收费、重复下单或重复触发外部操作。
• 对大型且可变的集合使用 offset 分页，却不保证排序稳定；不同页面之间可能重复或遗漏项目。
• 只在端点／列表上授权，而不对已加载的资源授权；有效 ID 可能跨越租户或范围。
• 每次新增变更都对 URL 进行版本控制；这会增加并行生效的契约，却无法解决兼容性规范问题。

验证

• 针对描述中的有效和无效示例，运行 request、response、header 和 Problem Details 契约测试。
• 使用正确身份、跨身份、过期凭据和权限范围不足等情况，验证按资源和租户授权。
• 模拟重试、重复请求、提交后超时、更新竞态，以及项目不断加入或移出时的分页。
• 对 OpenAPI/JSON Schema 执行 lint 和结构验证，并将破坏性变更与上一版已发布版本进行比较。
• 未通过重放证据和自动化测试验证使用者所观察到的契约前，不要宣称兼容或幂等。

相关技能

• $specsfy-specialist-astro 在框架中实现端点；此技能负责维护可在网站之外使用的 HTTP 契约。
• $specsfy-specialist-application-security 涵盖威胁建模、OAuth、机密保护、滥用和信任边界。
• $specsfy-specialist-domain-modeling 在将词汇和不变量公开为资源之前对其进行定义。
• $specsfy-specialist-typescript 对内部类型进行建模，但不会自动将其作为公开契约的来源。
• $specsfy-specialist-observability 除了契约中的关联字段，还定义遥测和 SLO。
• $specsfy-specialist-performance-engineering 衡量吞吐量和延迟，不会为了提升基准测试成绩而改变语义。

请阅读 references/standards.md，了解方法、错误、幂等性、并发、分页、Webhook 和兼容性演进矩阵。