自定义 cast 类必须实现 castsattributes 接口，否则报错；$casts 配置须用 ::class 语法；带参 cast 需通过 castable 接口 + castusing() 实现；cast 必须无状态、不依赖模型关系或外部副作用。
自定义 Cast 类必须实现 CastsAttributes 接口
直接写个普通类当 Cast 会报错：Class "App\Casts\CustomJson" is not a valid cast。Laravel 要求所有自定义 Cast 必须显式声明可被识别——要么实现 Illuminate\Contracts\Database\Eloquent\CastsAttributes 接口，要么继承 Cast 抽象类（后者已不推荐，接口更清晰）。
常见错误包括：
- 漏掉
implements CastsAttributes，只写了个空类 - 写了
get()但没写set()，或方法签名参数顺序/类型不对（比如$key必须是string） -
set()方法返回非string或null，Eloquent 会静默丢弃字段值，不报错也不存库
$casts 数组里必须用 ::class 语法
模型中配置时，$casts 的值必须是类的完整命名空间 + ::class，不是字符串路径、不是 new 实例、也不是裸类名。
正确写法：'metadata' => CustomJson::class
错误写法举例：
-
'metadata' => new CustomJson()→ Laravel 尝试调用__toString()，报错 -
'metadata' => CustomJson→ PHP 认为是未定义常量 -
'metadata' => 'App\Casts\CustomJson'→ 虽能运行，但 IDE 无法跳转，重构易出错
带参 Cast 必须用 Castable 接口 + castUsing()
Eloquent 实例化 Cast 时不传任何参数，所以不能靠构造函数注入配置（如 JSON 解码深度、加密密钥）。要支持动态参数，得用 Castable 接口做“代理”。
典型结构：
- 一个
JsonWithDepth类，implements Castable，构造函数接收$depth - 它的
castUsing()方法返回真实 Cast 类名（如JsonDepthCast::class） - 模型中写
'payload' => JsonWithDepth::class，等价于'payload' => JsonWithDepth::castUsing(['depth' => 10])
注意：castUsing() 返回的是字符串类名，不是实例，也不是数组。
Cast 内部必须无状态、不访问模型关系
Cast 实例在模型生命周期中可能被复用，且在模型属性尚未初始化、关系未加载时就被调用。因此：
- 不能在
get()或set()里调用$model->relation，会触发无限递归或空指针 - 不能依赖
$model->id等未保证存在的属性 - 不能写日志、发 HTTP 请求、查数据库——它只负责纯数据转换
- 若需加解密，密钥应硬编码或从 config 取，而非从模型某个字段读取
最易被忽略的一点：Cast 类里不要有私有属性存中间状态，否则多字段共用同一个 Cast 实例时会互相污染。
