问题
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
问题
GET /api/v1/trace端点在无匹配节点时返回404 Not Found,与 HTTP 搜索 API 的行业惯例不一致。证据
src/server/handlers.rs:413-423:为什么这是问题
HTTP 404 的语义是"资源(端点)不存在",不是"搜到的结果为空"。
/api/v1/trace?from=xxx标识的资源是"从 xxx 开始的调用链追踪结果",这个资源集合永远存在——只是有时为空。对比行业标准:
200 {"hits": []}200 {"total_count": 0, "items": []}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— 修改返回逻辑