设计一个用于查询人权报告的RESTful API，需支持分页、过滤（按国家、时间、事件类型）、排序，请说明API设计原则、数据传输格式（JSON）、错误处理，以及如何进行单元测试。

联合国人权事务高级专员办事处IT Applications Developer难度：中等

答案

1) 【一句话结论】
基于RESTful架构设计人权报告查询API，核心是通过资源URL标识（如/reports），用GET方法操作，采用cursor分页（高效处理大数据）、参数化过滤、稳定排序，传输JSON，用标准HTTP状态码和错误体处理异常，配合单元测试确保功能正确，并考虑数据库索引与缓存优化性能。

2) 【原理/概念讲解】
RESTful API的核心是资源识别与HTTP方法操作。对于人权报告查询，关键设计点如下：

资源标识：人权报告作为资源，通过URL /reports 标识，用GET方法获取资源列表。
分页（Cursor分页）：采用游标分页，用数据库自增ID作为游标（如上一次查询的最后一个报告ID），只查询比游标大的记录。类比：翻书时，每次看下一页（当前页最后一个ID+数量），而非从第一页开始数页码（偏移量），避免重复数据（偏移量分页数据量增长时性能下降，如offset=90000需扫描前90万条）。
过滤：通过查询参数（如country、time、type）动态构建SQL，用参数化查询（如JDBC的PreparedStatement或ORM的查询构建器）防止SQL注入，确保安全性。
排序：按字段顺序稳定排序（如先按country升序，再按date升序），确保相同条件结果一致，便于用户预期。
数据传输：JSON轻量、易解析，符合Web标准，便于客户端解析。
错误处理：用HTTP状态码（400 Bad Request：参数无效；404 Not Found：报告不存在；500 Internal Server Error：服务器错误；503 Service Unavailable：服务不可用）和错误体（含错误码、消息）反馈问题，帮助调试。
单元测试：用测试框架（如Jest+Supertest）模拟请求，验证响应状态码、分页参数、过滤条件、排序结果，确保功能正确。

3) 【对比与适用场景】

分页方式对比（Offset-Limit vs Cursor）
| 特性 | Offset-Limit（偏移量+数量） | Cursor（游标） |
|--------------|------------------------------|----------------------|
| 定义 | 偏移量（当前页起始位置）+数量 | 当前页最后一个ID+数量 |
| 优点 | 简单易实现，逻辑直观 | 更高效，避免重复数据 |
| 缺点 | 数据量增长时性能下降（如offset=90000，每次扫描前90万条） | 需存储游标，维护复杂（如游标过期处理） |
| 适用场景 | 数据量小（<10万条）、顺序固定 | 数据量大（>100万条）、频繁分页 |
过滤参数构建方式
- 动态参数化查询（推荐）：用占位符（如?或ORM占位符），将用户输入的参数作为参数传递，避免拼接SQL。
- 静态拼接：直接拼接用户输入的SQL，风险高（易被注入）。
排序稳定性
- 稳定排序：按字段顺序排序（如先country升序，再date升序），确保相同条件结果一致。
- 非稳定排序：可能因数据库实现不同导致结果顺序变化，不利于用户预期。

4) 【示例】

API端点：GET /reports
请求示例（cursor分页、过滤、排序，默认值）：
```
GET /reports?cursor=0&size=10&country=China&time=2023-01-01&type=Violations&sort=country:asc
```
（注：cursor默认为0（第一页第一个ID），size默认为10（每页10条））

响应示例（成功）：

{
  "cursor": "123",  // 下一次查询的游标（当前页最后一个ID）
  "size": 10,
  "totalElements": 150,
  "content": [
    {
      "id": 124,
      "country": "China",
      "date": "2023-01-20",
      "type": "Violations",
      "description": "Human rights violation report"
    },
    ...
  ]
}

错误响应（过滤参数无效值，如time格式错误）：

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": "InvalidTimeFormat",
  "message": "Time parameter must be in YYYY-MM-DD format"
}

5) 【面试口播版答案】
面试官好，针对人权报告查询的RESTful API设计，我遵循RESTful架构，核心是通过资源URL标识（如/reports），用GET方法获取，支持高效分页（cursor机制）、参数化过滤、稳定排序，传输JSON，用标准HTTP状态码和错误体处理异常，配合单元测试确保功能正确。具体来说，API端点为/reports，通过查询参数实现分页（cursor=lastId&size=10，cursor分页更高效，避免重复数据；默认cursor为0，size为10），过滤（country=国家、time=时间范围、type=事件类型），排序（sort=字段:升序/降序）。响应体包含游标、分页信息和报告列表。错误处理方面，参数无效（如page为负数）返回400 Bad Request，报告不存在返回404，服务器错误返回500，错误体含错误码和消息。单元测试用Jest+Supertest模拟请求，验证响应的cursor、size、过滤条件是否生效。这样设计既符合REST规范，又能高效处理大量人权报告数据，满足查询需求。

6) 【追问清单】

问：分页参数cursor为null时的处理逻辑？
回答要点：默认返回第一页数据，即cursor设为0（第一个报告ID），size按默认值（如10），确保用户首次查询能获取数据。
问：过滤参数中时间格式错误（如time=2023-02-30）如何处理？
回答要点：返回400 Bad Request，错误体提示时间格式错误，避免无效查询影响数据库性能。
问：排序参数无效字段（如sort=invalid_field）如何处理？
回答要点：返回400 Bad Request，提示无效排序字段，确保API健壮性。
问：如何优化分页查询性能？
回答要点：数据库对分页字段（如ID、时间、国家）建立索引，减少全表扫描；使用cursor分页避免重复数据；缓存常用查询结果（如ETag或Last-Modified）。
问：单元测试如何覆盖边界情况？
回答要点：测试cursor为null、过滤参数为空、排序参数无效等边界情况，确保API健壮性。

7) 【常见坑/雷区】

分页参数边界：如page为0或负数，size为0或负数，应返回400错误，而非继续查询或返回空结果。
过滤参数无效值：如time格式错误，应返回400错误，提示错误信息，避免数据库错误。
排序参数无效字段：如sort=invalid_field，应返回400错误，而非忽略或错误。
错误体不完整：错误体缺少错误码或消息，导致调试困难。
测试覆盖不足：仅测试正常情况，未测试边界情况（如cursor为null，过滤条件为空）。