c# - API 版本控制 - 如果模型发生变化我该怎么办

Question

我对 API 和版本控制还很陌生，但据我了解，如果 API 发生违约变更，开发人员(也就是我)应该保留代码。如果我错了请纠正我，但我认为模型更改是违反契约(Contract)的更改。

所以我的问题是 - 您是否只是为了版本控制而制作新模型(例如 ModelName.V2)？有一个更好的方法吗？这意味着即使我的模型中的属性发生轻微变化，我也会将其迭代到另一个版本。

附注让我知道是否需要编辑我的问题，因为我在 StackOverflow 中也是相当新的。

示例

public class Product
{
    public int ID {get;set;}
    public string Name {get;set;}
}

和随附的 Controller

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]/[action]")]
public class Products : Controller
{
   Product[] prod = new Product[]{
       new Product(){ID = 1, Name = "T-Shirt"},
       new Product(){ID = 2, Name = "Jeans"}
   };


   [HttpGet]
   [ActionName("gotcha")]
   public IActionResult GetProduct()
   {
       return Ok(prod);  
   }
}

和 V2 Controller

[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]/[action]")]
public class V2.Products : Controller
{
       [HttpGet]
       [ActionName("gotcha")]
       public IActionResult GetProduct()
       {
           var trash = "Hello World!";
           return OK(trash);  
       }
}

上面的代码是我理解的契约(Contract)破坏和需要版本控制，下面是我的模型契约(Contract)破坏问题:

public class Product
{
   public int ID {get;set;}
   public string Name {get;set;}
   public decimal Price {get;set;}
}

所以上面的示例显示我添加了一个新属性。我认为这是契约(Contract)破坏，我是否迭代新的 Controller 版本，然后也保留旧模型？如果我保留旧版本，将来会很困惑。

Answer 1

首先，只有在发生破坏性更改时才需要恢复。并非所有事情都一定是重大更改，通常添加新属性实际上并不是重大更改。过时的客户应该简单地忽略它，如果不是，那更多的是客户而不是你，因为他们会做一些奇怪的/错误的事情来导致任何东西以这种方式破坏。您需要更加关注更改或删除，从客户的角度来看，这是一回事；有了变化，就好像旧属性被删除并添加了新属性。尽管如此，只有名称或类型发生变化时才重要。任何后台处理都无关紧要，从技术上讲，即使您更改了属性名称，您也可以使用类似 JsonProperty 的内容。如果需要，使序列化返回旧名称的属性。

假设您确实有一个突破性的改变，那么是的，您应该创建一个新版本的模型类，可能还有一个新的 Action / Controller ，它们都以新版本命名编号，即 Product2和 GetProduct2和/或 Product2Controller等等。是的，这可能会导致代码重复，但您可以通过两件事来最大程度地减少这种情况:

1. 尽可能使用继承。例如，Product2可以继承自Product并简单地覆盖任何需要更改的属性。如果你只是添加一个新的 GetProduct2操作，您可以分解出 GetProduct 的原始代码进入私有(private)通用方法GetProduct2<TProduct> ，然后重新实现原始(和新)方法以简单地返回它，即 return GetProduct<Product>();和 return获取产品()；`。这些只是例子。有许多不同的方法来处理这个问题，但重点是它不一定需要主要代码重复来进行版本控制。

2. 如果您发现您的代码库开始变得困惑，您可以开始弃用 API 版本。向您的客户发出通知，告知您的一个或多个最旧版本现已弃用。然后，经过一段合理的时间(取决于更新所需更改的复杂性)，在新版本中删除旧代码。这当然会破坏任何过时的客户，但他们被预先警告并有时间进行更改，所以如果他们不这样做，那是他们的责任。你会注意到所有的大男孩都会时不时地这样做。我知道我已经收到大量来自 Facebook 的电子邮件，警告 API 版本即将被删除。这基本上就是他们在幕后所做的事情:清理他们的代码库。