Laravel 10 默认无法自动提取 API Resource 响应字段，需显式添加 @transformer 标签才能解析 toArray() 等方法；Resource 动态逻辑（如 whenLoaded）和中间件影响导致静态分析失效，必须配合 @responseField 手动声明条件字段以保障文档准确性。
Laravel 9 和 Laravel 10 在 API 资源层（API Resources）的文档生成能力上存在实质性断层：Laravel 9 可部分识别 Resource 类结构，而 Laravel 10 默认无法提取其响应字段，除非配合特定注释或配置。这不是功能退化，而是框架抽象层级变化导致工具链适配滞后。
Resource 类不再自动映射为响应结构
Laravel 9 中，主流文档工具（如 Scribe）能通过反射 toArray() 方法粗略推导响应字段，尤其当 Resource 继承自 JsonResource 且未重写 with() 或 additional() 时，有一定可用性。Laravel 10 则因 Eloquent Resource 的封装更彻底（例如支持 resolve() 动态字段、whenLoaded() 条件加载），导致静态分析失效——工具读不到运行时才确定的字段，直接跳过或生成空响应体。
- 典型表现：Laravel 10 下
UserResource::collection($users)返回的文档中，“data”数组显示为array<object></object>，无具体字段说明 - 根本原因：Scribe 的
GetFromResponseTag策略依赖控制器返回值类型提示或@response注释，不主动解析 Resource 类内部逻辑
必须显式使用 @transformer 标签才能激活 Resource 解析
Laravel 10 中，Scribe 仅在路由方法或控制器动作上标注 @transformer 时，才会加载并分析对应 Resource 类的 toArray() 和 with() 方法，进而生成字段表。该标签不是可选增强，而是必要开关。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- 正确写法：
/** * @transformer \App\Http\Resources\UserResource */
- 若 Resource 带泛型（如
UserResource::collection()），需额外加@transformerCollection标签 - 不写标签 → 工具跳过 Resource，仅靠
@response手动补全，易与实际输出脱节
中间件与 Resource 封装的耦合影响文档准确性
Laravel 10 移除了 RouteServiceProvider 的默认命名空间，同时强化了中间件对请求生命周期的控制。这导致两个连锁问题影响文档生成：
- 带
auth:sanctum或throttle的路由，若未在文档配置中启用中间件上下文策略（RequestContextStrategy），Scribe 会以“未认证状态”模拟响应，Resource 中的when()字段（如仅登录用户可见的email）将被忽略 - Resource 内部调用
$this->resource->relationLoaded('posts')等运行时判断，在文档生成阶段无法执行，必须靠@responseField显式声明条件字段及示例值
FormRequest 验证规则仍可自动提取，但与 Resource 脱钩
Laravel 10 保持对 FormRequest 的良好支持：Scribe 能完整读取 rules() 并生成请求参数表。但验证规则和 Resource 响应之间不再自动关联——即使请求字段名与 Resource 输出字段一致（如 name），工具也不会跨类建立映射。
- 需人工维护一致性：比如
StoreUserRequest中'name' => 'required|string'，应在UserResource对应字段旁加@responseField name string required - 避免字段名拼写差异（如
user_namevsname），否则文档与接口实际行为错位
