RESTful API 设计与实现：资源嵌套、IRI 控制与序列化组的精准应用

本文详解 API Platform 中为何同一响应内部分关联字段返回完整对象（如 company），而另一些仅返回 IRI（如 paymentStates），并基于 Symfony Serializer 的 @Groups 机制，说明如何通过正确声明序列化组、导入注解类及配置资源关系，实现对嵌入深度的精确控制。

本文详解 api platform 中为何同一响应内部分关联字段返回完整对象（如 company），而另一些仅返回 iri（如 paymentstates），并基于 symfony serializer 的 @groups 机制，说明如何通过正确声明序列化组、导入注解类及配置资源关系，实现对嵌入深度的精确控制。

在使用 API Platform 构建 RESTful 接口时，一个常见却易被忽视的问题是：同一响应中，不同关联资源呈现形式不一致——有的以完整嵌套对象形式展开（含 @id, @type, 字段数据），有的却仅以字符串 IRI（如 /api/payment_states/10）形式存在。这并非随机行为，而是由 序列化上下文（normalizationContext）与字段级序列化组（@Groups）的协同作用 决定的。

核心原理在于：API Platform 默认对非标量关联属性采用“惰性 IRI 引用”策略，除非显式声明该字段应在当前序列化组中被深度序列化（即展开为对象）。这一行为受两个关键因素控制：

1. 资源类是否启用 normalizationContext 并指定有效 groups；
2. 关联字段是否被 #[Groups(...)] 显式标注，且该组名存在于当前上下文的 groups 数组中。

在你的案例中：

• Company 类正确导入了 use Symfony\Component\Serializer\Annotation\Groups;，因此 #[Groups(["read"])] 生效 → company 字段在 "read" 组下被序列化 → 展开为完整对象；
• PaymentState 类未导入 Groups 注解类，导致 #[Groups(["read", "write"])] 实际被忽略 → 该字段不参与 "read" 序列化组 → API Platform 回退至默认行为：仅输出 IRI。

✅ 正确写法（以 PaymentState.php 为例）：