4. 幂等键（Idempotency-Key）设计

幂等键是任务调度平台实现接口幂等性的核心机制。客户端在发起关键操作（如创建任务、触发执行、修改配置）时，携带一个全局唯一的幂等键；服务端根据该键识别重复请求，确保同一键值仅被处理一次。本章从HTTP头规范、生成策略和生命周期管理三个维度展开设计实践。

4.1 HTTP头规范：Idempotency-Key 标准定义

幂等键通过自定义HTTP请求头 Idempotency-Key 传递。遵循RESTful最佳实践，该头应满足以下规范：

4.2 生成策略：UUID vs 业务ID+时间戳

幂等键的生成策略直接影响去重效果和系统复杂度。主流方案有两种：

• UUID v4 随机方案：客户端生成随机UUID，碰撞概率极低，实现简单。适用于无业务上下文的通用场景。
• 业务ID + 时间戳组合方案：将任务ID、操作类型、时间戳拼接后哈希。适用于需要业务可追溯、支持幂等键重用的场景。

// 业务ID+时间戳生成幂等键示例（Java）
public String generateIdempotencyKey(String taskId, String operation, long timestamp) {
    String raw = taskId + "_" + operation + "_" + timestamp;
    MessageDigest md = MessageDigest.getInstance("SHA-256");
    byte[] hash = md.digest(raw.getBytes(StandardCharsets.UTF_8));
    // 取前16字节，转32位十六进制字符串
    return bytesToHex(Arrays.copyOf(hash, 16));
}

4.3 生命周期管理：存储、过期与清理

幂等键的生命周期管理是保证系统可靠性和存储效率的关键。核心环节包括：

• 存储结构：使用Redis或内存数据库，以幂等键为key，存储首次请求的响应状态码、响应体、时间戳。
• 过期策略：设置TTL（Time-To-Live），默认24小时。任务调度场景建议延长至48小时，覆盖重试窗口。
• 清理机制：定期扫描过期键，释放存储空间。对于业务ID组合方案，可主动清理已完成的幂等键。
• 并发控制：使用Redis SETNX或分布式锁，防止同一幂等键的并发请求导致重复处理。

// Redis存储幂等键示例（伪代码）
public Response handleWithIdempotency(String idempotencyKey, Request request) {
    // 1. 尝试写入幂等键，仅当key不存在时成功
    boolean acquired = redis.setnx(idempotencyKey, "PROCESSING", 48, TimeUnit.HOURS);
    if (!acquired) {
        // 2. 键已存在，返回之前存储的响应
        return redis.get(idempotencyKey + ":response");
    }
    try {
        // 3. 执行业务逻辑
        Response response = processRequest(request);
        // 4. 存储响应结果
        redis.set(idempotencyKey + ":response", response, 48, TimeUnit.HOURS);
        return response;
    } catch (Exception e) {
        // 5. 失败时删除幂等键，允许重试
        redis.delete(idempotencyKey);
        throw e;
    }
}

4.4 幂等键生命周期流程图

下图展示了幂等键从生成、存储、校验到过期的完整生命周期：

4.5 幂等键存储架构图

在任务调度平台中，幂等键的存储架构通常采用分层设计，兼顾性能与可靠性：

4.6 幂等键设计检查清单

在任务调度平台中落地幂等键时，建议逐项核对以下要点：