📚 课程目录第3章因子评分接口业务逻辑解析

3、因子评分接口业务逻辑解析：输入参数、评分规则、因子权重、输出格式

因子评分接口是低延迟评分系统的核心计算单元。性能测试前，必须精确理解其业务逻辑：接口接收哪些参数、如何计算评分、各因子权重如何分配、最终输出什么结构。只有将业务逻辑映射为可量化的测试模型，才能设计出有效的压测场景。

3.1 输入参数结构

接口采用 JSON 格式的 POST 请求，核心字段分为请求头与请求体两部分。

参数层级	字段名	类型	说明	示例值
请求头	X-Request-Id	String	全局唯一请求标识，用于链路追踪	a1b2c3d4-1234-5678-9abc-def012345678
请求头	X-Timestamp	Long	客户端时间戳（毫秒），用于防重放	1712563200000
请求体	userId	String	用户标识，长度 8~32 字符	U20240315001
请求体	productId	String	产品标识，长度 6~20 字符	P10086
请求体	features	Map<String, Double>	特征因子键值对，至少包含 3 个因子	{"f1": 85.5, "f2": 92.0, "f3": 78.3}
请求体	channel	String	渠道编码，可选字段，默认 "default"	app_android

性能测试要点： 压测时需覆盖不同长度的 userId/productId，以及不同数量的 features 键值对（3~20 个），以验证序列化/反序列化性能边界。

3.2 评分规则与计算流程

评分引擎采用加权线性模型，辅以非线性截断与归一化处理。完整计算流程分为 4 个步骤：

特征提取与校验：从 features 中提取所有已注册因子，缺失因子按默认值 0.0 填充。
因子归一化：每个原始因子值通过 Sigmoid 函数映射到 [0, 1] 区间，公式为 norm = 1 / (1 + exp(-raw / 100))。
加权求和：将归一化后的因子值乘以对应权重，累加得到原始总分。
分数截断与映射：原始总分乘以 1000 后，截断到 [0, 999] 整数区间，作为最终评分。

  评分公式：

  score = min(max(Σ(weight_i × sigmoid(feature_i / 100)) × 1000, 0), 999)

3.3 因子权重配置

权重表由业务方定期调整，通过配置中心下发。性能测试需使用当前生产环境权重快照。以下为典型权重配置示例：

因子编码	因子名称	权重值	权重占比	说明
f1	用户活跃度	0.35	35%	近 30 天登录频次归一化
f2	历史转化率	0.25	25%	历史订单转化比例
f3	信用评分	0.20	20%	第三方信用分映射
f4	设备稳定性	0.12	12%	设备指纹异常次数
f5	网络环境分	0.08	8%	IP 归属地 & 代理检测

权重变更风险： 压测期间若权重发生热更新，评分结果会偏移。建议在压测前锁定权重版本号，并在测试报告中记录权重快照的 MD5 值。

3.4 输出格式规范

接口返回统一 JSON 结构，包含评分结果、因子明细与耗时信息。性能测试需重点验证序列化耗时与字段完整性。

{
  "code": 0,
  "message": "success",
  "data": {
    "score": 785,
    "version": "v2.3.1",
    "weightMd5": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    "details": [
      {"factor": "f1", "raw": 85.5, "norm": 0.702, "weight": 0.35, "contribute": 0.2457},
      {"factor": "f2", "raw": 92.0, "norm": 0.716, "weight": 0.25, "contribute": 0.1790},
      {"factor": "f3", "raw": 78.3, "norm": 0.687, "weight": 0.20, "contribute": 0.1374}
    ],
    "elapsedMs": 1.23
  }
}

字段	类型	说明	性能关注点
code	int	业务状态码，0 成功	压测需统计非 0 码比例
data.score	int	最终评分 [0, 999]	验证分数分布是否符合预期
data.details	array	每个因子的原始值、归一值、权重、贡献值	数组长度影响序列化大小
data.elapsedMs	double	服务端内部计算耗时（毫秒）	用于拆解接口响应时间构成

3.5 业务逻辑对性能测试的影响

理解业务逻辑后，性能测试需重点关注以下 4 个方面：

特征数量波动：features 中因子数量从 3 到 20 不等，归一化与加权求和的计算量线性增长，需测试不同数量级下的吞吐量。
权重热更新：权重配置中心推送可能导致计算过程中权重不一致，需验证接口在更新期间的原子性。
序列化开销：details 数组包含每个因子的明细，因子越多 JSON 序列化耗时越长，建议压测时监控序列化/反序列化耗时。
分数截断边界：边界值 0 和 999 的输入组合需纳入测试用例，验证截断逻辑正确性。

  测试建模建议： 将输入参数、权重配置、输出格式三者固化为 JSON Schema，压测脚本直接从 Schema 生成动态请求，确保每次压测的请求结构符合生产规范。