4. 数据采集与埋点：网关日志结构设计、关键字段定义、实时数据流接入

实时风控网关的拦截策略效果评估，其数据基础完全依赖于网关层输出的高质量日志。本章将深入讲解网关日志的结构化设计、关键字段的定义标准，以及如何通过 Kafka 与 Flink 构建高吞吐、低延迟的实时数据流接入管道。

4.1 网关日志结构设计原则

网关日志是风控策略评估的“第一手证据”，其设计需遵循以下原则：

• 扁平化：避免深层嵌套，便于 Flink 直接解析与处理。
• 高覆盖：包含请求上下文、策略执行过程、响应结果三要素。
• 可追溯：每条日志必须携带全局唯一的 TraceID，串联上下游链路。
• 低冗余：敏感信息（如密码、Token）脱敏或截断，仅保留必要特征。

4.2 关键字段定义与数据字典

一个标准的实时风控网关日志，应包含以下五大类核心字段。下表定义了每个字段的用途与示例：

4.3 实时数据流接入架构

为了支撑毫秒级的策略评估与秒级的聚合分析，我们采用 Kafka + Flink 的经典流处理架构。网关作为生产者，将结构化日志发送至 Kafka 集群；Flink 作为消费者，从 Kafka 拉取数据并进行实时清洗、聚合与指标计算。

4.4 网关日志生产端埋点实现

在网关过滤器（Filter）或中间件中，通过 AOP 切面统一采集日志。以下是一个简化的 Java 伪代码示例，展示如何构建标准日志对象并发送至 Kafka：

// 网关过滤器核心埋点逻辑
public class RiskLogFilter implements GlobalFilter {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        long startTime = System.currentTimeMillis();
        String traceId = UUID.randomUUID().toString();
        // 注入 TraceID 到请求上下文
        exchange.getAttributes().put("trace_id", traceId);

        return chain.filter(exchange).then(Mono.fromRunnable(() -> {
            // 构建日志对象
            RiskLog log = new RiskLog();
            log.setTraceId(traceId);
            log.setClientIp(getClientIp(exchange));
            log.setApiPath(exchange.getRequest().getURI().getPath());
            log.setUserId(extractUserId(exchange));
            log.setDecision((String) exchange.getAttribute("risk_decision"));
            log.setRuleIds((List<String>) exchange.getAttribute("matched_rules"));
            log.setExecutionTimeMs(System.currentTimeMillis() - startTime);
            log.setHttpStatus(exchange.getResponse().getStatusCode().value());
            log.setTimestamp(System.currentTimeMillis());

            // 异步发送至 Kafka
            kafkaTemplate.send("risk_gateway_log", JSON.toJSONString(log));
        }));
    }
}

4.5 Flink 实时数据接入与预处理

Flink 作业从 Kafka 消费原始日志后，需进行必要的清洗与字段补全，才能进入后续的指标计算环节。典型的预处理流程包括：

• 反序列化：将 JSON 字符串解析为 Flink 的 Row 或 POJO 对象。
• 脏数据过滤：丢弃 trace_id 为空、时间戳异常的数据。
• 字段补全：根据 client_ip 查询 IP 库，补充地理位置标签。
• 水位线分配：基于 @timestamp 字段设置事件时间水位线，用于窗口聚合。

4.6 数据质量保障要点