thinkphp实现api版本控制有五种方式：一、url路径版（如/api/v1/user）；二、请求头版（如x-api-version）；三、查询参数版（?version=v1）；四、子域名版（v1.api.example.com）；五、服务层抽象版（接口契约+适配器）。
如果您在ThinkPHP项目中需要为API接口提供不同版本的支持，则可能是由于业务迭代导致接口参数、返回格式或逻辑发生变更。以下是实现API版本控制的步骤：
一、URL路径版本控制
通过在请求路径中嵌入版本标识（如/api/v1/user），使路由直接区分不同版本，该方式语义清晰、易于理解且兼容性好，同时支持路由缓存与OpenAPI文档自动生成。
1、在route/app.php中使用Route::group()定义静态版本前缀路由组，避免使用变量路由或正则捕获；
2、为每个版本单独声明路由分组，并绑定对应控制器命名空间，例如Route::group('api/v1', function () { Route::get('user', 'v1.User/get'); });；
3、创建严格对应的控制器目录结构，如app/controller/v1/User.php与app/controller/v2/User.php，确保类名与命名空间一致；
4、各版本控制器不得复用同一方法签名逻辑，禁止在方法体内硬编码if ($version === 'v2') {...}分支；
5、每个版本分组应独立绑定中间件，例如v2需JWT鉴权而v1无需时，须显式调用->middleware(JwtAuth::class)链式挂载。
二、请求头版本控制
通过解析自定义HTTP请求头（如X-API-Version）识别客户端期望的API版本，保持URL统一性，适用于前后端分离架构及网关统一转发场景，且不干扰CDN缓存策略。
1、在config/route.php中配置'api_version' => 'X-API-Version'，声明版本头字段名称；
2、在route/app.php中定义路由时使用->version(['v1', 'v2'])标注支持版本，例如Route::get('user/:id', 'User/read')->version(['v1','v2']);；
3、客户端发起请求时必须携带头信息：GET /api/user/1 HTTP/1.1 X-API-Version: v2；
4、框架将依据头值自动匹配对应版本路由规则，未声明版本的请求默认返回404；
5、若需兼容Accept头（如application/vnd.example.v2+json），应在中间件中手动提取并注入Request对象，但不推荐替代X-API-Version主方案。
三、查询参数版本控制
在URL末尾添加?version=v1形式的参数以指定版本，实现成本低且无需修改路由配置，适用于灰度发布、AB测试或临时兼容场景，但存在缓存与监控归类风险。
1、在基础控制器的initialize()方法中调用$this->version = input('version', 'v1');获取参数值；
2、立即校验版本合法性：仅允许v1、v2等预设值，非法时返回400 Bad Request并终止执行；
3、依据$this->version动态加载对应服务类，例如$service = new "app\service\{$this->version}\UserService"();；
4、确保class_exists()检查通过，否则抛出HttpException(400)；
5、在最终JSON响应体中显式包含"version": "v1"字段，便于前端识别实际生效版本。
四、子域名版本控制
利用DNS子域名（如v1.api.example.com）映射到同一应用的不同入口或配置，物理隔离性强，便于运维部署、流量调度与独立监控，适合多团队协作或多租户架构。
1、在Nginx/Apache中将各子域名指向同一ThinkPHP应用根目录，不修改public/index.php路径；
2、在public/index.php入口文件顶部读取$_SERVER['HTTP_HOST']，提取子域名部分；
3、根据提取结果定义全局常量：define('APP_VERSION', 'v1');；
4、在config/目录下按APP_VERSION动态加载不同配置文件，如database_v1.php与database_v2.php；
5、确保各子域名对应的应用日志、缓存、限流规则完全隔离，避免共享runtime/目录引发并发冲突。
五、服务层抽象版本控制
在业务逻辑层构建可插拔的版本适配器，将接口契约与具体实现解耦，支持运行时切换版本策略，避免控制器膨胀为“版本判断器”，提升可测试性与可维护性。
1、定义统一接口契约，如appcontractUserServiceInterface，声明getUser()等核心方法；
2、为各版本实现该接口：app/service/v1/UserService与app/service/v2/UserService；
3、在控制器中通过工厂模式加载：$service = thinkContainer::getInstance()->make(UserServiceInterface::class, ['version' => $version]);；
4、服务类内部处理字段映射、参数校验、响应封装等差异逻辑，控制器仅负责接收请求与返回响应；
5、新增版本时只需实现接口并注册绑定，无需改动路由、控制器或中间件，符合开闭原则。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
