最稳妥的API版本分组方式是为每个主版本单独建路由文件（如api_v1.php、api_v2.php），在api.php中统一require并使用prefix('api/v1')，避免混写导致路由冲突。
API 路由怎么按版本分组才不冲突
直接在 routes/api.php 里用 Route::prefix('v1') 或 Route::middleware('api.version:v2') 是最稳妥的起点。Laravel 原生不带版本路由中间件，所以别指望 api.version 自动存在——它得自己写。
常见错误是把不同版本路由混在同一个文件、同一级 Route::group 里，结果 v1/users 和 v2/users 实际走的却是同一个控制器方法，只是参数处理逻辑没区分，导致字段缺失或 500 报错。
- 每个主版本建议单独建文件，比如
routes/api_v1.php和routes/api_v2.php，再在api.php中require进来 - 前缀统一用
prefix('api/v1')，别省略api/—— 否则和前端静态资源或 Web 路由容易路径重叠 - 避免用子域名（如
v1.app.test）做版本隔离，调试麻烦、HTTPS 配置复杂、前端发请求也得动态切 host
控制器怎么共享逻辑又保持接口契约稳定
不是所有 v2 接口都要重写控制器。更实际的做法是：v1 控制器只负责响应格式和字段映射，业务逻辑下沉到 Service 层；v2 控制器复用同一 Service，但用不同 Resource 或 Transformer 控制输出结构。
典型翻车点是直接在 UserController@getUsers 里硬编码返回字段，v2 加了个 is_verified 就得改方法、加判断、再测全部分支——其实只要把响应组装交给 UserResourceV1 和 UserResourceV2 就行。
- Resource 类必须严格对应版本，命名带上
V1/V2，别图省事叫UserResource然后靠构造参数切换行为 - 不要在 Resource 里调用模型方法（如
$user->profile->avatar），这会让 N+1 查询隐患在 v2 里突然爆发 - 如果 v2 新增了必须校验的请求参数（比如
country_code），验证规则别塞进FormRequest的通用类，单独建StoreUserRequestV2
数据库迁移和模型字段变更怎么不影响旧版 API
新增字段一般安全，但改类型（比如 string → text）、删字段、加 NOT NULL 约束，会立刻让 v1 接口崩在 Eloquent 的 getAttribute 或序列化阶段。
关键不是“能不能改”，而是“改完 v1 还能不能读写”。Laravel 模型默认对不存在字段返回 null，但某些场景（如 toArray() + JSON 返回）会抛 Illuminate\Database\Eloquent\MissingAttributeException。
- 旧版 API 对应的模型，用
$appends或访问器补字段时，务必包裹if (property_exists($this, 'new_field'))判断 - 迁移里加字段用
nullable()开头，等 v1 流量归零后再通过另一条迁移补默认值或去 null - 不要在模型
$casts里给 v2 新字段加类型转换，v1 请求进来反序列化时可能因类型不匹配静默失败
如何让 Swagger/OpenAPI 文档自动区分版本
用 darkaonline/l5-swagger 的话，它默认只扫 routes/api.php，不会识别 api_v2.php。结果就是 v2 接口在文档里找不到，或者全堆在一个 JSON 里，前端没法选版本。
根本原因在于注解扫描路径和文档分组配置没对齐，不是插件不支持——它支持多文档，但得手动配 paths 和 default_docs。
- 在
config/l5-swagger.php里为每个版本定义独立documentations项，比如'v1'扫routes/api_v1.php，'v2'扫routes/api_v2.php - 控制器方法的
@OA\Get注解里必须显式写tags={"v2-users"}，否则所有接口都归到默认 tag 下，前端无法过滤 - 别信“自动生成版本前缀”的第三方包，它们往往靠正则猜路由，遇到
Route::fallback()或动态绑定就漏掉接口
版本兼容最难的不是写代码，是确认「哪些 v1 用户还没升级」——日志里埋个 X-API-Version 请求头统计，比任何设计模式都管用。没数据支撑的版本下线，迟早要回滚。
