Symfony 4 + API Platform JSON格式缺失分页元数据求助

我之前在Symfony 4搭配API Platform开发API时，也碰到过完全一样的问题——返回的列表JSON里找不到totalItems、first、last这些分页元数据，折腾了好一阵才解决，给你分享几个排查和修复的方向：

1. 先确认分页功能是否真的开启 #

• 实体注解检查：确保你的实体类上的@ApiResource注解正确启用了分页，比如：

  /**
   * @ApiResource(
   *     attributes={
   *         "pagination_enabled"=true,
   *         "pagination_items_per_page"=20,
   *         "pagination_partial"=false // 这个很关键，设为true会关闭totalItems统计
   *     }
   * )
   */
  class YourEntity
  {
      // ...
  }
  

  注意pagination_partial如果设为true，API Platform会跳过总数查询，自然不会返回totalItems。
• 全局配置检查：打开config/packages/api_platform.yaml，确认全局分页没有被禁用：

  api_platform:
      pagination:
          enabled: true # 必须设为true，否则实体级的配置会被覆盖
          client_enabled: true # 允许客户端通过page参数触发分页
          client_items_per_page: true # 允许客户端自定义每页数量
  

2. 检查请求格式是否正确 #

这是我当时踩的坑！API Platform默认的分页元数据（totalItems、first等）是Hydra规范的一部分，如果你请求时用的是Accept: application/json，返回的是纯数据数组，不会包含这些元数据。

解决方法有两个：

• 改用Hydra格式请求：把请求头改成Accept: application/ld+json，返回的JSON-LD结构里就会包含完整的分页元数据；
• 配置让纯JSON格式也返回元数据：在api_platform.yaml里添加序列化配置，让集合数据被嵌套包装：

  api_platform:
      formats:
          json:
              mime_types: ['application/json']
      serializer:
          enable_nested_serialization: true # 开启嵌套序列化，让分页元数据被包含进来
  

3. 排查自定义序列化/归一化器 #

如果项目里自定义了CollectionNormalizer或者其他序列化相关的服务，可能覆盖了API Platform默认的分页元数据生成逻辑。这时候需要：

• 确保自定义归一化器的优先级低于API Platform的HydraCollectionNormalizer；
• 在自定义逻辑中保留对分页集合的处理，不要直接返回原始数据数组。

4. 检查API Platform版本兼容性 #

Symfony 4对应的API Platform版本主要是2.x系列，如果你的版本比较旧，可能存在已知的分页元数据bug。建议升级到对应分支的最新稳定版（比如2.7.x的最新版），很多这类小问题都会在后续版本中修复。

我当时的问题就是请求头用了application/json导致的，改成application/ld+json之后立刻就看到所有分页元数据了，你可以先排查这个点试试！

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