laravel api 版本应放在url路径中（如/api/v1/users），因accept头存在调试、缓存、工具链支持等硬伤；需用route::prefix()与namespace()物理隔离版本路由，控制器按语义断裂程度决定是否新建，资源与错误响应须严格版本对齐。
绝大多数 Laravel 项目应把 API 版本号放在 URL 路径中，比如 /api/v1/users。这不是权衡取舍的结果，而是调试、缓存、日志、CDN 和路由控制全部指向同一个结论：路径最稳。
为什么别用 Accept 头做版本路由
Accept 头（如 application/vnd.app.v2+json）在理论 REST 场景下成立，但实际落地时会立刻暴露三类硬伤：
- Postman、curl、Swagger UI 默认不带该头，每次测试都得手动补，漏一次就落到 v1 或 500
- Nginx、Cloudflare 等中间层可能 strip 或 normalize
Accept，导致路由匹配失效，且问题难以复现 - Laravel 的
route:cache不缓存基于 header 的匹配逻辑，v2 请求实际走的是未缓存的慢路径
更关键的是：php artisan route:list 完全看不到版本区分，IDE 跳转、PHPStan 分析、Git blame 全部失焦。
Route::prefix() + namespace() 是唯一可控组合
靠中间件动态切换命名空间（比如 app()->bind('UserController', ...)）看似灵活，实则破坏静态分析和工具链。正确做法是路由层物理隔离：
Route::prefix('api')->group(function () {
Route::prefix('v1')
->namespace('App\Http\Controllers\V1')
->middleware(['api', 'throttle:60,1'])
->group(base_path('routes/api/v1.php'));
Route::prefix('v2')
->namespace('App\Http\Controllers\V2')
->middleware(['api', 'throttle:100,1'])
->group(base_path('routes/api/v2.php'));
});
注意两点：
-
v1和v2必须是字面量前缀，禁止写成{version}—— 否则Route::prefix()的中间件绑定和命名空间就失效 - 每个版本路由文件（
routes/api/v1.php）里不要再套Route::prefix('v1')，否则变成/api/v1/v1/...
控制器要不要新建？看语义是否断裂
不是“有改动就要新建”，而是“行为契约变了才必须隔离”：
- v2 只新增字段、微调分页参数 → 复用
V1\UserController，在方法内轻量适配（如if ($request->version === 'v2') { ... }） - v2 改认证方式、重定义资源关系、变更幂等性规则 → 必须新建
V2\UserController，否则git log和权限审计无法追溯 - 绝对禁止
V2\UserController extends V1\UserController—— 继承会把 v1 的 bug、临时 patch、废弃逻辑一并继承过去
共享逻辑下沉到 App\Services\UserService 或 App\Http\Requests\V2\StoreUserRequest，控制器只做协调，不藏业务规则。
错误响应和资源类必须严格对齐版本
v2 请求返回 v1 格式的 422 错误，前端会解析失败；v1 请求拿到 v2 的 UserV2Resource，字段缺失直接报错。必须做到：
- 每个版本路由组绑定专属异常渲染器（在
app/Exceptions/Handler.php中按$request->route()->getPrefix()分流） - 控制器返回统一用对应版本 Resource：
return new V2\UserResource($user)，别用new UserResource($user)然后靠构造函数判断 - 弃用旧版本时，不在路由里删掉，而是在对应控制器中返回
response()->json(['error' => 'deprecated'], 410)->header('Deprecation', 'true')
最容易被忽略的是 OPTIONS 预检请求 —— 如果你用了自定义中间件解析版本，它必须显式放行 OPTIONS，否则 CORS 直接失败，且错误日志里根本不会提示版本问题。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
