ThinkPHP 6.1 分布式接口版本管理核心是路由层剥离、服务层收敛、运行时隔离；通过变量路由统一收口、按版本命名空间加载服务、跨服务透传版本上下文、缓存/日志/Session 加版本前缀实现四重压力下的稳定演进。
ThinkPHP 6.1 在分布式架构下做接口版本管理，核心不是堆服务或改网关，而是让版本逻辑在路由层剥离、在服务层收敛、在运行时隔离。它必须同时扛住多实例部署、跨服务调用、缓存共享和日志可追溯这四重压力。
路由层：用变量分组统一收口，不写死 v1/v2
别在 route.php 里逐条写 Route::get('api/v1/user', ...) —— 分布式环境下维护成本爆炸，且无法统一拦截非法版本。
- 用前置分组 + 可选变量路由，把版本号作为路径参数提取出来：
Route::group(['prefix' => 'api'], function () {
Route::rule(':version// ', 'api/:module/:action')
->pattern(['version' => 'v[12]']);
}); - :version 不会自动注入控制器，需显式获取：
$version = request()->param('version', 'v1'); - 所有 API 请求都走这一条规则，后续分流全靠 $version 值，便于统一加中间件校验或打标
服务层：按版本命名空间加载，避免 if-else 泛滥
控制器只负责调度，业务逻辑必须下沉到 service 层，并按版本隔离实现。
- 目录结构示例：
app/service/v1/UserService.php
app/service/v2/UserService.php - 控制器中动态加载：
$serviceClass = "app\service\{$version}\UserService";
if (!class_exists($serviceClass)) {
throw new HttpException(400, 'Unsupported API version');
}
$service = app()->make($serviceClass); - v2 可扩展字段、增强校验、兼容旧字段别名；v1 保持最小契约不变，确保老客户端零修改可用
分布式协同：跨服务调用时带版本上下文
当 A 服务调用 B 服务的 /user/info 接口时，若不透传版本，B 服务默认走 v1，可能引发数据结构错配。
立即学习“PHP免费学习笔记（深入）”；
- HTTP 调用方在 Header 中显式携带：
X-Api-Version: v2 或复用 Accept 头：
Accept: application/vnd.example.v2+json - B 服务的版本中间件优先读 Header，Fallback 到 URL 参数，最后才用默认值：
$version = request()->header('X-Api-Version') ?: request()->param('version', 'v1'); - RPC 场景（如 Swoole 微服务）则在请求 payload 中增加 version 字段，服务端统一解析
运行时隔离：避免缓存/日志/Session 混乱
同一套代码部署多个实例，若 runtime、Redis 缓存、Session 共享，v1 和 v2 的缓存键或 session 数据可能互相覆盖。
- 每个版本独占 runtime 目录：
define('RUNTIME_PATH', __DIR__ . '/../runtime-' . $version . '/'); - 缓存 key 加版本前缀：
cache()->set("user_{$uid}_profile_{$version}", $data); - Session 配置中设 prefix：
'prefix' => 'tp61_' . $version . '_'（如 tp61_v2_） - Nginx 日志中记录版本信息，便于问题定位：
log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$http_x_api_version"';
