API-Platform中如何正确更新关联实体

2025-05-26 19:33:59作者：秋泉律Samson

api-platform/api-platform: API Platform是一个基于Symfony和PHP构建的现代化API开发框架，旨在简化创建高性能、易于维护的REST和GraphQL APIs的过程。它支持Hydra（JSON-LD）和Swagger规范，内置了对数据过滤、排序、分页等功能的支持，并可轻松与 Doctrine ORM 或 MongoDB 集成。

项目地址：https://gitcode.com/gh_mirrors/ap/api-platform

在使用API-Platform进行RESTful API开发时，处理关联实体的更新操作是一个常见但容易出错的问题。本文将深入探讨在API-Platform中正确更新关联实体的方法。

问题背景

当我们需要更新一个主实体及其关联的子实体时，API-Platform的默认行为可能会导致意外的结果。例如，当我们尝试通过PATCH请求更新联系人(Contact)实体中的某个电子邮件(Email)子实体时，系统可能会删除所有现有的电子邮件并创建新的记录，而不是按预期只更新指定的电子邮件。

错误尝试分析

开发者通常会尝试以下两种方式更新关联实体：

仅包含子实体的ID和需要更新的字段：

{
    "emails": [
        {
            "id": 20,
            "address": "mail20_edited@example.com"
        }
    ]
}

使用子实体的IRI(国际资源标识符)：

{
    "emails": [
        {
            "@id": "/emails/20",
            "address": "mail20_edited@example.com"
        }
    ]
}

然而，这两种方式都会导致系统删除所有现有电子邮件并创建新记录，这显然不是我们想要的结果。

正确解决方案

经过实践验证，正确的做法是使用PUT请求而非PATCH请求，并在请求体中明确指定主实体和子实体的IRI：

{
    "@id": "/contacts/5",
    "emails": [
        {
            "@id": "/emails/20",
            "address": "mail20_edited@example.com"
        }
    ]
}

这种方法会正确更新指定的电子邮件记录。但需要注意的是，这种方式会删除所有未在请求中列出的电子邮件记录。

保留其他关联实体的方法

如果需要保留其他未修改的电子邮件记录，必须在请求体中显式包含它们的IRI：

{
    "@id": "/contacts/5",
    "emails": [
        "/emails/10",
        {
            "@id": "/emails/20",
            "address": "mail20_edited@example.com"
        }
    ]
}