REST API设计咨询：父资源与嵌套资源应合并还是分开获取？

单次请求 vs 分两次请求的权衡 #

没有一刀切的标准答案，核心要匹配你的业务场景和资源特性：

• 性能与开销：
  • 单次请求能减少HTTP握手、路由等链路开销，在高延迟网络下优势明显；但如果嵌套资源（比如Employees）数据量极大，单次返回的 payload 会过大，反而拖慢加载速度，甚至触发超时。
  • 分两次请求的话，两个资源可以独立加载，比如先展示Group基本信息，再异步加载Employees，能提升用户感知的加载速度。
• 缓存策略：
  • 分开请求时，Group和Employees可各自独立缓存——比如Group信息数月才更新一次，Employees每周更新，分开缓存能大幅降低无效请求占比。
  • 单次请求的缓存粒度是整个响应，只要其中一个资源更新，整个缓存就得失效，缓存效率更低。
• 客户端复杂度：
  • 单次请求客户端无需处理两次异步请求的同步逻辑，代码更简洁；但如果客户端经常只需要Group或Employees其中一个，单次请求会返回冗余数据，浪费带宽。

拿你的Group+Employees场景举例：

• 如果一个Group的Employees数量不多（比如几十人），且半数场景都要同时展示两者，单次请求是更优选择。
• 如果Employees数据量极大（比如上百人且带大量详情字段），哪怕多数场景需要，也建议分开请求，或者单次请求返回Employees的精简版（仅ID、姓名），再单独提供接口获取完整员工信息。

条件参数是否属于不良实践？ #

/group?withEmployees=true这种方式绝对不是不良实践，反而很常见，是处理可选关联资源的标准方案之一。不过要注意几个细节让它更健壮：

• 采用更通用的参数命名：比如换成include=employees，以后要加其他关联资源（比如部门、权限），直接用include=employees,departments即可，扩展性更强。
• 明确默认行为：建议默认不返回嵌套资源，让客户端主动声明需要的关联——避免默认返回大 payload，浪费带宽和服务器资源。
• 限制嵌套深度：如果支持多层嵌套（比如include=employees.projects），要明确限制最大深度，防止客户端请求include=employees.projects.tasks.comments这种无限嵌套，拖垮服务器。
• 文档清晰化：在API文档里明确说明include参数的可取值、返回结构的变化，以及性能限制。

总结 #

核心原则是以客户端需求和资源特性为导向：

• 当嵌套资源数据量小、多数场景需同时使用、缓存需求低时，带条件参数的单次请求更友好。
• 当嵌套资源数据量大、缓存需求独立、或客户端常单独使用其中一个资源时，分两次请求更合理。
• 条件参数是合理实践，但要做好扩展性和性能控制。

内容的提问来源于stack exchange，提问作者Mats