后端(四面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:
@@ -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;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user