SuperAPI AI 工具集

best-openapi-design

编程与开发

查看项目

更新于 10-16 09:55

技能介绍

用途:把 HTTP API 当作长期存在的资源协议来对待,先发现稳定的领域资源,再定义路由,并在 OpenAPI 契约、实现和验证中保持 HTTP 语义。当需要设计、评审、实现或强制遵循严格面向资源的 RESTful API 与 OpenAPI 契约时使用。

主要能力:强调只暴露资源,禁止把业务逻辑、用例、工作流步骤、界面、按钮、控制器方法或领域命令直接翻译成 API 操作。路径中只允许资源名词、稳定标识符和非动作的基础设施前缀,不允许业务动词、RPC 后缀、查询参数或请求体判别符。对拒绝与建模给出对照示例,例如拒绝 POST /orders/{orderId}/cancel,改为 POST /orders/{orderId}/cancellation-requests;拒绝 POST /users/{userId}/activate,改为 PUT /users/{userId}/activation。要求失败关闭:若某能力无法用经证明的资源模型表达,就停止并报告缺失的领域决策,不得回退到命令式端点。

使用方式:按步骤执行。先建立设计边界,阅读仓库说明、现有路由、OpenAPI、客户端、测试与约定,判断调用方、认证授权边界、兼容性与任务类型。再建立资源模型,为每个候选资源记录含义、身份、归属、领域分组、表示、生命周期、规范 URI 与关系,并做资源证明。随后定义 HTTP 契约,使用标准方法与状态码、统一错误模型、幂等与并发、分页、过滤、排序与异步工作。再发布和演进 OpenAPI,最后在契约边界实现或评审,并运行验证与报告。资料提供确定性路径检查命令:python scripts/check_resource_paths.py /orders '/orders/{orderId}' '/orders/{orderId}/cancellation-requests'。

适用场景:公开、合作方或内部 HTTP API 的设计、评审、演进与实现,尤其关注资源建模、OpenAPI 契约一致性、HTTP 语义、幂等性、并发控制和兼容性。

限制:资料未提供收费、价格、平台支持、效果数据或具体安装方式。文中提及的参考文件(如 references/resource-modeling.md、references/http-contract.md 等)内容未在资料中展开,需以实际仓库为准。分页配置、版本头必需性、过滤器语法等项目级决策需由项目自身规定,资料未给出默认答案。