架构与系统设计 / 系统课时
初始化任务幂等
初始化任务幂等
本课解决租户初始化被重复提交、超时重试或并发消费时的数据安全问题。你将用业务唯一约束、任务状态抢占和“只创建不存在数据”的写入方式,让同一初始化任务执行多次仍得到一致结果。
学习目标
- 识别初始化任务重复执行产生的典型脏数据
- 使用唯一约束和状态迁移阻止并发重复处理
- 设计可安全重试、可验证的初始化执行器
幂等要解决什么
初始化任务通常会创建默认角色、配置项、组织根节点或编号序列。消息重复投递、接口超时重试、服务重启补偿都可能让同一任务再次执行。幂等要求不是“拒绝所有重复请求”,而是同一业务键执行一次或多次后,最终数据状态一致,即 。
仅在应用代码中先查询再插入并不可靠。两个线程可能同时查到“数据不存在”,随后各自插入一条。因此幂等必须落到数据库约束,并配合任务状态判断,应用层检查只能作为友好提示,不能作为最后防线。
建立三层防线
第一层是任务业务键,例如 tenant_id + task_code,用于识别“哪个租户的哪项初始化”。第二层是目标数据唯一键,例如 tenant_id + role_code、tenant_id + config_key,用于防止重复实体。第三层是任务状态迁移,只有把任务从 PENDING 或 FAILED 原子更新为 RUNNING 的执行者才拥有本次执行权。

当任务已经是 SUCCESS 时,重复触发应直接返回成功;当任务为 RUNNING 时,应判断是否仍在租约时间内,避免另一个实例立即重复执行;当任务为 FAILED 或超时的 RUNNING 时,才允许重新抢占。
用唯一约束封住重复写入
下面的 MySQL 表结构同时约束初始化任务、默认角色和默认配置。目标数据使用“缺失时创建”语义,重试时不覆盖租户已经修改过的配置值。
CREATE TABLE tenant_init_task (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tenant_id BIGINT NOT NULL,
task_code VARCHAR(64) NOT NULL,
status VARCHAR(16) NOT NULL,
retry_count INT NOT NULL DEFAULT 0,
updated_at DATETIME NOT NULL,
UNIQUE KEY uk_tenant_task (tenant_id, task_code)
);
CREATE TABLE tenant_role (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tenant_id BIGINT NOT NULL,
role_code VARCHAR(64) NOT NULL,
role_name VARCHAR(128) NOT NULL,
UNIQUE KEY uk_tenant_role (tenant_id, role_code)
);
CREATE TABLE tenant_config (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
tenant_id BIGINT NOT NULL,
config_key VARCHAR(128) NOT NULL,
config_value VARCHAR(512) NOT NULL,
UNIQUE KEY uk_tenant_config (tenant_id, config_key)
);预期结果
三张表创建成功;同一 tenant_id 与 task_code、role_code 或 config_key 无法插入第二条记录,重复写入会触发唯一键冲突。唯一键冲突不应直接等同于任务失败。对于默认角色和默认配置,冲突通常表示数据已存在,可以按“已完成该步骤”处理;但如果已存在记录的关键字段与模板不一致,应记录差异并交由升级或配置迁移流程处理,而不是在初始化重试中强制覆盖。
原子抢占并执行初始化
下面是执行器片段示例,依赖能够返回影响行数的仓储方法。tryAcquire 必须使用带状态条件的单条 UPDATE,只有返回 1 才能继续;业务写入使用数据库唯一约束保证并发安全。
@Service
@RequiredArgsConstructor
public class TenantInitExecutor {
private final TenantInitTaskStateService taskStateService;
private final TenantBusinessInitializer businessInitializer;
public void execute(long tenantId, String taskCode) {
taskStateService.createIfAbsent(tenantId, taskCode);
// 用短事务原子抢占,影响行数为 0 时不再重复执行
if (!taskStateService.tryAcquire(tenantId, taskCode)) {
return;
}
try {
// 业务初始化在独立事务中执行,并通过唯一键实现 insertIfAbsent
businessInitializer.initializeDefaults(tenantId);
taskStateService.markSuccess(tenantId, taskCode);
} catch (RuntimeException ex) {
// 失败状态使用新事务记录,避免随业务事务一起回滚
taskStateService.markFailed(
tenantId, taskCode, ex.getMessage());
throw ex;
}
}
}预期结果
同一 tenantId 和 taskCode 被重复调用时,只有一个执行者完成初始化;默认角色、默认配置和任务记录各保留一条,任务最终状态为 SUCCESS。示例中的 taskStateService 应以短事务更新任务状态,businessInitializer 则在独立业务事务中写入默认数据。markFailed 需要使用新事务,确保业务初始化回滚后仍能保留错误摘要和重试次数,便于判断是临时故障还是模板数据错误。
验证重复与并发场景
至少验证三类场景:同一请求连续执行两次、两个线程同时执行、执行到一半抛出异常后再次重试。最终验收标准不是“接口没有报错”,而是业务表中没有重复记录,已被租户修改的配置没有被恢复为默认值,任务状态与实际数据一致。
可以用以下 SQL 检查重复数据。正常情况下查询结果为空。
SELECT tenant_id, role_code, COUNT(*) AS duplicate_count
FROM tenant_role
GROUP BY tenant_id, role_code
HAVING COUNT(*) > 1;
SELECT tenant_id, config_key, COUNT(*) AS duplicate_count
FROM tenant_config
GROUP BY tenant_id, config_key
HAVING COUNT(*) > 1;预期结果
两条查询均返回 0 行,表示默认角色和配置项不存在重复业务键。本课总结
- 初始化幂等必须同时依赖任务业务键、目标数据唯一键和原子状态迁移
- 重试应采用“缺失时创建”,不能无条件覆盖租户已经修改的配置
- 验收要覆盖重复、并发和失败重试,并以最终数据一致性为准
下一课预告
下一课将把幂等策略延伸到租户配置变更,讨论如何通过版本号、发布状态和审计记录安全地更新配置。