API资源类必须按版本严格隔离，不能复用或继承——v1与v2响应结构差异会破坏客户端契约；需为每版本创建独立类（如V1/UserResource、V2/UserResource），全限定名调用，禁止跨版本引用或继承，复用逻辑应提取为trait。
API 资源类（JsonResource）必须按版本严格隔离，不能复用或继承——v1 和 v2 的响应结构差异会直接破坏客户端契约，而资源类正是这个契约的最终出口。
为什么 Resource 类不能跨版本共享
资源类不是“格式美化层”，而是 API 契约的具象化表达。v1 返回 {data: {...}}，v2 改成 {result: {...}, meta: {...}}，哪怕只改一个字段名或嵌套层级，前端解析就会失败。
- PHPStan、IDE 跳转、
php artisan route:list全部依赖类路径静态可推导；若V1\UserResource和V2\UserResource都叫UserResource且没显式引用全名，工具链会混淆 - 路由里写
return new UserResource($user)时，PHP 默认从当前命名空间找——控制器在V1就加载V1\UserResource，但若控制器逻辑混用或被迁移，极易错绑 - 缓存键（如 ETag、Redis key）常含响应结构哈希，结构不一致却共用资源类会导致缓存污染
如何为每个版本配对独立 Resource 类
资源类路径必须与控制器命名空间严格对齐，且路由定义中显式调用全限定类名。
- 生成命令要带命名空间：
php artisan make:resource V1/UserResource和php artisan make:resource V2/UserResource - 控制器中必须写全路径：
return new \App\Http\Resources\V1\UserResource($user)，别省略\App\Http\Resources\... - 资源类内部禁止引用其他版本的资源（如
V2\UserResource里new V1\PostResource(...)），否则 v1 的 bug 或废弃字段会透传到 v2 - 若 v2 只新增字段，可用
when()条件渲染，但前提是基础结构一致；否则仍需新建类
资源类里哪些逻辑可以安全复用
真正可复用的是与“数据转换无关”的通用能力，比如序列化钩子、条件字段、关联预加载判断——这些应抽成 trait 或辅助函数，而非跨版本继承资源类。
- 推荐做法：定义
App\Support\Resources\HasMetatrait，封装meta数组构造逻辑，在V1\UserResource和V2\UserResource中分别use HasMeta - 绝对禁止：
class V2\UserResource extends V1\UserResource—— 继承会把 v1 的toArray()逻辑、临时兼容 patch、甚至已弃用的with()方法一并带入 v2 - 分页响应也需分版本：v1 用
LengthAwarePaginator+ 自定义toArray()，v2 改用游标分页时，整个ResourceCollection必须重写，不能靠父类 fallback
最易被忽略的一点：资源类的 preserveKeys = true 设置、withoutWrapping() 调用、甚至 JsonResource::wrap() 的全局配置，都可能因版本不同而需要开关——这些不是“配置”，而是契约的一部分，必须随资源类物理隔离。
