PHP实战保留旧接口 /v1/user，同时提供新接口 /v2/user。

它的本质是通过路由隔离 (Route Isolation)、逻辑解耦 (Logic Decoupling)和适配器模式 (Adapter Pattern)将“稳定的旧契约”与“创新的新逻辑”并行运行。既不让老用户Old Clients因强制升级而崩溃也不让新功能被旧代码的屎山Legacy Code束缚。这是一种用“空间代码冗余换时间迁移窗口”的战略妥协。如果把 API 版本管理比作餐厅菜单迭代/v1/menu老菜单。虽然有些菜做法落后但老顾客习惯了不能突然撤掉否则他们投诉。/v2/menu新菜单。引入了分子料理、健康轻食吸引新顾客也让老顾客有升级的选择。厨房 (Backend)策略 A (独立实现)两个厨师各做各的。简单但浪费人力。策略 B (核心复用)一个主厨负责核心炒菜Service Layer两个助手分别负责摆盘和调味Controller/DTO。这是推荐做法。一、架构设计如何组织代码在 Laravel/ThinkPHP 等现代框架中主要有三种策略1. 路由前缀隔离 (Route Prefixing) -最常用机制在路由文件中定义不同的前缀指向不同的 Controller 或同一 Controller 的不同方法。优点清晰直观URL 语义明确。缺点如果逻辑差异大可能导致 Controller 重复代码多。2. 命名空间隔离 (Namespace Separation)结构App/Http/Controllers/Api/V1/UserController.php App/Http/Controllers/Api/V2/UserController.php优点完全物理隔离V1 的代码烂了不影响 V2。缺点核心业务逻辑如“创建用户”可能需要在两个 Controller 中复制或者抽取到 Service 层。3. 核心逻辑复用 (Service Layer Pattern) -推荐机制Controller (V1/V2)只负责接收请求、参数验证、格式转换、返回响应。Service (UserServiceImpl)包含真正的业务逻辑查库、计算、事务。DTO/Resource负责数据结构的转换。优点DRY (Don’t Repeat Yourself)。业务逻辑只写一次V1 和 V2 只是不同的“展示层”。二、代码实现Laravel 实战示例假设场景V1返回扁平数组字段名为user_name。V2返回嵌套对象字段名为name且增加了avatar字段。1. 路由定义 (routes/api.php)useIlluminate\Support\Facades\Route;// V1 路由组Route::prefix(v1)-group(function(){Route::get(/user/{id},[App\Http\Controllers\Api\V1\UserController::class,show]);});// V2 路由组Route::prefix(v2)-group(function(){Route::get(/user/{id},[App\Http\Controllers\Api\V2\UserController::class,show]);});2. 核心服务层 (App/Services/UserService.php)namespaceApp\Services;useApp\Models\User;classUserService{publicfunctionfindById(int$id):?User{// 核心业务逻辑查询数据库returnUser::findOrFail($id);}publicfunctioncreateUser(array$data):User{// 核心业务逻辑创建用户发送欢迎邮件等returnUser::create($data);}}3. V1 控制器 (App/Http/Controllers/Api/V1/UserController.php)namespaceApp\Http\Controllers\Api\V1;useApp\Http\Controllers\Controller;useApp\Services\UserService;useIlluminate\Http\Request;classUserControllerextendsController{protected$userService;publicfunction__construct(UserService$userService){$this-userService$userService;}publicfunctionshow($id){$user$this-userService-findById($id);// V1 特有的数据格式化returnresponse()-json([code200,data[user_id$user-id,user_name$user-name,// 旧字段名email$user-email// 没有 avatar]]);}}4. V2 控制器 (App/Http/Controllers/Api/V2/UserController.php)namespaceApp\Http\Controllers\Api\V2;useApp\Http\Controllers\Controller;useApp\Services\UserService;useIlluminate\Http\Request;classUserControllerextendsController{protected$userService;publicfunction__construct(UserService$userService){$this-userService$userService;}publicfunctionshow($id){$user$this-userService-findById($id);// V2 特有的数据格式化returnresponse()-json([statussuccess,// 新的状态码风格data[id$user-id,name$user-name,// 新字段名email$user-email,avatar$user-avatar_url??null// 新增字段]]);}} 核心洞察Controller 越薄越好。V1 和 V2 的区别仅在于“输入参数的清洗”和“输出数据的包装”核心逻辑下沉到 Service 层共享。三、数据兼容数据库层面的挑战1. 字段新增场景V2 需要avatar字段。操作直接在数据库表中添加avatar列允许为NULL或有默认值。影响V1 不读取该字段无影响。V2 读取并返回。2. 字段改名/结构变更场景V1 用user_nameV2 用name。操作数据库中保持name列。兼容V1 Controller读取$user-name但在 JSON 中映射为user_name。V2 Controller读取$user-name在 JSON 中映射为name。禁忌不要在数据库中真正重命名列除非你同时修改所有版本的代码并部署。这会导致部署期间的短暂不可用。3. 行为变更场景V1 创建用户时不发送短信V2 要发送。操作错误做法在UserService::createUser中加if ($version v2) sendSms()。这会让核心逻辑污染。正确做法UserService::createUser只做创建。V1 Controller 调用createUser。V2 Controller 调用createUser成功后再调用NotificationService::sendWelcomeSms()。原则侧车模式 (Sidecar Pattern)。新功能作为附加步骤不侵入旧流程。四、退役策略如何优雅地杀死 V1保留旧接口是有成本的维护负担、安全风险。必须制定退役计划。1. 标记弃用 (Deprecation Header)在 V1 的响应头中添加警告returnresponse()-json($data)-header(Deprecated,true)-header(Sunset,Sat, 01 Jan 2027 00:00:00 GMT)// 预计下线时间-header(Link,/api/v2/user/.$id.; relsuccessor-version);作用告诉开发者“这个接口快死了请迁移到 V2。”2. 监控与数据分析动作在 Nginx 日志或 APM 中统计/v1/的流量占比。决策当 V1 流量低于 1% 或仅剩几个内部账号时启动下线流程。3. 沟通与缓冲期通知提前 3-6 个月邮件通知所有 API 使用者。文档在 Swagger/OpenAPI 文档中标记 V1 为 Deprecated并提供 V2 的迁移指南。4. 软下线与硬下线软下线返回 HTTP 410 Gone 或 503但 body 中包含迁移指引。硬下线直接移除路由代码返回 404。 总结原子化“版本共存”全景图维度策略关键点路由前缀隔离(/v1,/v2)URL 清晰便于网关分流代码Controller 分离Service 共享避免逻辑复制保持 DRY数据增量变更映射兼容数据库加列不加改Controller 做映射行为侧车模式新功能外挂不污染旧逻辑退役Header 警告 监控 通知给足缓冲期数据驱动下线终极心法API 版本管理的本质是“契约的神圣性”。一旦发布就是承诺。不要轻易打破它。如果必须改变就创造一个新的契约让旧契约自然老化。别试图修补破船去造一艘新船然后慢慢把乘客转移过去。于稳定中见演进于隔离中见复用以兼容为桥解断裂之牛于系统生命周期中求平滑之真。行动指令检查现状你的项目中是否有混合了 V1/V2 逻辑的臃肿 Controller重构提取核心逻辑到 Service 层。添加 Header在所有旧接口响应中加入Deprecated头。监控配置 Grafana/Prometheus 监控各版本接口的 QPS。思维升级记住代码可以重写但用户的信任一旦破碎很难修复。兼容性是对用户尊重的体现。