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] 但这似乎不正确，根据documentation，应该只在特殊情况下使用。 如果我不添加 [ApiVersion] 属性，则默认为新的 1.1 版本，并且 1.0 不再有效。

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

Answer 1

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

答：是的。 API 版本是离散的。如果服务器不能满足请求，客户端应该得到他们所要求的准确信息和适当的错误响应。

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

答：有几种可能的选择。 更好或更正确处理事情的方式是高度主观的。有很多因素，最终的决定可能只是归结为偏好。

一个常见的误解是 API 版本控制使用属性。它真的不关心属性，它只是一种可能性，也是一种倾向于作为元数据与开发人员产生共鸣的可能性。您可以选择使用开箱即用的属性、自定义属性、开箱即用的约定或您自己的自定义约定。

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

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

您的意思不是 100% 清楚：

“如果我不添加 [ApiVersion] 属性，则默认为新的 1.1 版本，1.0 不再工作。”

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