ApiPlatform自定义StateProvider下ApiFilter失效问题排查

1. 检查非实体类的API资源配置完整性 #

确保MyApiDataClass的注解配置符合API平台的资源识别要求，过滤器需要明确关联到类和属性：

#[ApiResource(
    collectionOperations: [
        'get' => [
            'method' => 'GET',
            'path' => '/my-api-data',
            'provider' => CustomStateProvider::class,
        ]
    ],
    filters: [SearchFilter::class]
)]
class MyApiDataClass
{
    // 为需要过滤的属性指定过滤策略
    #[SearchFilter(strategy: 'partial')]
    public string $name;

    // 其他属性定义...
}

注意：仅在类的filters数组中声明SearchFilter不够，必须为具体属性标注#[SearchFilter]并指定策略，否则过滤器无法绑定到目标属性。

2. 自定义StateProvider必须手动处理过滤参数 #

实体类的默认StateProvider会自动解析并执行过滤逻辑，但自定义Provider需要自行提取过滤参数并应用到数据源查询：

class CustomStateProvider implements StateProviderInterface
{
    public function provide(Operation $operation, array $uriVariables = [], array $context = []): object|array|null
    {
        // 从上下文提取过滤参数
        $filters = $context['filters'] ?? [];
        
        // 从数据源获取原始数据（示例：从外部API/缓存读取）
        $rawData = $this->fetchRawData();
        
        // 手动应用过滤逻辑，示例：根据name属性模糊匹配
        if (isset($filters['name'])) {
            $rawData = array_filter($rawData, fn($item) => str_contains($item['name'], $filters['name']));
        }
        
        // 将原始数据转换为MyApiDataClass实例
        return array_map(fn($data) => new MyApiDataClass($data['name'], ...), $rawData);
    }
}

关键：API平台不会为自定义Provider自动处理过滤逻辑，必须在provide方法中读取$context['filters']的参数，自行实现数据筛选。

3. 验证SearchFilter对非实体类的适配性 #

默认的SearchFilter是为Doctrine实体设计的，若你的非实体类数据来源并非Doctrine，需要确认过滤器能正确识别类的属性元数据：

• 开启API平台调试模式，查看生成的OpenAPI文档，确认MyApiDataClass的过滤参数是否被正确列出；
• 如果参数未显示，说明过滤器未正确关联到该类，可尝试自定义Filter类，实现针对非实体类的参数解析逻辑。

4. 调试请求参数传递链路 #

在CustomStateProvider中添加调试代码，确认请求中的过滤参数是否被正确传入：

// 在provide方法中添加调试输出
error_log(print_r($context['filters'], true));

发起测试请求GET /my-api-data?name=test，查看日志是否能拿到['name' => 'test']。如果没有，说明参数未被API平台正确解析，需要检查注解配置是否存在语法错误或遗漏。

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