Node.js AES加密解析天远风控API，构建前端可用的风控服务

在金融科技（Fintech）领域，快速构建和迭代产品至关重要。凭借其非阻塞I/O模型和丰富的npm生态，Node.js已成为构建BFF层或Serverless云函数的理想选择，非常适合处理来自多种前端客户端的请求。当我们需要对接像天远风控决策接口（JRZQ3P01） 这类返回标准JSON格式数据的服务时，Node.js可谓得心应手。

然而，出于金融数据安全性的极高要求，此类接口通常会对传输内容进行加密。天远风控采用的便是 AES-128-CBC 加密机制。这对于习惯了处理纯文本JSON的前端或全栈开发者来说，涉及到的二进制Buffer、IV向量和Base64编解码可能会带来一些挑战。本文将详细介绍如何仅使用Node.js原生模块，优雅地完成整个对接流程，将加密的风控数据转化为前端可直接消费的业务状态。

使用原生Crypto模块对接加密API

我们推荐使用流行的 axios 库处理HTTP请求，配合Node.js内置的 crypto 模块进行加解密。这套组合方案无需引入臃肿的第三方加密库，既轻量又标准。

环境准备

首先，安装 axios。crypto 是Node.js的内置模块，无需额外安装。

npm install axios

完整代码实现

以下代码封装了一个 TianyuanRiskClient 类，它自动处理了AES-128-CBC加密、解密、PKCS7填充（Node.js crypto 默认支持）以及IV与密文的Base64拼接逻辑。

const axios = require('axios');
const crypto = require('crypto');

class TianyuanRiskClient {
    constructor(accessId, accessKeyHex) {
        this.apiUrl = 'https://api.tianyuanapi.com/api/v1/JRZQ3P01';
        this.accessId = accessId;
        // 关键步骤：将配置的16进制字符串密钥转换为Buffer对象
        this.accessKey = Buffer.from(accessKeyHex, 'hex');
    }

    /**
     * 数据加密流程：
     * 1. 生成随机16字节IV向量
     * 2. 使用 AES-128-CBC 模式加密（默认PKCS7填充）
     * 3. 将 IV 和密文拼接后转换为Base64字符串
     */
    encrypt(data) {
        const iv = crypto.randomBytes(16);
        const cipher = crypto.createCipheriv('aes-128-cbc', this.accessKey, iv);

        const plainText = JSON.stringify(data);
        let encrypted = cipher.update(plainText, 'utf8');
        encrypted = Buffer.concat([encrypted, cipher.final()]);

        const combined = Buffer.concat([iv, encrypted]);
        return combined.toString('base64');
    }

    /**
     * 数据解密流程
     */
    decrypt(base64Data) {
        const buffer = Buffer.from(base64Data, 'base64');
        const iv = buffer.slice(0, 16); // 前16字节是IV
        const text = buffer.slice(16);  // 之后是密文

        const decipher = crypto.createDecipheriv('aes-128-cbc', this.accessKey, iv);
        let decrypted = decipher.update(text);
        decrypted = Buffer.concat([decrypted, decipher.final()]);

        return JSON.parse(decrypted.toString());
    }

    /**
     * 核心风控查询方法
     */
    async queryRisk(name, idCard) {
        try {
            // 1. 准备并加密请求数据
            const payload = { name, id_card: idCard };
            const encryptedData = this.encrypt(payload);

            // 2. 发起API请求
            const response = await axios.post(
                this.apiUrl, 
                { data: encryptedData }, // 请求体字段固定为 `data`
                {
                    headers: { 'Access-Id': this.accessId },
                    params: { t: Date.now() } // 时间戳参数，防止重放攻击
                }
            );

            const resData = response.data;

            // 3. 处理响应
            if (resData.code === 0) {
                // 成功：解密返回的数据
                const realData = this.decrypt(resData.data);
                console.log('✅ 风控查询成功');
                return realData;
            } else {
                console.error(`❌ API 错误: ${resData.message} (Code: ${resData.code})`);
                return null;
            }
        } catch (error) {
            console.error('网络请求异常:', error.message);
            return null;
        }
    }
}

// --- 调用示例 ---
(async () => {
    // ⚠️ 生产环境请务必从环境变量(process.env)等安全渠道读取密钥
    const client = new TianyuanRiskClient(
        'YOUR_ACCESS_ID', 
        'YOUR_HEX_KEY_STRING' // 十六进制格式的密钥字符串
    );

    const result = await client.queryRisk('李四', '33010619850101xxxx');

    if (result) {
        console.log('审核建议:', result.reviewSuggestions);
        console.log('详细数据:', result);
    }
})();

解析风控数据结构：避开JS类型陷阱

成功解密后，我们获得了结构扁平的JSON数据，这非常便于使用解构赋值。但JavaScript的动态类型特性在此处有几个关键陷阱需要特别注意，这对于全栈开发者尤为重要。

响应字段概览

const { 
    reviewSuggestions, // 核心审核建议，值为 A-F
    blackOrgNum,       // 关联的黑名单机构数量，可能为 “>3” 这样的字符串
    loanTypes,         // 借贷类型偏好对象
    lastCondition      // 近期风险标签对象
} = result;

“布尔值”实为字符串

这是最容易导致业务逻辑错误的点。在 lastCondition 和 loanTypes 对象中，字段值 “1” 表示命中该风险项，“0” 表示未命中。请注意，它们是 String 类型，而非 Number 或 Boolean。

• 错误写法：

  if (result.lastCondition.fraud) { 
      // 危险！字符串 "0" 在JS条件判断中也为真(true)！
      // 这将导致系统误判用户存在欺诈风险
  }

• 正确写法：

  const isFraud = result.lastCondition.fraud === '1';
  const isSeriousOverdue = result.lastCondition.seriousOverdue === '1';

关键字段映射与处理建议

字段名	JS 类型	含义	业务逻辑处理建议
reviewSuggestions	String	最终审核建议	前端可映射为颜色状态：A/B -> 红色(拒绝)，C/D -> 黄色(警告)，E -> 绿色(通过)。
overdueAmt	String	历史逾期总金额	可能返回如 “>8000”。建议用正则提取数字 parseInt(val.match(/\d+/)[0]) 用于排序或阈值判断。
blackOrgNum	String	黑名单机构数	多头借贷的重要指标，值越大风险越高，可直接用于风险评分。

应用场景拓展：Serverless与BFF实践

在Node.js生态中，我们可以将上述封装好的客户端应用于多种现代架构场景。

场景一：构建Serverless云函数

你可以将上述代码部署为AWS Lambda、腾讯云SCF或阿里云FC等Serverless函数。由于天远API按次计费，配合Serverless的按量计费模式，可以完美实现 “零闲置成本” 的风控能力，只在有贷款申请时产生费用。

场景二：BFF层的数据清洗与格式化

前端应用无需关心加密细节。我们可以在Node.js构建的BFF（面向前端的后端）层完成所有“脏活累活”：

1. 调用天远API并解密数据。
2. 数据清洗：将 “1”/“0” 转换为 true/false，将 reviewSuggestions: “A” 转换为结构化的 { status: “REJECT”, message: “严重逾期”, color: “#f5222d” }。
3. 向前端返回干净、友好、可直接用于渲染的JSON数据。

场景三：集成熔断机制提升稳定性

使用 opossum 等熔断库包装 queryRisk 方法。如果因网络波动导致API连续超时或失败，服务可以快速进入熔断状态（Fail Fast），并返回预设的兜底策略（例如“转人工审核”），避免用户前端长时间等待，提升系统整体韧性。这体现了良好的微服务设计思想。

总结

Node.js原生加密能力与天远风控API的结合，为构建轻量、高效的信贷审批中间层提供了优秀方案。通过crypto模块，我们能安全高效地打通数据链路；利用JavaScript灵活的数据处理能力，可轻松将原始风控标签转化为直观的业务洞察，供前端或下游系统使用。

最后的安全与成本提醒：

• 安全第一：Access Key是最高机密，必须存储在后端或云函数的环境变量中，严禁泄露到前端代码或仓库。
• 成本控制：API调用会产生费用，在开发调试阶段，强烈建议使用Mock数据模拟接口响应，避免不必要的开销。

示意图：数据从加密API到前端展示的转化流程