从重复点击到多实例并发:异步报表导出的五层幂等与防重设计

从重复点击到多实例并发:异步报表导出的五层幂等与防重设计

本文使用的业务名称、表名、字段值、接口名称及代码均为通用化示例,与任何具体项目无关。

一、业务背景:为什么一次"导出"会变成一个异步任务

在后台管理系统、数据分析平台和企业协作系统中,经常存在这样的功能:

  • 用户选择一组数据;
  • 选择报告模板;
  • 点击"导出 PPT"或"导出 PDF";
  • 后台查询数据、生成图表、渲染文件并上传到对象存储;
  • 前端轮询任务状态,任务完成后向用户提供下载链接。

如果报告内容比较多,生成过程可能持续几秒甚至几分钟。HTTP 请求不适合一直等待,因此系统通常会把导出设计成异步任务:

text 复制代码
用户点击导出
    ↓
API 创建导出任务
    ↓
任务进入消息队列
    ↓
后台 Worker 生成文件
    ↓
文件上传对象存储
    ↓
数据库记录任务完成
    ↓
前端获得下载链接

异步化解决了接口长时间阻塞的问题,却带来了另一个问题:同一份报告可能被重复生成。

1. 重复请求是怎么产生的

重复请求不一定是用户故意操作,常见原因包括:

  1. 用户连续点击两次"导出";
  2. 页面卡顿,用户误以为没有生效,再点一次;
  3. 前端超时后自动重试;
  4. API 网关发现响应超时,重新转发请求;
  5. 网络抖动导致调用方无法确认第一次请求是否成功;
  6. 同一个请求被负载均衡到不同服务实例;
  7. 消息中间件发生"至少一次"投递。

如果完全不防重,两次请求可能生成两条任务:

text 复制代码
第一次请求 → export-job-A → 生成 report-A.pptx
第二次请求 → export-job-B → 生成 report-B.pptx

两份文件内容相同,却会重复占用:

  • 数据库查询资源;
  • CPU 和内存;
  • 图表、PPT、PDF 渲染资源;
  • 消息队列资源;
  • 对象存储空间;
  • 用户的等待时间。

因此,我们希望实现的不是"接口永远只能调用一次",而是下面这条业务语义:

同一个逻辑导出操作,无论被提交多少次,都只创建一个导出任务;调用方重复请求时,返回原来的任务。

这就是导出接口的幂等性。


二、总体方案:五层机制分别解决什么问题

本文采用五个相互配合的要素:

diff 复制代码
+ 幂等键
+ 请求指纹
+ 确定性 export_job_id
+ 数据库主键
+ creation_token

需要先说明:它们不是五个作用相同的"幂等键",而是五种不同职责。

机制 核心问题 通俗理解
幂等键 两个请求是不是同一次业务操作 业务操作编号
请求指纹 同一个操作编号下,请求内容是否一致 内容防伪校验
确定性 export_job_id 同一业务操作应该映射到哪一条任务 导出工单号
数据库主键 多实例同时插入时,只允许一条成功 最终裁判
creation_token 哪个实例真正创建了任务,谁有权首次投递 创建者凭证

整体链路如下:

text 复制代码
收到导出请求
    │
    ├─ 计算幂等键:这是不是同一次业务操作?
    │
    ├─ 计算请求指纹:相同幂等键下,内容有没有变化?
    │
    ├─ 计算确定性 export_job_id:找到唯一导出工单号
    │
    ├─ 插入数据库:依靠主键裁决并发创建者
    │
    └─ 校验 creation_token:只有真正的创建者投递后台任务

这套设计的重点不是"堆了五层保险",而是每一层都在处理上一层无法处理的问题。


三、第一层:幂等键------识别是不是同一次业务操作

1. 幂等键是什么

幂等键是一个稳定的业务标识。相同的逻辑操作应该得到相同的幂等键,不同操作应该得到不同的幂等键。

通用示例:

text 复制代码
report-export:{business_process_id}:{data_snapshot_id}:{export_attempt}

假设:

text 复制代码
business_process_id = process-1001
data_snapshot_id    = snapshot-20261120
export_attempt      = 0

得到:

text 复制代码
report-export:process-1001:snapshot-20261120:0

只要还是同一个流程、同一份数据快照、同一次导出尝试,即使请求落到不同服务实例,生成的幂等键也相同。

2. 不同用户的幂等键一定不同吗

不一定,这取决于业务定义。

如果"用户 A 和用户 B 导出同一份公共报告"应该复用同一个任务,那么幂等键中不应包含用户 ID:

text 复制代码
report-export:{snapshot_id}:{attempt}

如果每个用户都有独立权限、独立水印或个性化内容,那么必须把用户或内容版本纳入作用域:

text 复制代码
report-export:{user_id}:{snapshot_id}:{attempt}

设计幂等键之前必须先回答:

业务上,什么条件相同才算"同一次导出"?

3. 为什么不能只有幂等键

因为幂等键只回答"业务操作是不是同一个",不能确认两次请求携带的参数是否一致,也不能原子阻止两个服务实例同时插入。


四、第二层:请求指纹------防止相同幂等键被不同内容复用

1. 问题场景

第一次请求:

json 复制代码
{
  "idempotency_key": "report-export:process-1001:snapshot-1:0",
  "format": "pptx",
  "template_id": "template-A",
  "data_version": "v1"
}

第二次请求错误地复用了同一个幂等键,但参数变成:

json 复制代码
{
  "idempotency_key": "report-export:process-1001:snapshot-1:0",
  "format": "pdf",
  "template_id": "template-B",
  "data_version": "v2"
}

如果系统只看幂等键,就会把第二次请求当成第一次请求,直接返回原来的 PPT 任务。调用方明明要求 PDF,却得到一个 PPT 任务。

2. 请求指纹怎么生成

先选出会影响导出结果的字段,再进行稳定序列化和哈希:

python 复制代码
def build_request_fingerprint(request):
    effective_input = {
        "template_id": request.template_id,
        "template_revision": request.template_revision,
        "format": request.format,
        "data_version": request.data_version,
        "filters": request.filters,
        "idempotency_key": request.idempotency_key,
    }

    canonical_json = json_encode(
        effective_input,
        sort_keys=True
    )

    return sha256(canonical_json)

得到类似:

text 复制代码
sha256:8e915d...

注意:示例代码已经通用化。真实工程还要保证日期、浮点数、空值和数组排序规则稳定。

3. 判断规则

text 复制代码
幂等键相同 + 请求指纹相同
→ 这是相同请求,返回原任务

幂等键相同 + 请求指纹不同
→ 幂等冲突,拒绝请求

请求指纹不是用来查找任务的主要业务标识,而是用来验证:

你声称这是同一个操作,那么请求内容也必须一致。


五、第三层:确定性 export_job_id------把业务操作映射成固定工单号

1. 随机任务 ID 的问题

如果每次请求都随机生成任务 ID:

text 复制代码
实例A → export-job-random-111
实例B → export-job-random-222

即使它们处理的是同一个逻辑操作,数据库也会认为是两条不同任务,两个插入都可能成功。

2. 确定性任务 ID

可以根据业务作用域和幂等键计算任务 ID:

python 复制代码
def build_export_job_id(tenant_id, workspace_id, idempotency_key):
    source = [tenant_id, workspace_id, idempotency_key]
    digest = sha256(stable_json(source))
    return "export-job-" + digest[:32]

其中:

  • tenant_id:租户或组织隔离标识;
  • workspace_id:租户下的逻辑业务空间;
  • idempotency_key:本次业务操作标识。

同样的输入永远得到同样的结果:

text 复制代码
tenant-01 + workspace-01 + key-ABC
→ export-job-7f29c1...

无论请求由服务实例 A 还是服务实例 B 处理,任务 ID 都相同。

3. workspace 是什么

workspace 可以理解成租户内部更细一级的业务隔离单元,例如:

text 复制代码
租户
├── 华东业务空间
├── 华南业务空间
└── 测试业务空间

它不是浏览器页面,也不是服务器实例,而是系统中的逻辑数据边界。通常来自登录上下文、访问令牌中的声明,或者网关解析后的请求上下文。

将它加入任务 ID 的计算,可以避免不同工作空间碰巧使用相同幂等键时错误地复用任务。


六、第四层:数据库主键------解决多实例并发竞态

1. 为什么应用查询不够

两个服务实例可能同时处理同一个请求:

text 复制代码
实例A:查询任务,不存在
实例B:查询任务,也不存在

实例A:准备插入
实例B:也准备插入

两次查询都没有错,因为查询发生时数据库确实还没有记录。但"查询时不存在"并不等于"我获得了独占创建权"。

2. 任务表的通用设计

下面是一份脱敏后的简化表结构:

sql 复制代码
CREATE TABLE async_export_job (
    export_job_id       VARCHAR(128) NOT NULL,
    tenant_id           VARCHAR(128) NOT NULL,
    workspace_id        VARCHAR(128) NOT NULL,

    export_format       VARCHAR(16)  NOT NULL,
    status              VARCHAR(32)  NOT NULL,
    attempt_count       INTEGER      NOT NULL DEFAULT 0,
    max_attempts        INTEGER      NOT NULL DEFAULT 3,

    requested_by        VARCHAR(128),
    trace_id            VARCHAR(128),

    source_metadata     JSON,
    render_context      JSON,
    artifact_manifest   JSON,

    error_code          VARCHAR(64),
    error_message       TEXT,

    queued_at           TIMESTAMP,
    rendering_at        TIMESTAMP,
    completed_at        TIMESTAMP,
    failed_at           TIMESTAMP,
    created_at          TIMESTAMP NOT NULL,
    updated_at          TIMESTAMP NOT NULL,

    PRIMARY KEY (tenant_id, export_job_id)
);

这里的 export_job_id 是一张导出工单的编号,一整行数据代表一次逻辑导出任务。

3. 一条任务记录如何变化

刚创建:

text 复制代码
export_job_id   = export-job-7f29c1
status          = queued
attempt_count   = 0
artifact_manifest = {"files": []}

Worker 开始执行:

text 复制代码
status          = rendering
attempt_count   = 1
rendering_at    = 当前时间

执行成功:

text 复制代码
status          = completed
completed_at    = 当前时间
artifact_manifest = {
  "files": [
    {
      "name": "report.pptx",
      "object_key": "exports/7f29c1/report.pptx",
      "checksum": "sha256:..."
    }
  ]
}

执行失败:

text 复制代码
status          = failed
failed_at       = 当前时间
error_code      = RENDER_FAILED
error_message   = ...

数据库保存的是任务状态和文件索引,PPT/PDF 二进制文件通常保存在对象存储中。

4. 主键如何完成最终裁决

两个实例计算出相同的确定性任务 ID:

text 复制代码
实例A → export-job-7f29c1
实例B → export-job-7f29c1

数据库执行:

text 复制代码
实例A插入 (tenant-01, export-job-7f29c1) → 成功
实例B插入 (tenant-01, export-job-7f29c1) → 主键冲突

应用捕获唯一约束冲突后,重新查询并返回实例 A 创建的任务:

python 复制代码
try:
    job = repository.insert(job_request)
except UniqueConstraintViolation:
    job = repository.find_by_id(
        tenant_id=tenant_id,
        export_job_id=export_job_id
    )

最终两个 HTTP 请求都得到:

json 复制代码
{
  "export_job_id": "export-job-7f29c1",
  "status": "queued"
}

主键不是普通的"额外兜底",而是并发场景下真正具备原子保证的最终裁判。


七、第五层:creation_token------只有真正的创建者可以首次投递

1. 数据库只解决了"只能有一行"

发生主键冲突后,实例 B 可以查询并获得实例 A 创建的记录。但此时 A 和 B 手上都有同一个任务对象:

text 复制代码
实例A → 拿到 export-job-7f29c1
实例B → 也拿到 export-job-7f29c1

如果二者都继续向消息队列发送任务,数据库虽然只有一行,但队列里可能出现两条相同消息:

text 复制代码
队列消息1:执行 export-job-7f29c1
队列消息2:执行 export-job-7f29c1

因此,还需要判断谁是真正完成插入的创建者。

2. creation_token 的生成与使用

每个服务实例在尝试插入前生成随机令牌:

text 复制代码
实例A → creation-token-A
实例B → creation-token-B

它们分别准备写入:

text 复制代码
实例A:export-job-7f29c1 + creation-token-A
实例B:export-job-7f29c1 + creation-token-B

最终 A 插入成功,数据库保存的是:

text 复制代码
export_job_id = export-job-7f29c1
creation_token = creation-token-A

B 因主键冲突重新读取数据库,只能读到 A 的令牌。

之后,每个实例比较:

python 复制代码
if database_job.creation_token != my_creation_token:
    return database_job

dispatch_to_queue(database_job.export_job_id)

结果是:

text 复制代码
实例A:数据库token == 自己的token → 有权投递
实例B:数据库token != 自己的token → 返回原任务,不投递

3. creation_token 不是幂等键

二者性质完全不同:

项目 幂等键 creation_token
稳定性 相同业务操作保持相同 每次插入尝试随机生成
标识对象 业务操作 本次创建竞争者
主要作用 找到或复用同一任务 判断谁赢得插入竞争
是否参与确定性任务 ID 是 否

八、完整的脱敏伪代码

下面的代码只表达设计思路,不对应任何具体项目实现:

python 复制代码
def create_export(request, identity):
    # 第一层:业务操作身份
    idempotency_key = request.idempotency_key
    if not idempotency_key:
        raise BadRequest("idempotency key is required")

    # 第二层:请求内容身份
    fingerprint = build_request_fingerprint(request)

    # 第三层:确定性任务编号
    export_job_id = build_export_job_id(
        identity.tenant_id,
        identity.workspace_id,
        idempotency_key,
    )

    # 顺序重复请求可以在这里快速返回
    existing = repository.find_by_id(
        identity.tenant_id,
        export_job_id,
    )

    if existing:
        if existing.request_fingerprint != fingerprint:
            raise IdempotencyConflict()
        return existing

    # 第五层:每个并发创建者都有自己的随机身份
    my_creation_token = random_token()

    new_job = ExportJob(
        export_job_id=export_job_id,
        tenant_id=identity.tenant_id,
        workspace_id=identity.workspace_id,
        status="queued",
        request_fingerprint=fingerprint,
        creation_token=my_creation_token,
        render_context=freeze_report_input(request),
    )

    try:
        # 第四层:数据库主键完成并发裁决
        stored_job = repository.insert(new_job)
    except UniqueConstraintViolation:
        stored_job = repository.find_by_id(
            identity.tenant_id,
            export_job_id,
        )

    # 防止相同幂等键携带不同参数
    if stored_job.request_fingerprint != fingerprint:
        raise IdempotencyConflict()

    # 只有真正插入成功的创建者执行首次投递
    if stored_job.creation_token != my_creation_token:
        return stored_job

    queue.dispatch(stored_job.export_job_id)
    return stored_job

九、不同场景下,到底是哪一层拦住了重复导出

场景一:用户先后点击两次,请求没有并发

text 复制代码
第一次请求:创建任务成功
第二次请求:任务已经存在

处理结果:

text 复制代码
相同幂等键
→ 计算出相同 export_job_id
→ 应用查询到已有任务
→ 请求指纹相同
→ 返回原任务

主要生效层:

text 复制代码
幂等键 + 请求指纹 + 确定性 export_job_id

数据库不需要再次发生主键冲突,因为第二次请求在查询阶段就找到任务了。

场景二:相同幂等键,却修改了导出格式

text 复制代码
第一次:template-A + PPTX
第二次:template-A + PDF
幂等键相同

处理结果:

text 复制代码
找到原任务
→ 计算请求指纹
→ 两个指纹不同
→ 返回 idempotency conflict

主要生效层:

text 复制代码
请求指纹

系统不会偷偷返回旧 PPT,也不会覆盖原任务。

场景三:两个服务实例同时创建同一任务

text 复制代码
实例A查询:没有
实例B查询:没有
实例A插入:成功
实例B插入:主键冲突

处理结果:

text 复制代码
相同幂等键
→ 相同确定性 export_job_id
→ 数据库主键只允许一个插入成功
→ 失败实例重新查询并复用原任务

主要生效层:

text 复制代码
确定性 export_job_id + 数据库主键

场景四:两个实例都拿到了任务对象,都想投递队列

处理结果:

text 复制代码
数据库记录 creation-token-A

实例A持有 token-A → 允许投递
实例B持有 token-B → 不允许投递

主要生效层:

text 复制代码
creation_token

场景五:任务正在生成,用户再次点击

数据库中已经存在:

text 复制代码
status = rendering

重复请求通过幂等关系找到原任务,直接返回:

json 复制代码
{
  "export_job_id": "export-job-7f29c1",
  "status": "rendering"
}

系统不会再创建任务,也不会重新投递。

主要生效层:

text 复制代码
幂等键 + 确定性 export_job_id + 任务状态

场景六:任务已经成功,用户再次点击

数据库中已经存在:

text 复制代码
status = completed
artifact_manifest = 已生成文件信息

系统返回原任务和原文件信息。需要下载时,可以重新生成一个短期下载链接,但不重新渲染文件。

主要生效层:

text 复制代码
幂等键 + 已完成任务记录

要特别区分:

防重复导出是防止重复生成文件,不是禁止用户多次下载同一个文件。

场景七:任务彻底失败后,用户主动重试

失败任务一般不应被无期限复用。业务层可以增加导出尝试号:

text 复制代码
第一次:report-export:process-1001:snapshot-1:0
重试:  report-export:process-1001:snapshot-1:1

新的幂等键会产生新的 export_job_id:

text 复制代码
旧任务 → export-job-old,status=failed
新任务 → export-job-new,status=queued

这不是重复创建,而是一次被明确授权的新尝试。

场景八:两个用户导出不同的数据

即使使用同一个模板,只要数据快照、过滤条件或业务流程不同:

text 复制代码
幂等键不同
→ export_job_id不同
→ 创建两条合法任务

五层机制不是阻止所有导出,而是只合并业务上应当视为同一次的导出。


十、为什么不能只用一个幂等键

只用幂等键,至少还有四个问题:

1. 无法识别参数冲突

相同幂等键可能错误地携带不同模板、格式或数据版本,需要请求指纹验证。

2. 无法直接成为数据库并发约束

如果幂等键只存放在 JSON 中,或者没有建立唯一索引,数据库无法依靠它原子裁决并发请求。

3. 无法阻止并发查询后的同时插入

两个实例都可能在对方提交之前查询到"不存在"。最终必须依靠数据库唯一约束。

4. 无法判断谁应该发送消息

主键保证数据库只有一行,但竞争失败的实例也能重新读到这一行。还需要创建者标识或其他机制控制首次投递。

所以完整关系是:

text 复制代码
幂等键
解决"是不是同一次业务操作"
        ↓
请求指纹
解决"同一操作的内容是否一致"
        ↓
确定性 export_job_id
解决"同一操作映射到哪张工单"
        ↓
数据库主键
解决"并发时只能创建一张工单"
        ↓
creation_token
解决"谁有权首次发送后台任务"

十一、五种机制是否缺一不可

需要区分"必须具备的能力"和"具体实现手段"。

下面这些能力基本都需要:

  • 稳定识别同一业务操作;
  • 检查重复请求的内容是否一致;
  • 数据库层原子防重;
  • 防止重复投递后台任务;
  • 保存可查询的任务状态。

但具体实现不一定只能使用本文中的五个字段。

例如,可以使用随机任务 ID,并在数据库增加:

sql 复制代码
UNIQUE (tenant_id, workspace_id, idempotency_key)

也可以把幂等键和指纹设计为独立字段:

sql 复制代码
idempotency_key     VARCHAR(256) NOT NULL,
request_fingerprint VARCHAR(128) NOT NULL,

UNIQUE (tenant_id, workspace_id, idempotency_key)

对于"谁负责投递",也可以不用 creation_token,改用:

  • INSERT ... ON CONFLICT ... RETURNING 判断是否插入成功;
  • 带条件的状态更新(CAS);
  • 数据库事务消息表;
  • Transactional Outbox 模式。

因此准确说法是:

五种具体字段不一定缺一不可,但它们所解决的五类问题不能被忽略。


十二、这套设计还有一个重要边界

creation_token 可以防止两个实例都投递消息,但仍然存在一个很短的故障窗口:

text 复制代码
实例A成功插入任务
    ↓
实例A还没来得及投递消息就宕机

此时数据库中存在:

text 复制代码
status = queued

但消息队列里可能没有任务。

对于要求较高的生产系统,可以进一步采用 Transactional Outbox:

text 复制代码
同一个数据库事务中:
1. 插入导出任务
2. 插入待发送事件

独立投递器持续扫描待发送事件
→ 成功发送后标记为已发送

这样即使 API 实例在提交事务后宕机,独立投递器仍然能够把消息补发出去。

此外,Worker 本身也应具备幂等保护。因为即使 API 只发送一次,某些消息队列也可能重复投递。Worker 在真正渲染前应检查任务状态,例如:

text 复制代码
completed → 直接结束,不重复生成
rendering → 根据租约或超时策略决定是否接管
queued    → 原子更新为 rendering,成功者开始执行
failed    → 根据重试策略处理

API 防重和 Worker 幂等共同组成完整闭环。


十三、总结

一个可靠的异步导出系统,不只是"点击按钮后生成文件",还需要回答下面五个问题:

  1. 两次请求是不是同一次业务操作?------幂等键;
  2. 相同操作编号下,请求内容是否相同?------请求指纹;
  3. 同一操作应该映射到哪一条任务?------确定性 export_job_id;
  4. 多实例同时创建时,谁能成功?------数据库主键;
  5. 多个实例都拿到任务后,谁可以首次投递?------creation_token。

最终形成的防重链路是:

text 复制代码
相同业务操作
→ 相同幂等键
→ 校验相同请求指纹
→ 计算相同 export_job_id
→ 数据库只允许一条任务记录
→ 只有真正创建者投递后台任务
→ 后续请求复用原任务及其状态

这套设计的核心并不是字段多,而是把"业务重复、参数冲突、并发插入、重复投递、任务状态"拆成不同问题,再让每一层只解决自己最擅长的问题。

相关推荐
斯维赤16 分钟前
三级缓存为什么是三级?二级缓存不够吗
前端·后端·面试
Rain的Java大神之路27 分钟前
把数组本身变成哈希表:原地哈希搞定 LeetCode 41「缺失的第一个正数」
java·后端·leetcode
卷无止境36 分钟前
FDE全解析:把软件真正落地到客户现场的那类工程师
后端
锋行天下1 小时前
LangGraph 对接 MCP 实战指南:从本地开发到线上部署与模型防坑
前端·人工智能·后端
利威尔xu1 小时前
2026-11-18-Go接口幂等设计实战
开发语言·后端·golang
喵个咪1 小时前
RushWind Admin — update_mask 写面:字段级白名单、显式清除与点路径合并
后端·rust
喵个咪2 小时前
RushWind Admin — 多租户行级隔离与租户回收站:Viewer 三态、repo_shell! 与全域级联清除
后端·rust
喵个咪2 小时前
RushWind CMS — 三服务拓扑:core 领域层、双 BFF 薄代理与一份契约的双面输出
后端·rust
天多高_风不晓得2 小时前
Comparable 与 Comparator
后端