后端(四面9分批次): 锁跳过留痕、状态词表收成单点、版本硬地板进 yml 并记账

- 14 处「拿不到锁就 continue」过去零日志,现统一带可聚合锚点并有留痕判据
  (LockSkipWitnessTest 7 例 + LockSkipSilentExitGuardrailTest 4 例)。
- 任务状态词表:散落内联集合改由单一定义点判方向(TaskStatusVocabularyRatchetTest 7 例),
  CANCELED/CANCELLED 只做归一映射,没改库值也没改对外契约。
- 版本硬地板三键(min-supported / enforce / rejectUnreported)此前在任何 yml 里 0 处=出厂即惰性;
  现在入册且 enforce=false 走记账模式(ClientVersionFloorConfigTest 9 例),真挡谁留给用户拍。
- 业务码→HTTP 状态只做映射单点 + 开关(默认关,开启前逐字节等价,BusinessErrorHttpStatusTest 8 例);
  直接翻面会让三个前端把业务失败读成网络挂了。
- 验收:mvn -o test 这 5 个类 35 例 0 红(用 python subprocess 起 mvn——bash 里 cmd 包一层
  开的是交互式 cmd,rc 是 cmd 的,会给出假的 rc=0)。
This commit is contained in:
2026-10-09 23:09:37 +08:00
parent 54cfb70a43
commit 15094309cf
63 changed files with 2454 additions and 95 deletions
@@ -0,0 +1,182 @@
package com.nanri.aiimage.common.util;
import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.MeterRegistry;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;
import java.util.concurrent.atomic.AtomicLong;
/**
* 分布式锁「没拿到就跳过」的可聚合出口(2026-10-09 评审「稳定 5.5」项)。
*
* <p>此前 {@code if (lockHandle == null) { continue; }} 在全树有 <b>27</b> 处(12 个文件),
* 一处日志都不留。表现是:巡检任务每轮都跑、锁竞争越激烈被跳过的任务越多,而现网看不出任何痕迹
* ——卡死任务没被收尾、结果作业没被续跑,日志里连一行都没有,只能靠人肉反推。跟
* {@code TaskFileJobPublisher} 的 MQ 降级是同一个病:那条已经补了 {@code task.file.job.mq.degraded}
* 计数出口,这批锁跳过出口是它的同类。
*
* <p>所以这里定的不是"把级别调大",而是<b>可聚合</b>:
* <ul>
* <li>锚点 {@value #ANCHOR}:一条 grep 得动的字面量,{@code point=}/{@code outcome=} 给聚合维度;</li>
* <li>进程内台账 {@link #countOf}:按 point 累计,供判据与巡检直接读;</li>
* <li>Micrometer 指标 {@value #METRIC}(可选,注册表缺席时只留日志与本地台账,判定一字不动,
* 与 {@code TaskFileJobPublisher} 同一口径)。</li>
* </ul>
*
* <p>{@code point} 是<b>稳定字面量</b>(形如 {@code brand:stale-running-scan}),不锚行号:
* 方法搬家、加几行注释都不该让一条已经在响的告警变成孤儿。新增调用点请同步
* {@code LockSkipWitnessTest} 里的点位台账。
*
* <p>静态 API 是有意的:这 12 个 Service 清一色 {@code @RequiredArgsConstructor},
* 塞一个实例字段等于改 12 个构造器签名、打断几十支 {@code new XxxService(...)} 的既有判据。
* 注册表由 Spring 在启动时绑一次({@link #LockSkipWitness});没起 Spring 的单测照样能调
* {@link #record},台账与日志都不依赖容器。
*/
@Slf4j
@Component
public class LockSkipWitness {
/** 巡检/判据用的日志锚点。改这条字面量等于把现网告警规则删掉,动之前先对巡检。 */
public static final String ANCHOR = "[lock-skip]";
/** 指标名:tag {@code point}/{@code outcome}/{@code moduleType}。 */
public static final String METRIC = "aiimage.distributed.lock.skip";
/** outcome:循环里跳过这一项,后面还有别的(巡检批量扫描)。 */
public static final String OUTCOME_SKIPPED = "skipped";
/** outcome:整次调用直接返回,本轮什么都没用做(含 try-with-resources 里锁没拿到)。 */
public static final String OUTCOME_ABANDONED = "abandoned";
/** outcome:调用方没给结果类型——单独成桶,不折叠进上面两个真桶。 */
public static final String OUTCOME_UNKNOWN = "unknown";
/** 台账键上限:point 是有限集合(调用点数),超上限后不再新增键,防无界增长。 */
static final int LEDGER_KEYS_MAX = 256;
private static final ConcurrentMap<String, AtomicLong> LEDGER = new ConcurrentHashMap<>();
private static final AtomicLong TOTAL = new AtomicLong();
/** 可为 null:没配 Micrometer 注册表时只留日志 + 本地台账。 */
private static volatile MeterRegistry registry;
public LockSkipWitness() {
}
/** 生产接线:注册表可选,缺席时不影响跳过语义与日志。 */
@Autowired
public LockSkipWitness(ObjectProvider<MeterRegistry> meterRegistryProvider) {
bind(meterRegistryProvider == null ? null : meterRegistryProvider.getIfAvailable());
}
/** 供 Spring 构造与单测显式接线;null 表示只用日志与本地台账。 */
public static void bind(MeterRegistry meterRegistry) {
registry = meterRegistry;
if (meterRegistry != null) {
// 计数器按 point 现建现取,注册一次总览 gauge,便于「一个 point 都没命中」也能看到 0。
Gauge.builder(METRIC + ".total", TOTAL, AtomicLong::get).register(meterRegistry);
}
}
/**
* 记一次「没拿到锁所以跳过/放弃」。
*
* @param point 稳定点位字面量(不要用行号/方法名+行号拼)
* @param outcome {@link #OUTCOME_SKIPPED} 或 {@link #OUTCOME_ABANDONED}
* @param moduleType 业务模块类型,可为 null(归一为 unknown)
* @param taskId 任务 id,可为 null
*/
public static void record(String point, String outcome, String moduleType, Long taskId) {
String key = point == null || point.isBlank() ? "unpointed" : point.trim();
// outcome 缺失归一到 unknown 而不是猜一个真桶:折叠进 skipped/abandoned 会让聚合面说谎。
String normalizedOutcome = outcome == null || outcome.isBlank() ? OUTCOME_UNKNOWN : outcome.trim();
String normalizedModule = moduleType == null || moduleType.isBlank() ? "unknown" : moduleType.trim();
long count = ledgerOf(key).incrementAndGet();
long total = TOTAL.incrementAndGet();
MeterRegistry current = registry;
if (current != null) {
current.counter(METRIC,
"point", key,
"outcome", normalizedOutcome,
"moduleType", normalizedModule)
.increment();
}
log.warn("{} point={} outcome={} moduleType={} taskId={} skippedSoFar={} total={} —— "
+ "未拿到分布式锁,本轮跳过(锁被其它实例持有或锁名不可用)",
ANCHOR, key, normalizedOutcome, normalizedModule, taskId, count, total);
}
/** 最省事的写法:跳过(skipped)结果 + 不带模块上下文。 */
public static void recordSkip(String point, String moduleType, Long taskId) {
record(point, OUTCOME_SKIPPED, moduleType, taskId);
}
/** 最省事的写法:整次放弃(abandoned)结果 + 不带模块上下文。 */
public static void recordAbandoned(String point, String moduleType, Long taskId) {
record(point, OUTCOME_ABANDONED, moduleType, taskId);
}
/** 定时任务级作业锁没抢到:整轮直接返回,没有模块/任务上下文。 */
public static void skipped(String point) {
record(point, OUTCOME_SKIPPED, null, null);
}
/** 定时任务级作业锁没抢到且方法直接返回:本轮什么都没做。 */
public static void abandoned(String point) {
record(point, OUTCOME_ABANDONED, null, null);
}
private static AtomicLong ledgerOf(String key) {
AtomicLong existing = LEDGER.get(key);
if (existing != null) {
return existing;
}
if (LEDGER.size() >= LEDGER_KEYS_MAX) {
// 超出上限:仍计入总量与日志,只是不再为未知点位开新键。
return LEDGER.computeIfAbsent("overflow", k -> new AtomicLong());
}
return LEDGER.computeIfAbsent(key, k -> new AtomicLong());
}
/** 某个点位累计跳过次数;没记过就是 0。 */
public static long countOf(String point) {
AtomicLong value = LEDGER.get(point);
return value == null ? 0L : value.get();
}
/** 全部点位的累计台账快照(不可变副本,按点位名排序)。 */
public static Map<String, Long> snapshot() {
Map<String, Long> out = new LinkedHashMap<>();
LEDGER.entrySet().stream()
.sorted(Map.Entry.comparingByKey())
.forEach(e -> out.put(e.getKey(), e.getValue().get()));
return Collections.unmodifiableMap(out);
}
/** 全部点位合计。 */
public static long total() {
return TOTAL.get();
}
/**
* 测试专用:清空台账,返回清理前的快照。
*
* <p>生产代码不要调——它会把巡检窗口里的计数抹平,看起来像"这段时间没人被锁挡"。
* 之所以留着:判据要能钉住"走到这个分支留下了可查记录",而点位是全局静态计数,
* 不清就测不出单次增量(用 delta 也能测,但 27 个点位共用一张表,清一次比 27 处读基线更好读)。
*/
public static Map<String, Long> resetLedgerForTests() {
Map<String, Long> before = snapshot();
LEDGER.clear();
TOTAL.set(0L);
return before;
}
}