SuperAPI AI 工具集

bep-best-openapi-design

编程与开发

查看项目

更新于 11-06 21:02

技能介绍

用途

bep-best-openapi-design 用于设计、评审、实现并强制约束严格面向资源的 RESTful HTTP API 与 OpenAPI 契约。它把 HTTP API 视为长期存在的资源协议:先发现稳定的领域资源,再定义路由,然后在 OpenAPI 契约、实现和验证中保持 HTTP 语义。

主要能力

该技能的核心是不可协商的“只暴露资源”规则:绝不把业务逻辑、用例、工作流步骤、界面、按钮、控制器方法、服务方法或领域命令直接翻译成 API 操作。业务行为应通过资源的创建、读取、替换、部分更新或删除来表达。路径中只允许资源名词、稳定标识符和非动作型基础设施前缀,禁止业务动词、RPC 后缀、查询参数或请求体判别器。

技能按以下顺序应用权威:遵守适用的 IETF HTTP RFC 要求;保持 Fielding REST 约束,尤其是资源标识、表示、自描述消息和统一接口;保持兼容的已发布契约和明确的项目级策略;在项目没有冲突要求或既有约定时应用本技能的基线配置。Google AIP、GitHub REST 等成熟 API 被视为证据而非权威,不应复制其 RPC 转码、protobuf 约定、旧式分页、自定义错误封装或兼容性包袱。

技能提供资源建模、资源组织、HTTP 契约、认证授权、OpenAPI 演进、框架集成等参考文档,并包含一个确定性的路径违规检查脚本,用于检测显式动词、RPC 后缀和命令选择器。

使用方式

技能按六个步骤推进:

  1. 建立设计边界:阅读仓库说明、现有路由、OpenAPI 描述、schema、客户端、测试和 API 约定,确定调用方、认证授权边界、受影响的现有操作与消费者、兼容性/延迟/一致性/保留/监管约束,以及任务是设计、评审、演进还是实现。

  2. 构建资源模型:在资源清单连贯之前不设计路径或方法。为每个候选资源记录含义、标识、所有权、领域分组、表示、生命周期、规范 URI 和关系。每个资源必须归属恰好一个领域分组,跨组关系用规范资源 URL 表示。

  3. 定义 HTTP 契约:完整定义每个操作,包括规范路径、方法、稳定唯一操作标识符、API-Version 头契约、参数、媒体类型与 schema、成功状态与响应体、统一错误模型、认证授权、重试与幂等、乐观并发与前置条件、缓存、集合排序过滤分页一致性、异步工作的轮询取消保留与结果发现。

  4. 发布与演进 OpenAPI:产出或更新完整的机器可读契约,而非部分文档覆盖层。使用所有必需验证器、生成器、网关、文档工具和运行时都支持的最新 OpenAPI 特性集。

  5. 在契约边界实现或评审:实现时把验证和授权放在系统边界,集中共享契约类型,保持领域独立于传输细节。评审时不修改代码,按契约影响分类发现并引用确切的路径、操作、schema 或行为。

  6. 验证与报告:运行仓库中最窄的契约验证、schema 差异、类型检查和测试。报告资源门禁、路径动词审计、RPC 形态审计的结果,以及边界、假设、兼容性约束、资源清单、规范 URI、字段与资源决策、领域分组放置证明和能力到资源的映射。

适用场景

适用于需要设计、评审、演进或实现 RESTful HTTP API 与 OpenAPI 契约的场景,尤其是希望严格保持资源导向、避免 RPC 风格端点、统一错误与分页模型、明确认证授权边界、管理兼容性与版本演进的项目。

限制

技能明确要求“失败关闭”:如果任何请求的能力无法通过经过验证的资源模型表达,应停止并报告缺失的领域决策,不得为该能力输出路径、OpenAPI 操作或实现代码,也绝不回退到命令式端点。分页配置必须为整个项目选择恰好一种(page 或 cursor),不能孤立地根据单个端点选择;当没有项目级决策或足够证据时,应报告 PAGINATION PROFILE INCOMPLETE 并停止。过滤默认使用单独声明的强类型参数,仅在需要复合谓词时启用单一过滤表达式,且项目必须为整个 API 发布完整的语法和类型系统。

关于该技能的具体安装方式、运行环境要求、收费或价格信息,资料中暂未提供。