如何关闭Laravel API响应中的data外层封装？

本文共计835个文字，预计阅读时间需要4分钟。

在默认情况下，Laravel 的 API 资源（如 `JsonResource` 和 `ResourceCollection`）会将响应数据自动包裹在 `data` 键下。这不是配置项的开关，而是资源类底层的默认行为——您无法通过全局配置一键禁用，必须在资源类内部显式控制。

为什么 withoutWrapping() 不生效？

很多人尝试在控制器或服务提供者里调用 JsonResource::withoutWrapping()，但发现对单个资源实例无效。这是因为该方法只影响 ResourceCollection::collection() 静态调用生成的集合响应，且必须在调用前设置；它对 new UserResource($user) 这类实例化方式完全无作用。

• JsonResource::withoutWrapping() 仅对 UserResource::collection($users) 有效
• 它不改变单个资源实例的 toArray() 行为，也不影响手动 new 的对象
• 若在中间件或控制器中调用，但 collection 方法已在之前执行，就已错过时机

禁用单个资源的 data 包裹

单个资源（如 UserResource）没有内置“取消包裹”机制。它的输出结构完全由 toArray() 返回值决定。所谓“包裹”，其实是 Laravel 在序列化时自动套了一层 ['data' => $array] —— 但这个动作只发生在资源被当作响应返回时，且仅当该资源是 JsonResource 子类的实例（非集合）。

• 真正能绕过包裹的方式，是**不返回资源实例，而直接返回数组或响应对象**：
  return response()->json($user->only(['id', 'name', 'email']));
• 如果仍想用资源类做字段过滤和关系处理，可重写 toResponse() 方法：
  

  public function toResponse($request) { return response()->json($this->toArray($request)); }

• 注意：此举会跳过 Laravel 默认的响应头、状态码继承等逻辑，需自行处理 200 或 404 等状态

禁用资源集合的 data 包裹

资源集合（UserResource::collection($users) 或 UserCollection）默认也套 data，但有更可控的出口。

• 推荐做法：在集合类中重写 toArray()，直接返回扁平数组：
  

  public function toArray($request) { return $this->collection->map(function ($user) use ($request) { return (new UserResource($user))->toArray($request); })->values(); }

• 若用 ResourceCollection 子类（如 UserCollection），也可在构造后调用 withoutWrapping()：
  return (new UserCollection($users))->withoutWrapping();
• 不要混用静态 ::collection() 和实例 withoutWrapping() —— 前者返回的是 ResourceCollection 实例，后者是链式调用，但 UserResource::collection($users)->withoutWrapping() 是合法的

最易被忽略的一点：Laravel 的包裹行为与是否启用 APP_DEBUG、是否使用 api 中间件无关，它只取决于你返回的是资源实例还是普通数组。一旦你开始用资源类，就要接受它默认的封装契约；想彻底摆脱 data，就得放弃“返回资源实例”这个动作本身，或亲手接管序列化流程。