📚 课程目录第4章请求与响应格式

4. 请求与响应格式：JSON数据结构设计、必填与可选字段、错误码规范

API 的请求与响应格式是客户端与服务端之间通信的契约。本章围绕 JSON 数据结构设计、必填与可选字段 以及 错误码规范 三个核心维度，定义图谱评分接口的标准化通信协议。良好的格式设计能降低集成成本、提升可维护性，并为后续的监控与告警提供结构化数据基础。

4.1 JSON 数据结构设计原则

图谱评分接口统一采用 JSON 作为数据交换格式。设计遵循以下原则：

扁平优先：避免过度嵌套，核心评分数据不超过两层。
字段命名：使用小驼峰（camelCase），如 scoreValue、graphId。
类型明确：所有字段必须声明数据类型，禁止动态类型。
版本前缀：响应体顶层包含 apiVersion 字段，便于后续兼容。

设计提示：JSON 结构应优先考虑“可读性”而非“极致压缩”。字段名长度控制在 3~20 个字符之间，避免使用缩写歧义（如 sc 应写为 score）。

4.2 请求体结构规范

所有 POST /v1/graph/score 请求必须遵循以下 JSON 结构。下表列出必填与可选字段：

字段名	类型	必填/可选	说明	示例值
`graphId`	string	必填	图谱唯一标识符，UUID v4 格式	`"a1b2c3d4-..."`
`nodes`	array[object]	必填	节点列表，至少包含 1 个节点	`[{"id":"n1"}]`
`edges`	array[object]	可选	边列表，可为空数组	`[{"from":"n1","to":"n2"}]`
`config`	object	可选	评分配置参数，如权重、阈值	`{"weight":0.8}`
`requestId`	string	可选	客户端请求追踪 ID，建议必传	`"req-001"`

请求体示例：

{
  "graphId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "nodes": [
    { "id": "n1", "type": "entity", "label": "张三" },
    { "id": "n2", "type": "entity", "label": "李四" }
  ],
  "edges": [
    { "from": "n1", "to": "n2", "relation": "朋友" }
  ],
  "config": {
    "algorithm": "default",
    "weight": 1.0
  },
  "requestId": "req-20240501-abc123"
}

4.3 响应体结构规范

所有响应均包含固定顶层字段，确保客户端可统一解析。响应分为 成功响应 与 错误响应 两种形态。

4.3.1 成功响应

字段名	类型	必填/可选	说明
`apiVersion`	string	必填	接口版本号，当前为 `"1.0"`
`success`	boolean	必填	固定为 `true`
`data`	object	必填	评分结果数据体
`timestamp`	string	必填	ISO 8601 格式时间戳
`requestId`	string	可选	回传客户端请求 ID

成功响应示例：

{
  "apiVersion": "1.0",
  "success": true,
  "data": {
    "graphId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "overallScore": 0.87,
    "dimensions": {
      "completeness": 0.92,
      "consistency": 0.85,
      "freshness": 0.78
    },
    "summary": "图谱质量良好，建议提升数据新鲜度"
  },
  "timestamp": "2024-05-01T12:00:00Z",
  "requestId": "req-20240501-abc123"
}

4.3.2 错误响应

字段名	类型	必填/可选	说明
`apiVersion`	string	必填	接口版本号
`success`	boolean	必填	固定为 `false`
`error`	object	必填	错误详情对象
`timestamp`	string	必填	ISO 8601 格式时间戳

错误响应示例：

{
  "apiVersion": "1.0",
  "success": false,
  "error": {
    "code": "ERR_INVALID_GRAPH_ID",
    "message": "提供的 graphId 格式无效，应为 UUID v4",
    "details": {
      "field": "graphId",
      "reason": "格式不匹配"
    }
  },
  "timestamp": "2024-05-01T12:01:00Z",
  "requestId": "req-20240501-abc123"
}

4.4 错误码规范

错误码采用 三段式结构：ERR_ + 模块名 + 具体错误。所有错误码均为大写字母与下划线组合。下表列出图谱评分接口的核心错误码：

错误码	HTTP 状态码	说明	触发条件
`ERR_MISSING_FIELD`	400	缺少必填字段	请求体中 `graphId` 或 `nodes` 缺失
`ERR_INVALID_GRAPH_ID`	400	图谱 ID 格式错误	graphId 不是合法的 UUID v4
`ERR_EMPTY_NODES`	400	节点列表为空	nodes 数组长度为 0
`ERR_RATE_LIMIT`	429	请求频率超限	超过 API 调用配额
`ERR_INTERNAL`	500	服务端内部错误	评分引擎异常或数据库故障
`ERR_TIMEOUT`	504	评分超时	图谱规模过大导致处理超时

重要：客户端必须根据 error.code 进行逻辑分支处理，而非仅依赖 HTTP 状态码。例如 ERR_RATE_LIMIT 应触发退避重试，而 ERR_MISSING_FIELD 应提示用户修正请求体。

4.5 请求-响应流程与错误处理路径

下图展示从客户端发起请求到接收响应的完整数据流，以及错误发生时的处理路径：

4.6 字段校验规则速查

为帮助开发者在集成阶段快速定位问题，以下列出常见字段的校验规则：

graphId：必须符合 UUID v4 正则 ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$。
nodes：数组长度 1~1000；每个节点必须包含 id（string，非空）和 type（string，预定义枚举）。
edges：可选，数组长度 0~5000；每条边必须包含 from 和 to，且引用已存在的节点 ID。
config.algorithm：可选，仅支持 "default"、"fast"、"deep" 三种值。
requestId：可选，若传入则长度不超过 64 字符，仅允许字母、数字、连字符和下划线。

  最佳实践：建议客户端始终携带 requestId 字段，便于在监控系统中关联请求日志与评分结果。服务端会在响应中原样回传该字段。

4.7 版本兼容与扩展策略

JSON 结构设计需考虑未来扩展。以下策略确保向后兼容：

禁止删除已有必填字段：任何版本迭代不得移除 graphId、nodes 等必填字段。
新增字段默认可选：新版本如需增加字段，必须设为可选，并附带默认值或空值处理逻辑。
响应体顶层版本号：客户端通过 apiVersion 字段判断响应结构，避免解析错误。
错误码只增不减：已发布的错误码永久保留，新错误码使用新的 ERR_ 前缀，不得复用旧码。

通过以上规范，图谱评分接口的请求与响应格式具备了 可读性、可校验性 和 可演进性，为后续的监控与告警体系奠定了坚实的数据基础。