REST API设计：子集合与HTTP PATCH的两类场景选型问询

让我结合REST API设计的最佳实践，逐一拆解这两个场景的问题：

对于面向多客户端的通用公共API，方案1（子集合端点/customers/{id}/addresses）是更合适的选择，理由如下：

• 语义清晰，符合REST资源模型：地址是依附于客户的子资源，有独立的业务属性（比如街道、邮编、类型），用子集合端点能明确表达这种从属关系。客户端看到/customers/123/addresses就能立刻理解这是获取客户123的所有地址，直观易懂，降低了学习成本。
• 职责单一，易于维护：地址的CRUD逻辑可以独立封装在子端点的处理逻辑中，和客户资源的逻辑解耦。比如新增地址时，只需要针对地址的业务规则做校验，不需要和客户的其他属性逻辑混在一起，后续迭代也更灵活。
• 客户端友好：不同客户端（比如Web、移动端）都能轻松理解这种分层结构的API，不需要掌握复杂的JSON-PATCH语法。而且独立端点的调试、监控也更方便，出现问题时更容易定位。

再说说另外两个方案的不足：

• 方案2（顶级/addresses端点）：地址本身是依附于客户的，脱离客户的地址资源几乎没有独立业务意义。客户端使用时还需要额外传递客户ID参数，反而增加了关联复杂度，不符合资源聚合的设计原则。
• 方案3（PATCH + JSON-PATCH）：虽然能减少端点数，但要求客户端熟悉JSON-PATCH的操作语法，学习成本高。而且地址的复杂操作（比如批量更新、单独验证）会被迫耦合到客户资源的处理逻辑中，后期维护难度大，对于通用公共API来说，易用性和兼容性才是优先考虑的。

这个场景和场景一有本质区别，不应该采用场景一的方案1，方案3（PATCH + JSON-PATCH）是更优的选择，具体分析如下：

首先，编辑者列表只是Document资源的一个属性集合——它是primitive类型的用户ID数组，没有自己的独立业务属性或逻辑（你不会单独对某个编辑者ID做CRUD，只是添加/移除这个ID）。这种情况下：

• 方案1（子集合端点/documents/{id}/editors）确实很不自然：因为单个编辑者ID不是一个有独立业务意义的资源，为它创建CRUD端点会导致端点数无意义地激增（如果还有viewers、commenters这类集合，会出现大量类似的子端点），反而让API变得臃肿难用。
• 方案3的优势非常明显：
  1. 语义合理：编辑者列表是文档的一部分属性，用PATCH修改文档属性完全符合REST语义；
  2. 支持批量操作：可以在一个请求中同时完成添加编辑者、修改文档标题等多个操作，减少客户端的请求次数，提升性能；
  3. 简化API结构：不需要新增额外端点，避免了端点爆炸的问题，让API整体更简洁；
  4. 学习成本低：对于这种简单的集合操作，JSON-PATCH的add/remove语法足够直观，通用公共API支持JSON-PATCH也是行业常见做法，兼容性有保障。

关于“能否将这类简单primitive类型视为资源？”的问题：REST中的资源应该是具有独立业务意义的实体（比如Customer、Document），primitive类型的ID本身没有独立的业务逻辑，只是父资源的一个属性，因此不适合作为独立资源来设计端点。

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