Unleash REST API 设计规范URL 结构、响应契约与分页策略的工程实践指南【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleash本文是开源特性管理平台 Unleash 后端团队的 REST API 设计规范ADR解读系统梳理了新端点从 URL 前缀选择、路径命名、响应信封结构、分页策略、查询参数约定到 SQL 过滤原则的完整决策链。读者读完将掌握一套可直接复用的企业级 API 设计清单并能理解 Unleash 如何通过release稳定性字段与 OpenAPI 工具链来长期维护每一个公开端点这一核心设计哲学。这份 ADR 要解决什么问题contributing/ADRs/back-end/rest-api-guidelines.md是一份架构决策记录ADR它捕获了 Unleash 后端团队希望所有新端点遵循的约定。其出发点是三个现实约束每个公开端点都是一份长期契约Unleash 需要长时间维护和弃用deprecate已有端点因为 SDK 客户端、集成方都依赖它们。仓库配备 OpenAPI diff 工具正是为了在变更时及早发现破坏性改动——破坏或删除一个端点的代价非常高。优先向后兼容而非另起炉灶当现有端点无法满足新用例时首先判断能否以向后兼容的方式扩展它。只有破坏性变更别无出路时才新建端点例如把裸数组响应改造成信封结构参见下文 列表响应形状。约定适用于新工作不强制重构旧端点这并不意味着要为一个不符合规范的旧端点去创建替代端点。文档还引用了两份配套 ADR 作为相邻约定POST/PUT API payload 处理请求体中的undefined与null语义Separation of request and response schemas 处理请求/响应模式的精确性。URL 结构为端点的角色选择正确前缀新端点首先要选择与自身角色匹配的 URL 前缀。ADR 给出了明确的分配表前缀用途与定位/api/client服务端 SDK 评估 flag 使用公共、稳定/api/frontend浏览器 SDK 评估 flag 使用公共、稳定/edgeUnleash Edge 专用/api/integration/*新的集成类端点/api/admin文档化的公共管理 API以下前缀虽然已存在但新端点不应继续扩充它们它们各有专属定位前缀定位/api/signal-endpoint外部 webhook 回调进 Unleash集成类/scimSCIM 2.0 用户供给集成类/health、/ready、/internal-backstage面向编排器和监控的操作类端点/auth/*、/invite、/logout、/feedback面向浏览器的公共流程稳定性由release字段声明而非前缀前缀内的稳定性由 OpenAPI 规范中的release: { alpha \| beta \| stable }字段表达——alpha 端点在公开文档中会被隐藏。这一机制详见 API Version Tracking and Stability Lifecycle。一个关键原则是URL 前缀描述的是资源resource而不是当前受众audience。端点可以从 alpha 一路成长为 stable但路径不需要随之迁移这避免了为阶段变化付出重命名成本。在源码层面这一约定已经落地为强类型约束。ApiOperation类型将release声明为必填字段见 api-operation.tsexport type ApiOperationTag OpenApiTag Omit OpenAPIV3.OperationObject, tags { operationId: string; tags: [Tag]; enterpriseOnly?: boolean; release: StabilityRelease; };StabilityRelease支持四种声明形态api-operation.tsexport type StabilityRelease | { alpha: true } // 明确保持 alpha | { beta: StrictXyzVersion } // alpha → beta | { beta: StrictXyzVersion; stable: StrictXyzVersion } // alpha → beta → stable | { stable: StrictXyzVersion }; // alpha → stable稳定性等级由calculateStability()用语义化版本比较计算得出api-stability.ts当前版本早于第一个里程碑为 alpha位于beta与stable里程碑之间为 beta晚于stable为 stable。配套单元测试 api-stability.test.ts 以7.6.0为当前版本覆盖了{beta:7.6.5, stable:7.7.0} → alpha、{beta:7.5.0, stable:7.7.0} → beta、{beta:7.5.0, stable:7.6.0} → stable等全部过渡分支。SDK 面对的前缀是最严格的稳定性层级/api/client和/api/frontend是 Unleash 最严格的稳定性层级——即使最老版本的 SDK 也必须能理解这些响应。在这两个前缀下新增端点时需要格外谨慎地遵守本 ADR 的其余条款因为一个细微的破坏可能先在客户环境中悄悄劣化 flag 评估而团队很久之后才会收到反馈。从源码可以看到这些前缀下的控制器确实逐个声明了release里程碑例如 frontend-api-controller.ts 等 30 余个控制器文件均包含release: { ... }声明。避免动态路径段被遮蔽Shadowing这是 URL 设计中一个隐蔽的坑。如果存在路由/api/admin/projects/:projectId那么同级的静态路由/api/admin/projects/some-word会迫使some-word成为保留的项目 id——这依赖路由器优先匹配静态路由。问题在于这种“保留”只存在于路由注册顺序里一旦重排控制器冲突会重新出现每新增一个同级静态路径就会隐式保留一些:id值而现有数据可能已经包含了这些值。推荐的处置方式默认使用顶层兄弟路径用/api/admin/users-access-log而不是/api/admin/users/access-log。这样可以保持父级命名空间干净彻底绕开保留 id 问题。长期方案尚未启用未来可能采用-作为动态父级下集合级操作的保留段例如/api/admin/users/-/access-log遵循 Google AIP-159 规范。但当前并未落地不要临时自行引入如果有受益场景应提出讨论以便正式采纳该约定。停止使用 shadowing现有 case 保持不变不迁移但视为遗留代码不要因为同集合下已有类似端点就继续扩展它。ADR 明确列出了应当被避免的 shadowing 反例/api/admin/user-admin/:id/api/admin/user-admin/search/api/admin/user-admin/validate-password/api/admin/segments/validate命名约定端点各组成部分遵循统一的命名风格保证开发者无需查阅文档即可预测 URL 与字段名静态路径段使用kebab-case例如/api/admin/release-plan-templates/api/admin/projects/default/environments/${environment}/change-requests查询字符串参数使用camelCase例如strategyId、variantForFlag响应体字段使用camelCase例如hasMore、flagCreators。这一约定与前端消费方的直觉一致也让搜索、分页、排序等通用参数在多个端点间保持可预测性。列表响应形状新列表端点必须返回对象信封envelope而不是裸数组{ users: [ ... ] }信封结构使响应易于在不破坏 API 的前提下扩展例如追加分页元数据total、hasMore、游标{ total: 2000, users: [ ... ] }具体要求还包括集合字段以资源命名用users、flagCreators、events而不是泛化的data或items——在调用侧可读性更好也与现有端点保持一致新列表端点默认带limit端点必须设置maxLimit始终返回实际生效的limit与offset——即使调用方没有分页也要返回这样信封保持一致调用方可以看清实际使用了什么值例如请求limit10000000可能实际只返回最多1000条在可支持时包含total何时合理参见下文分页一节。完整信封示例{ total: 2000, limit: 1000, offset: 0, users: [ ... ] }这一“响应紧凑而精确、请求模式可更宽松”的思路正是 Separation of request and response schemas 的响应侧落地响应要小而有意请求模式则可以更宽容。分页策略既然新列表端点默认带limit调用方就必须有办法获取超过限制的数据“加载更多”或翻页。ADR 的核心立场是新列表端点默认分页。从第一天起就支持分页远比日后改造一个客户端已依赖一次性全量返回的端点便宜得多。具体策略默认采用 offset/limit?offset?limit并尽可能返回totaltotal计算代价过高时改用hasMore或取limit 1条来判断是否还有更多游标分页?cursorhasMore仅在特定场景使用当跨页稳定性比已知的total更重要时——例如数据快速变化的 feed 类端点。何时必须分页任何基数无上限unbounded、由客户控制、或成本可能显著增长的集合都必须分页。“通常很短”不是跳过分页的理由——实例规模各异数据库负载随时可能迫使后续加上限制。而像“特性策略类型”这种有明确领域上限的小集合则可以在绝大多数情况下在首页内返回完整列表。查询参数约定在发明新参数名之前先复用既有参数名这样前端和 API 消费者无需逐个阅读端点文档即可预测查询参数的语义?q——对自然可见字段用户类端点通常是 name/username/email的自由文本搜索。不要要求最小长度空q应与省略该参数行为一致。?offset/?limit——分页控制。?sortBy/?sortOrderasc|desc——排序。每个端点应文档化允许的sortBy值及其默认值sortOrder默认asc。?fieldIS:value——通过共享的通用查询参数助手实现的字段级过滤。优先使用它而不是一次性的布尔开关或自造参数名。从仓库源码看这类通用查询参数助手在 event-search-controller.ts、project-controller.ts、environments-controller.ts 等大量控制器中被复用正是“共享 helper 优于各自为政”这一决策的直接体现。只返回调用方需要的字段响应形状应针对具体用例设计不要以“客户端自己挑就行”为由返回完整的内部模型。理由很实际日后移除有问题的字段比按需新增字段困难得多。同时每个字段都增加线上传输成本并把客户端与内部形状耦合在一起。目标消费者用不到的字段就不应返回不同调用方需要不同数据量时优先拆分成独立端点而不是用?viewminimal|full参数——专用端点更易于推理和缓存。这是 Separation of request and response schemas 的响应侧对应物响应紧凑精确请求模式可以更宽容。在 SQL 中过滤而不是在 JS 中过滤所有行级过滤都必须在 SQL 查询中完成包括回退逻辑如“跳过没有 name/username/email 的行”。绝不能在查询返回之后再做过滤。原因有两点且都与分页正确性直接相关limit100可能返回少于 100 行破坏分页契约total不再与调用方实际看到的数据匹配。这不是边界情况——只要过滤在当前页移除了一行以上这就是常态行为。由于过滤、分页、排序如今全部在查询内执行新增或修改 SQL 成为审查热点要在真实数据量下检查查询计划、确认过滤列与排序列存在索引、警惕意外的全表扫描。一个糟糕的执行计划会直接拖垮端点而不是被内存中的补救工作掩盖。作为权衡把回退逻辑推入 SQL 有时意味着更复杂的查询例如用COALESCE处理回退列。ADR 明确接受这一复杂度以换取分页正确性——并且指出 Postgres 的查询规划器非常擅长规划它高频见到的查询因此这通常反而带来更短的响应时间和更少的 Unleash 与 Postgres 之间的数据传输。后果与权衡正向收益新列表端点默认分页从调用方视角行为一致前端与 API 消费者无需阅读每个端点文档即可预测搜索、分页、排序的查询参数响应形状小而有意内部模型变化不会自动改变 API 表面过滤行为与分页元数据保持一致UI 可以信任total与页大小。代价与让步给列表响应加信封对某些端点属于破坏性变更。该约定只适用于新端点现有裸数组端点保持不变除非有独立的理由重塑它们把所有过滤推入 SQL 有时意味着更复杂的查询如回退列的COALESCE团队以查询复杂度换取分页正确性。在仓库中进一步探索ADR 全文rest-api-guidelines.md稳定性计算实现api-stability.ts其中calculateStability的默认回退逻辑为未声明release的遗留端点在当前版本低于8.1.0时按 stable 处理之后按 alpha 处理为存量端点回填留出窗口与 ADR 中描述的临时兼容窗口一致源码以8.1.0为截止线。稳定性类型定义与测试api-operation.ts、api-stability.test.ts端点声明release的控制器示例frontend-api-controller.ts、project-controller.ts、event-search-controller.ts配套约定POST/PUT API payload、Separation of request and response schemas、API Version Tracking and Stability Lifecycle综上这份 ADR 的价值不仅在于给出了一套可勾选的清单更在于确立了三条贯穿始终的设计哲学公开端点是长期契约兼容优先、工具护航、前缀描述资源而非受众稳定性由release声明、分页与过滤的一致性优先于实现便利SQL 过滤 信封响应 默认分页。对新端点而言遵循这套约定就是默认行为只有在需求确实非常规时才有理由偏离。【免费下载链接】unleashOpen-source feature management platform项目地址: https://gitcode.com/GitHub_Trending/un/unleash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考