应直接使用JsonResponse类返回JSON响应，它自动设置Content-Type、UTF-8编码并安全处理null等值；避免手写json_encode()+Response或传入未处理的Doctrine实体；需统一监听kernel.exception处理API异常并校验Accept头；CORS推荐使用nelmio/cors-bundle配置。
直接用 JsonResponse，别手写 json_encode() + Response
这是最常见也最容易踩坑的点：有人在控制器里写 return new Response(json_encode($data))，结果前端收不到 JSON，或者中文乱码、null 变成空字符串甚至报错。因为 Response 不会自动设 Content-Type: application/json，也不处理 UTF-8 编码和 null 安全序列化。
正确做法是引入并使用 JsonResponse：
use Symfony\Component\HttpFoundation\JsonResponse; // 在控制器方法里 return new JsonResponse(['message' => 'ok', 'data' => $userArray]);
JsonResponse 会自动设置 header、确保 UTF-8、把 null 转成 JSON null，还兼容标量、数组、实现 JsonSerializable 的对象。
要改状态码？传第二个参数：new JsonResponse($data, 400)。
常见错误：
- 传入未处理的 Doctrine 实体（会触发循环引用或 N+1）
- 传入资源句柄（如
fopen()返回值）、闭包、未初始化属性 - 在
JsonResponse之前已输出内容（比如var_dump()或 echo），导致 headers already sent
Doctrine 实体不能直接塞进 JsonResponse
你写 return new JsonResponse($user)，大概率会遇到 SerializationException 或响应卡死——因为 Doctrine 实体带代理对象、懒加载关系（比如 $user->getPosts()）、双向关联（User ↔ Post），默认序列化时会无限递归或触发额外查询。
简单安全的做法是先“投影”成数组或 DTO：
- 实体里加一个
toArray()方法，只返回需要的字段（避免暴露$passwordHash、$createdAt等） - 用轻量 DTO 类（比如
UserOutputDto），配合 builder 手动赋值 - 避免用
get_object_vars($user)——它会暴露私有属性、代理内部字段（如__isInitialized__）
示例：
return new JsonResponse($user->toArray()); // 假设你写了这个方法
如果真要用 Serializer（比如需要 @Groups 或嵌套展开），必须配 ObjectNormalizer + JsonEncoder，并设 circular_reference_limit，否则开发环境不报错、生产环境偶发 500。
API 异常必须转成 JSON，且只对 API 请求生效
Symfony 默认异常页面是 HTML，直接扔给前端会崩掉整个 API 调用链。但不能全局把所有异常都转 JSON —— 否则普通网页请求（比如访问 /admin）也会返回 JSON，破坏跳转和表单提交。
得靠 kernel.exception 事件监听器做精准拦截：
- 检查
$request->headers->get('Accept')是否含application/json - 或按路由前缀判断：
$request->getPathInfo() === '/api/'开头 - 或看格式：
$request->getRequestFormat() === 'json'
匹配后才用 JsonResponse 返回结构化错误，比如：
['error' => 'validation_failed', 'details' => ['email' => ['This value is not a valid email.']]]
不匹配就让原异常继续走 HTML 流程，不影响后台管理页。
$this->json() 是快捷方式，但要注意它的隐式行为
控制器里可以直接用 $this->json($data)，它底层就是封装好的 JsonResponse，等价于 return new JsonResponse($data)。省事，但容易忽略两点：
- 它默认状态码是 200，哪怕你传的是错误数据；要改状态码得显式写
$this->json($data, 404) - 它不会自动处理 Doctrine 实体 —— 和
JsonResponse一样，传$user还是会崩，不是“智能序列化”
另外，$this->json() 不依赖 Serializer 组件，所以即使你没开 framework.serializer.enabled，它也能用。这点常被误认为“它用了 Serializer”，其实没有。
真正需要深度控制序列化逻辑（比如字段分组、忽略敏感字段、自定义命名）时，才该启用 Serializer 并显式调用 $serializer->serialize()，而不是依赖 $this->json() 的“自动”能力。
