深入理解API Platform中的资源嵌套与序列化组：解决IRI返回问题-php教程-PHP中文网

深入理解API Platform中的资源嵌套与序列化组：解决IRI返回问题

本文深入探讨了symfony api platform中，即使正确配置了序列化组（groups）注解，关联实体仍以iri（国际化资源标识符）形式而非完整对象返回的常见问题。通过分析`normalizationcontext`与`@groups`注解的工作机制，本文将揭示导致此行为的根源，并提供两种有效的解决方案：移除关联实体的`normalizationcontext`或为其定义独立的序列化组，从而实现期望的资源嵌套输出。

在开发API时，我们经常需要返回包含关联数据的复杂资源。Symfony的API Platform框架结合了Doctrine ORM和Symfony Serializer组件，提供了强大的功能来构建RESTful API。其中，序列化组（Serialization Groups）是控制API响应内容的关键机制。然而，开发者有时会遇到一个困惑：即使为关联实体设置了正确的序列化组，API响应中却依然返回关联资源的IRI，而非其完整数据。本文将详细解析这一问题，并提供解决方案。

问题场景描述

假设我们有两个实体：AUDField（字段）和 AUDFieldType（字段类型），一个 AUDField 关联一个 AUDFieldType。我们希望在获取 AUDField 资源时，其关联的 AUDFieldType 能够作为嵌套对象被完整序列化，而不是仅仅返回一个IRI。

以下是初始的实体定义：

AUDField 实体

<?php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;

/**
 * @ApiResource(
 *     normalizationContext={"groups"={"field:read"}},
 * )
 * @ORM\Entity(repositoryClass="App\Repository\AUDFieldRepository")
 * @ORM\Table(name="aud_field")
 */
class AUDField
{
    /**
     * @ORM\Id
     * @ORM\GeneratedValue
     * @ORM\Column(type="integer")
     * @Groups("field:read")
     */
    private $id;

    /**
     * @ORM\Column(type="string", length=255, unique=true)
     * @Groups({"field:read"})
     */
    private $name;

    // ... 其他属性和方法 ...

    /**
     * @ORM\ManyToOne(targetEntity=AUDFieldType::class)
     * @ORM\JoinColumn(nullable=false)
     * @Groups({"field:read"}) // 期望通过此组序列化AUDFieldType
     */
    private $type;

    // ... getters and setters ...
}

登录后复制

AUDFieldType 实体

<?php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;

/**
 * @ApiResource(normalizationContext={"groups"={"field:read"}}) // 注意这里的normalizationContext
 * @ORM\Entity(repositoryClass="App\Repository\AUDFieldTypeRepository")
 * @ORM\Table(name="aud_field_type")
 */
class AUDFieldType
{
    /**
     * @ORM\Id
     * @ORM\GeneratedValue
     * @ORM\Column(type="integer")
     * @Groups({"field:read"}) // 期望在field:read组中序列化id
     */
    private $id;

    /**
     * @ORM\Column(type="string", length=100)
     * @Groups({"field:read"}) // 期望在field:read组中序列化name
     */
    private $name;

    // ... getters and setters ...
}

登录后复制

当我们请求 http://127.0.0.1:8000/api/field/1 时，预期的结果是 type 属性包含 AUDFieldType 的完整对象数据。然而，实际的API响应却如下所示：

{
    "@context": "/api/contexts/AUDField",
    "@id": "/api/field/1",
    "@type": "AUDField",
    "id": 1,
    "name": "Identifiant",
    "specifications": {
        "minlength": 4
    },
    "type": "/api/fieldtype/1", // 仍然是IRI
    "attributesTypes": [
        "/api/attributetype/1"
    ]
}

登录后复制

type 属性返回了一个IRI (/api/fieldtype/1)，而不是一个包含 id 和 name 的嵌套对象。

问题根源分析

API Platform在处理资源序列化时，遵循一套特定的逻辑。当一个实体（例如 AUDField）引用另一个实体（AUDFieldType）时，API Platform默认的行为是返回被引用实体的IRI。这是为了避免深度嵌套和循环引用，同时提供一种轻量级的引用方式。

要实现资源嵌套，我们需要依赖Symfony Serializer的序列化组功能。在 AUDField 实体中，我们在 $type 属性上添加了 @Groups({"field:read"})，这表明当 AUDField 在 field:read 组中被序列化时，应该尝试序列化其关联的 AUDFieldType 对象。同时，在 AUDFieldType 实体内部，其 id 和 name 属性也标记了 @Groups({"field:read"})，这告诉序列化器当 AUDFieldType 在 field:read 组中被序列化时，这些属性应该被包含。

问题出在 AUDFieldType 实体顶部的 @ApiResource 注解中的 normalizationContext 配置：

/**
 * @ApiResource(normalizationContext={"groups"={"field:read"}}) // 这一行是关键
 * @ORM\Entity(repositoryClass="App\Repository\AUDFieldTypeRepository")
 * @ORM\Table(name="aud_field_type")
 */
class AUDFieldType

登录后复制

这里的 normalizationContext={"groups"={"field:read"}} 意味着当 AUDFieldType 作为顶级资源 被请求时，它会使用 field:read 组进行序列化。当API Platform尝试序列化 AUDField 中的 $type 属性时，它会检查 AUDFieldType 是否是一个API资源，并且是否定义了自己的 normalizationContext。如果 AUDFieldType 自身也定义了 normalizationContext 并且与父资源（AUDField）的序列化组重叠，API Platform可能会默认将其视为一个独立的、可单独访问的资源，从而返回IRI以保持一致性或避免潜在的循环引用问题。

AI建筑知识问答

用人工智能ChatGPT帮你解答所有建筑问题

查看详情

简而言之，AUDFieldType 上的 normalizationContext 告诉API Platform，AUDFieldType 资源本身应该如何被序列化。当父资源试图嵌套它时，这个独立的 normalizationContext 可能会干扰嵌套行为，导致API Platform选择返回IRI。

解决方案

解决此问题的关键在于正确管理关联实体的 normalizationContext。我们有两种主要策略：

方案一：移除关联实体的 normalizationContext (推荐)

如果 AUDFieldType 实体主要通过其他实体（如 AUDField）进行嵌套暴露，并且不打算作为具有特定默认序列化组的顶级资源被直接访问，那么我们可以移除其 @ApiResource 注解中的 normalizationContext。

修改 AUDFieldType 实体：

<?php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;

/**
 * @ApiResource() // 移除 normalizationContext
 * @ORM\Entity(repositoryClass="App\Repository\AUDFieldTypeRepository")
 * @ORM\Table(name="aud_field_type")
 */
class AUDFieldType
{
    /**
     * @ORM\Id
     * @ORM\GeneratedValue
     * @ORM\Column(type="integer")
     * @Groups({"field:read"})
     */
    private $id;

    /**
     * @ORM\Column(type="string", length=100)
     * @Groups({"field:read"})
     */
    private $name;

    // ... getters and setters ...
}

登录后复制

解释： 移除 AUDFieldType 上的 normalizationContext 后，当 AUDField 在 field:read 组中被序列化并尝试嵌套 AUDFieldType 时，API Platform会根据 AUDFieldType 内部属性上定义的 @Groups({"field:read"}) 注解来序列化其内容。由于 AUDFieldType 不再声明自己作为顶级资源时默认使用 field:read 组，API Platform会更倾向于将其作为嵌套对象进行序列化。

方案二：为关联实体使用独立的序列化组

如果 AUDFieldType 既需要作为嵌套对象被访问，也需要作为顶级资源（例如 /api/fieldtypes/1）被直接访问，并且希望在直接访问时有特定的序列化行为，那么我们应该为其定义一个独立且不冲突的 normalizationContext 组。

修改 AUDFieldType 实体：

<?php

namespace App\Entity;

use ApiPlatform\Core\Annotation\ApiResource;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Serializer\Annotation\Groups;

/**
 * @ApiResource(normalizationContext={"groups"={"field_type:read"}}) // 使用独立的组
 * @ORM\Entity(repositoryClass="App\Repository\AUDFieldTypeRepository")
 * @ORM\Table(name="aud_field_type")
 */
class AUDFieldType
{
    /**
     * @ORM\Id
     * @ORM\GeneratedValue
     * @ORM\Column(type="integer")
     * @Groups({"field:read", "field_type:read"}) // 两个组都包含此属性
     */
    private $id;

    /**
     * @ORM\Column(type="string", length=100)
     * @Groups({"field:read", "field_type:read"}) // 两个组都包含此属性
     */
    private $name;

    // ... getters and setters ...
}

登录后复制

解释： 通过为 AUDFieldType 定义一个独立的 normalizationContext 组（例如 field_type:read），我们明确区分了其作为顶级资源时的序列化行为。同时，其属性上的 @Groups({"field:read", "field_type:read"}) 确保了在 AUDField 的 field:read 组中嵌套时，AUDFieldType 的 id 和 name 属性依然能够被序列化。这种方法提供了更大的灵活性，因为它允许 AUDFieldType 拥有两种不同的序列化视图：一种用于嵌套，一种用于直接访问。

预期结果

无论采用哪种方案，重新部署并请求 http://127.0.0.1:8000/api/field/1 后，你将获得期望的嵌套资源输出：

{
    "@context": "/api/contexts/AUDField",
    "@id": "/api/field/1",
    "@type": "AUDField",
    "id": 1,
    "name": "Identifiant",
    "specifications": {
        "minlength": 4
    },
    "type": { // 嵌套对象
        "@id": "/api/field_types/1", // 即使是嵌套，API Platform也可能添加@id，但内容已是完整对象
        "@type": "AUDFieldType",
        "id": 1,
        "name": "Text"
    },
    "attributesTypes": [
        "/api/attributetype/1"
    ]
}

登录后复制

请注意，即使是嵌套对象，API Platform也可能为其添加 @id 和 @type 属性，这是其LDAP和Hydra规范的一部分，表示这是一个可独立寻址的资源。

总结与注意事项

@Groups 注解：用于标记实体属性，指定在哪些序列化组中该属性应该被包含。
normalizationContext (在 @ApiResource 中)：定义了当该实体作为顶级资源被请求时，默认应该使用哪些序列化组。
IRI vs. 嵌套对象：当API Platform在序列化一个父资源时遇到关联子资源，它会检查子资源是否也是一个 @ApiResource。如果子资源有自己的 normalizationContext 且与父资源的序列化组存在潜在冲突或重叠，API Platform可能会优先返回IRI。
最佳实践：
- 对于主要作为嵌套对象存在的关联实体，如果不需要作为顶级资源进行特定组的序列化，移除其 @ApiResource 中的 normalizationContext 是最简洁的方案。
- 如果关联实体既需要作为嵌套对象，又需要作为独立资源提供不同视图，则应为其 normalizationContext 定义一个独立的序列化组，并在属性上同时标记所有适用的组。
- 仔细规划你的序列化组，避免命名冲突和不必要的重复，这将有助于API Platform正确地序列化你的资源。