本文详解 laravel 中如何科学实现 api 路由版本化，包括路由分组、控制器复用策略、文件组织方式及关键注意事项，帮助开发者兼顾向后兼容性与可维护性。
在 Laravel 中进行 API 版本化，核心目标是保障向后兼容、降低维护成本、明确演进边界。你无需为每个版本强制创建全新控制器——是否复用控制器取决于API 行为是否发生实质性变更。
✅ 推荐的版本化结构（基于 RouteServiceProvider）
首先，在 App\Providers\RouteServiceProvider 的 boot() 方法中，按需注册多版本路由文件：
public function boot()
{
$this->configureRateLimiting();
$this->routes(function () {
Route::middleware('web')
->group(base_path('routes/web.php'));
// 原始 v1 路由
Route::prefix('api/v1')
->middleware('api')
->group(base_path('routes/api/v1.php'));
// 新增 v2 路由（独立文件，清晰隔离）
Route::prefix('api/v2')
->middleware('api')
->group(base_path('routes/api/v2.php'));
});
}? 建议将版本路由文件统一放在 routes/api/ 目录下（如 v1.php, v2.php），便于管理与 IDE 导航。
? 控制器复用原则：何时共用？何时拆分？
| 场景 | 是否复用控制器 | 说明 |
|---|---|---|
| 仅新增字段或可选参数（如 v2 返回 updated_at 字段） | ✅ 强烈推荐复用 | 在控制器中通过请求头（Accept: application/vnd.app.v2+json）或路由参数判断版本逻辑，保持单一职责 |
| 接口行为变更（如 /posts 在 v2 中改为分页响应，或认证方式升级） | ⚠️ 可复用但需条件分支 | 使用 request()->route()->getPrefix() 或自定义中间件注入 $version，避免硬编码分支污染业务逻辑 |
| 资源结构/语义彻底重构（如 v2 将 POST /posts 拆为 POST /drafts + PATCH /posts/{id}/publish） | ❌ 应新建控制器（如 V2\PostController） | 避免控制器内充斥 if ($version === 'v2') { ... }，牺牲可读性与测试性 |
示例：在 v2.php 中复用原控制器，但启用版本感知中间件：
// routes/api/v2.php
Route::middleware('api.version:v2')->group(function () {
Route::get('me', [API\UserController::class, 'getUserInfo'])->name('v2.me');
Route::apiResource('posts', API\PostController::class)->only(['index', 'store']);
});// app/Http/Middleware/ApiVersionMiddleware.php
public function handle($request, Closure $next, $version)
{
$request->attributes->set('api_version', $version);
return $next($request);
}? 关键注意事项
- 禁止跨版本共享路由缓存：运行 php artisan route:clear 后，务必分别缓存各版本路由（php artisan route:cache --env=production 默认只处理 api.php；建议配合部署脚本显式清理并重缓存）。
- 文档与测试必须按版本隔离：使用 Laravel Pint + Swagger（如 darkaonline/l5-swagger）时，为 v1 和 v2 分别生成独立 OpenAPI 文档。
- 废弃版本应明确标注：在 v1.php 顶部添加注释 // ⚠️ DEPRECATED: Will be removed after 2025-12-31，并在响应头中返回 Deprecated: true 和 Sunset: Wed, 31 Dec 2025 23:59:59 GMT。
- 绝不混用前缀风格：避免同时存在 api/v1 和 api?version=2 —— 统一采用路径前缀（RESTful 语义清晰、CDN 友好、易于监控）。
✅ 总结
Laravel API 版本化不是“复制粘贴控制器”，而是以路由为边界、以控制器为能力单元、以中间件为策略枢纽的系统工程。优先复用稳定逻辑，隔离破坏性变更；用清晰的文件结构替代隐式判断；让每个版本成为可独立部署、可独立测试、可独立下线的契约单元。
