fractal 已弃用且不支持 php 8.1+，推荐改用 thinkphp 6.1+ 原生资源类；若需兼容旧版，可降级 fractal 至 v0.19.2、封装中间件或切换为 symfony/serializer。
如果您在 ThinkPHP 项目中尝试集成 League\Fractal 进行 API 数据结构转换，但遇到兼容性报错或序列化失败，则很可能是由于 Fractal 已被官方弃用且不支持 PHP 8.1+。以下是针对该问题的多种可行集成与替代方案：
一、降级适配（仅限 PHP ≤ 8.0 环境）
此方法适用于仍运行在 PHP 7.4 或 PHP 8.0 的旧版 ThinkPHP 5.1 项目，通过锁定兼容版本绕过 PHP 8.1+ 的迭代器废弃问题。
1、在项目根目录执行 Composer 命令安装指定兼容版本：composer require league/fractal:^0.19.2
2、确认 composer.json 中 "php" 版本约束未高于 8.0
3、在 ThinkPHP 的控制器中手动实例化 Fractal：引入 League\Fractal\Manager 与 League\Fractal\Resource\Collection 类
4、创建 Transformer 类（如 app/transformers/UserTransformer.php），继承 League\Fractal\TransformerAbstract，实现 transform() 方法
5、在控制器中调用：$fractal = new Manager(); $resource = new Collection($users, new UserTransformer()); return json($fractal->createData($resource)->toArray());
二、中间件封装（ThinkPHP 6/8 兼容层）
此方法不依赖 Fractal 运行时，而是将其逻辑封装为 ThinkPHP 原生中间件，在响应前统一处理数据结构，规避自动迭代器调用链。
1、创建中间件类 app/middleware/FractalMiddleware.php，在 handle() 方法中拦截 JSON 响应
2、解析原始响应体为数组，判断是否存在 _fractal 键或自定义标记字段
3、若存在，则动态加载已预编译的 Transformer 实例（使用反射避免 new Transformer() 触发构造器中的过时方法）
4、调用 transform() 方法对数据逐项处理，保留原 Fractal 的字段映射逻辑
5、将处理后数组重新封装为 json() 响应并返回
三、完全迁移至 ThinkPHP 原生资源类（推荐）
ThinkPHP 6.1+ 内置了类似 Laravel Resource 的 think\facade\Json 与可扩展的 think\Response 机制，无需第三方包即可实现条件字段、关系嵌套和分页包装。
1、创建资源类 app/resource/UserResource.php，继承 think\Response
2、重写 output() 方法，在其中定义数据结构：return ['id' => $this->id, 'name' => $this->name, 'email' => $this->when($this->hasEmail(), $this->email)]
3、在控制器中直接返回：return (new UserResource($user))->output();
4、对集合使用 UserResource::collection($users) 并调用 output()
5、如需嵌套关联，可在资源类中调用 $this->relationLoaded('profile') 判断并注入子资源
四、采用 symfony/serializer 替代方案
此方案适用于 ThinkPHP 5.1 或非 Laravel 生态的纯 PHP 项目，利用 Symfony Serializer 的解耦设计与完整 PHP 8.1+ 支持，替代 Fractal 的序列化职责。
1、执行命令安装：composer require symfony/serializer symfony/property-access symfony/yaml
2、在容器中注册序列化器实例，启用 ObjectNormalizer 和 JsonEncoder
3、创建 app/serializer/UserNormalizer.php，实现 NormalizerInterface 接口，定义字段白名单与条件逻辑
4、在控制器中获取序列化器服务，调用 $serializer->normalize($user, 'json', ['groups' => ['api']])
5、使用 JsonEncoder 将归一化结果编码为 JSON 字符串并返回
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
