SuperAPI AI 工具集

api-surface-review

编程与开发

查看项目

更新于 10-16 03:44

技能介绍

用途:这是 polar(Polar)仓库中用于审查 API 合约变更的技能。一次变更是否影响 API 合约、是否构成破坏性变更,由人工判断,CI 只负责展示差异。审查范围包括 /schemas.py、/endpoints.py、polar/openapi.py、docs/openapi.json、sdk/、clients/packages/client/。

主要能力与检查点:一是公开或私有,APITag 有 public 与 private 两种值,新路由需显式设置,不要用 include_in_schema=False 隐藏,私有接口不应按公开 API 推理;需要时给单个路由而非整个 router 打标签。二是 schema 形状,输出字段应必填、必要时可空,默认值会让 OpenAPI 变成可选并生成错误的 TS 字段(ADR-0007);类型字段用枚举而非 str;复用相关资源的 base schema;已有模型属性的值用普通字段,不重写 computed_field;描述面向用户,写 None 不写 null;写入 SQL INT 列的字段用 Int32;枚举用 Literal 列出允许值;判别联合用 Discriminator 加 SetSchemaReference;不要过度约束支付处理方传入的字段。三是命名,联合用干净名称、变体加限定,字段用 snake_case。四是破坏性变更,删除字段、翻转必填/可选、改类型、重命名或改客户端分支依赖的状态码都算破坏性;删除前应在 Logfire 查真实使用情况,仍在使用则保留兼容层并用 SkipJsonSchema;确实破坏性就明确说明,由人决策。五是路由形状,根端点尾斜杠、同路由错误需不同状态码、查询参数必须是纯过滤。

使用方式与输出:CI 的 OpenAPI Diff 工作流会以 PR 评论形式发布 schema 差异,OpenAPI Client Regeneration Check 会在客户端过期时失败,不要手工重算,直接读差异评论判断是否可接受。部分议题归其他技能:ADR-0002 与 ADR-0007 归 adr-check,端点约定归 conventions-check,共享类型复用归 reuse-check。输出按 API Surface 格式给出:🔴 Blocking(文件:行号、破坏内容、修复方式)、🟠 Should fix、🟡 Question、Notes(公开面差异一行或指向 OpenAPI Diff 评论)、Verdict(Clean 或 n blocking, n should-fix)。

限制:任何 Blocking 项在合并前都需要人工决策;本技能不手工重算 CI 已完成的差异,也不覆盖归其他技能所有的规则。具体安装命令与收费信息暂未提供。