API Platform自定义非实体资源返回统计数据的集合格式问题解决

问题场景 #

• 基于Symfony 7.1和API Platform 4开发接口
• 需要返回非Doctrine实体映射的自定义统计数据（按状态统计公司数量）
• 已创建App\ApiResource\CompanyStatistics资源类和App\State\CompanyStatisticsStateProvider状态提供者
• 调用API时返回集合格式数据（如{"hydra:member": [...], ...}），而非预期的扁平单条数据结构

解决方法 #

在CompanyStatistics类的#[ApiResource]注解中添加paginationEnabled: false配置，禁用分页后即可返回扁平的单条统计数据：

<?php

namespace App\ApiResource;

use ApiPlatform\Metadata\ApiResource;
use ApiPlatform\Metadata\Get;
use App\State\CompanyStatisticsStateProvider;

#[ApiResource(
    operations: [
        new Get(provider: CompanyStatisticsStateProvider::class)
    ],
    paginationEnabled: false // 关键配置：禁用默认分页
)]
class CompanyStatistics
{
    public int $activeCompanyCount;
    public int $inactiveCompanyCount;
    // 其他需要暴露的统计字段...
}

非实体数据接口的最佳实践 #

• 资源类设计：资源类仅定义需要对外暴露的字段，无需关联或继承Doctrine实体，保持结构简洁
• 状态提供者实现：在StateProvider中直接编写自定义查询（如Doctrine原生SQL查询、DBAL查询）获取统计数据，手动映射到资源类对象
• 单条数据配置：如果接口仅返回单条数据，必须禁用分页，否则API Platform会默认将数据包裹在集合响应结构中
• 响应格式控制：可通过outputFormats配置指定返回JSON、XML等格式，适配前端消费需求

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