如何处理Pimcore(Symfony) routing.yml中NotFoundHttpException返回HTML问题

你在路由defaults中配置的_format: json仅能作用于成功匹配到对应路由集合的请求。NotFoundHttpException返回HTML的核心原因是：大部分触发404的API请求是路径错误，根本没有匹配到你定义的API路由集合，此时路由内的_format配置不会被加载，系统会fallback到默认的HTML格式错误渲染逻辑。

你不需要编写全局异常监听器，以下两种方案都可以将异常处理逻辑完全限定在API范围内，不会干扰后台的HTML响应：

方案1：路由兜底（推荐，完全隔离无侵入） #

在你独立API Bundle的路由配置文件末尾，添加一个API路径前缀下的兜底路由，所有未匹配到具体接口的API请求都会走到这个路由，直接返回JSON格式的404响应，不会触发全局错误页渲染：

# 你的API Bundle内的routing.yml
# 注意：该路由必须放在所有API具体路由的最后
api_not_found_catch:
  path: /api/{rest_path}
  defaults:
    _controller: '你的API错误控制器::notFound'
    _format: json
  requirements:
    rest_path: .*
  methods: [GET, POST, PUT, DELETE, PATCH, OPTIONS]

在对应的notFound方法中，你可以直接返回自定义结构的404 JSON响应，该配置仅对/api前缀下的请求生效，和Pimcore后台/admin前缀的逻辑完全隔离。
如果是已经匹配到API路由、控制器内部抛出的NotFoundHttpException，你原本配置的_format: json本身就会正常返回JSON，不需要额外处理。

方案2：框架原生路径级异常配置 #

Symfony（Pimcore底层框架）原生支持按路径配置异常响应格式，不需要编写自定义监听器，直接修改框架配置即可：

# config/packages/framework.yaml
framework:
  exceptions:
    Symfony\Component\HttpKernel\Exception\NotFoundHttpException:
      paths:
        # 仅对/api前缀下的请求生效，后台/admin路径不受影响
        '^/api': json

该配置会让所有/api前缀下抛出的404异常默认返回JSON格式响应，后台请求依然保持原有的HTML错误页。

路由配置文件本身不支持直接定义异常场景下的返回JSON结构，但你可以配合上述两种方案实现自定义：

• 用方案1的兜底路由时，你可以直接在兜底路由对应的控制器方法中，组装任意你需要的JSON结构返回，比如错误码、业务提示信息、请求ID等字段
• 用方案2的路径级异常配置时，你可以单独给API路径指定专属的错误控制器，在专属控制器中自定义JSON返回结构，后台依然使用Pimcore默认的错误控制器，不会互相干扰

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