前言
山水一程，各有天命；
对错不由心，聚散不由人。
1.API Versioning
在微服务或 Web API 中，接口会随着业务发展不断迭代：
- v1：旧版本接口，客户端仍在使用
- v2：新版本接口，引入新功能或改进
如果没有版本控制，升级接口会破坏已有客户端。
API Versioning 就是用来支持多版本接口并保持兼容性的机制。
常见做法：
- URL 版本：
/api/v1/products - Query 参数：
?api-version=1.0（eshop就是使用的这种方式） - Header 版本：
api-version: 1.0
withApiVersioning 就是“多版本 API 的配置对象”，它让你的应用和文档生成知道有哪些 API 版本，并支持不同版本的接口共存。
2.配置OpenAPI 与Scalar
在应用运行时注册OpenAPI路由和开发环境下的Scalar 文档路由。
- 检查
appsettings.json的OpenAPI配置 - 映射
OpenAPI路由到应用 - 仅在开发环境打开
Scalar文档
3.注册OpenAPI和多版本配置
根据配置注册 OpenAPI，并支持 API 版本化的多个文档。
- 获取
appsettings.json中的OpenAPI和Identity的配置节点 - 提取
Identity的Scopes，用于OpenAPI安全检查
- 判断
apiVersioning - 假设有
v1、v2俩个版本， 为这2个版本注册OpenAPI文档
4.注册多版本OpenAPI
在Programe调用AddDefaultOpenApi注册多版本OpenAPI
5.Minimal API多版本路由配置
``app.NewVersionedApi("Catalog")`：创建一个版本化 API 的路由组
vApi.MapGroup("api/catalog") ：创建一个路由组，所有 /api/catalog 下的接口都可以挂在它下面
HasApiVersion(1,0) ：表示这个路由组只属于 v1
HasApiVersion(2,0) ：表示这个路由组只属于 v2
可以给同一条路由同时指定多个版本，比如 api 路由同时支持 v1 和 v2
启动项目，可以成功访问2个版本的api
6.访问不同版本的接口
6.1源码解读
从AddApiVersioning跟踪到AddApiVersioningServices
然后查看AddApiVersioningServices的实现
我们发现单利注册2次ApiVersionReader，这是依赖注入的常见做法：一个对象实现多个接口，需要分别注册。
IApiVersionReader：用于解析 API 版本IApiVersionParameterSource：用于提供版本来源信息
接着查看ApiVersionReader的实现，这里的Versioning.ApiVersionReader.Default就是获取接口版本的默认实现，上面提到有三种方式区分接口版本：查询字符串（/api/products?api-version=2.0）、HTTP头（Header: api-version: 2.0）、URL路径（/v2/products）
接着查看ApiVersionReader Default的实现：默认会从查询字符串和地址获取版本
Combine 方法（多来源 API 版本读取器组合器）：
- 把多个
IApiVersionReader组合成一个，允许从多个来源读取 API 版本（query string、URL、header 等）。 - 返回一个
CombinedApiVersionReader，按顺序尝试每个读取器。
剩下的不多跟了，本来这块不想看这么细的，突然好奇如何区分版本的，就捯饬了一下
6.1访问不通版本接口
我们打开俩个版本的scalar访问/api/catalog/items/{id}接口，发现版本号在查询参数里面
http://localhost:5222/scalar/v1#tag/items/GET/api/catalog/items/{id}
http://localhost:5222/scalar/v2#tag/items/GET/api/catalog/items/{id}
既然发现了API Versioning 的 实现方式，我们就可以通过不同的api-version访问接口
这里为了方便测试，选了2个版本都有的接口GetItemById，自己可以在GetItemById打上断点，发现不管请求api-version=1.0还是api-version=2.0，请求都可以进断点，知道规则后以后就知道如何单独访问2个版本的接口了
http://localhost:5222/api/catalog/items/1?api-version=1.0
http://localhost:5222/api/catalog/items/1?api-version=2.0
📌 创作不易，感谢支持！
每一篇内容都凝聚了心血与热情，如果我的内容对您有帮助，欢迎请我喝杯咖啡☕，您的支持是我持续分享的最大动力！
💬 加入交流群（QQ群）：576434538
