ThinkPHP实现API版本控制有五种方式：一、URL路径版（如/api/v1/user/info），语义清晰且兼容性好；二、请求头版（如X-API-Version），保持URL统一；三、查询参数版（?version=v1），适合灰度发布；四、子域名版（v1.api.example.com），物理隔离性强；五、服务层抽象版（接口契约+适配器），支持运行时切换。
如果您在ThinkPHP项目中需要为API接口提供不同版本的支持，则可能是由于业务迭代导致接口参数、返回格式或逻辑发生变更。以下是实现API版本控制的步骤：
一、URL路径版本控制
通过在请求路径中嵌入版本标识（如/api/v1/user/info），使路由直接区分不同版本，该方式语义清晰、易于理解且兼容性好，同时支持路由缓存与OpenAPI文档自动生成。
1、在route/app.php中使用Route::group()定义静态版本前缀路由组，避免使用变量路由或正则捕获；
2、为每个版本组独立绑定控制器命名空间，例如api/v1.User对应app\api\v1\User类；
立即学习“PHP免费学习笔记（深入）”；
3、确保各版本控制器文件严格位于对应子目录下，目录名与命名空间小写一致，文件名与类名完全匹配；
4、为不同版本组分别配置专属中间件，如v2可启用更高频限流策略throttle:100,1，而v1保持throttle:60,1；
5、修改路由后必须执行<strong><font color="green">php think route:clear</font></strong>以清除旧缓存，否则新规则不生效。
二、请求头版本控制
通过解析X-API-Version或Accept请求头识别客户端期望的API版本，保持URL统一性，适用于前后端分离架构及需隐藏版本信息的场景。
1、在config/route.php中配置'api_version' => 'X-API-Version'指定头字段名称；
2、在路由定义中使用->version(['v1', 'v2'])声明支持的版本列表；
3、在全局中间件中读取头字段值，并通过think\Container注入当前版本号供后续调用；
4、在控制器基类initialize()方法中依据版本号动态加载对应服务类，例如app\service\v2\UserService；
5、禁止在中间件中修改原始Request对象的input()数据，否则将破坏日志审计与请求重放校验能力。
三、查询参数版本控制
在URL末尾添加?version=v1形式的参数以指定版本，实现成本低且无需修改路由配置，适用于灰度发布或临时兼容场景，但存在缓存与监控隔离缺陷。
1、在基础控制器initialize()方法中调用input('version')获取版本标识；
2、校验参数是否属于预设合法值（如v1或v2），非法时立即返回<strong><font color="green">400 Bad Request</font></strong>并终止执行；
3、依据版本号初始化不同的数据验证器类，例如app\validate\v2\UserCreate；
4、在JSON响应体中显式包含version字段，格式为{"version":"v1","data":{}}；
5、禁止将该方式用于生产环境长期维护，因CDN与浏览器会将/user?version=v1和/user?version=v2视为同一缓存键。
四、子域名版本控制
利用DNS子域名（如v1.api.example.com）映射到同一应用的不同入口或配置，物理隔离性强，便于运维与监控，但需额外Web服务器与DNS配合。
1、在Nginx或Apache中将各子域名指向同一ThinkPHP应用根目录；
2、在public/index.php入口文件中读取$_SERVER['HTTP_HOST']并提取子域名部分；
3、根据子域名设置运行时常量APP_VERSION，例如define('APP_VERSION', 'v1');；
4、在数据库连接、缓存驱动等配置文件中使用APP_VERSION动态加载对应策略；
5、禁止在子域名方案中叠加路径前缀（如v1.api.example.com/v1/user），否则造成路径冗余与语义冲突。
五、服务层抽象版本控制
在业务逻辑层构建可插拔的版本适配器，将接口契约与具体实现解耦，支持运行时切换版本策略，适合高复杂度、多租户或需热切换版本的系统。
1、定义统一接口契约，例如app\contract\UserServiceInterface；
2、为各版本实现独立服务类，如app\service\v1\UserService与app\service\v2\UserService，均实现该接口；
3、在控制器中通过工厂模式加载服务：$service = service("User", request()->param('version', 'v1'));；
4、使用class_exists()校验目标类是否存在，不存在时抛出<strong><font color="green">400 Bad Request</font></strong>而非触发ClassNotFoundException；
5、禁止将版本判断逻辑写入控制器构造函数或基类__construct()，否则会导致所有请求强制加载全部版本服务类，引发资源浪费。
