📚 课程目录第3章特征采集原理

3. 特征采集原理：请求链路中的特征采集点、特征字段定义、特征值格式规范

特征采集是风险网关的“眼睛”。如果采集点错位、字段定义模糊或格式不统一，后续的巡检规则和模型将失去判断基础。本章从请求全链路出发，明确特征在哪里采、采什么、怎么存。

3.1 请求链路中的特征采集点

一次完整的业务请求从客户端到达后端服务，会经过多个网络与中间件节点。风险网关需要在以下关键位置埋点，捕获原始特征：

采集阶段	典型节点	可采集特征示例	采集时机
入口网关	Nginx / Kong / APISIX	源 IP、User-Agent、Referer、请求方法、URL 路径	TCP 连接建立后，HTTP 头部解析完成时
应用防火墙	WAF / ModSecurity	请求体大小、Content-Type、SQL/XSS 攻击签名命中数	请求体完全接收并解码后
身份认证	OAuth2 / JWT 网关	Token 类型、用户 ID、角色、会话有效期	Token 校验通过后，业务路由前
限流熔断	Sentinel / Hystrix 中间件	当前 QPS、滑动窗口拒绝数、熔断状态	每次请求计数更新时
业务路由	Spring Cloud Gateway / Envoy	目标服务名、路由规则版本、请求超时时间	路由匹配完成后，转发前
响应出口	反向代理 / 响应过滤器	HTTP 状态码、响应体大小、响应耗时	响应头部生成后，发送给客户端前

巡检要点： 特征缺失巡检的核心是检查每个采集点是否按规范上报了字段。例如入口网关必须上报 source_ip 和 user_agent，如果日志中这两个字段为空或格式异常，应立即告警。

下图展示了请求从客户端到后端服务的完整链路，以及各采集点的位置关系：

3.2 特征字段定义

每个采集点输出的特征必须遵循统一的字段定义。以下是风险网关核心特征字段的规范清单：

字段名	类型	采集点	说明	是否必填
`request_id`	string	入口网关	全局唯一请求标识，UUID v4 格式	是
`source_ip`	string	入口网关	客户端真实 IP，IPv4 或 IPv6	是
`user_agent`	string	入口网关	原始 User-Agent 字符串，不做截断	是
`http_method`	string	入口网关	GET / POST / PUT / DELETE 等	是
`request_path`	string	入口网关	URL 路径，不含 query string	是
`query_params`	string	入口网关	URL 查询参数，JSON 序列化	否
`body_size`	int	WAF	请求体字节数	是
`content_type`	string	WAF	Content-Type 头部值	是
`attack_score`	int	WAF	攻击检测评分，0-100	是
`user_id`	string	身份认证	认证后的用户唯一标识	是
`token_type`	string	身份认证	Bearer / Basic / OAuth	是
`current_qps`	float	限流熔断	当前服务实例的 QPS 值	是
`circuit_breaker_state`	string	限流熔断	CLOSED / OPEN / HALF_OPEN	是
`target_service`	string	业务路由	路由目标服务名	是
`http_status`	int	响应出口	HTTP 响应状态码	是
`response_time_ms`	int	响应出口	从入口到出口的总耗时，毫秒	是

常见缺失问题： 巡检中发现 user_agent 字段常被截断为 128 字符，导致指纹计算偏差；query_params 字段因未序列化而存储为原始字符串，造成下游解析失败。必须按规范严格约束字段格式。

3.3 特征值格式规范

特征值格式直接影响巡检规则的匹配效率和模型训练的稳定性。以下为各类特征值的格式要求：

3.3.1 字符串类型

编码： 统一使用 UTF-8 编码，禁止 GBK、ISO-8859-1 等非 Unicode 编码。
长度： 单字段最大长度不超过 4096 字符，超出部分截断并记录截断标记 _TRUNCATED。
转义： 包含特殊字符（如引号、反斜杠）时，使用 JSON 标准转义。

3.3.2 数值类型

整数： 使用 64 位有符号整数，范围 -2^63 到 2^63-1。
浮点数： 保留 2 位小数，使用 %.2f 格式化，避免科学计数法。
布尔值： 使用 true / false 小写字符串，禁止 0/1 或 yes/no。

3.3.3 时间类型

格式： ISO 8601 标准，如 2025-03-21T14:30:00.000Z。
时区： 统一使用 UTC 时间，禁止使用本地时间。
精度： 毫秒级，3 位小数。

3.3.4 枚举类型

定义： 所有枚举值必须在特征字典中预定义，禁止动态新增。
大小写： 统一使用大写字母 + 下划线，如 CIRCUIT_OPEN。
未知值： 使用 UNKNOWN 作为兜底值，不允许空字符串。

格式校验示例： 以下为一段符合规范的特征 JSON 输出：

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "source_ip": "192.168.1.100",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "http_method": "POST",
  "request_path": "/api/v1/order/create",
  "body_size": 2048,
  "attack_score": 0,
  "user_id": "user_98765",
  "current_qps": 1250.50,
  "circuit_breaker_state": "CLOSED",
  "http_status": 200,
  "response_time_ms": 45
}

下图展示了特征字段从采集到格式化的完整流程：

3.4 特征缺失巡检的切入点

基于上述采集原理，特征缺失巡检应重点关注以下三类场景：

字段缺失： 必填字段在日志或消息中不存在，如 request_id 为空。
格式异常： 字段值不符合规范，如 source_ip 包含非 IP 字符、response_time_ms 为负数。
采集点遗漏： 某个采集点完全未上报特征，如限流熔断节点未输出 current_qps。

实战建议： 在巡检系统中建立“特征完整性基线”，将每个采集点的必填字段列表作为配置项。当某采集点的上报字段与基线偏差超过阈值时，自动触发告警并生成巡检报告。