首选URL路径版本（如/api/v1/users），因其直观、易调试、兼容缓存与代理；请求头版本易受CORS、CDN、Swagger及前端限制，常见406错误和fetch失败。
WebAPI 版本控制该用 URL 路径还是请求头
URL 路径版本（如 /api/v1/users）是绝大多数团队的首选，不是因为它最“优雅”，而是它最直观、最易调试、最兼容缓存和代理。请求头（如 Accept: application/vnd.myapi.v1+json）看似规范，但实际会卡在 CORS、CDN 缓存、Swagger 文档生成、前端 Axios 默认行为等多个环节。
常见错误现象：406 Not Acceptable 频繁出现，Postman 测试正常但前端 fetch 失败，Swagger UI 根本不显示 v2 接口。
- 路径版本：直接路由匹配，
MapControllers()自动识别[Route("api/v{version:apiVersion}/[controller]")] - 请求头版本：需手动注册
Microsoft.AspNetCore.Mvc.Versioning并配置ApiVersionReader，且 Swagger 必须额外集成Swashbuckle.AspNetCore.Filters - 混合使用（如路径 + 查询参数）会导致路由歧义，ASP.NET Core 6+ 会静默忽略部分版本声明
如何在 C# 中启用 API 版本并声明多个版本
核心是两步：注册服务 + 声明控制器版本。不注册服务的话，[ApiVersion("1.0")] 注解完全无效，运行时不会报错，但所有版本都 fallback 到默认（通常是 1.0），这是最常被忽略的坑。
实操建议：
- 在
Program.cs中调用services.AddApiVersioning(...)，至少要配options.DefaultApiVersion = new ApiVersion(1, 0)和options.AssumeDefaultVersionWhenUnspecified = true - 控制器上必须同时标注
[ApiVersion("1.0")]和[ApiVersion("2.0")]才能支持多版本共存；单个控制器不能只写一个版本还指望自动降级 - 不同版本的同名控制器可共存，但需用命名空间或类名区分，例如
UsersControllerV1和UsersControllerV2，否则编译报错Type 'UsersController' already defines a member called 'Get'...
为什么 [MapToApiVersion] 有时不生效
[MapToApiVersion] 的作用是把某个 Action 显式绑定到特定版本，但它只在控制器已声明对应版本的前提下才起效。如果控制器只标了 [ApiVersion("1.0")]，却给某个方法加 [MapToApiVersion("2.0")]，这个方法在 v2 下根本不可达——不是 404，而是路由系统压根不注册它。
典型误用场景：
- 想用同一控制器支持 v1/v2，只在类上写
[ApiVersion("1.0"), ApiVersion("2.0")]，然后靠[MapToApiVersion("2.0")]控制个别方法升级，结果 v2 请求调用到未标记的方法，返回的是 v1 逻辑 - 没意识到
[MapToApiVersion]不影响参数绑定或模型验证，它只管路由分发；v2 方法里仍可能调用 v1 的 service 层，造成语义不一致 - 搭配
[Route]使用时，路径模板必须与版本策略一致，比如用了路径版本策略，就别在 Action 上写死[Route("api/users")]，而应写[Route("users")]
版本废弃和重定向怎么处理更稳妥
直接删掉旧版控制器或返回 410 Gone 很干脆，但现实里往往要留窗口期。ASP.NET Core 没内置“软废弃”机制，得靠组合手段实现平滑过渡。
可行做法：
- 对已废弃的
[ApiVersion("1.0")]控制器，在每个 Action 开头手动检查HttpContext.Request.Headers["User-Agent"]或来源 IP，记录日志并返回426 Upgrade Required+ 提示信息 - 用中间件拦截
/api/v1/.*路径，301 重定向到 v2 对应路径——但注意：POST/PUT 请求重定向后浏览器会转为 GET，必须改用 307 或前端配合处理 - Swagger 文档中隐藏 v1 接口：通过
ISchemaFilter过滤掉ApiVersion("1.0")的操作，避免误导新接入方
真正的难点不在代码怎么写，而在于版本号语义是否清晰、废弃节奏是否和客户端更新强同步。很多团队卡在“以为接口下线了，其实 App 还在悄悄调 v1”。
