SuperAPI AI 工具集

rest-api-principles

编程与开发

查看项目

更新于 10-15 17:25

技能介绍

用途:这是一套 REST API 设计原则,用于规范领域资源的建模与 URL 结构,帮助团队保持 API 一致性。

主要能力: 资源建模:每个核心领域概念是一个资源,路径为 /api/v{version}/{entities}/{id};资源名用复数 kebab-case,如 /api/v1/flow-categories/{id}。当领域语言把多词概念当作一个词时,写作一个词,并在项目中明确记录该例外。 版本控制:v{version} 只写主版本(v1,不写 v1.2)。公共 API 必填,内部 API 可选。 方法与状态码:GET 安全;PUT、DELETE 幂等;POST 创建或执行。校验失败返回 400 Bad Request;与资源当前状态冲突返回 409 Conflict。 集合:资源根 /api/v{version}/{entities} 是列出该类型的集合。若不适合无过滤列举,集合接收查询参数过滤;无过滤请求返回 400 并指明所需过滤条件。不设分页约定,按需引入。 所有权与嵌套:若实体拥有子资源集合(删除父级即删除它们),表示为父级下的子集合 /api/v{version}/{parents}/{id}/{children},默认最多一层。不拥有的资源属于其自身根集合,在引用方表示中仅以 ref(id 加显示名)出现。 资源形态:关联数据以嵌入(完整表示)或 ref 两种形式出现;被拥有的子资源可嵌入,非拥有资源只以 ref 出现。ref 可选带 self 链接;完整 HATEOAS 非目标。 操作:领域操作是自有资源,后缀 -operation,动词优先并保留该后缀;POST 执行,长任务带 id 返回 202 Accepted 和 Location 头。 报表:跨多实体的请求是顶层资源,后缀 -report,名称单数,只读 GET,缺参数返回 400;可含冗余数据以精简高效。

限制:未提供安装命令、代码示例的完整实现、收费方式或具体平台信息;分页明确不设约定,需按规模决定是否引入。