后端(四面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,233 @@
package com.nanri.aiimage.common.util;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.fail;
import com.nanri.aiimage.testutil.SourceScan;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Stream;
import org.junit.jupiter.api.Test;
/**
* 锁跳过出口的<b>逐处</b>判据(2026-10-09 评审「稳定 5.5」项 1,权重 1.5)。
*
* <p>要拦的行为很具体:{@code if (<某个 lock 变量> == null) { continue; }} /
* {@code { return; }} —— 巡检任务每轮跑、被锁挡掉的任务直接消失,一行日志都不留。
* 实测基线(2026-10-10 自己数出来的,不是评审给的 14):全树 {@code src/main/java} 共
* <b>29</b> 处这种形状,28 处已接 {@link LockSkipWitness},1 处判定不该接(见
* {@link #LEDGERED_EXCEPTIONS})。
*
* <p>判据打在<b>分支体</b>上而不是打在"某个类里出现过锚点"上:分支体剥掉注释后必须只剩
* {@code continue;} / {@code return;}(顶多一行 {@code LockSkipWitness.*} 调用)。
* 这样"锚点方法存在但没人调"(2026-10-09 踩过的那坑)在这儿会直接红——
* {@link #witnessedSiteCountCannotShrink} 把已接线的点位数钉成 28,掉一处就红,
* {@link #everyPointLiteralIsUsedByExactlyOneSite} 保证点位没有互相覆盖成一坨。
*/
class LockSkipSilentExitGuardrailTest {
/** 形如 lock / jobLock / taskLockHandle / neverReportedLock / distributedJobLockService 的变量判空。 */
private static final Pattern LOCK_NULL_CHECK =
Pattern.compile("if\\s*\\(\\s*(\\w*[Ll]ock\\w*)\\s*==\\s*null\\s*\\)\\s*\\{");
/** 分支体剥掉出口调用后,只剩这两种语句就是「跳过但什么都不做」。 */
private static final List<String> BARE_EXITS = List.of("continue;", "return;");
private static final Pattern WITNESS_CALL = Pattern.compile("LockSkipWitness\\.\\w+\\s*\\(([^;]*)\\);");
/**
* 例外台账:<b>文件名 -&gt; 判定不该接的原因</b>。加一行要有现网证据,删一行就是补了出口。
*
* <p>{@code TaskDistributedLockService.close()} 里的 {@code heldLock == null} 不是"跳过任务":
* 它是重复 close 的幂等护栏(第二次 close 时本地登记已经没了,无事可做),不挡任何工作、
* 也不丢数据。给它加锚点等于每次正常重复 close 都刷一条 WARN,把真正在响的那 28 处淹掉。
*/
private static final Set<String> LEDGERED_EXCEPTIONS =
Set.of("TaskDistributedLockService.java");
/** 已接线点位数的硬分母:只许升(新增出口),不许降(出口被摘)。 */
private static final int MIN_WITNESSED_SITES = 28;
@Test
void everyLockNullSkipBranchCarriesAVisibleWitness() {
List<String> unwitnessed = new ArrayList<>();
int witnessed = 0;
for (Path file : mainSources()) {
String source = SourceScan.withoutComments(read(file));
for (String body : lockNullBranches(source)) {
if (!isSkipOnlyBranch(body)) {
continue;
}
if (body.contains("LockSkipWitness.")) {
witnessed++;
} else if (!LEDGERED_EXCEPTIONS.contains(file.getFileName().toString())) {
unwitnessed.add(file.getFileName() + " -> " + body.strip());
}
}
}
// 自检(否定句必须配同口径非零对照):扫描器真抓得到已接线的那批,否则下面那句 isEmpty() 是恒绿
assertThat(witnessed)
.as("已接 LockSkipWitness 的锁跳过点位数(掉一处就是在摘出口)")
.isGreaterThanOrEqualTo(MIN_WITNESSED_SITES);
assertThat(unwitnessed)
.as("剩下「判空即跳过且零日志」的锁出口,必须全在例外台账里")
.isEmpty();
}
@Test
void lockedExceptionsStayExactlyOneAndCannotGrowQuietly() {
List<String> bareExceptions = new ArrayList<>();
for (Path file : mainSources()) {
if (!LEDGERED_EXCEPTIONS.contains(file.getFileName().toString())) {
continue;
}
String source = SourceScan.withoutComments(read(file));
for (String body : lockNullBranches(source)) {
if (isSkipOnlyBranch(body) && !body.contains("LockSkipWitness.")) {
bareExceptions.add(file.getFileName() + ":" + body.strip());
}
}
}
// 台账里那个例外只剩 1 处(close() 的幂等护栏)。变成 2 处说明同一个文件里又新写了一处裸跳过,
// 那不是"台账里已论证过的形状",必须停下来看。
assertThat(bareExceptions)
.as("例外台账文件里的裸跳过分支数(基线:TaskDistributedLockService.close() 一处)")
.hasSize(1);
}
/**
* 「跳过但什么都不做」的分支体:剥掉出口调用与空白后,只剩 {@code continue;} 或 {@code return;}。
* 有别的语句(比如 {@code taskFileJobService.requeue(...)})就不是被拦的对象——那条路本来就留了痕。
*/
private static boolean isSkipOnlyBranch(String body) {
String stripped = body.replaceAll("LockSkipWitness\\.\\w+\\s*\\([^;]*\\);", "").strip();
return BARE_EXITS.contains(stripped);
}
@Test
void everyPointLiteralIsUsedByExactlyOneSite() {
List<String> points = new ArrayList<>();
for (Path file : mainSources()) {
if ("LockSkipWitness.java".equals(file.getFileName().toString())) {
continue;
}
Matcher m = WITNESS_CALL.matcher(SourceScan.withoutComments(read(file)));
while (m.find()) {
String args = m.group(1);
String first = args.split(",")[0].strip();
if (first.startsWith("\"") && first.endsWith("\"") && first.length() > 2) {
points.add(first);
} else if (!first.isBlank()) {
fail("点位字面量必须写死在第一个参数(不打行号、不拼变量),实际=" + args
+ " @ " + file.getFileName());
}
}
}
Set<String> distinct = new LinkedHashSet<>(points);
assertThat(points)
.as("全树 LockSkipWitness 调用数")
.hasSizeGreaterThanOrEqualTo(MIN_WITNESSED_SITES);
assertThat(distinct)
.as("点位字面量必须一一对应:两个跳过处共用一个点位,现网就分不出是谁在被挡")
.hasSize(points.size());
// 命名口径也钉一下:点位都是小写 kebab,允许带一个 ":用途" 后缀。
// 带后缀的是任务级点位(模块内多处跳过要分得开);不带后缀的是作业锁点位,
// 它直接沿用 tryLock 已有的锁名(如 expired-account-task-stop),不去另起一套标识。
assertThat(distinct).allSatisfy(point ->
assertThat(point).matches("\"[a-z0-9][a-z0-9.-]*(:[a-z0-9.-]+)?\""));
}
@Test
void anchorIsReusedFromTheSingleDefinitionPoint() {
// 锚点只有 LockSkipWitness 一处定义;业务侧禁止把 "[lock-skip]" 抄成字面量,
// 否则改了常量之后 grep 得到的是半套出口。
String witnessSource = SourceScan.withoutComments(SourceScan.sourceText("LockSkipWitness.java"));
assertThat(witnessSource).contains("public static final String ANCHOR = \"[lock-skip]\"");
List<String> copycats = new ArrayList<>();
for (Path file : mainSources()) {
if ("LockSkipWitness.java".equals(file.getFileName().toString())) {
continue;
}
if (SourceScan.withoutComments(read(file)).contains("[lock-skip]")) {
copycats.add(file.getFileName().toString());
}
}
assertThat(copycats).as("[lock-skip] 字面量不得在业务侧被抄第二遍").isEmpty();
}
// ---- 扫描助手:抓 if (<lock> == null) { … } 的分支体(含大括号配对,注释已剥) ----
private static List<String> lockNullBranches(String sourceWithoutComments) {
List<String> bodies = new ArrayList<>();
Matcher m = LOCK_NULL_CHECK.matcher(sourceWithoutComments);
while (m.find()) {
int open = m.end() - 1;
int close = matchingBrace(sourceWithoutComments, open);
if (close > open) {
bodies.add(sourceWithoutComments.substring(open + 1, close));
}
}
return bodies;
}
/** 朴素大括号配对(剥注释后字符串字面量里的大括号仍可能干扰,够用即止:只在判空分支上用)。 */
private static int matchingBrace(String text, int openIndex) {
int depth = 0;
for (int i = openIndex; i < text.length(); i++) {
char c = text.charAt(i);
if (c == '{') {
depth++;
} else if (c == '}') {
depth--;
if (depth == 0) {
return i;
}
}
}
return -1;
}
private static List<Path> mainSources() {
Path root = moduleRoot().resolve("src/main/java");
try (Stream<Path> walk = Files.walk(root)) {
List<Path> files = walk.filter(p -> p.toString().endsWith(".java"))
.sorted(Comparator.comparing(Path::toString))
.toList();
assertThat(files).as("src/main/java 扫到的 .java 数(扫不到就是路径坏了)")
.hasSizeGreaterThan(900);
return files;
} catch (IOException e) {
throw new IllegalStateException("扫描失败: " + root, e);
}
}
private static Path moduleRoot() {
Path here = Path.of("").toAbsolutePath();
if (Files.isDirectory(here.resolve("src/main/java"))) {
return here;
}
Path nested = here.resolve("backend-java");
if (Files.isDirectory(nested.resolve("src/main/java"))) {
return nested;
}
throw new IllegalStateException("无法定位 backend-java 源码目录(cwd=" + here + ")");
}
private static String read(Path file) {
try {
return Files.readString(file);
} catch (IOException e) {
throw new IllegalStateException("读不了 " + file, e);
}
}
}
@@ -0,0 +1,182 @@
package com.nanri.aiimage.common.util;
import static org.assertj.core.api.Assertions.assertThat;
import ch.qos.logback.classic.Logger;
import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.read.ListAppender;
import io.micrometer.core.instrument.Measurement;
import io.micrometer.core.instrument.simple.SimpleMeterRegistry;
import java.util.ArrayList;
import java.util.List;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import org.slf4j.LoggerFactory;
/**
* 分布式锁跳过出口({@link LockSkipWitness})的判据(2026-10-09 评审「稳定 5.5」项 1)。
*
* <p>这条判据要钉住的是<b>两件事</b>,不是两件里的一件:
* <ol>
* <li>锚点字面量真的打在日志上(能被巡检 grep);</li>
* <li>调用它确实<b>累计</b>得出数(可聚合,不是"记了一行没人看的日志")。</li>
* </ol>
* 只判第 1 件就会重演 2026-10-09 踩过的坑:锚点方法存在、零调用者,判据恒绿而现网照旧。
* 调用面由 {@link LockSkipSilentExitGuardrailTest} 按点位台账逐处钉住,两支合起来才是"出口在响"。
*/
class LockSkipWitnessTest {
@AfterEach
void unbindRegistry() {
LockSkipWitness.bind(null);
}
private ListAppender<ILoggingEvent> capture() {
Logger logger = (Logger) LoggerFactory.getLogger(LockSkipWitness.class);
ListAppender<ILoggingEvent> appender = new ListAppender<>();
appender.start();
logger.addAppender(appender);
return appender;
}
private void release(ListAppender<ILoggingEvent> appender) {
((Logger) LoggerFactory.getLogger(LockSkipWitness.class)).detachAppender(appender);
}
@Test
void recordEmitsAnchorLineWithAggregationFields() {
ListAppender<ILoggingEvent> captured = capture();
try {
long before = LockSkipWitness.total();
LockSkipWitness.record("test:anchor-shape", LockSkipWitness.OUTCOME_SKIPPED, "PUBLISH", 123L);
List<String> messages = captured.list.stream().map(ILoggingEvent::getFormattedMessage).toList();
assertThat(messages).as("走到跳过分支必须留下一行日志").hasSize(1);
String line = messages.get(0);
// 锚点 + 聚合维度都得在这一行里,巡检才分得出是哪个点位、挡了多少
assertThat(line).contains(LockSkipWitness.ANCHOR)
.contains("point=test:anchor-shape")
.contains("outcome=skipped")
.contains("moduleType=PUBLISH")
.contains("taskId=123");
assertThat(captured.list.get(0).getLevel().toString()).isEqualTo("WARN");
assertThat(LockSkipWitness.total()).as("同一行也必须进台账计数").isEqualTo(before + 1);
} finally {
release(captured);
}
}
@Test
void ledgerAggregatesPerPointAndSnapshotIsReadable() {
LockSkipWitness.resetLedgerForTests();
LockSkipWitness.recordSkip("test:agg-a", "BRAND", 1L);
LockSkipWitness.recordSkip("test:agg-a", "BRAND", 2L);
LockSkipWitness.abandoned("test:agg-b");
assertThat(LockSkipWitness.countOf("test:agg-a")).isEqualTo(2);
assertThat(LockSkipWitness.countOf("test:agg-b")).isEqualTo(1);
assertThat(LockSkipWitness.countOf("test:never-recorded")).as("没记过的点位读数必须是 0 而不是抛").isZero();
assertThat(LockSkipWitness.snapshot())
.as("快照要能一次看全点位(巡检/告警的取数面)")
.containsEntry("test:agg-a", 2L)
.containsEntry("test:agg-b", 1L);
assertThat(LockSkipWitness.total()).isEqualTo(3);
}
@Test
void skippedAndAbandonedAreTwoDifferentOutcomes() {
LockSkipWitness.resetLedgerForTests();
ListAppender<ILoggingEvent> captured = capture();
try {
LockSkipWitness.recordSkip("test:outcome-skipped", "PUBLISH", 7L);
LockSkipWitness.recordAbandoned("test:outcome-abandoned", "PUBLISH", 8L);
List<String> lines = captured.list.stream().map(ILoggingEvent::getFormattedMessage).toList();
assertThat(lines).hasSize(2);
assertThat(lines.get(0)).contains("outcome=skipped");
assertThat(lines.get(1)).contains("outcome=abandoned");
// 两种结果都得进台账——只有一种被数到就等于另一种仍然没有出口
assertThat(LockSkipWitness.snapshot()).containsKeys("test:outcome-skipped", "test:outcome-abandoned");
} finally {
release(captured);
}
}
@Test
void micrometerCounterCarriesPointAndOutcomeTagsWhenBound() {
LockSkipWitness.resetLedgerForTests();
SimpleMeterRegistry registry = new SimpleMeterRegistry();
LockSkipWitness.bind(registry);
try {
LockSkipWitness.record("test:metric-shape", LockSkipWitness.OUTCOME_ABANDONED, "SIMILAR_ASIN", 9L);
List<String> found = new ArrayList<>();
for (var meter : registry.getMeters()) {
if (LockSkipWitness.METRIC.equals(meter.getId().getName())) {
found.add(meter.getId().getTag("point") + "/" + meter.getId().getTag("outcome")
+ "/" + meter.getId().getTag("moduleType"));
}
}
assertThat(found).as("指标必须带得上点位/结果/模块三个聚合标签").containsExactly(
"test:metric-shape/abandoned/SIMILAR_ASIN");
double value = registry.get(LockSkipWitness.METRIC)
.tag("point", "test:metric-shape")
.counter()
.count();
assertThat(value).isEqualTo(1.0);
assertThat(registry.get(LockSkipWitness.METRIC + ".total").gauge().value())
.as("总览 gauge 也在,读数为零时能区分「没人被挡」和「指标没接上」")
.isGreaterThanOrEqualTo(1.0);
} finally {
registry.close();
}
}
@Test
void missingContextLandsOnKnownBucketInsteadOfThrowing() {
LockSkipWitness.resetLedgerForTests();
ListAppender<ILoggingEvent> captured = capture();
try {
// 点位缺失 + 模块缺失:不能抛,也不能悄悄丢掉这次记录
LockSkipWitness.record(null, null, " ", null);
assertThat(captured.list).hasSize(1);
assertThat(captured.list.get(0).getFormattedMessage())
.contains("point=unpointed")
.as("缺失的 outcome 单独进 unknown 桶,不许折叠进 skipped/abandoned 那两个真桶")
.contains("outcome=unknown")
.contains("moduleType=unknown");
assertThat(LockSkipWitness.countOf("unpointed")).isEqualTo(1);
assertThat(LockSkipWitness.snapshot()).containsKey("unpointed");
} finally {
release(captured);
}
}
@Test
void ledgerStopsGrowingPastItsKeyCeilingButKeepsCounting() {
LockSkipWitness.resetLedgerForTests();
for (int i = 0; i < LockSkipWitness.LEDGER_KEYS_MAX + 60; i++) {
LockSkipWitness.record("test:flood-" + i, LockSkipWitness.OUTCOME_SKIPPED, null, null);
}
assertThat(LockSkipWitness.snapshot())
.as("点位键数封顶,不被未知点位撑爆内存")
.hasSizeLessThanOrEqualTo(LockSkipWitness.LEDGER_KEYS_MAX + 1);
assertThat(LockSkipWitness.snapshot()).containsKey("overflow");
assertThat(LockSkipWitness.total())
.as("封顶只影响键的数量,不影响总次数:一次都不能少记")
.isEqualTo(LockSkipWitness.LEDGER_KEYS_MAX + 60L);
}
@Test
void anchorLiteralIsTheContractInspectionGreps() {
// 巡检/告警按这条字面量匹配;改它等于删掉现网规则,所以这里钉死字面值
assertThat(LockSkipWitness.ANCHOR).isEqualTo("[lock-skip]");
assertThat(LockSkipWitness.METRIC).isEqualTo("aiimage.distributed.lock.skip");
// 另一半:锚点必须真被 record() 打进日志(不是只当常量挂着)——上一条用例已实测,
// 这里再钉一次源码形状,防止有人把 log.warn 里的 ANCHOR 换成写死的别的字符串。
String source = com.nanri.aiimage.testutil.SourceScan.withoutComments(
com.nanri.aiimage.testutil.SourceScan.sourceText("LockSkipWitness.java"));
assertThat(source).as("record() 里的日志必须带锚点参数").contains("ANCHOR, key");
}
}