3. 接口设计原则：RESTful API设计规范、接口幂等性、请求与响应格式约定

实时欺诈评分接口作为风控系统的核心入口，其设计质量直接影响系统的可维护性、调用方集成效率以及数据一致性。本章围绕RESTful API设计规范、接口幂等性保障、请求与响应格式约定三个核心维度展开，帮助开发者构建标准化、高可用的评分接口。

3.1 RESTful API设计规范

REST（Representational State Transfer）是一种基于HTTP协议的架构风格，强调资源导向、无状态通信和统一接口。在实时欺诈评分场景中，我们将“评分请求”视为一种资源操作，遵循以下设计原则：

3.2 接口幂等性设计

幂等性（Idempotency）是指同一操作多次执行产生的结果与执行一次相同。在实时欺诈评分场景中，网络重试、消息重复投递等异常情况可能导致同一笔交易被重复评分，进而产生重复的扣分、冻结或风控记录。幂等性设计是保障数据一致性的关键防线。

3.2.1 幂等性实现策略

3.2.2 幂等性处理流程

以下是一个基于请求ID的幂等性处理伪代码示例：

// 幂等性校验核心逻辑
public FraudScoreResponse handleScoreRequest(ScoreRequest request) {
    String idempotencyKey = request.getIdempotencyKey();

    // 1. 检查缓存中是否已存在该请求的处理结果
    FraudScoreResponse cachedResult = cacheService.get(idempotencyKey);
    if (cachedResult != null) {
        return cachedResult;  // 直接返回历史结果，避免重复处理
    }

    // 2. 尝试写入数据库（利用唯一约束防止并发重复写入）
    try {
        // 执行评分逻辑
        FraudScore score = fraudEngine.evaluate(request);
        FraudScoreResponse response = buildResponse(score);

        // 写入评分记录表（idempotency_key 字段有唯一索引）
        scoreRepository.insertWithUniqueKey(idempotencyKey, response);

        // 3. 写入缓存，设置过期时间（如24小时）
        cacheService.set(idempotencyKey, response, Duration.ofHours(24));

        return response;
    } catch (DuplicateKeyException e) {
        // 唯一键冲突：说明其他请求已写入成功，查询并返回已有结果
        return scoreRepository.queryByIdempotencyKey(idempotencyKey);
    }
}

3.3 请求与响应格式约定

统一的请求与响应格式能够降低调用方的集成成本，提升接口的可读性和可维护性。以下是在实时欺诈评分接口中推荐的格式规范。

3.3.1 请求格式

{
  "idempotencyKey": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "transaction": {
    "orderId": "ORD20250321001",
    "amount": 2999.00,
    "currency": "CNY",
    "timestamp": "2025-03-21T14:30:00+08:00"
  },
  "payer": {
    "userId": "U12345678",
    "phone": "138****5678",
    "email": "user@example.com",
    "deviceFingerprint": "FP_ABC123XYZ"
  },
  "payee": {
    "merchantId": "M98765432",
    "merchantName": "示例商户"
  },
  "additionalInfo": {
    "ipAddress": "192.168.1.100",
    "userAgent": "Mozilla/5.0 ...",
    "billingAddress": "北京市朝阳区..."
  }
}

3.3.2 响应格式

{
  "code": 200,
  "message": "success",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "score": 85,
    "riskLevel": "HIGH",
    "decision": "REJECT",
    "hitRules": [
      {
        "ruleId": "R001",
        "ruleName": "高频交易检测",
        "riskScore": 40
      },
      {
        "ruleId": "R007",
        "ruleName": "异地登录检测",
        "riskScore": 30
      }
    ],
    "processingTimeMs": 156
  }
}

3.4 错误处理与异常响应

当接口发生错误时，应返回统一的错误响应格式，帮助调用方快速定位问题。以下为推荐的错误响应结构：

{
  "code": 400,
  "message": "参数校验失败",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "errors": [
    {
      "field": "transaction.amount",
      "message": "交易金额必须大于0"
    },
    {
      "field": "payer.userId",
      "message": "用户ID不能为空"
    }
  ]
}