Api-platform v3.2：如何避免空ID时的IRI @ID序列化？

从v2.6升级到v3.2后，ApiPlatform对IRI生成的逻辑做了严格限制：未持久化（无ID）的实体默认无法生成合法IRI，因此抛出Unable to generate an IRI for the item异常。以下是几种符合ApiPlatform设计规范的解决方案，替代你当前的临时Normalizer：

方法1：序列化上下文禁用强制IRI生成 #

在序列化未保存的实体时，直接传入force_iri_generation: false上下文参数，阻止ApiPlatform强制生成IRI，同时可手动指定@id值保持和v2.6一致的输出格式。

控制器中手动序列化示例 #

use Symfony\Component\Serializer\SerializerInterface;

// $unpersistedResource 是未持久化的实体实例
$serializedData = $this->serializer->normalize(
    $unpersistedResource,
    'json',
    [
        'force_iri_generation' => false,
        'iri' => '/my/api/resource/' // 可选：保持原v2.6的@id格式
    ]
);

表单场景自动序列化（事件监听修改上下文） #

如果是通过ApiPlatform自动序列化返回给前端表单，可通过事件订阅器动态修改序列化上下文：

use ApiPlatform\Serializer\SerializerContextBuilderInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use ApiPlatform\Core\EventListener\EventPriorities;
use Symfony\Component\HttpKernel\Event\ViewEvent;

class UnpersistedResourceContextSubscriber implements EventSubscriberInterface
{
    private $serializerContextBuilder;

    public function __construct(SerializerContextBuilderInterface $serializerContextBuilder)
    {
        $this->serializerContextBuilder = $serializerContextBuilder;
    }

    public static function getSubscribedEvents()
    {
        return [
            ViewEvent::class => ['adjustSerializationContext', EventPriorities::PRE_SERIALIZE],
        ];
    }

    public function adjustSerializationContext(ViewEvent $event)
    {
        $resource = $event->getControllerResult();
        // 替换成你的资源类
        if (!$resource instanceof YourResourceClass) {
            return;
        }

        // 检测实体是否未分配ID
        if (null === $resource->getId()) {
            $context = $this->serializerContextBuilder->createFromRequest($event->getRequest(), false, ['object' => $resource]);
            $context['force_iri_generation'] = false;
            $context['iri'] = '/my/api/resource/'; // 可选：自定义@id值
            $event->getRequest()->attributes->set('_api_normalization_context', $context);
        }
    }
}

方法2：自定义IRI生成器（全局生效） #

通过装饰ApiPlatform默认的IriConverter，全局处理无ID实体的IRI生成逻辑，无需在每个序列化场景单独配置：

use ApiPlatform\Api\IriConverterInterface;
use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;

class CustomIriConverter implements IriConverterInterface
{
    private $originalIriConverter;
    private $resourceMetadataFactory;
    private $router;

    public function __construct(
        IriConverterInterface $originalIriConverter,
        ResourceMetadataCollectionFactoryInterface $resourceMetadataFactory,
        UrlGeneratorInterface $router
    ) {
        $this->originalIriConverter = $originalIriConverter;
        $this->resourceMetadataFactory = $resourceMetadataFactory;
        $this->router = $router;
    }

    public function getIriFromResource($item, int $referenceType = UrlGeneratorInterface::ABS_PATH): string
    {
        // 仅处理无ID的实体
        if (method_exists($item, 'getId') && null === $item->getId()) {
            $resourceMetadata = $this->resourceMetadataFactory->create(get_class($item))->getOperation();
            // 生成不带ID的基础IRI（和v2.6输出一致）
            return $this->router->generate(
                $resourceMetadata->getRouteName(),
                [],
                $referenceType
            );
        }

        // 其他情况使用默认逻辑
        return $this->originalIriConverter->getIriFromResource($item, $referenceType);
    }

    // 直接委托默认实现处理IRI转实体的逻辑
    public function getItemFromIri(string $iri, array $context = []): object
    {
        return $this->originalIriConverter->getItemFromIri($iri, $context);
    }
}

然后在services.yaml中配置装饰：

services:
    App\Api\CustomIriConverter:
        decorates: api_platform.iri_converter
        arguments:
            $originalIriConverter: '@.inner'
            $resourceMetadataFactory: '@api_platform.resource.metadata.collection_factory'
            $router: '@router'

方法3：针对特定操作配置序列化上下文 #

如果只需要在某个特定API操作中处理无ID实体，可直接在ApiResource注解的操作配置中指定序列化上下文：

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;

#[ApiResource(
    operations: [
        new Get(
            name: 'form_template',
            normalizationContext: [
                'force_iri_generation' => false,
                'iri' => '/my/api/resource/'
            ]
        )
    ]
)]
class YourResourceClass
{
    // 实体字段定义...
}

为什么临时Normalizer不妥？ #

你的临时方案通过手动修改上下文参数绕过IRI生成，但没有遵循ApiPlatform v3的设计逻辑，容易导致嵌套资源序列化异常，或和其他序列化扩展冲突。上面的方法都是基于ApiPlatform内置机制实现，更稳定且易于维护。

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