架构与系统设计 / 系统课时

初始化任务幂等

初始化任务幂等

本课解决租户初始化被重复提交、超时重试或并发消费时的数据安全问题。你将用业务唯一约束、任务状态抢占和“只创建不存在数据”的写入方式,让同一初始化任务执行多次仍得到一致结果。

学习目标

  • 识别初始化任务重复执行产生的典型脏数据
  • 使用唯一约束和状态迁移阻止并发重复处理
  • 设计可安全重试、可验证的初始化执行器

幂等要解决什么

初始化任务通常会创建默认角色、配置项、组织根节点或编号序列。消息重复投递、接口超时重试、服务重启补偿都可能让同一任务再次执行。幂等要求不是“拒绝所有重复请求”,而是同一业务键执行一次或多次后,最终数据状态一致,即 f(f(x))=f(x)f(f(x)) = f(x)。

仅在应用代码中先查询再插入并不可靠。两个线程可能同时查到“数据不存在”,随后各自插入一条。因此幂等必须落到数据库约束,并配合任务状态判断,应用层检查只能作为友好提示,不能作为最后防线。

建立三层防线

第一层是任务业务键,例如 tenant_id + task_code,用于识别“哪个租户的哪项初始化”。第二层是目标数据唯一键,例如 tenant_id + role_code、tenant_id + config_key,用于防止重复实体。第三层是任务状态迁移,只有把任务从 PENDING 或 FAILED 原子更新为 RUNNING 的执行者才拥有本次执行权。

初始化任务幂等状态与并发抢占

当任务已经是 SUCCESS 时,重复触发应直接返回成功;当任务为 RUNNING 时,应判断是否仍在租约时间内,避免另一个实例立即重复执行;当任务为 FAILED 或超时的 RUNNING 时,才允许重新抢占。

用唯一约束封住重复写入

下面的 MySQL 表结构同时约束初始化任务、默认角色和默认配置。目标数据使用“缺失时创建”语义,重试时不覆盖租户已经修改过的配置值。

sql
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)
);

预期结果

text
三张表创建成功;同一 tenant_id 与 task_code、role_code 或 config_key 无法插入第二条记录,重复写入会触发唯一键冲突。

唯一键冲突不应直接等同于任务失败。对于默认角色和默认配置,冲突通常表示数据已存在,可以按“已完成该步骤”处理;但如果已存在记录的关键字段与模板不一致,应记录差异并交由升级或配置迁移流程处理,而不是在初始化重试中强制覆盖。

原子抢占并执行初始化

下面是执行器片段示例,依赖能够返回影响行数的仓储方法。tryAcquire 必须使用带状态条件的单条 UPDATE,只有返回 1 才能继续;业务写入使用数据库唯一约束保证并发安全。

java
@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;
        }
    }
}

预期结果

text
同一 tenantId 和 taskCode 被重复调用时,只有一个执行者完成初始化;默认角色、默认配置和任务记录各保留一条,任务最终状态为 SUCCESS。

示例中的 taskStateService 应以短事务更新任务状态,businessInitializer 则在独立业务事务中写入默认数据。markFailed 需要使用新事务,确保业务初始化回滚后仍能保留错误摘要和重试次数,便于判断是临时故障还是模板数据错误。

验证重复与并发场景

至少验证三类场景:同一请求连续执行两次、两个线程同时执行、执行到一半抛出异常后再次重试。最终验收标准不是“接口没有报错”,而是业务表中没有重复记录,已被租户修改的配置没有被恢复为默认值,任务状态与实际数据一致。

可以用以下 SQL 检查重复数据。正常情况下查询结果为空。

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;

预期结果

text
两条查询均返回 0 行,表示默认角色和配置项不存在重复业务键。

本课总结

  • 初始化幂等必须同时依赖任务业务键、目标数据唯一键和原子状态迁移
  • 重试应采用“缺失时创建”,不能无条件覆盖租户已经修改的配置
  • 验收要覆盖重复、并发和失败重试,并以最终数据一致性为准

下一课预告

下一课将把幂等策略延伸到租户配置变更,讨论如何通过版本号、发布状态和审计记录安全地更新配置。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

初始化任务幂等

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通