API设计教程【免费下载链接】http-api-designHTTP API design guide extracted from work on the Heroku Platform API项目地址https://gitcode.com/gh_mirrors/ht/http-api-design点击查看免费下载导读本篇文章聚焦 http-api-design 仓库中 Responses 章节的「Provide resource (UU)IDs」规范讲解为什么每个 API 资源都应默认携带id属性、为什么优先选择 UUID 而非自增 ID以及如何将 UUID 渲染为规范化的8-4-4-4-12全小写格式。读完本文你将掌握一套可直接落地的资源标识符设计规范并理解它与响应中完整资源表示、时间戳、外键嵌套等相邻规范的协同方式。规范出处与定位本条规范位于仓库的 en/responses/provide-resource-uuids.md属于整部指南的 Responses响应部分。该指南最初提炼自 Heroku Platform API 的设计实践见 en/README.md目标是给出「一致、良好文档化」的 HTTPJSON API 设计方式避免团队在细节上的反复争论。在整部指南的目录结构中见 en/SUMMARY.mdResponses 章节还包含「返回合适的状态码」「提供完整资源」「提供标准时间戳」「提供标准响应类型」「嵌套外键关系」等条目资源 ID 规范与它们是紧密配套的一组约定下面会逐一交叉说明。核心规则每个资源默认拥有id属性原文的规范第一条要求是默认给每个资源一个id属性。{ id: 01234567-89ab-cdef-0123-456789abcdef, created_at: 2012-01-01T12:00:00Z, updated_at: 2012-01-01T13:00:00Z }这意味着一份合格的资源响应中id是最基础、最稳定的字段客户端可以依赖它来缓存、排序、去重以及在后续请求中引用该资源。与「提供标准时间戳」规范见 en/responses/provide-standard-timestamps.md一致这类「默认提供」的字段只有在个别资源确实不适用时才允许省略——对id而言几乎不存在不适用的情况。为什么优先使用 UUID全局唯一性的价值原文给出的选择依据非常明确除非有非常充分的理由否则使用 UUID不要使用无法在「服务实例之间」或「服务内其他资源之间」保证全局唯一的 ID尤其是自增 ID。其背后的设计逻辑可以拆解为三点跨实例唯一在多实例部署、分库分表、数据迁移或跨服务合并数据的场景下自增 ID 会在不同实例中重复导致冲突与数据污染UUID 由算法生成不需要协调者即可保证唯一天然适合分布式环境。不可枚举自增 ID 可被顺序遍历客户端很容易猜出下一个资源的 ID例如1、2、3带来资源枚举与越权访问的风险UUID 的取值空间巨大无法通过递增来遍历。客户端预生成UUID 可以由客户端在创建请求时先行生成服务端直接落库即可简化了「先创建、再回读 ID」的两段式流程。渲染格式全小写的8-4-4-4-12原文对 UUID 的字符串渲染做了严格要求使用全小写按8-4-4-4-12的分组方式用连字符分隔即 8 位十六进制 4 位 4 位 4 位 12 位共 32 个十六进制字符与 4 个连字符。原文给出的标准示例id: 01234567-89ab-cdef-0123-456789abcdef8-4-4-4-12是对 128 位 UUID 的标准文本表示即 RFC 4122 规定的规范字符串形式。强制全小写、固定分组的意义在于消除表示层面的歧义客户端、缓存键、日志索引和数据库主键无需再处理大小写归一化或格式判断可以直接按字符串比较与去重。在 JSON 中id应作为字符串string而非数字返回。这一点与「提供标准响应类型」规范见 en/responses/provide-standard-response-types.md中关于 Number 的说明相互印证某些 JSON 解析器对超过 15 位十进制精度的数字会退化为字符串导致客户端拿到的类型不稳定。UUID 形如 32 位十六进制文本根本无法用普通 JSON 数字准确表达因此必须且只能以字符串形式序列化这也保证了客户端始终能预期id是 string 类型。与其他响应规范的协同使用资源 ID 规范不是孤立的它与 Responses 章节的多个条目共同构成完整的响应设计完整资源表示en/responses/provide-full-resources-where-available.md200/201 响应应返回带全部属性的完整资源对象其中自然包含id。原文的 DELETE 示例中被删除资源依然原样返回其id、hostname与时间戳便于客户端完成本地清理与对账。嵌套外键关系en/responses/nest-foreign-key-relations.md对外键引用应使用嵌套对象而非扁平的owner_id字段例如owner: { id: 5d8201b0... }。嵌套时只允许两种形态——只含可查回完整记录的外键如id、slug、email或直接内联完整记录不能提供字段子集。这里的id正是本规范定义的 UUID保证嵌套外键与主资源标识使用同一套格式与语义。标准时间戳en/responses/provide-standard-timestamps.md与UTC/ISO8601 时间en/responses/use-utc-times-formatted-in-iso8601.mdid负责唯一性created_at/updated_at负责变更追溯两者都是「默认提供」级别的资源基础字段。落地检查清单在设计或评审自己的 HTTPJSON API 时可用以下清单快速对照本规范检查项要求默认性每个资源响应默认包含id属性生成方式默认使用 UUID除非有非常充分且明确的理由唯一性ID 在服务所有实例间、以及服务内所有资源间全局唯一禁用项不使用自增 ID 等仅单实例/单表内唯一的 ID字符串类型id在 JSON 中以字符串而非数字返回大小写全小写分组格式8-4-4-4-12共 32 位十六进制字符加 4 个连字符引用一致性外键嵌套引用时id使用与本规范一致的 UUID 格式遵循这些约定可以让 API 的标识体系在分布式部署、数据迁移和客户端缓存等场景下保持一致与稳定同时为「嵌套外键」「完整资源返回」「标准响应类型」等相邻规范提供统一的标识基础。赞分享API设计教程【免费下载链接】http-api-designHTTP API design guide extracted from work on the Heroku Platform API项目地址https://gitcode.com/gh_mirrors/ht/http-api-design点击查看免费下载相关推荐UUID设计模式构建全球唯一资源标识符的终极指南UUID设计模式构建全球唯一资源标识符的终极指南 在当今分布式系统和API开发中确保资源标识的唯一性至关重要。UUID通用唯一标识符作为一种强大的设计模API设计教程security-audit-skill最高原则只确认已成立的边界失效其他都不算漏洞security audit skill最高原则只确认已成立的边界失效其他都不算漏洞 security audit skill 是一个让编码智能体变身安全审AI 技能应用安全Graphene UUID类型实现全局唯一标识方案Graphene UUID类型实现全局唯一标识方案 在分布式系统开发中你是否还在为ID冲突、类型转换错误和数据一致性问题头疼Graphene框架提供的UU后端API设计上一篇ncmdump终极指南3步搞定网易云NCM音乐解密实现跨平台自由播放下一篇猫抓插件你的浏览器资源嗅探专家轻松捕获网络宝藏创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考