Spring Boot 金融实战：如何清洗天远API的 KV 数组格式风控数据

一、构建精细化的信贷审批"流水线"

在银行核心信贷系统或消费金融的风控中台（Risk Decision Engine）构建中，单一的"黑名单"查询已无法满足差异化的客群经营需求。业务部门往往需要更细粒度的数据来支撑决策：比如，一个申请人虽然有多次借贷记录，但如果是"银行系"借贷，可能代表其信用良好；若是高频的"互金系"或"夜间"申请，则风险倍增。

天远API 的"多头借贷行业风险版"接口，通过输出 5大维度风险评分 （如银行分、非银分）和 分行业/分时段 的行为统计，为 Java 后端开发者提供了丰富的数据原料。然而，该接口返回的 List<KV> 结构数据在 Java 这种强类型语言中处理稍显繁琐。本文将提供一套标准化的 Java 接入方案，涵盖 AES-128 安全传输、响应数据的 POJO 映射及 Map 化清洗策略，帮助开发者高效集成这一关键风控能力。

二、API接口调用示例（Java版）

本接口要求严格的 AES-128-CBC 加密通信。在 Java 企业级开发中，我们通常会封装通用的 AesUtil 工具类，并结合 RestTemplate 或 HttpClient 发起请求。

1. 接口配置参数

• 服务地址 ：https://api.tianyuanapi.com/api/v1/DWBG7F3A
• 请求方式：POST
• 鉴权方式 ：HTTP Header (Access-Id) + Body (data 密文)

2. Curl 连通性测试

在编写 Java 代码前，确保您的服务器网络策略允许访问天远域名：

Bash

curl -X POST "<https://api.tianyuanapi.com/api/v1/DWBG7F3A?t=1716345678000>" \
  -H "Content-Type: application/json" \
  -H "Access-Id: YOUR_ACCESS_ID" \
  -d '{"data": "Encrypted_Base64_String..."}'

3. Java 完整接入代码

本示例模拟了一个 Spring Boot 服务中的 Service 层实现。为了处理接口返回的"对象数组"结构，我们利用 Jackson 库将其转换为 Map<String, String>，以便通过 Key（如 41001）实现 O(1) 复杂度的快速读取。

Java

import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import javax.crypto.Cipher;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.security.SecureRandom;
import java.util.*;
import java.util.stream.Collectors;

/**
 * 天远行业风险API 对接服务类
 */
public class IndustryRiskService {

    private static final String API_URL = "<https://api.tianyuanapi.com/api/v1/DWBG7F3A>";
    private static final String ACCESS_ID = "YOUR_ACCESS_ID";
    private static final String ACCESS_KEY = "YOUR_ACCESS_KEY_HEX"; // 16字节16进制字符串

    public static void main(String[] args) {
        try {
            // 1. 模拟业务调用
            Map<String, String> riskData = queryRiskProfile("李四", "110101199001011234", "13900000000");
            
            if (riskData != null) {
                System.out.println("=== 风险画像解析结果 ===");
                System.out.println("多头通用分(41001): " + riskData.getOrDefault("41001", "0"));
                System.out.println("银行系多头分(41005): " + riskData.getOrDefault("41005", "0"));
                System.out.println("近7天深夜申请次数(40105): " + riskData.getOrDefault("40105", "0"));
                
                // 简单的风控规则示例
                int nightApply = Integer.parseInt(riskData.getOrDefault("40105", "0"));
                if (nightApply > 3) {
                    System.err.println("[警告] 检测到高频夜间申请行为，建议转人工审核！");
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

    /**
     * 查询并清洗数据
     * @return Key为风险Code(如41001), Value为数值的Map
     */
    public static Map<String, String> queryRiskProfile(String name, String idCard, String mobile) throws Exception {
        // 1. 组装参数
        Map<String, String> params = new HashMap<>();
        params.put("name", name);
        params.put("id_card", idCard);
        params.put("mobile_no", mobile);

        // 2. 加密
        String encryptedData = AesUtil.encrypt(new ObjectMapper().writeValueAsString(params), ACCESS_KEY);

        // 3. 发送请求
        String responseJson = sendPost(encryptedData);
        
        // 4. 解析响应
        ObjectMapper mapper = new ObjectMapper();
        Map<String, Object> respMap = mapper.readValue(responseJson, new TypeReference<Map<String, Object>>() {});

        if ((int) respMap.get("code") == 0) {
            String encryptedResult = (String) respMap.get("data");
            String decryptedJson = AesUtil.decrypt(encryptedResult, ACCESS_KEY);
            
            // 5. 核心：将 List<KV> 结构转化为 Map<Code, Value>
            Map<String, Object> rawData = mapper.readValue(decryptedJson, new TypeReference<Map<String, Object>>() {});
            List<Map<String, Object>> reportList = (List<Map<String, Object>>) rawData.get("riskInfo_report_v3.1");

            // 使用 Stream API 进行清洗
            return reportList.stream().collect(Collectors.toMap(
                    item -> String.valueOf(item.get("riskCode")),
                    item -> String.valueOf(item.get("riskCodeValue")),
                    (v1, v2) -> v1 // 键冲突处理
            ));
        } else {
            System.err.println("API调用失败: " + respMap.get("message"));
            return null;
        }
    }

    // --- HTTP工具方法 (建议在生产环境使用 OkHttp/RestTemplate) ---
    private static String sendPost(String encryptedData) throws Exception {
        URL url = new URL(API_URL + "?t=" + System.currentTimeMillis());
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("POST");
        conn.setRequestProperty("Content-Type", "application/json");
        conn.setRequestProperty("Access-Id", ACCESS_ID);
        conn.setDoOutput(true);

        String body = "{\"data\": \"" + encryptedData + "\"}";
        try (OutputStream os = conn.getOutputStream()) {
            os.write(body.getBytes(StandardCharsets.UTF_8));
        }
        
        try (BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8))) {
            return br.lines().collect(Collectors.joining());
        }
    }

    // --- AES 加解密工具类 ---
    static class AesUtil {
        public static String encrypt(String content, String key) throws Exception {
            byte[] keyBytes = key.getBytes(StandardCharsets.UTF_8);
            byte[] iv = new byte[16];
            new SecureRandom().nextBytes(iv); // 随机IV

            Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
            cipher.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(keyBytes, "AES"), new IvParameterSpec(iv));
            
            byte[] encrypted = cipher.doFinal(content.getBytes(StandardCharsets.UTF_8));
            byte[] combined = new byte[iv.length + encrypted.length];
            System.arraycopy(iv, 0, combined, 0, iv.length);
            System.arraycopy(encrypted, 0, combined, iv.length, encrypted.length);
            
            return Base64.getEncoder().encodeToString(combined);
        }

        public static String decrypt(String content, String key) throws Exception {
            byte[] decoded = Base64.getDecoder().decode(content);
            byte[] iv = Arrays.copyOfRange(decoded, 0, 16);
            byte[] cipherText = Arrays.copyOfRange(decoded, 16, decoded.length);

            Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
            cipher.init(Cipher.DECRYPT_MODE, new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "AES"), new IvParameterSpec(iv));
            
            return new String(cipher.doFinal(cipherText), StandardCharsets.UTF_8);
        }
    }
}

三、核心数据结构解析

Java 是强类型语言，理解数据结构是定义 DTO（数据传输对象）的基础。天远API 的响应设计非常独特，它没有使用扁平的 JSON 字段（如 bank_score: 80），而是采用了一个KV 对象数组。

1. 原始 JSON 结构

JSON

{
  "riskInfo_report_v3.1": [
    { "riskCode": 41001, "riskCodeValue": 43 },
    { "riskCode": "40105", "riskCodeValue": "1" },
    ...
  ]
}

2. Java 处理策略

直接操作 List 进行遍历查找效率较低（时间复杂度 O(n)）。在 Java 业务层中，最佳实践是在获取数据后立即将其转换为 Map<String, String> 或 HashMap（如上述代码所示）。这样后续在Drools规则引擎或代码中，可以通过 map.get("41001") 以 O(1) 的效率直接获取指标。

四、字段详解（分行业与分时段）

以下表格梳理了 Java 后端风控系统在进行"客群分层"和"准入判断"时最常用的核心字段。

1. 风险评分维度（Risk Scores）

RiskCode (Key)	含义	类型	业务逻辑建议
41001	多头申请通用分	Integer (0-100)	全局风控基准分，分数越高风险越大。
41005	银行多头共债子分	Integer (0-100)	衡量在传统金融机构的负债压力。若此分高，建议查询征信详版。
41004	非银行多头共债子分	Integer (0-100)	衡量在P2P、小贷、互金平台的共债压力。高分通常意味着资质下沉。

2. 细分行为维度（Behavior Stats）

RiskCode (Key)	含义	说明	风险信号
40002	7天内银行申请次数	行业=银行	正常融资需求，容忍度较高。
40004	7天内互金申请次数	行业=互金	急借贷信号，容忍度低。
40105	7天总申请夜晚次数	时间=0点-7点	高危欺诈指标。正常人极少在凌晨批量申请贷款。
40161	7天新增总平台数	突发性	相比过去30天，最近7天是否突然"撸"了很多新口子。

五、应用价值分析

对于使用 Java 构建后端服务的金融机构，集成天远API的行业风险版数据具有深远的业务价值：

1. 精细化定价（Risk-Based Pricing）：

   在核额系统中，可以根据 41005（银行分）和 41004（非银分）的比例进行差异化定价。

   • 场景：若用户银行分低、非银分高，说明其主要混迹于高息平台，风险成本高，系统应自动提高贷款利率（如年化24%）。
   • 场景：若用户银行分高、非银分低，说明是优质客群，可提供优惠利率（如年化8%）以留存客户。

2. 工作流引擎集成（Activiti/Camunda）：

   在 Java 工作流中，可以将 API 查询作为一个 ServiceTask。

   • 定义规则：riskData.get("40105") > 2（7天内有2次以上凌晨申请）。
   • 执行动作：流程自动跳转至"人工反欺诈调查"节点，而非直接拒单或通过。

3. 存量客户预警：

   利用 Java 的 ScheduledExecutorService 定期跑批。关注 41002（短周期分）的突变。如果某存量客户的短周期分数突然飙升，说明其近期资金链极度紧张，可能即将发生违约，系统应及时冻结额度。

六、总结

天远多头借贷行业风险版 API 提供了超越传统黑名单的"高分辨率"风险画像。对于 Java 开发者而言，核心工作在于封装安全可靠的 AES 加解密组件 以及构建高效的 Map 化数据清洗逻辑。

通过将 41005（银行分）、40105（夜间申请）等原子指标输入到企业的风控模型中，您将能够构建出一个既能防范欺诈风险，又能精准识别优质客户的智能信贷系统。