Rest Api url版本控制方案：资源与服务

Question

在我们的应用程序中，我们采用了URI版本控制方案。

例如：server.com/v2/resource1

现在团队中有两种思想流派：

1. 我们不应该向客户端公开资源级别的版本，而应该给他们一个版本。如果他们调用/ v2 / resource1，而resource1不存在v2，那么我们应该在内部将请求重新路由到/ v1 / resource1。

2. 我们应该向客户端公开资源级别的版本控制。如果没有对resource1调用/ v2 / resource1和v2，则我们应该向客户端发送简单的404错误响应。

第一种方法的好处是，客户不必担心版本控制的详细程度。但是这种方法使我们无法进行端点的增量重构，因为一旦我们公开了v2，对于客户端，每个资源都是v2版本，则会破坏向后兼容性。

第二种方法使我们可以更好地控制增量重构，并且还可以从客户端的角度清楚地了解资源版本。

想法？

Answer 1

根据REST规范，建议不要在URL中包含版本信息，因为REST URI应该引用唯一的资源。但是，几乎所有最流行的基于REST的API都不遵循此建议。

为了简化工作，如果没有可用的新版本，请在v2中部署resource1。如果有可用的新版本，则在v2中部署该版本。

请同时保持两个版本都运行，并留出一段时间让客户端有时间升级和删除较旧的版本。

Answer 2

IMO API版本应处于API级别。即使您只需要更改单个特定操作的版本；所有现有的API操作也应使用新版本进行访问，例如您不应具有在/api/v2/template/op1可以访问一个操作的情况，但是在同一API中的第二个操作只能在/api/v1/template/op2而不是/api/v2/template/op2进行访问。这会给API使用者增加很多混乱。

我们在我目前的公司中使用.NET Core。为实现上述目的，API控制器类的所有已知版本均标有ApiVersion属性。不是最新版本的特定操作将使用MapToApiVersion属性标记-最新操作版本不应使用特定MapToApiVersion属性标记，例如

[ApiVersion("1.0")]
[ApiVersion("2.0")]
[ApiController]
[Route("api/v{version:apiVersion}/template/test")]
public class TestController : ControllerBase
{
   [HttpGet]
   [MapToApiVersion("1.0")]
   public IActionResult Get()
   {
      return Ok(nameof(Get));
   }

   [HttpGet]
   public IActionResult GetV2()
   {
      return Ok(nameof(Get));
   }

此方法为您带来好处； a）客户端不必担心版本控制的详细程度，b）仍然可以对端点进行增量重构，而不会破坏向后兼容性。