Hyperf 3.1 模型序列化失败的根本原因是框架默认不调用 JsonSerializable::jsonSerialize()，其 toJson() 和 toArray() 完全忽略该接口；正确做法是使用 JsonDeSerializable 接口或手动 json_encode() 并预加载关联。
Hyperf 3.1 中模型序列化失败，**根本原因不是没实现 JsonSerializable，而是默认未启用该接口的自动支持，且框架内置的序列化逻辑会绕过它**。直接补上接口声明不会生效，必须配合手动触发或配置调整。
Hyperf 3.1 默认不调用 JsonSerializable::jsonSerialize()
Hyperf 的 Model 类继承自 Hyperf\Database\Model\Model，其 toArray() 和 toJson() 方法默认走的是属性遍历 + $casts 转换流程，**完全忽略 JsonSerializable 接口**。即使你实现了该接口，json_encode($model) 也不会调用它——PHP 只在显式使用 json_encode() 且对象未重写 __toString() 时才检查该接口，而 Hyperf 的响应层通常先调用 toJson()，再交给 Swoole 响应，中间断开了这个链路。
- 验证方式：在模型中加
var_dump('jsonSerialize called');，实际请求返回里看不到输出 - 本质是框架封装层级太深，
json_encode()没被直接调用 - Hyperf 官方文档未说明此限制，容易误以为“实现即生效”
正确做法：用 toArray() + 手动 json_encode() 强制走 JsonSerializable
若你坚持用 JsonSerializable（比如需要深度定制字段、动态过滤、嵌套关系处理），必须绕过框架的 toJson()，改用原生 JSON 编码：
- 在 Controller 中不要写
return $model;或return $model->toJson(); - 改为
return json_encode($model, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES); - 此时 PHP 会检测到
JsonSerializable并调用jsonSerialize() - 注意：需自行处理 HTTP 头（如
Content-Type: application/json），或包裹进Response对象
示例：
将一个或多个视频上传至YouTube。当用户想“上传到YouTube”“发YouTube”“批量上传”“upload to YouTube”“post videos to YouTube”或发布到YouTube时使用此技能。
use Hyperf\HttpServer\Contract\ResponseInterface;
public function show(ResponseInterface $response)
{
$user = User::find(1);
return $response->json(json_encode($user, JSON_UNESCAPED_UNICODE));
}
更推荐方案：用 Hyperf\Contract\JsonDeSerializable 替代
Hyperf 自己提供的 JsonDeSerializable 接口才是为框架深度集成设计的，它会在 toArray()、toJson()、fill() 全流程生效，无需手动干预编码流程：
- 实现
jsonSerialize()方法，返回要序列化的数组结构 - 该方法会被
Model::toArray()自动调用（Hyperf 3.1+ 已支持） - 比原生
JsonSerializable更可靠，兼容$casts、访问器（getXXXAttribute）、隐藏字段（$hidden）等机制 - 反序列化（
fromArray()）也一并支持，适合微服务间数据交换场景
示例：
use Hyperf\Contract\JsonDeSerializable;
class User extends Model implements JsonDeSerializable
{
public function jsonSerialize(): array
{
return [
'id' => $this->id,
'name' => $this->name,
'created_at' => $this->created_at?->toDateTimeString(),
];
}
}
容易忽略的关键点：序列化上下文丢失与循环引用
无论用哪种方式，Hyperf 模型常带关联关系（with()），而 JsonSerializable 或 JsonDeSerializable 默认不处理加载状态。如果模型未预加载关联，jsonSerialize() 里访问 $this->posts 会触发懒加载，但此时 DB 连接可能已关闭（Swoole 协程环境下），导致空数组或异常。
- 务必在查询时用
with('posts')预加载，不要依赖运行时懒加载 - 避免在
jsonSerialize()中调用未定义的访问器或触发新查询 - 若需条件序列化（如仅对 API 用户暴露邮箱），别在方法里硬编码判断，应通过请求上下文注入，否则单元测试难覆盖
