3. 评分接口概述：图谱评分接口的调用链路、输入输出参数与业务逻辑
图谱评分接口是反欺诈系统的核心决策节点，它将实时入参的实体关系数据映射到知识图谱中，通过图算法与规则引擎计算风险分值。理解其调用链路、参数结构与业务逻辑，是定位延迟瓶颈的前提。
3.1 调用链路全景
一次完整的图谱评分请求从客户端发起，经过网关、特征服务、图计算引擎，最终返回评分结果。下图展示了标准调用链路中的关键节点与数据流向。
延迟关键点：图计算引擎与图谱存储之间的网络往返（步骤④→⑤）通常占总耗时的 60%~75%，是延迟分析的首要关注区域。
3.2 输入输出参数
接口参数分为请求参数（Request）与响应参数（Response）。下表列出核心字段及其数据类型、说明。
| 方向 | 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| 请求 | userId |
String | 是 | 用户唯一标识 |
deviceId |
String | 是 | 设备指纹 ID | |
orderId |
String | 否 | 关联订单号（可选） | |
extraFeatures |
Map<String,Object> | 否 | 扩展特征字段 | |
timeout |
Integer | 否 | 超时时间（ms），默认 3000 | |
| 响应 | score |
Integer | 是 | 风险分值 0~100，越高越危险 |
riskLevel |
String | 是 | 风险等级：LOW / MEDIUM / HIGH | |
hitRules |
List<String> | 否 | 命中规则列表 | |
elapsedMs |
Long | 是 | 服务端处理耗时（ms） |
3.3 业务逻辑流程
图谱评分接口的业务逻辑可拆解为以下 5 个步骤，每个步骤对应一个可观测的延迟阶段。
- 入参校验与特征组装：校验 userId、deviceId 等必填字段，组装扩展特征为图查询参数。
- 图谱关系查询：根据入参在知识图谱中检索关联实体（如设备、IP、手机号），返回子图结构。
- 图算法计算：执行社区发现、路径分析、相似度计算等算法，生成图特征向量。
- 规则引擎评分：将图特征向量输入规则引擎，匹配风险规则，计算综合分值。
- 结果封装与返回：将 score、riskLevel、hitRules 等字段封装为响应 JSON，记录耗时日志。
业务逻辑示例：当 userId=U123 与 deviceId=D456 在 1 小时内关联过 3 个以上被标记为 HIGH_RISK 的 IP 时，规则引擎将触发“设备聚集风险”规则，score 增加 30 分。
3.4 延迟阶段划分
为便于后续的延迟分析，我们将接口处理时间划分为 4 个阶段，每个阶段对应一个独立的监控埋点。
| 阶段编号 | 阶段名称 | 起始点 | 结束点 | 典型耗时占比 |
|---|---|---|---|---|
| T1 | 入参处理 | 请求到达 | 特征组装完成 | 5%~10% |
| T2 | 图谱查询 | 发起图查询 | 子图返回 | 40%~55% |
| T3 | 图计算 | 子图就绪 | 特征向量生成 | 20%~30% |
| T4 | 规则评分 | 特征向量输入 | 结果返回 | 10%~15% |
从表中可见，T2（图谱查询）与T3（图计算）合计占比超过 70%，是延迟优化的主攻方向。后续章节将针对这两个阶段进行深度剖析与案例实战。
注意：如果 T1 阶段耗时超过 15%，通常意味着入参序列化或特征服务存在性能瓶颈，需优先排查特征服务的线程池配置与缓存命中率。