REST API路径参数版本化：兼容旧分类引用的最优方案选择

我正在寻找REST API路径参数版本化的可靠方案，但未找到可信资料。现有获取指定分类下产品的端点：

GET /categories/{categoryReference}/products

需同时支持实体的旧版categoryReference，我想到两种实现方式，请问哪种更优及原因？也欢迎补充其他方案：

方案1：新增端点 #

基于新增参数的思路，创建新端点：

GET /categories/oldCatRef/{oldCategoryReference}/products

方案2：使用查询参数 #

通过不同参数过滤查询，添加查询参数：

GET /categories/{oldCategoryReference}/products?usingOldCatRef=true

方案对比与推荐 #

方案1（新增端点）更优，原因如下：

• 语义清晰直观：从路径就能直接区分是使用新版还是旧版分类标识，调用方无需额外查阅文档就能理解端点用途，降低沟通和使用成本。
• 代码解耦易维护：新旧标识的处理逻辑可以放在独立的路由函数中，避免在同一个函数里写大量分支判断，后续修改或迭代其中一种逻辑时，不会影响到另一种。
• 贴合REST设计原则：REST中路径用于定位资源，不同的标识类型本质是对资源的不同定位方式，用独立路径更符合资源导向的设计理念。

它的唯一小缺点是会增加端点数量，但只要不是需要兼容大量版本，这个问题可以忽略。

方案2（查询参数）的不足：

• 语义模糊：路径中的参数类型依赖查询参数才能确定，调用方容易混淆，甚至可能误传参数导致错误。
• 逻辑混杂风险高：同一个端点需要处理两种标识的逻辑，随着兼容需求增多，分支会越来越复杂，容易引入bug，也不利于后续维护。
• 违背REST设计惯例：查询参数通常用于过滤、排序、分页等辅助操作，而标识类型属于资源定位的核心部分，用查询参数来区分并不合适。

补充可行方案 #

1. API版本前缀区分：如果是整体API版本迭代导致的标识变更，可以给API添加版本前缀，比如：

   GET /v1/categories/{oldCategoryReference}/products
   GET /v2/categories/{categoryReference}/products
   

   这种方式适合API有大量整体变更的场景，能清晰隔离不同版本的逻辑，避免新旧API互相干扰。
2. 后端自动识别标识：如果新旧categoryReference有明确可区分的特征（比如长度、前缀格式），可以在后端处理函数中自动判断标识类型，无需调用方额外指定参数。这种方式对调用方最友好，完全透明，但前提是标识特征足够稳定，不会出现误判。

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