我们的后端服务同时承载几类流量：
部分用户请求会触发耗时较长、成本较高的外部操作，例如创建 Merge Request 和运行流水线。
在这样的服务里，横切关注点（限流、功能开关、鉴权、幂等、指标）本身也会出问题：配置缺失、配置写错、依赖服务异常、埋点代码抛出异常。我们的目标是：
Map，横切逻辑不能依赖统一的返回类型。拦截器按以下顺序注册，Spring 按注册顺序执行：
@RateLimit 的处理方法。限流排在第一位有两个原因。其一，被拒绝的请求不应消耗任何后续处理。其二，业务活动计数衡量的是”用户完成了多少次业务动作”，被 429 拒绝的请求不应计入其中；它们由单独的”被限流次数”指标统计。
业务活动指标使用路径白名单而不是通配符，这样与该业务无关的流量根本不会进入这个拦截器。
限流和鉴权都放在拦截器里实现，在参数绑定之前执行，有两个好处：
@PostMapping("/apply")
@RateLimit(bucket = "apply", limitKey = "APPLY_RATE_LIMIT", defaultLimit = 10,
message = "提交过于频繁，请稍后再试")
public ResponseEntity<?> apply(@RequestBody Map<String, String> body) { ... }
public boolean preHandle(HttpServletRequest req, HttpServletResponse resp, Object handler) {
RateLimit rl = annotationOf(handler);
if (rl == null) return true;
int limit = config.getInt(rl.limitKey(), rl.defaultLimit()); // 每次请求读取，热更新即时生效
if (limit <= 0) return true; // 清空或非正数：停止限流，而不是全部拦截
String subject = resolveSubject(req);
if (limiter.tryAcquire(rl.bucket() + ":" + subject, limit, windowMillis())) return true;
metrics.recordRateLimited(subject, rl.bucket());
writeJson(resp, 429, ApiResponse.error("RATE_LIMITED", rl.message()));
return false;
}
限流的主体优先使用登录身份。 这样同一个人换浏览器或开多个标签页，消耗的是同一份额度。只有在读不到身份时，才退回到客户端地址，并加上 ip: 前缀与身份区分。之所以退回到地址而不是归入一个共享桶，是因为共享桶会被任意一个调用方耗尽，进而影响所有无法识别身份的调用方。
限流器是滑动窗口日志。 每个桶保存一个时间戳队列，在 ConcurrentHashMap.compute 中完成”清理过期时间戳、判断、追加”，整个过程对单个桶是原子的。桶清空后返回 null，该键即被移除：
buckets.compute(key, (k, q) -> {
Deque<Long> d = (q == null) ? new ArrayDeque<>() : q;
while (!d.isEmpty() && now - d.peekFirst() >= windowMillis) d.pollFirst();
if (d.size() < limit) { d.addLast(now); allowed[0] = true; }
return d.isEmpty() ? null : d;
});
取舍需要写进注释。 限流先于幂等检查执行，所以超出额度的重复提交得到的是 429，而不是”重复提交”。我们接受这一点，并在接口注释中写明，避免后来的维护者误以为这是缺陷。
热更新配置随时可能缺失或写错。我们为每个配置项明确规定缺省时的行为，规则是：看误配置的主要后果是什么，朝后果较轻的方向缺省。
| 配置项 | 误配置的主要后果 | 缺省行为 |
|---|---|---|
| 限流阈值 | 误伤正常流量 | 不限流（阈值 ≤ 0 视为关闭限流） |
| 受限资源的开放模式 | 资源被意外开放 | 未知值视为”关闭” |
| 受限资源的开放时间窗口 | 资源被意外开放 | 任一字段缺失或格式错误即视为不在窗口内 |
| 鉴权所需的规则码 | 越权访问 | 缺失即拒绝 |
| 新流程开关 | 启用未经验证的路径 | 走旧流程 |
| 重试次数、退避时间 | 负值导致跳过调用或负数休眠 | 下限截断为 0 |
开放模式的解析如下：
AccessMode resolve(String raw) {
if (raw == null || raw.isBlank()) return TEST_WINDOW; // 未配置：受限开放（默认）
return switch (raw.trim().toUpperCase(Locale.ROOT)) {
case "OPEN" -> OPEN;
case "TEST_WINDOW" -> TEST_WINDOW;
default -> CLOSED; // 拼写错误等任何未知值：关闭
};
}
开放时间窗口按固定时区解析，而不是使用 JVM 默认时区，保证同一份配置在每台主机上对应同一段时间。
__authenticatedOperator 参数。顺序不能颠倒，否则客户端可以通过提交同名参数伪造操作者。审计日志只记录经过脱敏和长度截断的参数。我们在接口层区分两类错误：
// 客户端错误：返回一条可操作的提示，具体细节只写日志
ResponseEntity<?> clientFacingError(String code, String userMessage, String logDetail) {
log.warn("rejected code={} detail={}", code, logDetail);
return ApiResponse.error(code, userMessage);
}
// 服务端错误：日志记录原因和堆栈，客户端只收到通用提示
ResponseEntity<?> internalError(String code, String logDetail, Throwable cause) {
log.error("internal code={} detail={}", code, logDetail, cause);
return ApiResponse.error(code, GENERIC_ERROR_MESSAGE);
}
状态码按”客户端接下来应该做什么”来设计，而不是按”服务端内部发生了什么”：
DUPLICATE_SUBMIT 与 ACCEPTED 分开。 两者的 HTTP 状态都是 202，但前端收到 DUPLICATE_SUBMIT 时会保持表单锁定，而不是把它当作一次新的受理。幂等。 写接口以客户端提供的 operationId 作为幂等键，依赖数据库唯一约束完成”查询、插入、冲突后重读”（详见数据库篇 3.4 节）。并发的重复请求中，只有一个会继续执行，其余的返回胜出方的结果。
长操作。 长操作在完成同步校验后返回 HTTP 202，后续在有界线程池中执行。线程池拒绝任务时，失败状态会写入数据库（详见 MR 生命周期篇 3.2 节）。客户端始终能通过轮询看到一个明确的状态。
我们为指标代码制定了几条规则，并在实现中逐条落实：
preHandle 永远返回 true，从不写响应。request.getParameter，而不是自己读请求体，避免消耗输入流、影响后续的参数绑定。try/catch 中，异常只记日志。标签值经过规范化，并截断到 128 个字符；维度为空或非法时跳过发送。afterCompletion 中计数，并且只统计 2xx 响应。public void incrementUserCounter(String name, Map<String, String> tags) {
try {
Map<String, String> safe = normalizeAndTruncate(tags, 128);
if (safe == null) { log.warn("skip metric {}: invalid tags", name); return; }
registry.counter(name, safe).inc();
} catch (RuntimeException e) {
log.error("metric {} failed; business request continues", name, e); // 指标失败不影响业务
}
}
SPA 发布之后，已打开的旧页面会请求新版本中已被删除的带 hash 资源。如果不做处理，这类请求会落到全局异常处理器，返回 500。我们从服务端和客户端两侧处理：
服务端：
index.html 设置 Cache-Control: no-store，保证每次都拿到最新的资源清单；max-age=365d, public, immutable；Accept: text/html 且路径不含扩展名）返回一个回退页面，静态资源或 API 请求返回 404 JSON。两种响应都设置 no-store。客户端：
sessionStorage 记录上次自动重载的时间。30 秒内不再自动重载，改为显示一个”刷新页面”按钮，避免陷入重载循环。我们还为这些响应头和状态码编写了冒烟脚本，在预发布环境验证。
X-Forwarded-For 的第一跳，而这个值客户端可以伪造。后续计划改为取可信代理追加的那一跳，或在网关层统一限流。operationId，不重放原始响应。 如果客户端没有提供 operationId，服务端生成的 ID 含有时间戳，重试请求无法去重。try/catch。 它能否做到失败不影响业务，取决于追踪和指标库本身不抛异常。另外，部分用户接口不在 API 指标的覆盖范围内。我们的系统通过向 Git 仓库发起 Merge Request（MR）来落地用户的变更申请。如果每个申请各自发起一个 MR，多个 MR 会同时修改同一个仓库，彼此导致 rebase，并在流水线上排队。为此我们引入了批量聚合：申请审批通过后先进入等待集合，每一轮把等待中的申请合并成一个 MR 统一处理。
这个设计要求以下不变量始终成立：
目标是让数据库直接保证这些不变量，而不是依赖”应用代码恰好没有写错”。
CREATE UNIQUE INDEX ... WHERE status = 'RUNNING'）。CREATE TABLE merge_batch (
id BIGINT NOT NULL AUTO_INCREMENT,
status TINYINT NOT NULL DEFAULT 1 COMMENT '1=RUNNING 2=SUCCEEDED 3=FAILED 4=BLOCKED',
active_slot TINYINT GENERATED ALWAYS AS
(CASE WHEN status IN (1, 4) THEN 1 ELSE NULL END) STORED,
mr_id VARCHAR(64) NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (id),
UNIQUE KEY uk_active_slot (active_slot),
KEY idx_status_created (status, created_at, id)
) ENGINE = InnoDB;
这个设计利用了 MySQL 唯一索引的一条语义：唯一索引允许多个 NULL。
active_slot 为 1，唯一索引保证全表最多一行取值为 1。active_slot 为 NULL，任意多行可以共存。UPDATE status 同时让 active_slot 变成 NULL，槽位随之释放，不需要额外的释放步骤。这在效果上等价于部分唯一索引 UNIQUE (status) WHERE status IN (RUNNING, BLOCKED)。
我们也比较了其他互斥方案：
| 方案 | 主要问题 |
|---|---|
锁行加 SELECT ... FOR UPDATE |
锁要么在整个批次期间持有（数分钟的长事务），要么另外维护一个租约字段 |
GET_LOCK() 会话级锁 |
锁绑定在数据库连接上，与连接池的连接复用不易配合 |
| Redis 等外部分布式锁 | 需要新组件；租约过期时间与任务实际耗时难以对齐 |
| 生成列加唯一索引 | 锁与状态是同一列，不存在租约，也不会出现”状态已终结而锁未释放” |
最后一行是我们选择它的原因：互斥状态就是业务状态本身。持有者崩溃时，批次停在 RUNNING，槽位保持占用，但这是一个可以被查询、被处理的显式状态，而不是一个看不见的泄漏锁。超时扫描或运维工具把它推进到终态，槽位即释放。阻塞态（BLOCKED）同样占用槽位，后续批次会停下来，直到这个批次被处理。
CREATE TABLE merge_batch_request (
id BIGINT NOT NULL AUTO_INCREMENT,
operation_id VARCHAR(36) NOT NULL,
batch_id BIGINT NULL COMMENT 'NULL 表示仍在等待',
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (id),
UNIQUE KEY uk_operation_id (operation_id),
KEY idx_batch_created (batch_id, created_at, id)
) ENGINE = InnoDB;
每一轮的认领在一个事务中完成：
@Transactional
public Claim claim(int maxRequests) {
// 1. 占用槽位
long batchId;
try {
batchId = insertReturningKey("INSERT INTO merge_batch (status) VALUES (1)");
} catch (DuplicateKeyException e) {
return Claim.slotOccupied(); // 本事务尚未写入任何数据，正常返回等价于回滚
}
// 2. 读取等待中的申请：普通读，不加 FOR UPDATE
List<Req> pending = query(
"SELECT id, operation_id FROM merge_batch_request " +
"WHERE batch_id IS NULL AND created_at < CURRENT_TIMESTAMP " +
"ORDER BY created_at, id LIMIT ?", maxRequests);
if (pending.isEmpty()) {
throw new NothingToClaimException(); // 回滚，释放刚占用的槽位
}
// 3. 守卫式认领：只认领仍未被认领的行，且影响行数必须与读到的行数一致
int updated = update(
"UPDATE merge_batch_request SET batch_id = ? " +
"WHERE batch_id IS NULL AND id IN (" + placeholders(pending) + ")",
batchId, ids(pending));
if (updated != pending.size()) {
throw new ClaimPreemptedException(); // 有行被别处改动，整体回滚
}
// 4. 写入只追加的成员历史
insertHistory(batchId, pending);
return Claim.claimed(batchId, pending);
}
为什么第 2 步不用 FOR UPDATE。 在 REPEATABLE READ 隔离级别下，带范围条件的锁定读会对扫描到的索引区间加 next-key lock。这里扫描的是 idx_batch_created 上 batch_id IS NULL 的区间，而新入队的申请恰好插入这个区间，于是会被阻塞到认领事务结束，违反 I3。去掉锁定读并不影响正确性：
WHERE batch_id IS NULL 和影响行数校验也会发现，并让整个事务回滚。为什么读到空集要抛异常。 如果正常提交，就会留下一个没有任何成员、却占着槽位的 RUNNING 批次。抛异常让槽位随事务一起回滚。
事务外的无锁预检。 进入认领事务之前，先执行一次 SELECT ... WHERE batch_id IS NULL ... LIMIT 1。等待集合为空时直接结束本轮，不会出现”占用槽位后又回滚”的空转。
统一使用数据库时钟。 判断条件写成 created_at < CURRENT_TIMESTAMP，超时扫描写成 created_at < DATE_SUB(CURRENT_TIMESTAMP, INTERVAL ? SECOND)。写入时间和比较时间来自同一个时钟，应用服务器之间的时钟偏差不会影响判断。
实现时需要确认的一点。 第 1 步在事务内捕获了唯一键冲突后正常返回。在 MySQL 中，单条语句失败只回滚这条语句，事务本身仍然可用。但部分数据访问框架会在异常被翻译时把事务标记为 rollback-only，导致提交时报错。采用这一写法前，需要确认所用框架的行为。
所有状态写入都带上预期的当前状态，并检查影响行数：
-- 批次终态转移：只有仍处于 RUNNING 的批次才能转移
UPDATE merge_batch SET status = 2 WHERE id = ? AND status = 1; -- 影响行数必须为 1
-- 普通行的乐观并发控制：以刚读到的状态作为版本
UPDATE operation SET status = ?, ... WHERE operation_id = ? AND status = ?;
影响行数为 0 时，表示状态已被别处改动，写入方抛出”被抢占”异常。
这类守卫写入在组合事务中的位置也很重要。批次失败时的结算事务包含多步：把批次标记为 FAILED，再删除或重置该批次下每个申请的记录。我们把批次的守卫写入放在第一步：
tx.execute(List.of(
() -> batchRepo.markFailed(batchId, code, msg), // WHERE status = RUNNING，影响行数须为 1
() -> resetOperations(batchId) // 后续步骤
));
如果这个批次已经被另一条路径结算过（例如超时扫描与运行中的任务同时到达），第一步就会失败，整个事务回滚，后续的重置不会执行第二遍。
唯一约束冲突在不同场景下有明确的业务含义，我们分别处理：
// 入队：重复表示"已经入队过"，返回 false，不报错
public boolean admit(String opId) {
try {
insert("INSERT INTO merge_batch_request (operation_id) VALUES (?)", opId);
return true;
} catch (DuplicateKeyException e) {
return false;
}
}
// 审计记录：重复表示"已经记录过"，不覆盖已有行（它可能已经是终态）
public void insertAudit(Audit a) {
try { insert(a); } catch (DuplicateKeyException e) { /* 预期内的去重结果 */ }
}
// 请求幂等：先查；查不到则插入；插入冲突说明并发请求先插入了，重读并返回胜出方的结果
public Result checkOrInsert(String requestId, String opId) {
Record r = findById(requestId);
if (r != null) return Result.duplicate(r.operationId());
try {
insert(new Record(requestId, opId));
return Result.fresh();
} catch (DuplicateKeyException e) {
Record winner = findById(requestId);
return winner != null ? Result.duplicate(winner.operationId())
: Result.retryLater();
}
}
这三种写法都没有显式加锁，并发下的正确性来自唯一约束本身。
binding 表以 (subject_id, target_key) 为唯一键，每个关系只有一行。但每次申请会生成一个新的 operation_id，于是”每次操作一行”的写入模型与”每个关系一行”的唯一键之间需要协调：
Binding existing = findBySubjectAndTarget(subject, target);
if (existing == null) {
insert(newRow); // 首次申请
} else if (REAPPLIABLE.contains(existing.status())) {
int n = update(
"UPDATE binding SET status = ?, operation_id = ?, expires_at = ? " +
"WHERE subject_id = ? AND target_key = ? AND status = ?", // 锁定读到的确切旧状态
newRow.status(), newRow.operationId(), newRow.expiresAt(),
subject, target, existing.status());
if (n == 0) throw new PreemptedException(); // 并发的重新申请或状态变化
} else {
throw new ConstraintViolationException(); // 拒绝覆盖活跃或待恢复的行
}
operation_id，这正是上一篇里过期回调被识别出来的依据。operation_id 会被替换，挂在旧 operation_id 上的恢复流程将找不到目标。需要同时修改 operation 和 binding 两张表的转移，统一先锁 operation、再锁 binding，不同路径使用相同的加锁顺序，避免死锁。推进方法只在本次调用真正改变了状态时返回非空结果，调用方据此决定是否产生副作用（发送指标、通知）。这样并发的两条路径中，只有一条会产生副作用（细节见上一篇 3.7 节）。
批次失败时 MR 可能已经存在，并且可能恰好在失败判定之后合并成功。结算流程是：如果 MR 仍处于打开状态，先关闭它，然后重新读取 MR 的最终状态。
version 列，目前尚未启用。对于可能往返的状态，后续计划改用单调递增的版本号。CASE WHEN status IN (1, 4) THEN partition_key END，唯一索引就变成”每个分区最多一个活跃批次”。IN 列表最多可达上千个占位符，且未分片。后续计划改为批量查询、批量插入，并对 IN 列表分片。status 加时间范围过滤，但只有单列时间索引；取最大 MR 编号使用 ORDER BY CAST(mr_id AS UNSIGNED)，表达式排序无法利用索引。后续计划补充 (status, updated_at) 复合索引，并把 MR 编号改存为数值列。created_at 精度为秒，认领条件是 created_at < CURRENT_TIMESTAMP，因此当前这一秒内入队的申请要等到下一轮。这是有意的取舍，但需要在文档中写明。我们维护一个”配置即代码”的自助变更系统。用户提交一次变更申请后，系统需要依次完成：
一次变更跨越审批系统、Git 托管平台（GitLab）和 CI 三个外部系统，耗时从几分钟到几小时不等。如果把它当作一次普通的同步请求来处理，会面临几个问题：HTTP 连接无法等待这么久；任何一步失败都可能让请求停在一个无人知晓的中间态；外部系统的回调可能重复、迟到或乱序；进程重启会丢失正在执行的步骤。
我们为这条流程设定了四个目标：
外部调用不在本地事务内。 在 GitLab 上创建分支、提交和 MR 之后，本地写库仍可能失败；反过来，本地状态已经写入，远端调用也可能失败。两边之间不存在可以依赖的原子性。
事件来源多，且投递语义弱。 驱动状态变化的来源包括：用户提交、审批系统回调、系统自身推进、部署流水线回调、定时对账、运维人员手动恢复。外部回调按”至少一次”投递，可能迟到，也可能早于我们自己的状态写入到达。
上游响应存在歧义。 GitLab 对”同一账号重复批准”返回 HTTP 401，与”该账号无权批准”是同一个状态码。只看响应无法区分两者。
部署形态。 服务多实例部署。我们不希望为这一条流程引入工作流引擎或分布式锁等新组件，现有的共享协调点只有关系数据库。
流程需要演进。 流程顺序要从”先建 MR 再审批”调整为”先审批再建 MR”，切换时已有审批在途。上游平台还计划在审批接口中新增一个必填的结构化字段，并给出了兼容期。
我们用两张表分别记录两个粒度的状态：
operation 表记录步骤状态，细到”流水线超时”“rebase 冲突”“机器人批准失败”。状态码按阶段划分号段（创建阶段 10001 起、处理阶段 10101 起、关闭阶段 10201 起），按号段前缀即可聚合统计。binding 表记录对外状态，只表达用户关心的阶段：审批中、MR 创建中、合并中、已合并、已生效、失败、已拒绝。该表以 (subject_id, target_key) 为唯一键，每个”主体—目标”关系只有一行。enum StepStatus { // 细粒度：服务于排障和指标
CREATE_STARTED(10001), CREATE_SUCCEEDED(10002), CREATE_PIPELINE_FAILED(10004),
HANDLE_STARTED(10101), HANDLE_APPROVED(10102), HANDLE_REBASE_CONFLICT(10105),
HANDLE_PIPELINE_PENDING(10501), CALLED_BACK(10301), /* ... */;
}
enum BindingStatus { // 粗粒度：服务于展示和"能否重新申请"
APPROVAL_SENDING, APPROVAL_SENT, MR_CREATING, MR_CREATED, MERGING, MERGED, VALIDATED,
CREATE_FAILED, HANDLE_FAILED, REJECTED, CLOSED;
/** 唯一的事实来源：数据层和接口层都引用它判断能否重新申请。 */
static final Set<BindingStatus> REAPPLIABLE = Set.of(REJECTED, CLOSED);
}
之所以拆成两层，是因为两类读者的需求不同。排障需要知道请求停在哪个具体步骤；用户和”能否重新申请”的判断只关心所处的大阶段。如果只用一个状态字段，每次细化内部步骤都会牵动前端展示和重新申请规则。
每次状态转移都在同一个本地事务里同时写两张表：
void transition(OperationBuilder op, StepStatus step, BindingStatus status) {
tx.execute(List.of(
() -> operationRepo.update(op.status(step)), // 以刚读到的状态做乐观并发校验
() -> bindingRepo.updateStatus(op.id(), status)
));
}
下图是对外状态的主路径（省略了各类失败分支）：
stateDiagram-v2
[*] --> APPROVAL_SENT: 提交申请
APPROVAL_SENT --> REJECTED: 审批拒绝或撤回
APPROVAL_SENT --> MR_CREATING: 审批通过
MR_CREATING --> MR_CREATED: 检查流水线通过
MR_CREATING --> CREATE_FAILED
MR_CREATED --> MERGING
MERGING --> MERGED: 合并成功
MERGING --> HANDLE_FAILED
MERGED --> VALIDATED: 部署回调或定时对账
REJECTED --> [*]
VALIDATED --> [*]
提交接口只做同步校验（参数、幂等、是否已有进行中的申请），然后把长流程提交到有界线程池，立即返回 HTTP 202 和 operationId。客户端按 operationId 轮询。
private void fireAsync(String opId, Task task, StepStatus failStep, BindingStatus failStatus) {
try {
executor.execute(() -> {
try {
task.run();
} catch (Exception e) {
log.error("async step failed", e); // 失败状态已由切面写入，见下文
} catch (Throwable t) {
log.error("[CRITICAL] JVM-level error", t); // JVM 可能已处于异常状态，只记录不写库
}
});
} catch (RejectedExecutionException e) {
// 线程池满或正在关闭：把失败写进库，轮询方看到"失败"而不是"处理中"
tx.execute(List.of(
() -> operationRepo.updateStatus(opId, failStep),
() -> bindingRepo.updateStatus(opId, failStatus)));
}
}
线程池的核心线程数等于最大线程数，队列有界，拒绝策略选择 AbortPolicy。没有选另外两种常见做法，原因如下：
CallerRunsPolicy 会让 Web 线程执行一个耗时数分钟的任务，过载会被传导到所有接口。AbortPolicy 加上”拒绝即落库”，把过载转化成一个用户可见、可以统计的失败状态。
每个步骤方法通过注解声明自己的失败状态，由切面统一兜底：
@WorkflowStep(onErrorStep = StepStatus.HANDLE_MERGE_FAILED,
onErrorStatus = BindingStatus.HANDLE_FAILED)
public Result handleMergeRequest(String opId, long mrIid) { ... }
方法内部已经识别的失败（如流水线失败、rebase 冲突）由业务代码写入更具体的状态；未预料的异常由切面写入注解声明的状态。两者合起来，保证任何一条退出路径都会留下终态。
审批回调的处理分两层。第一层按回调自身携带的请求 ID 做幂等，挡住重复投递。第二层判断这个回调是否仍然有效：
Binding row = bindingRepo.findByOperationId(callback.operationId());
if (row == null || !AWAITING_APPROVAL.contains(row.status())) {
return accepted("IGNORED_STALE"); // 返回 2xx，避免上游把它当作失败反复重试
}
这里有两个设计点。
binding 行会被原地重置并换上新的 operationId（见数据库篇）。旧申请的迟到回调因此查不到行，被直接忽略，不会把新申请推进到错误的状态。AWAITING_APPROVAL = {APPROVAL_SENDING, APPROVAL_SENT}。我们在调用审批接口之前写入 SENDING，调用成功后写入 SENT。审批系统的回调可能比 SENT 的写入更早到达，如果等待集合只包含 SENT，这类回调会被误判为过期。本地状态与远端状态之间没有原子性，所以每个会改动远端的步骤在执行前先读远端状态：
机器人批准这一步需要额外处理 401 的歧义：
void approveAsReviewer(Api reviewer, long mrIid) throws ApiException, InterruptedException {
int maxRetries = Math.max(0, config.getInt("approval.maxRetries", 3)); // 负值按 0 处理
ApiException last = null;
for (int attempt = 1; attempt <= maxRetries + 1; attempt++) {
if (hasApprovalFrom(reviewer, mrIid)) {
return; // 已经批准过：跳过调用
}
try {
approver.approve(reviewer, mrIid);
return;
} catch (ApiException e) {
last = e;
if (attempt > maxRetries) break;
Thread.sleep(backoffBaseMs << (attempt - 1)); // 指数退避
}
}
// 重复批准与无权批准都返回 401。最后再读一次，确认批准是否其实已经存在。
if (hasApprovalFrom(reviewer, mrIid)) {
return;
}
throw last;
}
这些检查让”从中断处重新执行”变得安全，运维恢复工具可以直接重新触发某个步骤。
rebase 结果和流水线状态都需要轮询。我们把轮询抽象成一个通用组件：前 N 次用短间隔，之后改用长间隔，达到上限后返回超时。轮询结果有三种：通过、失败、超时。
接口层据此向用户给出不同的提示：确定性失败提示”需要联系维护团队”，结果未知的情况提示”可以继续等待”（详见 API 篇）。
把流程从”先建 MR 再审批”改为”先审批再建 MR”时，我们没有设置停机或排空窗口，而是让两种顺序在一段时间内并存：
回调按载荷形态区分流程。 旧流程在发起审批时 MR 已经存在，会把 MR 编号放进审批单的扩展字段；新流程发起审批时还没有 MR。回调处理据此判断：
boolean legacyFlow = StringUtils.isNotEmpty(callback.ext().get("mrId"));
if (approved) {
if (legacyFlow) workflow.fireHandle(opId, mrId); // MR 已存在：批准并合并
else workflow.fireCreateAfterApproval(opId); // 先创建 MR
}
切换开关前发出、切换后才回调的审批，仍按旧流程处理。
创建步骤通过查库判断”插入还是推进”，而不是依赖调用方传入的标志：
if (operationRepo.exists(opId)) {
transition(op, CREATE_STARTED, MR_CREATING); // 新流程：行在发起审批时已创建
} else {
insertOperationAndBinding(op); // 旧流程：首次创建
}
这让同一个步骤对两种顺序都成立，对运维重新触发也保持幂等。
部署流水线的回调可能丢失，相应的请求会停在”已合并”。我们用一个定时任务收敛这类记录。
滑动时间窗口。 每次只扫描最后变更时间位于 (now - maxAge, now - minAge) 内的”已合并”记录。早于 minAge 的记录可能只是回调还在路上，跳过；晚于 maxAge 的记录移出窗口，以此限制单次工作量。
用水位线代替逐行查询。 回调表只记录 MR 编号，不含业务字段。对账任务只做两次查询：一次 IN 查询批量取出 operationId → mrIid，一次查询取回调表中最大的 MR 编号。之后对每一行做一次比较：
mrIid <= maxCallbackIid → 推进为"已生效"
mrIid > maxCallbackIid → 保持"已合并"，等待下一轮
mrIid == max 表示这个 MR 自己的回调已经到达；mrIid < max 表示编号更大的 MR 已有回调，而 MR 编号在项目内单调递增，由此推断较早的这条回调已经丢失。这条推断成立的前提是：部署流水线按合并顺序执行，且后一次执行不会遗漏之前已合并的变更。minAge 窗口用来防止把”迟到”误判为”丢失”。
与正常回调路径并发时只生效一次。 回调处理和对账任务都会调用同一个状态推进方法：
@Transactional
public String markValidated(String opId) {
Operation op = operationRepo.selectForUpdate(opId); // 固定加锁顺序：先 operation
Binding b = bindingRepo.selectForUpdate(opId); // 再 binding
if (b == null || (b.status() != MERGED && b.status() != VALIDATED)) {
return null; // 不符合条件：幂等空操作
}
if (op.status() != CALLED_BACK) {
operationRepo.updateStatus(opId, CALLED_BACK); // 修复可能滞后的步骤状态
}
if (b.status() == MERGED) {
requireOneRow(bindingRepo.update(
"SET status = VALIDATED WHERE operation_id = ? AND status = MERGED", opId));
return b.subjectId(); // 只有真正翻转时才返回非空
}
return null;
}
两条路径并发时，行锁保证只有一方完成翻转，另一方读到 VALIDATED 后返回 null。调用方只在返回非空时计入”生效成功”指标，并且等外层事务提交之后再统一发出，所以事务回滚不会留下多计的指标，并发也不会导致重复计数。
上游平台计划在批准接口中新增一个必填字段：一组需要逐项确认的检查项。我们使用的 GitLab 客户端库无法表达这个字段。处理方式如下：
成熟的工作流引擎能提供持久化执行、自动重试和崩溃恢复，这些正是本方案中手工实现的部分。我们没有采用的原因是：这条流程的步骤数量有限；团队已有的共享基础设施只有关系数据库；而真正困难的部分（外部响应的歧义、回调的过期判断、以远端状态为准的幂等）是业务语义，引擎并不能替我们解决。代价是部分持久化执行能力需要自己补齐，见第 5 节。
operationId 查到所处阶段和停止的具体步骤，排障不需要翻日志重建过程。