4. 自助查询接口设计原则：RESTful风格、幂等性、分页、过滤、排序规范

值班台分布式追踪自助查询接口是平台工程团队与研发人员之间的核心契约。设计不当的接口会导致调用方频繁出错、查询超时、数据不一致，甚至引发级联故障。本章围绕 RESTful 风格、幂等性、分页、过滤、排序 五大原则，给出可落地的设计规范与代码示例。

4.1 RESTful 资源建模与端点设计

追踪数据本质上是资源集合，应遵循 REST 资源导向设计。核心资源包括：

以下 SVG 展示了追踪查询接口的资源层次与端点映射关系：

4.2 幂等性设计

查询接口天然应是幂等的——同一请求无论调用一次还是多次，资源状态不变，返回结果一致。但在分布式追踪场景中，需额外注意以下陷阱：

• 时间窗口漂移：查询最近 N 分钟的链路时，若后端存储持续写入新数据，两次相同请求可能返回不同结果。解决方案：查询参数中显式指定时间范围（startTime / endTime），而非使用相对时间。
• 分页游标稳定性：使用基于偏移量的分页时，若数据在两次请求间发生变更，可能导致重复或遗漏。推荐使用 游标分页（cursor-based pagination）保证幂等。
• HTTP 方法选择：所有查询操作必须使用 GET 或 POST（当查询条件复杂时），禁止使用 POST 执行非幂等操作。

4.3 分页规范

追踪数据量可能极大（单日数亿 Span），必须强制分页。推荐使用 游标分页 替代传统偏移分页：

游标分页的请求与响应示例：

// 请求：查询第一页，每页 20 条
GET /api/v1/traces?limit=20&startTime=2025-01-01T00:00:00Z&endTime=2025-01-01T01:00:00Z

// 响应
{
  "items": [ ... ],
  "nextCursor": "eyJ0aW1lIjogIjIwMjUtMDEtMDFUMDA6MzA6MDBaIn0="
}

// 请求：使用游标获取下一页
GET /api/v1/traces?limit=20&cursor=eyJ0aW1lIjogIjIwMjUtMDEtMDFUMDA6MzA6MDBaIn0=

4.4 过滤规范

过滤条件通过查询参数传递，遵循以下约定：

• 精确匹配：直接使用参数名，如 serviceName=order-service。
• 范围查询：使用 min / max 前缀，如 minDuration=100（查询耗时 ≥ 100ms 的链路）。
• 多值过滤：使用逗号分隔，如 status=error,timeout。
• 标签过滤：使用 tag.key=value 格式，如 tag.http.method=POST。

以下 SVG 展示了过滤参数在查询流程中的处理逻辑：

4.5 排序规范

排序参数使用 sort 字段，格式为 sort=字段名:排序方向，排序方向可选 asc 或 desc。支持多字段排序，用逗号分隔。

// 按开始时间降序排列
GET /api/v1/traces?sort=startTime:desc

// 先按服务名升序，再按耗时降序
GET /api/v1/traces?sort=serviceName:asc,duration:desc

可排序字段必须预先定义，避免用户传入任意字段导致存储层报错：

4.6 综合查询接口示例

将以上原则整合为一个完整的查询请求：

GET /api/v1/traces?serviceName=order-service
  &status=error
  &minDuration=500
  &tag.http.method=POST
  &startTime=2025-01-01T00:00:00Z
  &endTime=2025-01-01T23:59:59Z
  &limit=20
  &cursor=eyJ0aW1lIjogIjIwMjUtMDEtMDFUMTI6MDA6MDBaIn0=
  &sort=duration:desc,startTime:asc

该请求同时应用了：

• 过滤：服务名、状态、最小耗时、标签
• 时间范围：显式起止时间保证幂等
• 游标分页：稳定翻页
• 排序：先按耗时降序，再按开始时间升序