后端(四面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,315 @@
package com.nanri.aiimage.config;
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.Counter;
import io.micrometer.core.instrument.simple.SimpleMeterRegistry;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import org.junit.jupiter.api.Test;
import org.slf4j.LoggerFactory;
import org.springframework.boot.env.YamlPropertySourceLoader;
import org.springframework.core.env.EnumerablePropertySource;
import org.springframework.core.env.PropertySource;
import org.springframework.core.io.ClassPathResource;
import org.springframework.mock.web.MockFilterChain;
import org.springframework.mock.web.MockHttpServletRequest;
import org.springframework.mock.web.MockHttpServletResponse;
import org.springframework.test.util.ReflectionTestUtils;
/**
* 版本硬地板三键的<b>配置面</b>判据(2026-10-09 评审「流程 6.0」项 3,服务端这一半)。
*
* <p>评审量到的事实是:{@code min-supported} / {@code enforce} / {@code rejectUnreported}
* 三键<b>在任何 yml 里 0 处</b>,只有 {@link ClientVersionGuardFilter} 里的 {@code @Value} 默认值。
* 后果不是"值不对",是<b>出厂即惰性</b>:{@code minSupportedVersion} 默认空串 ⇒
* {@code shouldNotFilter} 每个请求直接跳过 ⇒ 连"记账"都不发生,谁也不知道翻 true 会打到谁。
*
* <p>这一支钉四件事,每件都是能跑的断言不是文字:
* <ol>
* <li>三键在 {@code application.yml} 里真存在(打进 jar 的那份,读 classpath 不读工作区);</li>
* <li>出厂默认值就是 {@code 4.0.47 / false / false},且 {@code enforce=false} 那一档
* <b>确实在记账</b>——旧版本被计数、被留日志,同时响应一个字节都不许多;</li>
* <li>三键缺失(地板被改回空)时<b>启动可见</b>:一条点名"闸门惰性"的 WARN,而不是静默跳过;</li>
* <li>其它 profile 没把地板偷偷改回空值。</li>
* </ol>
*
* <p>翻真({@code enforce=true})这一轮<b>没有发生</b>,也不该由我拍:判据 2 量出来的
* {@code verdict=below}/{@code unreported} 两个桶就是"翻上去会挡到谁"的现网答案。
*
* <p>重跑:{@code mvn -o test -Dtest=ClientVersionFloorConfigTest}(cwd = backend-java)。
*/
class ClientVersionFloorConfigTest {
private static final String KEY_MIN = "aiimage.client-version.min-supported-version";
private static final String KEY_ENFORCE = "aiimage.client-version.enforce";
private static final String KEY_REJECT_UNREPORTED = "aiimage.client-version.reject-unreported";
/** {@code ${ENV:默认}} 形状;只取默认段,这样测试判的是<b>出厂值</b>,不受跑测试的机器上的环境变量影响。 */
private static final Pattern PLACEHOLDER = Pattern.compile("^\\$\\{([^:}]+):([^}]*)\\}$");
private final List<String> anchorLines = new ArrayList<>();
// ---------------------------------------------------------------- 1. 三键真的存在
@Test
void threeFloorKeysShipInsideApplicationYml() {
Map<String, String> flat = flatten("application.yml");
assertThat(flat.keySet())
.as("三键必须都在 application.yml 里(缺一个就又是出厂即惰性)")
.contains(KEY_MIN, KEY_ENFORCE, KEY_REJECT_UNREPORTED);
assertThat(shippedDefault(flat, KEY_MIN)).isEqualTo("4.0.47");
assertThat(shippedDefault(flat, KEY_ENFORCE)).isEqualTo("false");
assertThat(shippedDefault(flat, KEY_REJECT_UNREPORTED)).isEqualTo("false");
}
@Test
void shippedFloorIsANumberTheGateCanActuallyParse() {
// 地板写成 "v4.0" / "4.x" 这类形状时闸门只记账不拒,等于配了个假地板——这里把出厂值验到能解析
Map<String, String> flat = flatten("application.yml");
String min = shippedDefault(flat, KEY_MIN);
long[] parsed = ClientVersionGuardFilter.parse(min);
assertThat(parsed).as("出厂地板 " + min + " 必须解析成数字段").isNotNull();
assertThat(parsed).containsExactly(4L, 0L, 47L);
// 4.0.46(不报版本的上一个包)在地板之下,4.0.48(现网最新包)在地板之上
assertThat(ClientVersionGuardFilter.compare(ClientVersionGuardFilter.parse("4.0.46"), parsed))
.as("4.0.46 必须被判成低于地板,否则记账桶永远是空的").isNegative();
assertThat(ClientVersionGuardFilter.compare(ClientVersionGuardFilter.parse("4.0.48"), parsed))
.as("现网最新的 4.0.48 不能落在地板之下").isPositive();
}
@Test
void otherProfilesDoNotBlankTheFloor() {
// server profile 里若把地板覆盖成空串,打包上去了就等于把闸门关掉——这不允许悄悄发生
for (String file : List.of("application-server.yml")) {
Map<String, String> flat = flatten(file);
String min = flat.get(KEY_MIN);
if (min != null) {
assertThat(shippedDefault(flat, KEY_MIN))
.as(file + " 把地板覆盖成了空值 = 关掉闸门")
.isNotEmpty();
}
}
}
// ---------------------------------------------------------------- 2. 记账模式真的在记账
@Test
void accountingModeRecordsOldClientWithoutTouchingResponse() throws Exception {
SimpleMeterRegistry registry = new SimpleMeterRegistry();
ClientVersionGuardFilter filter = filter("4.0.47", false, false, registry);
ListAppender<ILoggingEvent> captured = capture();
try {
MockHttpServletRequest request = clientRequest("4.0.40");
MockHttpServletResponse response = new MockHttpServletResponse();
MockFilterChain chain = new MockFilterChain();
filter.doFilter(request, response, chain);
// 记账 = 留痕 + 放行,两件事都得判:只判"放行了"就退化成"这个过滤器没干活"
assertThat(chain.getRequest())
.as("enforce=false 必须原样放行到业务")
.isSameAs(request);
assertThat(response.getStatus()).isEqualTo(200);
assertThat(response.getContentAsString())
.as("记账模式下响应体一个字节都不许多")
.isEmpty();
assertThat(counterValue(registry, "below", "4.0.40"))
.as("低于地板的版本必须进 below 桶")
.isEqualTo(1L);
assertThat(messages(captured))
.as("记账必须留下一条能 grep 的 WARN")
.anySatisfy(line -> assertThat(line)
.contains("[版本地板]")
.contains("自报版本=4.0.40")
.contains("verdict=below")
.contains("enforce=false")
.contains("记账模式,暂不拒绝"));
} finally {
release(captured);
registry.close();
}
}
@Test
void unreportedLegacyClientGoesToItsOwnBucketNotBelow() throws Exception {
SimpleMeterRegistry registry = new SimpleMeterRegistry();
ClientVersionGuardFilter filter = filter("4.0.47", false, false, registry);
try {
// 4.0.46 及更早压根不发 X-Client-Version:它们进 unreported 桶,不冒充"低于地板"
MockHttpServletRequest request = clientRequest(null);
filter.doFilter(request, new MockHttpServletResponse(), new MockFilterChain());
// 没报版本时版本标签归一成 unknown(空串当标签会把同一批装机拆成看不见的两桶)
assertThat(counterValue(registry, "unreported", "unknown")).isEqualTo(1L);
assertThat(registry.find(ClientVersionGuardFilter.METRIC).tag("verdict", "below").counter())
.as("没报版本不能记进 below 桶")
.isNull();
} finally {
registry.close();
}
}
@Test
void defaultConfigCannotRejectAnyoneEvenWhenUnreportedFlagIsOn() throws Exception {
// 出厂 enforce=false 时,reject-unreported=true 也不该挡任何请求——拒绝动作只由 enforce 决定
ClientVersionGuardFilter filter = filter("4.0.47", false, true, null);
MockHttpServletRequest request = clientRequest(null);
MockFilterChain chain = new MockFilterChain();
filter.doFilter(request, new MockHttpServletResponse(), chain);
assertThat(chain.getRequest()).as("enforce=false 是唯一的总闸,谁都越不过它").isSameAs(request);
}
// ---------------------------------------------------------------- 3. 缺失/惰性态启动可见
@Test
void blankFloorIsLoudAtStartupNotSilentlyInert() {
ListAppender<ILoggingEvent> captured = capture();
try {
filter("", false, false, null).reportFloorState();
assertThat(messages(captured))
.as("地板被留空 = 闸门惰性,必须点名说清楚,不能和「这个功能不存在」长得一样")
.anySatisfy(line -> assertThat(line)
.contains("[版本地板]")
.contains("min-supported-version 未配置")
.contains("闸门惰性"));
assertThat(captured.list)
.as("这条自述得是 WARN 级,INFO 在生产日志级别下会被淹掉")
.allSatisfy(event -> assertThat(event.getLevel().toString()).isEqualTo("WARN"));
} finally {
release(captured);
}
}
@Test
void accountingModeAnnouncesItselfAtStartup() {
ListAppender<ILoggingEvent> accounting = capture();
ListAppender<ILoggingEvent> enforcing;
try {
// 出厂默认(4.0.47 / false / false)启动时把三键状态原样报出来,运维不用猜
filter("4.0.47", false, false, null).reportFloorState();
assertThat(messages(accounting))
.anySatisfy(line -> assertThat(line)
.contains("[版本地板]")
.contains("最低支持版本=4.0.47")
.contains("enforce=false")
.contains("记账模式")
.contains("rejectUnreported=false"));
} finally {
release(accounting);
}
// 同一支方法在 enforce=true 时得改口说「真拒绝」——只测一半就等于自述不可信
enforcing = capture();
try {
filter("4.0.47", true, true, null).reportFloorState();
assertThat(messages(enforcing))
.anySatisfy(line -> assertThat(line)
.contains("enforce=true")
.contains("真拒绝")
.contains("rejectUnreported=true"));
} finally {
release(enforcing);
}
}
@Test
void unparsableFloorIsNamedAtStartup() {
ListAppender<ILoggingEvent> captured = capture();
try {
filter("v4.0", false, false, null).reportFloorState();
assertThat(messages(captured))
.as("配置写坏(v4.0 解析不出数字段)要说出来,否则永远只记 unparsable 还没人知道")
.anySatisfy(line -> assertThat(line)
.contains("[版本地板]")
.contains("解析不出数字段")
.contains("v4.0"));
} finally {
release(captured);
}
}
// ---------------------------------------------------------------- 助手
private ClientVersionGuardFilter filter(String minVersion, boolean enforce, boolean rejectUnreported,
SimpleMeterRegistry registry) {
ClientVersionGuardFilter filter = new ClientVersionGuardFilter(
new com.fasterxml.jackson.databind.ObjectMapper(), registry);
ReflectionTestUtils.setField(filter, "minSupportedVersion", minVersion);
ReflectionTestUtils.setField(filter, "enforce", enforce);
ReflectionTestUtils.setField(filter, "rejectUnreported", rejectUnreported);
return filter;
}
private MockHttpServletRequest clientRequest(String reportedVersion) {
MockHttpServletRequest request = new MockHttpServletRequest("POST", "/api/publish/tasks");
if (reportedVersion != null) {
request.addHeader(ClientVersionGuardFilter.HEADER, reportedVersion);
}
return request;
}
private long counterValue(SimpleMeterRegistry registry, String verdict, String version) {
Counter counter = registry.find(ClientVersionGuardFilter.METRIC)
.tag("verdict", verdict).tag("version", version).counter();
return counter == null ? 0L : (long) counter.count();
}
private ListAppender<ILoggingEvent> capture() {
Logger logger = (Logger) LoggerFactory.getLogger(ClientVersionGuardFilter.class);
ListAppender<ILoggingEvent> appender = new ListAppender<>();
appender.start();
logger.addAppender(appender);
return appender;
}
private void release(ListAppender<ILoggingEvent> appender) {
((Logger) LoggerFactory.getLogger(ClientVersionGuardFilter.class)).detachAppender(appender);
}
private List<String> messages(ListAppender<ILoggingEvent> appender) {
return appender.list.stream().map(ILoggingEvent::getFormattedMessage).toList();
}
/** 读打进 classpath 的那份 yml({@code src/main/resources} 会被拷进 target/classes),读不到就红。 */
private Map<String, String> flatten(String fileName) {
ClassPathResource resource = new ClassPathResource(fileName);
assertThat(resource.exists())
.as("classpath 上找不到 " + fileName + " —— 判据读不到出厂配置就是空转")
.isTrue();
try (InputStream in = resource.getInputStream()) {
Map<String, String> flat = new LinkedHashMap<>();
for (PropertySource<?> source : new YamlPropertySourceLoader().load(fileName, resource)) {
if (source instanceof EnumerablePropertySource<?> enumerable) {
for (String name : enumerable.getPropertyNames()) {
Object value = enumerable.getProperty(name);
flat.put(name, value == null ? "" : String.valueOf(value));
}
}
}
assertThat(flat).as(fileName + " 解析出来的键数(0 就是解析坏了)").isNotEmpty();
return flat;
} catch (Exception e) {
throw new IllegalStateException("读 " + fileName + " 失败", e);
}
}
/** 取 {@code ${ENV:默认}} 的默认段;没占位符就按字面值返回。 */
private String shippedDefault(Map<String, String> flat, String key) {
assertThat(flat)
.as("三键缺一即判红(出厂即惰性的老坑)")
.containsKey(key);
String raw = flat.get(key).trim();
Matcher m = PLACEHOLDER.matcher(raw);
return m.matches() ? m.group(2).trim() : raw;
}
}