从重复点击到多实例并发:异步报表导出的五层幂等与防重设计
本文使用的业务名称、表名、字段值、接口名称及代码均为通用化示例,与任何具体项目无关。
一、业务背景:为什么一次"导出"会变成一个异步任务
在后台管理系统、数据分析平台和企业协作系统中,经常存在这样的功能:
- 用户选择一组数据;
- 选择报告模板;
- 点击"导出 PPT"或"导出 PDF";
- 后台查询数据、生成图表、渲染文件并上传到对象存储;
- 前端轮询任务状态,任务完成后向用户提供下载链接。
如果报告内容比较多,生成过程可能持续几秒甚至几分钟。HTTP 请求不适合一直等待,因此系统通常会把导出设计成异步任务:
text
用户点击导出
↓
API 创建导出任务
↓
任务进入消息队列
↓
后台 Worker 生成文件
↓
文件上传对象存储
↓
数据库记录任务完成
↓
前端获得下载链接
异步化解决了接口长时间阻塞的问题,却带来了另一个问题:同一份报告可能被重复生成。
1. 重复请求是怎么产生的
重复请求不一定是用户故意操作,常见原因包括:
- 用户连续点击两次"导出";
- 页面卡顿,用户误以为没有生效,再点一次;
- 前端超时后自动重试;
- API 网关发现响应超时,重新转发请求;
- 网络抖动导致调用方无法确认第一次请求是否成功;
- 同一个请求被负载均衡到不同服务实例;
- 消息中间件发生"至少一次"投递。
如果完全不防重,两次请求可能生成两条任务:
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 幂等共同组成完整闭环。
十三、总结
一个可靠的异步导出系统,不只是"点击按钮后生成文件",还需要回答下面五个问题:
- 两次请求是不是同一次业务操作?------幂等键;
- 相同操作编号下,请求内容是否相同?------请求指纹;
- 同一操作应该映射到哪一条任务?------确定性
export_job_id; - 多实例同时创建时,谁能成功?------数据库主键;
- 多个实例都拿到任务后,谁可以首次投递?------
creation_token。
最终形成的防重链路是:
text
相同业务操作
→ 相同幂等键
→ 校验相同请求指纹
→ 计算相同 export_job_id
→ 数据库只允许一条任务记录
→ 只有真正创建者投递后台任务
→ 后续请求复用原任务及其状态
这套设计的核心并不是字段多,而是把"业务重复、参数冲突、并发插入、重复投递、任务状态"拆成不同问题,再让每一层只解决自己最擅长的问题。