Skip to content

serve: trace 端点空匹配返回 200 而非 404 #125

Description

@c2j

问题

GET /api/v1/trace 端点在无匹配节点时返回 404 Not Found,与 HTTP 搜索 API 的行业惯例不一致。

证据

src/server/handlers.rs:413-423:

async fn trace(
    State(state): State<AppState>,
    Query(query): Query<TraceQuery>,
) -> Result<impl IntoResponse, StatusCode> {
    let store = state.store();
    let matches = store.search_nodes(&query.from);
    let graph = state.graph();

    if matches.is_empty() {
        return Err(StatusCode::NOT_FOUND);  // ← 这里
    }

为什么这是问题

HTTP 404 的语义是"资源(端点)不存在",不是"搜到的结果为空"。

/api/v1/trace?from=xxx 标识的资源是"从 xxx 开始的调用链追踪结果",这个资源集合永远存在——只是有时为空。

对比行业标准:

API 无结果行为
Elasticsearch 200 {"hits": []}
GitHub Search 200 {"total_count": 0, "items": []}
Stripe API (list) 200 {"data": []}

无一使用 404 表示空结果。

此外,同一个 codebase 中 search_sql 端点(line 143-197)在空匹配时返回 200 + {"total": 0, "nodes": []},与 trace 行为不一致。

建议方案

trace 的空匹配从 Err(StatusCode::NOT_FOUND) 改为返回 Ok(Json({"target": null, "callers": [], "callees": [], ...}))

影响范围

  • src/server/handlers.rs:421-423 — 修改返回逻辑
  • 相关集成测试 — 更新期望状态码从 404 到 200

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions