为何API Platform部分结果显示IRI，部分显示实体对象？

差异原因 #

出现这种输出差异的核心原因有两点：

1. 关联基数的默认序列化策略：
   API Platform对不同基数的关联有内置序列化规则：
   • 单值关联（比如Order与Company的多对一/一对一关系）：默认序列化完整实体对象，只要关联字段和目标实体属性配置了匹配的序列化组。
   • 多值关联（比如Order与PaymentState的一对多/多对多关系）：默认仅输出IRI列表，这是框架为避免递归序列化、减少数据过载的默认行为。
2. 序列化组的配置匹配：
   你的Company和PaymentState实体都配置了read序列化组，但需确认Order实体中对应的关联字段是否也添加了#[Groups(['read'])]注解。若Order的$company字段加了该注解、而$paymentStates没加，会放大这种差异，但核心原因还是基数策略。

自定义输出形式的方法 #

方法1：通过序列化组强制展开多值关联 #

在Order实体的$paymentStates关联字段上添加#[Groups(['read'])]，同时在Order的ApiResource归一化上下文里启用enable_max_depth避免递归序列化问题：

// Order实体示例
#[ApiResource(
    normalizationContext: [
        'groups' => ['read'],
        'enable_max_depth' => true // 防止循环引用
    ]
)]
class Order
{
    // 单值关联：默认展开
    #[Groups(['read'])]
    private ?Company $company = null;

    // 多值关联：添加Groups后强制展开为完整实体列表
    #[Groups(['read'])]
    #[ORM\OneToMany(mappedBy: 'order', targetEntity: PaymentState::class)]
    private Collection $paymentStates;
}

方法2：使用#[ApiSubresource]灵活控制 #

通过#[ApiSubresource]注解，可默认返回IRI，也允许通过请求参数主动展开实体：

// Order实体的paymentStates字段配置
#[ApiSubresource]
#[Groups(['read'])]
#[ORM\OneToMany(mappedBy: 'order', targetEntity: PaymentState::class)]
private Collection $paymentStates;

• 默认请求：返回IRI列表
• 添加?hydra:expand=paymentStates参数：返回完整实体对象列表

方法3：强制单值关联返回IRI #

如果需要让company也返回IRI而非完整实体，可在关联字段上使用#[ApiProperty(iri: true)]：

// Order实体的company字段配置
#[ApiProperty(iri: true)]
#[Groups(['read'])]
private ?Company $company = null;

内容的提问来源于stack exchange，提问作者Daniel Richter