路由模板必须含 v{version:apiVersion} 占位符，否则 Microsoft.AspNetCore.Mvc.Versioning 无法提取版本号导致匹配失败；正确写法是 pattern: "api/v{version:apiVersion}/[controller]" 并配合 [ApiVersion] 和 [Route] 使用。
路由模板必须含 v{version:apiVersion} 占位符
不加这个占位符，Microsoft.AspNetCore.Mvc.Versioning 就无法从 URL 提取版本号，所有版本匹配都会失败。常见错误是只写 api/[controller] 或 api/v1/[controller]（硬编码），前者根本没传版本，后者让框架失去路由分发能力。
正确做法是在 Program.cs 中注册路由时明确使用 API 版本约束：
app.MapControllers(); // 确保启用控制器路由
// ✅ 正确：带 apiVersion 约束
routes.MapControllerRoute(
name: "versioned",
pattern: "api/v{version:apiVersion}/[controller]"
);
- 不能同时注册
api/[controller]和api/v{version:apiVersion}/[controller]—— 前者会贪婪匹配所有请求，后者永远不生效 -
apiVersion是 MVC 内置的路由约束，不是自定义字符串，拼错（比如写成v{version:Version}）会导致 404 - 若用终结点路由（.NET 6+ 默认），应改用
endpoints.MapControllers()并确保AddApiVersioning已调用
[ApiVersion] 必须和 [Route] 配合使用
只标 [ApiVersion("1.0")] 不起作用，控制器不会自动绑定到对应路由。必须显式声明 [Route] 模板，并确保其中包含 {version} 占位符。
典型写法：
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiController]
public class UsersController : ControllerBase { ... }
- 支持多版本时，可叠加多个
[ApiVersion]：[ApiVersion("1.0")][ApiVersion("2.0")]，但每个都需对应一个能匹配的路由模板 - 若某 action 只属于 v2，但 controller 默认是 v1，可用
[MapToApiVersion("2.0")]显式标记该方法 - 不要在 controller 上漏掉
[ApiController]，否则模型验证、自动 400 响应等特性失效，影响版本行为一致性
Query String 版本（?api-version=2.0）仅限临时验证
虽然框架默认支持 query string 方式传版本，但它在生产环境有明显缺陷：缓存不可控、CDN/代理可能丢弃参数、日志和监控难以按版本聚合。
更关键的是，它和 URL 路由版本共存时容易引发歧义。例如：
- 请求
GET /api/v1/users?api-version=2.0—— 框架优先按 URL 匹配 v1，query string 被忽略（取决于配置） - 若开启
AssumeDefaultVersionWhenUnspecified = true，未带任何版本标识的请求会被默认路由到 v1，掩盖真实意图 - Swagger 文档生成时，query string 版本不会自动出现在路径中，导致前端无法直观识别接口归属
所以，生产环境应强制使用 URL 路径版本，禁用 query string 版本（通过 options.AssumeDefaultVersionWhenUnspecified = false + options.ReportApiVersions = true 提前暴露错误）。
Swagger 多版本文档需手动过滤，不能靠自动扫描
AddSwaggerGen 默认会把所有 controller 方法塞进一个文档，不管它们标了什么 [ApiVersion]。必须用 DocInclusionPredicate 手动筛选。
核心逻辑是：遍历每个 API 描述，提取其所在 controller 或 action 的 [ApiVersion] 属性，再比对当前文档名（如 "1.0"）是否在其中。
常见疏漏点：
- 忘记检查
methodInfo.DeclaringType是否为 null，导致空引用异常 - 误用
GetCustomAttribute<apiversionattribute>()</apiversionattribute>（只取第一个），而实际可能叠加多个版本，应改用GetCustomAttributes<apiversionattribute>()</apiversionattribute>+SelectMany(attr => attr.Versions) - 文档名习惯写成
"v1.0"，但[ApiVersion("1.0")]生成的版本字符串是"1.0"，比对时要统一格式（建议全部用"1.0"，不在 Swagger 名里加v）
真正容易被忽略的是：当某个 controller 同时支持 v1 和 v2，但只有一部分 action 标了 [MapToApiVersion("2.0")]，其余 action 默认走 v1 —— 这种混合场景下，DocInclusionPredicate 必须分别检查 controller 级和 action 级的版本属性，否则 v2 文档里会漏掉那些显式映射的方法。
