Api Platform SearchFilter无法通过UUID搜索的原因及解决方法

原因 #

单个UUID详情请求（api/products/{uuid}）正常，但批量使用uuid[]=xxx参数搜索无结果，核心问题在于：

• 默认SearchFilter处理数组形式的UUID参数时，未将字符串UUID转换为实体依赖的UUID对象（如Ramsey\Uuid\UuidInterface实例）。
• 详情请求能正常工作，是因为Api Platform的路由转换器会自动将路径中的字符串UUID转换为匹配实体类型的UUID对象，而批量搜索的参数未经过这个转换，导致Doctrine执行查询时，字符串与数据库中UUID类型（或二进制存储的UUID）不匹配，最终返回空结果。

解决办法 #

方法1：自定义UUID数组过滤器 #

创建继承自SearchFilter的自定义过滤器，手动处理字符串UUID到UUID对象的转换：

<?php
// src/Filter/UuidArraySearchFilter.php

namespace App\Filter;

use ApiPlatform\Doctrine\Orm\Filter\SearchFilter;
use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
use ApiPlatform\Metadata\Operation;
use Doctrine\ORM\QueryBuilder;
use Ramsey\Uuid\Uuid;

class UuidArraySearchFilter extends SearchFilter
{
    protected function filterProperty(string $property, $values, QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, Operation $operation = null, array $context = []): void
    {
        // 仅处理UUID类型的数组参数
        if (!is_array($values) || !$this->isUuidProperty($resourceClass, $property)) {
            parent::filterProperty($property, $values, $queryBuilder, $queryNameGenerator, $resourceClass, $operation, $context);
            return;
        }

        // 将字符串UUID转换为Uuid对象
        $uuidObjects = array_map(function(string $uuid) {
            return Uuid::fromString($uuid);
        }, $values);

        // 调用父类逻辑处理转换后的UUID数组
        parent::filterProperty($property, $uuidObjects, $queryBuilder, $queryNameGenerator, $resourceClass, $operation, $context);
    }

    private function isUuidProperty(string $resourceClass, string $property): bool
    {
        $metadata = $this->managerRegistry->getManagerForClass($resourceClass)->getClassMetadata($resourceClass);
        $type = $metadata->getTypeOfField($property);
        
        return in_array($type, ['uuid', 'ramsey_uuid'], true);
    }
}

在实体中配置该自定义过滤器：

// src/Entity/Product.php

use ApiPlatform\Metadata\ApiFilter;
use App\Filter\UuidArraySearchFilter;

#[ApiFilter(UuidArraySearchFilter::class, properties: ['uuid' => 'exact'])]
class Product
{
    use UuidTrait;
    // ... 其他属性定义
}

方法2：通过Doctrine查询扩展修正参数类型 #

创建查询扩展，拦截批量搜索请求并修正UUID参数的类型：

<?php
// src/Doctrine/Orm/Extension/UuidArrayFilterExtension.php

namespace App\Doctrine\Orm\Extension;

use ApiPlatform\Doctrine\Orm\Extension\QueryCollectionExtensionInterface;
use ApiPlatform\Doctrine\Orm\Util\QueryNameGeneratorInterface;
use ApiPlatform\Metadata\Operation;
use Doctrine\ORM\QueryBuilder;
use Ramsey\Uuid\Uuid;
use App\Entity\Product;

class UuidArrayFilterExtension implements QueryCollectionExtensionInterface
{
    public function applyToCollection(QueryBuilder $queryBuilder, QueryNameGeneratorInterface $queryNameGenerator, string $resourceClass, Operation $operation = null, array $context = []): void
    {
        // 仅处理Product实体的uuid数组过滤
        if ($resourceClass !== Product::class || !isset($context['filters']['uuid'])) {
            return;
        }

        $uuidValues = $context['filters']['uuid'];
        if (!is_array($uuidValues)) {
            return;
        }

        // 转换字符串UUID为Uuid对象
        $uuidObjects = array_map(fn(string $uuid) => Uuid::fromString($uuid), $uuidValues);
        $alias = $queryBuilder->getRootAliases()[0];
        $parameterName = $queryNameGenerator->generateParameterName('uuid');
        
        // 重新设置查询条件与参数
        $queryBuilder->andWhere(sprintf('%s.uuid IN (:%s)', $alias, $parameterName))
            ->setParameter($parameterName, $uuidObjects, 'uuid');
    }
}

注册该扩展（Symfony环境下在services.yaml中添加）：

services:
    App\Doctrine\Orm\Extension\UuidArrayFilterExtension:
        tags:
            - { name: api_platform.doctrine.orm.query_extension.collection }

额外检查点 #

• 确认实体中uuid字段的Doctrine类型配置正确，示例：

  #[ORM\Column(type: 'uuid', unique: true)]
  private ?UuidInterface $uuid = null;
  

• 确保UuidTrait在实体构造函数中正确初始化UUID。

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