ASP.NET Core API 版本控制 - 所有版本使用相同的控制器

Question

我有一个 ASP.NET Core 3.1 API，我正在为我的一个控制器引入新版本。我正在使用Microsoft.AspNetCore.Mvc.Versioning NuGet 包，并且已将新版本设置为默认版本。我的所有其他控制器都应适用于旧版本（1.0）和新版本（1.1）。

例如：

    [ApiVersion("1.0", Deprecated = true)]
    public class MySampleController
    {
    }
    
    [ApiVersion("1.1")]
    public class MyNewSampleController
    {
    }

    [ApiVersion("1.0", Deprecated = true)]
    [ApiVersion("1.1")]
    public class AllOtherController
    {
    }

问题：
我真的必须将所有版本添加到所有控制器吗？
有更好/正确的方法来处理这个问题吗？

我尝试使用 [ApiVersionNeutral] 但这似乎不正确，根据文档，应该只在特殊情况下使用。如果我不添加 [ApiVersion] 属性，则默认为新的 1.1 版本，1.0 不再有效。

由于这是我的第一个问题，我希望它符合指导方针:)

Answer 1

问：我真的必须将所有版本添加到所有控制器吗？

答：是的。API 版本是离散的。如果服务器无法满足请求，客户端应该准确地得到他们所要求的内容以及适当的错误响应。

问：有更好/正确的方法来处理这个问题吗？

答：有几种可能的选择。更好或更正确的处理事情的方法是非常主观的。因素有很多，最终的决定可能只是取决于偏好。

一个常见的误解是 API 版本控制使用属性。它确实不关心属性，这只是一种可能性，并且作为元数据往往会引起开发人员的共鸣。您可以选择使用开箱即用属性、自定义属性、开箱即用约定或您自己的自定义约定。

如何应用版本元数据的选择通常是偏好和实际管理的。常见的场景是按 API 版本在文件夹中组织控制器。在多种 .NET 语言中，文件夹名称会转换为相应命名空间的部分或全部。这种安排很常见，因此有一个开箱即用的VersionByNamespaceConvention 。有关详细信息，请参阅文档。By Namespace 示例还演示了如何端到端地构建这样的项目。

API 版本无关意味着 API 可以采用任何版本和所有版本，包括根本没有版本。这可能意味着您不关心 API 版本，或者您接受您自己处理的整个范围。它实际上只适合与永远不会随时间变化的 API 一起使用。例如，HTTPDELETE操作通常不会随时间或跨版本而改变。

这并不是 100% 清楚你的意思：

“如果我不添加 [ApiVersion] 属性，它将默认为新的 1.1 版本，并且 1.0 不再有效。”

本身没有默认值。此语句似乎暗示您已将选项设置AssumeDefaultVersionWhenUnspecified为true。除非您有充分的理由，否则您不应该这样做。这可能是 API 版本控制最被滥用的功能之一。客户必须知道它所要求的版本。允许客户端不指定版本并让事情从 过渡1.0到1.1 可能会破坏客户端。服务器不能假设它不会。此功能旨在为先前未定义显式版本的现有服务提供祖父功能。这种情况仅在首次启用 API 版本控制时存在。如上所述，所有控制器都必须有一个或多个离散的 API 版本，但原始的一组 API 没有明确定义。如果此功能不存在，那么不知道 API 版本的客户端基线集就会中断。