核心是遵循RESTful原则：按资源设计URL（如/api/users/123）、用HTTP方法表达操作、严格使用标准状态码（200/204/404/400等）、防N+1查询、序列化时用Groups控制字段、全局监听kernel.exception统一返回JSON错误响应，并通过Query Param支持分页过滤排序。
用 Symfony2 开发数据库查询类 API 接口，核心不是“怎么连数据库”，而是“怎么让接口既符合 RESTful 原则，又安全、高效、可维护”。重点在资源建模、HTTP 方法语义、状态码使用、序列化控制和错误响应统一——这些比写一条 $em->getRepository(User::class)->findAll() 重要得多。
按资源设计 URL，别用动词
把数据库表抽象成“资源”，URL 路径体现层级与归属，不带 get、list、query 这类动词：
-
✅ 正确：
GET /api/users（获取用户集合）GET /api/users/123（获取单个用户）GET /api/users/123/posts（获取某用户的全部文章） -
❌ 避免：
GET /api/getUsers、POST /api/queryUserByStatus、GET /api/user?mode=list
URL 中的斜杠代表关系，不是目录结构。比如 /api/orders/456/items 表示订单 456 下的所有子项，天然支持嵌套资源查询。
用标准 HTTP 状态码表达业务结果
状态码是 API 的“语气”，它告诉调用方这次请求到底是成功、失败还是需要重试：
-
200 OK：查询成功，返回数据（如GET /api/users/789找到用户） -
204 No Content：查询成功但无数据（如GET /api/users?status=inactive返回空数组） -
404 Not Found：请求的资源不存在（如GET /api/users/999999数据库中无此 ID） -
400 Bad Request：参数格式错误（如 ID 不是数字、日期格式非法） -
406 Not Acceptable：客户端声明只接受application/xml，但你的 API 只支持 JSON
不要所有成功都返回 200，也不要所有失败都塞进 500 —— 状态码是契约的一部分，前端靠它做不同分支处理。
查库时防 N+1，序列化时控字段
Symfony2 默认用 Doctrine ORM，但直接返回实体对象容易触发懒加载爆炸（N+1 查询），也暴露敏感字段（如密码哈希、创建时间戳）：
- 用
Query Builder或 DQL 显式JOIN关联数据，避免在 Twig 模板或JsonResponse中访问$user->getPosts()这类 Proxy 关系 - 用
Serializer组件定义组（groups），控制器中指定序列化上下文：$serializer->serialize($user, 'json', ['groups' => 'user:read']) - 在实体上用注解标记字段可见性：
@Groups({"user:read"})、@SerializedName("email_hash")、@Ignore
统一错误响应格式，不混 HTML 页面
默认异常会渲染成 Symfony HTML 错误页，API 客户端无法解析。必须拦截并转为结构化 JSON：
- 监听
kernel.exception事件，只对Accept: application/json请求生效 - 区分异常类型：
–NotFoundHttpException→404+{"error": "not_found", "message": "User not found"}
–ValidationException→400+{"error": "validation_failed", "details": {"email": ["This value is not a valid email."]}} - 避免裸抛异常，也不要在每个 action 里写
try/catch—— 全局监听才是可维护的做法
分页、过滤、排序由 Query Param 控制
列表接口必须支持基础数据操作能力，且通过标准方式暴露：
-
GET /api/users?page=2&itemsPerPage=20→ 返回分页元信息（totalItems、currentPage、lastPage） -
GET /api/users?status=active&role=admin→ 后端做字段映射，拒绝未定义参数（如?xyz=1应报 400） -
GET /api/users?orderBy=name&orderDirection=desc→ 限定可排序字段，防止 SQL 注入 - 响应体中用
Link响应头提供上一页/下一页 URI（RFC 5988），方便客户端发现导航
不推荐把分页逻辑硬编码进控制器；可用现成 Bundle（如 KnpPaginatorBundle）或封装通用 Repository 方法。
