SuperAPI AI 工具集

old-coder-api

编程与开发

查看项目

更新于 10-15 16:48

技能介绍

用途:覆盖 HTTP/JSON 契约与可运维性,适用于设计、变更或评审 API 表面。它假设消费者为 JSON;用于 gRPC/protobuf、GraphQL、WebSockets 等其他协议时,只应套用与传输无关的原则,并结合该协议自身的兼容规则。它不替代完整的安全评审。

主要能力:通过一组“门槛”约束设计,避免两种默认失败:发明不必要的新奇接口,以及在更名、重构或收紧字段时静默破坏下游调用。门槛包括:接口应“无聊”可猜(资源用复数名词、标准动词与状态码、标准字段名);不破坏现有使用者(新增端点、可选参数、响应字段可行,删除、改名、改类型、移动、收窄枚举或收紧校验属于破坏);认证应让最简单安全的路径易于使用(服务端到服务端默认用可限定范围、可撤销的 API 密钥,浏览器/移动端或高敏场景用 OAuth 等短期或发送方约束流程,并定义范围、轮换、撤销和安全传输);授权须在服务端对已解析资源强制执行,不信任调用方提供的 tenant_id、owner ID、角色或范围,列表、搜索、批量、导出、嵌套与间接查找路径同样适用;非幂等且会创建、触发或应用相对变化的操作应接受幂等键,重复键返回原结果,支付等不可接受重复的场景应强制幂等并原子去重;评估爆量风险、限流并用 X-RateLimit-Remaining 和 Retry-After、保留按消费者熔断;可能变大的集合使用游标分页并返回 next_page,有界集合可用页码;昂贵字段默认关闭,通过 include 按需返回;避免实现细节泄漏。

使用方式:先执行 Step 0 明确范围(公开还是内部、现有表面还是全新、资源模型是否支持),现有表面先跑 references/breaking-changes.md。逐项运行门槛,用 ✓ 表示已验证通过、✗ 加具体修复表示失败、N/A 加原因表示不适用、? 加原因表示未验证,不得静默跳过。与 old-coder 组合时,本技能负责 HTTP/JSON 契约,old-coder 负责工作流顺序、SPEC 批准、gauntlet 和 EVIDENCE;仅评审无实现时使用评审输出格式。评审报告优先顺序为破坏性变更、安全边界、事故风险、易用性,仓库代码须引用 file:line,已发布契约引用稳定 URL 与章节,源码证据须用不可变提交固定链接。

限制:兼容规则假定 JSON 消费者;不替代完整应用安全评审;参考文档和示例未在资料中给出具体内容;详细实现配方(幂等键存储、游标分页、限流头、includes)位于未提供的 references/patterns.md。