使用路由前缀、请求头版本控制和API资源类实现Laravel API版本管理，保持结构清晰与数据兼容，推荐结合默认版本兜底与文档生成。
在构建 Laravel API 时，版本控制是确保前后端兼容、系统可维护的重要环节。优雅地处理 API 版本控制，不仅能避免接口变更带来的破坏性影响，还能提升团队协作效率。以下是几种 Laravel 中推荐的实践方式。
使用路由前缀进行版本划分
最常见也最清晰的方式是通过路由前缀来区分 API 版本。Laravel 的路由系统天然支持前缀配置，可以将不同版本的接口隔离在独立的命名空间中。
在 routes/api.php 中，你可以这样组织：
// v1 版本
Route::prefix('v1')->group(function () {
Route::apiResource('posts', 'V1\PostController');
});
// v2 版本
Route::prefix('v2')->group(function () {
Route::apiResource('posts', 'V2\PostController');
});
对应的控制器放在 app/Http/Controllers/V1 和 app/Http/Controllers/V2 目录下，结构清晰，便于维护。
通过请求头传递版本信息
部分项目希望 URL 保持简洁，不暴露版本号。这时可以通过自定义请求头（如 Accept 或自定义头）来指定版本。
例如，客户端发送请求时设置：
Accept: application/vnd.myapp.v2+json
在 Laravel 中，可以通过中间件解析该头部，并动态绑定到对应的服务或控制器。
创建一个中间件 HandleApiVersion：
public function handle($request, $next)
{
$version = 'v1';
if ($request->header('Accept')) {
if (str_contains($request->header('Accept'), 'v2')) {
$version = 'v2';
}
}
// 将版本注入请求，后续逻辑可据此判断
$request->attributes->set('api_version', $version);
return $next($request);
}
然后根据 $request->attributes->get('api_version') 动态调用不同服务层或资源类。
使用 API 资源类（API Resources）做数据适配
Laravel 的 ApiResource 是实现版本兼容的关键工具。不同版本的接口可能需要返回不同结构的数据，利用资源类可以轻松做到“同一模型，多种输出”。
例如：
// v1 返回简单字段
class V1\PostResource extends JsonResource
{
public function toArray($request)
{
return [
'title' => $this->title,
'content' => $this->content,
];
}
}
// v2 增加作者信息
class V2\PostResource extends JsonResource
{
public function toArray($request)
{
return [
'title' => $this->title,
'content' => $this->content,
'author' => $this->user->name,
];
}
}
控制器中根据版本选择对应资源类，实现平滑过渡。
文档与默认版本兜底
无论采用哪种方式，建议明确设定一个默认版本（如 v1），防止客户端未传版本时出错。同时配合 Swagger/OpenAPI 或 Insomnia 等工具为每个版本生成独立文档，方便前端查阅。
可以在中间件或路由层面拦截无效版本请求，返回 400 Bad Request 或 415 Unsupported Media Type，提示用户升级。
基本上就这些。关键是保持结构清晰、版本隔离、数据兼容。Laravel 提供了足够灵活的机制，只要约定好规范，就能做到既优雅又实用。
