必须用JsonResponse或$this->json()返回JSON，禁用手动json_encode()+Response；Doctrine实体须转数组或DTO再序列化；统一异常监听器按Accept头拦截并返回结构化JSON错误响应。
直接用 Symfony 7.2 构建可上线的 RESTful API，核心不是“能不能”，而是“怎么绕开默认 HTML 行为、避免序列化陷阱、让错误响应不崩前端”。它不像 Laravel 那样开箱 API 友好，但胜在可控——前提是别踩那几个关键坑。
控制器里别手写 json_encode() + Response
这是最常导致前端收不到 JSON 的操作：手动拼字符串、漏设 Content-Type: application/json、UTF-8 BOM 或 headers already sent 报错。
- 必须用
JsonResponse：它自动设 header、处理 null/NaN/资源句柄安全、兼容 UTF-8 字节流 - 返回写法统一为
return $this->json($data, $status = 200, $headers = [])，别 new JsonResponse 每次都写三参数 -
$data只接受数组、标量、实现了JsonSerializable的对象；Doctrine 实体必须先转成数组或 DTO，否则会触发循环引用或代理加载（N+1） - 禁止用
get_object_vars($entity)——它暴露私有属性、$proxyInitializer、$initializer等内部字段，JSON 里出现"__initializer__": {}就是这个原因
Doctrine 实体不能直接塞进 $this->json()
哪怕加了 @Groups，没配好序列化器时，User 关联 Post 再反向关联 User，就会栈溢出或 500。开发环境可能不报，生产环境偶发失败。
- 最简解法：实体里加
public function toArray(): array，只返回需要的字段，比如['id' => $this->id, 'name' => $this->name] - 如果要用
Serializer，必须显式配置ObjectNormalizer+JsonEncoder，并在config/packages/serializer.yaml中禁用循环引用处理器：circular_reference_handler: ~或设max_depth: 2 - 警惕
$user->getPosts()：这是 Proxy，$this->json()触发时才查库；一个用户带 20 篇文章，就真会发 20 条 SQL —— 改用 DQL 显式JOIN+select()投影
全局拦截异常并转成 JSON 响应
Symfony 默认的 kernel.exception 事件返回的是 HTML 错误页，API 客户端收到 500 HTML 会解析失败。不能靠每个控制器 try-catch，得统一拦截。
- 写一个
ApiExceptionListener，监听kernel.exception事件 - 开头加判断：
if (!$request->headers->get('Accept')?->contains('application/json')) { return; }，避免影响普通页面跳转 - 对常见异常映射状态码：
ValidationException → 422，AccessDeniedException → 403，NotFoundHttpException → 404 - 响应结构保持一致：
['error' => 'validation_failed', 'details' => $violations]，别混用message和errors字段
路由和响应格式必须显式声明版本与媒体类型
没有 /api/v1/users 这种路径，或没检查 Accept: application/vnd.api+json，后期加版本或切换序列化协议时就得改所有客户端。
- 路由前缀强制加版本：
#[Route('/api/v1')]，别依赖中间件动态解析 - 在控制器方法上加内容协商：
#[Route('/users', methods: ['GET'], condition: "request.headers.get('Accept') matches '/application\/json/'")] - 统一响应包装层（可选但推荐）：封装一个
ApiResponse工具类，确保所有成功响应都是['success' => true, 'data' => ..., 'message' => '']结构，前端不用反复适配 - CORS 配置别只靠
nelmio/cors-bundle默认规则：API 必须明确允许credentials: true、expose_headers: ['X-Total-Count']等实际用到的头
真正难的不是写完第一个 /api/users，而是让第 37 个接口在加了缓存、JWT、分页、文件上传后，仍保持响应结构一致、错误可定位、序列化不翻车。Symfony 7.2 的组件解耦是优势，也是责任——你得亲手把 Serializer、Validator、Security 这几块粘牢，而不是指望它们自动咬合。
