必须写自定义Normalizer当内置Normalizer无法处理特殊数据结构时，如第三方SDK对象无getter、私有属性不可反射、需扁平化嵌套或运行时计算字段；严禁用json_encode/decode替代，因其丢失类型、跳过私有属性且不支持循环引用。
什么时候必须写自定义 Normalizer
当内置的 ObjectNormalizer、DateTimeNormalizer 或 BackedEnumNormalizer 无法处理你的数据结构时，就得自己写。典型场景包括：第三方 SDK 返回的对象没有 getter 方法、属性全是私有且无反射访问权限、需要把嵌套对象“拍平”成单层键值对（比如 user.profile.name → profile_name）、或字段值需运行时计算（如拼接全名、生成签名哈希）。
别指望靠 json_decode(json_encode($obj)) 搞定——它会丢掉类型、跳过私有属性、不触发任何上下文逻辑，而且在循环引用时直接崩溃。
实现 NormalizerInterface 的关键三步
自定义 Normalizer 必须实现 NormalizerInterface，重点不是写多复杂，而是守住两个方法的契约：
-
supportsNormalization()要严格匹配目标类或接口，避免误判。例如判断是否为OAuthUserResponse实例，别用is_object()这种宽泛条件 -
normalize()返回值只能是数组、标量、null或\ArrayObject；不能返回对象，否则后续Encoder会报TypeError: Expected array, got object - 如果要支持反序列化（即
denormalize()），还得同时实现DenormalizerInterface，但多数只转出不转回，可先不实现
示例骨架：
class OAuthUserNormalizer implements NormalizerInterface
{
public function supportsNormalization(mixed $data, ?string $format = null, array $context = []): bool
{
return $data instanceof OAuthUserResponse;
}
public function normalize(mixed $object, ?string $format = null, array $context = []): array
{
return [
'id' => $object->getId(),
'email' => $object->getEmail() ?? '',
'full_name' => trim($object->getFirstName().' '.$object->getLastName()),
];
}
}
注册与优先级陷阱
自定义 Normalizer 必须作为服务注册，并打上 serializer.normalizer 标签，否则 Serializer 根本看不到它：
- 在
config/services.yaml中加：App\Serializer\OAuthUserNormalizer: tags: [{ name: 'serializer.normalizer' }] - 默认所有 Normalizer 无显式优先级，
supportsNormalization()返回true就会被选中。如果多个 Normalizer 都支持同一类型，Symfony 会取第一个匹配的——顺序由服务加载顺序决定，不可靠 - 解决冲突：给服务加
priority属性，数值越大越优先。例如：tags: [{ name: 'serializer.normalizer', priority: 100 }]确保它排在ObjectNormalizer（默认 priority 0）前面
漏掉 priority 是调试时最常卡住的地方：你改了代码，缓存清了，日志也显示服务加载成功，但 normalize() 就是不进断点——大概率是被别的 Normalizer 截胡了。
context 参数才是真正的控制中枢
$context 数组不是摆设，它是传递行为开关的唯一通道。常见用法：
- 通过
groups控制字段粒度：['groups' => ['api:read']]，再配合实体上的#[Groups(['api:read'])]注解 - 用
max_depth防止无限递归：['max_depth' => 2]，尤其在处理 Doctrine 关联对象时 - 传入运行时参数：
['include_sensitive' => true]，然后在normalize()里做分支判断 - 绕过循环引用检查：
['circular_reference_handler' => fn($obj) => $obj->getId()]，比全局配置更精准
别在 Normalizer 内部硬编码业务逻辑分支，所有可变行为都应从 $context 读取。这样同一个 Normalizer 才能复用于 API 响应、日志记录、队列消息等不同场景。
真正难的不是写完一个 Normalizer，而是让它在嵌套调用中仍保持行为一致——比如你自定义的 UserNormalizer 里调用了 $this->serializer->normalize($user->getProfile(), ...)，这时传进去的 $context 必须显式透传，否则子层级就丢失了分组或深度限制。
