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 Guide源自 Heroku Platform API 实践Requests 章节中的Minimize path nesting设计原则当数据模型存在层层嵌套的父子资源关系时路径极易被拉得过深、过长。本文将从问题成因出发详解资源优先平铺到根路径、仅用嵌套表达作用域集合的核心策略并以 org / app / dyno 三层模型为例给出可复用的路径重构方案帮助读者在设计 REST API 时兼顾路径的可读性、可记忆性与路由的灵活性。一、为什么路径会越写越深在真实业务模型中资源之间普遍存在父子parent/child关系组织拥有应用、应用拥有 dyno进程实例。如果沿用把父子关系原样映射进 URL的直觉做法路径会随关系层级逐级叠加例如/orgs/{org_id}/apps/{app_id}/dynos/{dyno_id}这条路径存在几个明显问题层级过深难以阅读与记忆——调用者必须记住每一层资源的 ID 才能定位到目标资源把资源的身份与导航路径耦合在一起——对 dyno 的引用被迫依赖 org、app 两级上下文即便调用方只关心 dyno 本身服务端路由逻辑被层级绑定——新增中间层级或调整归属关系时所有客户端路径同步失效违背了关注点分离原则——separate-concerns.md 明确指出Use the path to indicate identity用路径表达身份而过度嵌套让路径同时承载了身份与父子导航两层语义。二、核心原则限制嵌套深度嵌套只用来表达作用域集合该指南给出的解法简洁明确Limit nesting depth by preferring to locate resources at the root path. Use nesting to indicate scoped collections.通过优先将资源定位在根路径来限制嵌套深度仅用嵌套表示作用域集合。拆解为两条可执行的规则单个资源实体尽量放在根路径/orgs/{org_id}、/apps/{app_id}、/dynos/{dyno_id}每个实体都可以独立寻址嵌套只出现在集合场景只有当你要表达属于某个父资源的一组子资源时才使用一层父子嵌套如/orgs/{org_id}/apps。三、重构示例org → app → dyno 三层模型原文档针对dyno 属于 appapp 属于 org的经典场景给出了完整的路径清单/orgs/{org_id} /orgs/{org_id}/apps /apps/{app_id} /apps/{app_id}/dynos /dynos/{dyno_id}逐条解读这套设计路径语义层级/orgs/{org_id}单个 org 资源根路径/orgs/{org_id}/apps某个 org 作用域下的 app 集合一层嵌套作用域集合/apps/{app_id}单个 app 资源根路径/apps/{app_id}/dynos某个 app 作用域下的 dyno 集合一层嵌套作用域集合/dynos/{dyno_id}单个 dyno 资源根路径关键观察嵌套深度被严格限制在一层。dyno 虽然同时从属于 app进而从属于 org但它的实体寻址路径/{dynos}/{dyno_id}并不需要把祖先关系全部铺开而/orgs/{org_id}/apps、/apps/{app_id}/dynos这类集合端点恰好保留了按父子关系筛选集合的能力。对比最初的三层路径/orgs/{org_id}/apps/{app_id}/dynos/{dyno_id}重构后单资源端点从 1 个变为 3 个各自可独立操作GET / PATCH / DELETE集合端点保留了关系语义调用方仍可按 org 查 apps、按 app 查 dynos最大路径深度从 6 段降至 3 段。四、配套规则让平铺路径保持一致的形态平铺之后的路径要真正好用还需要与本仓库 Requests 章节的其他规则协同4.1 资源名使用复数resource-names.md 规定除非是系统内单例如/status资源名一律使用复数形式保持指代一致。上面的/apps、/dynos正是复数形态配合根路径定位端点语义一目了然。4.2 路径小写并使用连字符downcase-paths-and-attributes.md 要求路径与主机名对齐全部小写、以连字符分隔如service-api.com/app-setups。这保证平铺出的多段根路径同样符合统一的 URL 形态规范。4.3 支持 ID 之外的便利寻址support-non-id-dereferencing-for-convenience.md 建议在用户习惯用名称而非 UUID 时允许id_or_name混合寻址例如$ curl https://service.com/apps/{app_id_or_name} $ curl https://service.com/apps/97addcf0-c182 $ curl https://service.com/apps/www-prod这与实体平铺到根路径相辅相成——根路径寻址配合名称/ID 双通道能显著降低调用方的记忆负担但不建议只接受名称而排斥 ID。4.4 特殊动作走actions前缀避免加深嵌套actions.md 提醒优先采用不需要特殊动作的端点配置确需动作时用actions前缀清晰分隔例如/runs/{run_id}/actions/stop、/actions/restart/servers。这同样服务于控制路径深度的目标——不要把业务动词揉进资源层级里。五、何时该嵌套何时该平铺边界判断综合本仓库的原则可以提炼出如下判断准则需要独立操作增删改查的实体 → 平铺到根路径如/dynos/{dyno_id}需要按父资源筛选/聚合的集合 → 保留一层父子嵌套如/orgs/{org_id}/apps路径深度超过两层时/parent/{id}/child/{id}/...应触发重构信号审视是否可以把中间层实体提升为根资源嵌套仅表达作用域不重复携带祖先链——子资源的实体端点不需要把整条祖先链写进路径。六、与响应体中外键嵌套的区别需要注意本原则管的是URL 路径与 Responses 章节中 nest-foreign-key-relations.md 讨论的响应体 JSON 结构是两个不同层面路径层尽量平铺、限制嵌套深度方便寻址与路由响应体层外键引用建议用嵌套对象owner: {id: ...}而非owner_id: ...以便在不改响应结构的前提下内联更多关联信息。二者并行不悖路径的扁平化降低 API 的调用复杂度响应体的嵌套化提升数据的自描述性。作为 API 设计者应在设计评审时同时检查这两个层面。七、小结最小化路径嵌套是 HTTP API 设计中最容易上手也最容易被忽视的规则之一。它不要求为每个资源都发明独立的端点体系而是给出一个简单可执行的折中实体放根路径集合留一层嵌套。这样既保留了父子关系的查询能力又把路径深度和心智负担控制在合理范围。结合资源复数命名、小写连字符、ID/名称双通道寻址与actions动作前缀等配套约定即可构建出一套一致、可记忆、易于演进且被本指南en/SUMMARY.md Requests 章节推荐的请求路径设计。对于正在从层层嵌套的 URL向平铺 作用域集合迁移的团队建议从最高频的资源端点开始逐条按上述清单重构并辅以文档与 schema 同步更新确保调用方平滑过渡。赞分享API设计教程【免费下载链接】http-api-designHTTP API design guide extracted from work on the Heroku Platform API项目地址https://gitcode.com/gh_mirrors/ht/http-api-design点击查看免费下载相关推荐Interagent/HTTP-API设计指南如何最小化路径嵌套Interagent/HTTP API设计指南如何最小化路径嵌套 什么是路径嵌套问题 在RESTful API设计中当资源之间存在父子关系时开发者常常会创API设计教程LLaMa CPU fork深度解析为什么这个项目能让AI模型在普通电脑上运行LLaMa CPU fork深度解析为什么这个项目能让AI模型在普通电脑上运行 LLaMa CPU fork是Meta LLaMa模型的一个特殊分支它打破RESTful API 设计指南基于 HTTP 的资源化接口设计与最佳实践RESTful API 设计指南基于 HTTP 的资源化接口设计与最佳实践 导读 RESTful APIRepresentational State Tra文档教程知识库上一篇5分钟快速上手 virt-manager从安装到创建第一个虚拟机下一篇Skopeo镜像元数据查询内存数据库应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考