幂等机制

1. 概述

本平台写操作接口均支持幂等调用。幂等性保证相同请求在 24 小时内重复提交不会导致重复操作，而是返回首次处理的结果。requestId 为全接口统一必传参数：写操作接口用作幂等键；查询类接口不参与幂等去重，用于请求链路追踪与日志关联。

2. 幂等键规则

幂等键构成：

幂等键 = accessKey + method + requestId

• method 为接口路径（如 /open-api/v1/xxx/xxx），用于区分不同业务操作
• 幂等缓存有效期：24 小时
• 超过 24 小时后 requestId 可复用（但不建议）

3. requestId 生成规范

建议格式：req_ + 时间戳（毫秒） + 随机串，或直接使用标准 UUID。

import uuid
import time
import random
import string

# 推荐方式 1
def generate_request_id():
    return "req_" + str(int(time.time() * 1000)) + "_" + ''.join(random.choices(string.ascii_lowercase + string.digits, k=8))

# 推荐方式 2（标准 UUID）
def generate_request_id_uuid():
    return str(uuid.uuid4())

约束：

• 长度 ≤ 64 字符
• 仅支持字母、数字、下划线、中划线
• 幂等键已包含接口路径，不同写操作天然隔离，互不干扰；重试同一操作时才复用相同 requestId

4. 并发处理

并发请求同一 requestId 时，第一个请求加锁执行，后续请求返回 41107（请求正在处理中）。

5. 重试策略

超时或网络异常时，必须使用相同 requestId 重试，系统返回首次处理结果，避免重复操作：

幂等键已按接口路径区分业务操作，不同操作使用相同 requestId 也不会相互影响；重试同一操作时必须使用相同的 requestId。