feat(护栏三面): 鉴权盲区启动自检 + SQL 分层口径落码 + 六页等待循环合一

后端
- AdminApiGuardFilter 增 guardedPrefixes()/matchesPrefix() 公开入口(原 private,
  自检抄一份清单迟早与守卫脱钩);行为零变化
- 新增 ApiGuardCoverageAuditor:启动期把"已映射端点既不在守卫前缀名单、也不在
  公开/待收清单里"打成 API_GUARD_UNCOVERED 一行 WARN,供现网巡检 grep;
  PUBLIC_BY_DESIGN 与 PENDING_CONVERGENCE 两张清单逐条写理由(只读不拦)
- SQL 分层按新口径落码:AsinResultCacheMapper 的两条动态 SQL(<foreach> 批量 +
  ON DUPLICATE KEY UPDATE + 逐列 COALESCE)迁到 resources/mapper/asincache/,
  注解摘干净(注解+XML 同名会让启动期抛重复语句)
- 判据:SqlLayeringConventionTest(注解写 SQL 基线 16 接口/29 条只减不增、
  @Select 65 条/16 文件、wrapper 夹带函数级 SQL 4 文件/15 条,last("LIMIT n")
  205 处显式豁免并反向钉住豁免面)、ApiGuardCoverageAuditorTest(含清单腐烂与
  欠账/名单重叠两类反向失明)、AsinResultCacheMapperXmlTest(真解析 XML 向
  BoundSql 断言 28 个占位符与 5 个 COALESCE 列)

用户端 frontend-vue
- 终态集合合一:实测六页里 PriceTrack/ProductRisk 只认 SUCCESS|FAILED,
  而 COMPLETED≡SUCCESS 早有出处(task-status-text 两者都译「已完成」,
  后端 TaskCenterQueryMapper SUCCESS_STATUSES_ORDERED 也含 COMPLETED)
  ⇒ 窄集合页收到 COMPLETED 会空转到瞬断预算耗尽,PriceTrack 的轮询摘除路径
  同样窄 ⇒ 任务永不退出轮询、列表卡在"执行中"
- 新增 shared/utils/task-terminal.ts 循环骨架(disposed/瞬断预算/恢复提示/
  每轮 sleep/非瞬断上抛),六页全部接上;取数、文案、快照合并、DELETED 语义
  留在各页回调,没有顺手统一
- 判据两支:骨架 8 例契约 + 六页源码窄集合回归钉(含"判据自己先自证"一例,
  loop-run 的 STOPPED 词表不误报)
This commit is contained in:
2026-10-08 09:20:41 +08:00
parent 5b310986bb
commit 207225eb86
16 changed files with 1418 additions and 216 deletions
@@ -0,0 +1,402 @@
package com.nanri.aiimage;
import org.junit.jupiter.api.Test;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
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 java.util.stream.Collectors;
import java.util.stream.Stream;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.junit.jupiter.api.Assertions.fail;
/**
* SQL 分层约定的守卫。口径(2026-10-08 定):<b>SQL 尽量写进 mapper XML</b>,
* wrapper 只留给"简单单表"(无 join、无函数级谓词、无动态标签),注解里不再新增 SQL。
*
* <p>为什么要钉住而不是写在文档里:这个仓原来 0 个 XML、写 SQL 全在注解里,复杂语句
* ({@code <foreach>} + {@code ON DUPLICATE KEY} + 逐列 COALESCE)以 Java 文本块存在,
* 改一列要在字符串里数括号,也没有任何工具在写错时拦你。约定只存在于注释的话,
* 下一个人加 {@code @Insert} 时它就不存在了。所以这里把"当前有多少"逐个钉死:
* <ul>
* <li>新增注解 SQL ⇒ {@link #annotationSqlInventoryDoesNotGrow} 红;</li>
* <li>新增 wrapper 里夹带的函数级 SQL ⇒ {@link #rawSqlInsideWrappersDoesNotGrow} 红,
* 那正是"简单单表"的边界,越界就该进 XML;</li>
* <li>迁走一条 ⇒ 必须同时改基线常量,减法出现在 diff 上。</li>
* </ul>
*
* <p>反向失明也一并堵:XML 里的坏 SQL 没有编译期反馈,所以
* {@link #everyXmlStatementMatchesAnInterfaceMethod} 要求 XML 语句名逐字对上接口方法名——
* 对不上的表现是"启动正常、调用才报 no statement",那是线上才会撞到的面。
*/
class SqlLayeringConventionTest {
/** 写 SQL(@Insert/@Update/@Delete)在注解里的现状清单:文件名 → 条数。只许减,不许加。 */
private static final Map<String, Integer> WRITE_SQL_BASELINE = writeSqlBaseline();
/**
* 读侧注解 SQL 的总量与文件数(2026-10-08 实测 65 条 / 16 个接口)。
* 读侧按"尽量 XML"是主要待迁面,最重的是 TaskCenterQueryMapper;
* 钉总数而不是逐条清单,是因为逐条会把这份守卫变成迁移进度表——它该只做"别再加"的闸门。
*/
private static final int SELECT_ANNOTATION_TOTAL = 65;
private static final int SELECT_ANNOTATION_FILES = 16;
/**
* wrapper 里夹带函数级 SQL 的现状("这不是简单单表"的证据),文件名 → 条数:
* apply/inSql 是真谓词,last("FOR UPDATE") 是行锁。
*/
private static final Map<String, Integer> RAW_SQL_IN_WRAPPERS_BASELINE = rawSqlInWrappersBaseline();
/**
* 其中"复杂"的写 SQL(注解正文含动态标签)——Wrapper 表达不了(批量/INSERT…SELECT/upsert),
* 按约定应迁到 XML。这是待迁 backlog,不是许可名单:迁走一条要同时从这里划掉。
*/
private static final List<String> COMPLEX_WRITE_SQL_BACKLOG = List.of(
"CollectDataItemMapper", "DedupeTotalDataMapper", "InvalidAsinDataMapper",
"UserColumnPermissionMapper", "PublishItemMapper", "ShopDataCrawlItemMapper",
"QueryAsinMapper", "TaskResultItemMapper");
/** 唯一没有实体可走的 mapper:连 wrapper 的入口都没有,所以只能写裸 SQL。 */
private static final List<String> MAPPERS_WITHOUT_ENTITY = List.of("UserColumnPermissionMapper");
/** 已经迁到 XML 的:反向钉住"不许再用注解把 SQL 写回来"(注解 + XML 同名会让启动期抛重复语句)。 */
private static final List<String> MIGRATED_TO_XML = List.of("AsinResultCacheMapper");
private static final Pattern WRITE_ANNOTATION = Pattern.compile("@(Insert|Update|Delete)\\(");
private static final Pattern SELECT_ANNOTATION = Pattern.compile("@Select\\(");
private static final Pattern WRITE_ANNOTATION_BODY =
Pattern.compile("@(Insert|Update|Delete)\\(\\s*\"\"\"(.*?)\"\"\"", Pattern.DOTALL);
private static Map<String, Integer> writeSqlBaseline() {
Map<String, Integer> baseline = new LinkedHashMap<>();
baseline.put("CollectDataItemMapper", 1);
baseline.put("DedupeTotalDataMapper", 1);
baseline.put("DeviceLogFileMapper", 1);
baseline.put("ImageVideoAsyncTaskMapper", 3);
baseline.put("InvalidAsinDataMapper", 1);
baseline.put("UserNotificationMapper", 2);
baseline.put("UserColumnPermissionMapper", 4);
baseline.put("PriceTrackLoopRunMapper", 1);
baseline.put("PublishItemMapper", 1);
baseline.put("ShopDataCrawlItemMapper", 4);
baseline.put("ShopDataDuplicateScanMapper", 1);
baseline.put("QueryAsinMapper", 1);
baseline.put("SoftwareVersionMapper", 1);
baseline.put("TaskImageCacheMapper", 4);
baseline.put("TaskResultItemMapper", 1);
baseline.put("UserSecretUsageMapper", 2);
return baseline;
}
private static Map<String, Integer> rawSqlInWrappersBaseline() {
Map<String, Integer> baseline = new LinkedHashMap<>();
baseline.put("PublishTaskService", 6); // ownerInstanceId 的 JSON_EXTRACT 谓词
baseline.put("SimilarAsinTaskOwnershipSupport", 3); // 同上,state_json 维度
baseline.put("ShopDataCrawlDailyFileService", 4); // last("FOR UPDATE") 行锁
baseline.put("TaskScopePayloadStorageService", 1); // last("limit 1 FOR UPDATE") 混写
baseline.put("SimilarAsinTaskProgressSupport", 1); // inSql 子查询
return baseline;
}
@Test
void annotationSqlInventoryDoesNotGrow() throws IOException {
Map<String, Integer> actual = new LinkedHashMap<>();
int selects = 0;
List<String> selectFiles = new ArrayList<>();
for (Path file : mappers()) {
String text = stripComments(read(file));
int writes = count(WRITE_ANNOTATION, text);
if (writes > 0) {
actual.put(stem(file), writes);
}
int read = count(SELECT_ANNOTATION, text);
if (read > 0) {
selects += read;
selectFiles.add(stem(file));
}
}
assertEquals(WRITE_SQL_BASELINE, actual, () -> "注解里的写 SQL 清单变了。" + System.lineSeparator()
+ " 新增 → 写进 src/main/resources/mapper/<模块>/<Name>Mapper.xml;"
+ "简单单表才用 BaseMapper/实体(wrapper)。" + System.lineSeparator()
+ " 迁走 → 把这一项从 WRITE_SQL_BASELINE 里减掉,让减法出现在 diff 上。");
assertFalse(actual.isEmpty(), "清单为空说明本用例没扫到任何 mapper,判据本身坏了");
assertEquals(SELECT_ANNOTATION_TOTAL, selects,
() -> "注解里的 @Select 总数变了(读侧同样按 XML 优先)。迁一条就减一:" + selectFiles);
assertEquals(SELECT_ANNOTATION_FILES, selectFiles.size(),
"带注解 @Select 的接口个数变了:" + selectFiles);
}
/**
* wrapper 只该出现在"简单单表"上。函数级谓词(JSON_EXTRACT)、行锁(FOR UPDATE)、
* 子查询(inSql)都说明这条查询已经越过那条线——按口径应进 XML。
*
* <p>{@code last("LIMIT n")} 故意不算越界:MP 的分页 idiomatic 写法就是它,
* 全仓 205 处,把它算成违规只会让守卫第一天就没人管。豁免面由
* {@link #limitExemptionDoesNotHideRealSql} 反向钉住。
*/
@Test
void rawSqlInsideWrappersDoesNotGrow() throws IOException {
Map<String, Integer> actual = new LinkedHashMap<>();
for (Path file : mainSources()) {
int hits = countRawSqlInWrapper(stripComments(read(file)));
if (hits > 0) {
actual.put(stem(file), hits);
}
}
assertEquals(RAW_SQL_IN_WRAPPERS_BASELINE, actual, () -> "wrapper 里夹带的函数级 SQL 变了。"
+ System.lineSeparator()
+ " 新增 → 这条已经不是简单单表,SQL 写进 mapper XML;" + System.lineSeparator()
+ " 迁走 → 同步减 RAW_SQL_IN_WRAPPERS_BASELINE。当前实测:" + actual);
assertTrue(actual.values().stream().mapToInt(Integer::intValue).sum() >= 10,
"只数到 " + actual + " 条,多半是正则或目录坏了——恒 0 的闸门比没有闸门更糟");
}
@Test
void limitExemptionDoesNotHideRealSql() {
// 计数器必须"看见" JSON_EXTRACT / FOR UPDATE / inSql,但放过 LIMIT —— 四种形状各喂一条
assertEquals(1, countRawSqlInWrapper("q.apply(\"JSON_UNQUOTE(JSON_EXTRACT(a, '$.b')) = {0}\", v));"));
assertEquals(1, countRawSqlInWrapper("q.last(\"FOR UPDATE\"));"));
assertEquals(1, countRawSqlInWrapper("q.inSql(FileTaskEntity::getId, \"select id from t\"));"));
assertEquals(0, countRawSqlInWrapper("q.last(\"LIMIT \" + safeLimit));"),
"LIMIT 分页 idiomatic 写法不该计入,否则 205 处噪音会把这条守卫淹掉");
// 但 "LIMIT 1 FOR UPDATE" 这种混写必须计入——不能被前缀是 LIMIT 就放过
assertEquals(1, countRawSqlInWrapper("q.last(\"limit 1 FOR UPDATE\"));"));
}
@Test
void noNewComplexWriteSqlInAnnotations() throws IOException {
List<String> complex = new ArrayList<>();
for (Path file : mappers()) {
Matcher matcher = WRITE_ANNOTATION_BODY.matcher(stripComments(read(file)));
while (matcher.find()) {
String body = matcher.group(2);
if (body.contains("<script>") || body.contains("<if ")
|| body.contains("<foreach") || body.contains("<set>")) {
complex.add(stem(file));
}
}
}
List<String> unexpected = complex.stream().distinct()
.filter(name -> !COMPLEX_WRITE_SQL_BACKLOG.contains(name))
.collect(Collectors.toList());
assertTrue(unexpected.isEmpty(), () -> "这些 mapper 新写了带动态标签的 SQL 注解:" + unexpected
+ " —— 按约定放进 src/main/resources/mapper/<模块>/<Name>Mapper.xml");
assertEquals(COMPLEX_WRITE_SQL_BACKLOG.stream().sorted().collect(Collectors.toList()),
complex.stream().distinct().sorted().collect(Collectors.toList()),
"复杂写 SQL 的待迁清单变了:迁走一条就同时从 COMPLEX_WRITE_SQL_BACKLOG 划掉");
}
@Test
void everyMigratedMapperHasNoAnnotatedSqlLeft() {
for (String name : MIGRATED_TO_XML) {
Path file = findMapperInterface(name);
String text = stripComments(read(file));
assertFalse(count(WRITE_ANNOTATION, text) > 0,
() -> name + " 已迁到 XML,注解里却又出现写 SQL:同名会让 MyBatis 启动期抛重复语句");
assertFalse(count(SELECT_ANNOTATION, text) > 0,
() -> name + " 已迁到 XML,注解里却又出现 @Select:" + name);
assertFalse(text.contains("<script>"),
() -> name + " 的注解里还留着 <script>:迁移只做了一半,调用时会报 no statement");
assertTrue(xmlFiles().stream().anyMatch(x -> stem(x).equals(name)),
() -> name + " 声称已迁 XML,但 src/main/resources/mapper 下没有同名文件");
}
}
@Test
void everyXmlStatementMatchesAnInterfaceMethod() throws IOException {
List<Path> xmls = xmlFiles();
assertFalse(xmls.isEmpty(), "mapper XML 目录是空的——迁移通道没落地,本用例就成了恒绿");
for (Path xml : xmls) {
String text = read(xml);
String namespace = firstGroup(Pattern.compile("namespace=\"([^\"]+)\""), text,
xml + " 缺 namespace(MyBatis 无法把语句绑到接口)");
Path iface = findMapperInterfaceByFqn(namespace);
List<String> statementIds = allGroups(Pattern.compile(
"<(select|insert|update|delete)\\s+id=\"([^\"]+)\""), text, 2);
assertFalse(statementIds.isEmpty(), () -> xml + " 里没有任何语句");
for (String id : statementIds) {
assertTrue(declaredMethods(iface).contains(id),
() -> id + "(" + xml.getFileName() + ")在 " + namespace
+ " 上没有同名方法:启动不报错,调用时才报 no statement");
}
assertEquals(stem(iface), stem(xml), "XML 文件名应与接口名一致,便于按名找 SQL");
}
}
@Test
void newMappersMustBeEntityBacked() throws IOException {
List<String> offenders = new ArrayList<>();
for (Path file : mappers()) {
String text = stripComments(read(file));
if (count(WRITE_ANNOTATION, text) > 0 && !text.contains("BaseMapper<")) {
offenders.add(stem(file));
}
}
assertEquals(MAPPERS_WITHOUT_ENTITY, offenders.stream().distinct().sorted().collect(Collectors.toList()),
() -> "带写 SQL 又不继承 BaseMapper<T> 的 mapper 变了:没有实体就没有 wrapper 入口,"
+ "新 mapper 请 extends BaseMapper<XxxEntity>");
}
@Test
void xmlDirectoryIsActuallyOnTheLoadPath() throws IOException {
Path resources = moduleRoot().resolve("src/main/resources/mapper");
assertTrue(Files.isDirectory(resources), "src/main/resources/mapper 不存在,迁移无处可放");
String yml = read(moduleRoot().resolve("src/main/resources/application.yml"));
assertTrue(yml.replaceAll("\\s+", " ").contains("mapper-locations: classpath*:mapper/**/*.xml"),
"application.yml 的 mapper-locations 变了:XML 会被静默忽略,调用时才报 no statement");
}
// ---------- 判据本体(纯函数,喂字符串即可验,不依赖目录里恰好有什么) ----------
/** 数一段源码里"wrapper 夹带函数级 SQL"的次数;last("LIMIT …") 是允许的写法。 */
static int countRawSqlInWrapper(String text) {
int hits = 0;
Matcher m = Pattern.compile("\\.(apply|inSql|having|last)\\(\\s*(\"[^\"]*\"|[^,)\\n]+,\\s*\")")
.matcher(text);
while (m.find()) {
String tail = text.substring(m.start(), Math.min(text.length(), m.end() + 120));
String upper = tail.toUpperCase();
boolean realSql = upper.contains("JSON_") || upper.contains("FOR UPDATE")
|| upper.contains("SELECT ") || upper.contains("WHERE ")
|| m.group(1).equals("inSql") || m.group(1).equals("having");
if (realSql) {
hits++;
}
}
return hits;
}
// ---------- 取样 ----------
private static List<Path> mappers() throws IOException {
return mainSources().stream()
.filter(p -> p.getFileName().toString().endsWith("Mapper.java"))
.collect(Collectors.toList());
}
private static List<Path> mainSources() throws IOException {
Path root = moduleRoot().resolve("src/main/java");
if (!Files.isDirectory(root)) {
fail("找不到 " + root + " —— 用例依赖以 backend-java 为工作目录运行,别让守卫静默通过");
}
try (Stream<Path> walk = Files.walk(root)) {
return walk.filter(Files::isRegularFile)
.filter(p -> p.getFileName().toString().endsWith(".java"))
.sorted()
.collect(Collectors.toList());
}
}
private static List<Path> xmlFiles() {
try (Stream<Path> walk = Files.walk(moduleRoot().resolve("src/main/resources/mapper"))) {
return walk.filter(Files::isRegularFile)
.filter(p -> p.getFileName().toString().endsWith(".xml"))
.sorted()
.collect(Collectors.toList());
} catch (IOException e) {
throw new IllegalStateException("遍历 mapper XML 失败", e);
}
}
private static Path findMapperInterface(String simpleName) {
try {
return mappers().stream()
.filter(p -> stem(p).equals(simpleName))
.findFirst()
.orElseThrow(() -> new IllegalStateException("找不到 mapper 接口 " + simpleName));
} catch (IOException e) {
throw new IllegalStateException(e);
}
}
private static Path findMapperInterfaceByFqn(String fqn) {
String simpleName = fqn.substring(fqn.lastIndexOf('.') + 1);
Path file = findMapperInterface(simpleName);
assertTrue(read(file).contains("package " + fqn.substring(0, fqn.lastIndexOf('.')) + ";"),
() -> "XML namespace 指向 " + fqn + ",但 " + file + " 不在那个包里");
return file;
}
private static List<String> declaredMethods(Path iface) {
// 只要声明行:形如 "Xxx yyy(" 的方法签名,跳过注解与注释
List<String> names = new ArrayList<>();
for (String raw : stripComments(read(iface)).split("\n", -1)) {
String line = raw.trim();
if (line.isEmpty()) {
continue;
}
Matcher m = Pattern.compile("^[\\w<>?,.\\[\\]\\s]+?\\s(\\w+)\\s*\\(").matcher(line);
if (m.find()) {
names.add(m.group(1));
}
}
return names;
}
private static String firstGroup(Pattern pattern, String text, String message) {
Matcher m = pattern.matcher(text);
if (!m.find()) {
throw new IllegalStateException(message);
}
return m.group(1);
}
private static List<String> allGroups(Pattern pattern, String text, int group) {
List<String> out = new ArrayList<>();
Matcher m = pattern.matcher(text);
while (m.find()) {
out.add(m.group(group));
}
return out;
}
private static int count(Pattern pattern, String text) {
int hits = 0;
Matcher m = pattern.matcher(text);
while (m.find()) {
hits++;
}
return hits;
}
private static String stripComments(String text) {
return text.replaceAll("/\\*[\\s\\S]*?\\*/", "").replaceAll("//[^\\n]*", "");
}
private static String stem(Path path) {
String name = path.getFileName().toString();
return name.substring(0, name.length() - (name.endsWith(".java") ? 5 : 4));
}
private static String read(Path path) {
try {
return Files.readString(path, StandardCharsets.UTF_8);
} catch (IOException e) {
throw new IllegalStateException("读取失败: " + path, e);
}
}
/** surefire 的工作目录是模块目录;从仓库根或 IDE 跑时退到 backend-java/。 */
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 + ")");
}
}
@@ -0,0 +1,177 @@
package com.nanri.aiimage.config;
import org.junit.jupiter.api.Test;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.Set;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import java.util.stream.Stream;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* {@link ApiGuardCoverageAuditor} 的守卫守卫。
*
* <p>自检本身有两个会静默失效的地方,这里逐个钉住:
* <ol>
* <li>清单腐烂——PUBLIC_BY_DESIGN / PENDING_CONVERGENCE 里的前缀对应的控制器早就没了,
* 条目却还"掩护"着以后随便挂上来的同名前缀端点;</li>
* <li>名单抄歪——守卫实际用的前缀数组(USER_TOOL_PREFIXES 等)与自检看到的必须是同一份,
* 少一条就会把"其实被看守"的端点报成欠账,多一条就会把没人看守的报成 covered。</li>
* </ol>
*/
class ApiGuardCoverageAuditorTest {
@Test
void classifiesEachOfTheFourBuckets() {
ApiGuardCoverageAuditor.Report report = ApiGuardCoverageAuditor.audit(List.of(
"/api/admin/users", // 名单内,无条件
"/api/notifications/summary", // 自助前缀,无条件
"/api/collect-data/pull", // 用户态前缀(在开关后面,但仍算"在名单里")
"/login", // 设计公开
"/api/dedupe/runs", // 待收欠账
"/api/brand-check-tasks/1")); // 谁都不沾
assertEquals(3, report.covered(), "守卫名单内应有 3 条:admin / 自助 / 用户态");
assertEquals(List.of("/login"), report.publicPaths());
assertEquals(List.of("/api/dedupe/runs"), report.pending());
assertEquals(List.of("/api/brand-check-tasks/1"), report.uncovered(),
"新端点必须落进 uncovered,否则这条护栏就是装饰");
}
@Test
void alertAnchorIsEmittedOnlyWhenSomethingIsUncovered() {
assertTrue(ApiGuardCoverageAuditor.audit(List.of("/api/admin/x")).uncovered().isEmpty(),
"全 covered 时不该报警");
List<String> uncovered = ApiGuardCoverageAuditor.audit(List.of("/api/yolo")).uncovered();
assertEquals(1, uncovered.size());
assertFalse(ApiGuardCoverageAuditor.ALERT_ANCHOR.isBlank(), "锚点为空的话巡检 grep 到的是空气");
}
@Test
void guardedPrefixesCarriesEveryGuardedList() {
List<String> guarded = AdminApiGuardFilter.guardedPrefixes();
assertTrue(guarded.contains("/api/admin"), "admin 前缀没进自检可见名单");
assertTrue(guarded.contains("/debug"), "debug 前缀没进自检可见名单");
// 这两组条数是实测基线(2026-10-08:用户态 15 条、自助 6 条)。
// 只钉"contains 某条"的话,从数组里删掉一整段都可能不红,所以钉总数。
assertEquals(22, count(guarded, "/api/"), () -> "以 /api/ 开头的守卫前缀数变了(基线 22 = admin 1 + 用户态 15 + 自助 6):" + guarded);
assertEquals(23, guarded.size(), "守卫前缀总数变了(22 条 /api/ + /debug):" + guarded);
assertTrue(guarded.contains("/api/publish"), "2026-10-07 补的上架前缀不能退回名单外");
assertTrue(guarded.contains("/api/tasks"), "心跳/打断前缀不能退回名单外");
assertTrue(guarded.contains("/api/internal"), "内部端点前缀不能退回名单外");
}
@Test
void everyDeclaredPublicOrPendingPrefixIsStillLive() throws IOException {
Set<String> controllerBases = controllerBasePaths();
List<String> dead = new ArrayList<>();
for (String prefix : ApiGuardCoverageAuditor.PUBLIC_BY_DESIGN) {
if (prefix.equals("/error")) {
continue; // Spring 自带的错误页,不是控制器映射
}
if (controllerBases.stream().noneMatch(base -> base.equals(prefix) || base.startsWith(prefix + "/"))) {
dead.add(prefix);
}
}
for (String prefix : ApiGuardCoverageAuditor.PENDING_CONVERGENCE) {
if (controllerBases.stream().noneMatch(base -> base.equals(prefix) || base.startsWith(prefix + "/"))) {
dead.add(prefix);
}
}
assertTrue(dead.isEmpty(), () -> "这些清单条目已经对不上任何控制器映射,条目还在就会掩护同名新端点:" + dead);
}
@Test
void pendingListDoesNotOverlapTheGuardedList() {
List<String> overlap = ApiGuardCoverageAuditor.PENDING_CONVERGENCE.stream()
.filter(prefix -> ApiGuardCoverageAuditor.audit(List.of(prefix)).covered() > 0)
.collect(Collectors.toList());
assertTrue(overlap.isEmpty(), () -> "欠账清单与守卫名单重叠,说明这一条早已收敛却还挂在欠账里:" + overlap);
}
@Test
void publicListDoesNotOverlapTheGuardedList() {
List<String> overlap = ApiGuardCoverageAuditor.PUBLIC_BY_DESIGN.stream()
.filter(prefix -> ApiGuardCoverageAuditor.audit(List.of(prefix)).covered() > 0)
.collect(Collectors.toList());
assertTrue(overlap.isEmpty(), () -> "这些前缀已被守卫看守,登记成『设计公开』会让欠账看起来已收口:" + overlap);
}
/** 从控制器源码取映射基路径:类级 @RequestMapping 优先,没有类级的才看方法级绝对路径。 */
private static Set<String> controllerBasePaths() throws IOException {
Set<String> out = new java.util.LinkedHashSet<>();
for (Path file : controllers()) {
String text = stripComments(read(file));
List<String> bases = new ArrayList<>();
Matcher klass = Pattern.compile("@RequestMapping\\(\\s*(?:value\\s*=\\s*)?\"([^\"]+)\"").matcher(text);
while (klass.find()) {
bases.add(klass.group(1));
}
if (bases.isEmpty()) {
Matcher method = Pattern.compile(
"@(?:Get|Post|Put|Delete|Request)Mapping\\(\\s*(?:value\\s*=\\s*)?\"([/][^\"]+)").matcher(text);
while (method.find()) {
String absolute = method.group(1);
while (absolute.endsWith("/")) {
absolute = absolute.substring(0, absolute.length() - 1);
}
String[] parts = absolute.split("/"); // "/login" -> ["", "login"]
for (int depth = 1; depth <= parts.length - 1 && depth <= 3; depth++) {
bases.add("/" + String.join("/", java.util.Arrays.copyOfRange(parts, 1, 1 + depth)));
}
bases.add(absolute);
}
}
out.addAll(bases);
}
return out;
}
private static int count(List<String> values, String startsWith) {
return (int) values.stream().filter(v -> v.startsWith(startsWith)).count();
}
private static List<Path> controllers() throws IOException {
try (Stream<Path> walk = Files.walk(moduleRoot().resolve("src/main/java"))) {
return walk.filter(Files::isRegularFile)
.filter(p -> p.getFileName().toString().contains("Controller"))
.collect(Collectors.toList());
}
}
private static String stripComments(String text) {
return text.replaceAll("/\\*\\s*\\n[\\s\\S]*?\\*/", "")
.replaceAll("/\\*.*?\\*/", "")
.replaceAll("//[^\\n]*", "");
}
private static String read(Path path) {
try {
return Files.readString(path, StandardCharsets.UTF_8);
} catch (IOException e) {
throw new IllegalStateException("读取失败: " + path, 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 + ")");
}
}
@@ -0,0 +1,165 @@
package com.nanri.aiimage.modules.asincache.mapper;
import com.baomidou.mybatisplus.core.MybatisConfiguration;
import com.nanri.aiimage.modules.asincache.model.entity.AsinResultCacheEntity;
import org.apache.ibatis.io.Resources;
import org.apache.ibatis.builder.xml.XMLMapperBuilder;
import org.apache.ibatis.mapping.BoundSql;
import org.apache.ibatis.mapping.MappedStatement;
import org.apache.ibatis.session.Configuration;
import org.junit.jupiter.api.Test;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertSame;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* {@code AsinResultCacheMapper} 的 SQL 已从注解搬到 mapper XML,本用例钉住"搬完还是同一条 SQL"。
*
* <p>为什么必须有:注解与 XML 同名会让 MyBatis 在启动期直接抛异常(本地不起容器就看不见),
* 而只搬一半(select 在 XML、upsert 还在注解)表现是"启动正常、调用时报无此语句"。
* 这里用真 {@code XMLMapperBuilder} 解析、向真 {@code BoundSql} 断言,
* 并把列级继承口径(5 个 COALESCE 列)逐条钉住——XML 里没有注解那种编译期约束,
* 少写一个 COALESCE 只会让线上把卖家名抹成空,不会有任何测试自然变红。
*/
class AsinResultCacheMapperXmlTest {
private static final String XML = "mapper/asincache/AsinResultCacheMapper.xml";
private static final String NS = "com.nanri.aiimage.modules.asincache.mapper.AsinResultCacheMapper";
/** 参与"新值没带到就保旧值"的列——与实体注释里的继承口径一一对应。 */
private static final List<String> INHERITED_COLUMNS = List.of(
"brand", "delivery_method", "seller_name", "seller_id", "declared_members_json");
/** 本行结论的主体,重采必须直接覆盖(404 要能把 price 清空)。 */
private static final List<String> OVERWRITTEN_COLUMNS = List.of(
"availability", "price", "source_chain", "source_task_id", "observed_at", "updated_at");
@Test
void xmlIsParsableAndBindsEveryInterfaceMethod() throws Exception {
Configuration configuration = parseXml();
for (String id : List.of("selectByCountryAndAsins", "upsertBatch")) {
assertTrue(configuration.hasStatement(NS + "." + id),
() -> XML + " 里没有 " + id + "(语句名必须与接口方法名逐字一致)");
}
// namespace 能绑到接口,说明 mapper-locations 扫得到、包名没写错
assertTrue(configuration.hasMapper(AsinResultCacheMapper.class),
"namespace 没能绑定到接口——检查 mybatis-plus.mapper-locations 与包路径");
}
@Test
void annotationsAreGoneSoTheStatementIsNotDefinedTwice() throws Exception {
for (var method : AsinResultCacheMapper.class.getDeclaredMethods()) {
assertFalse(method.isAnnotationPresent(org.apache.ibatis.annotations.Select.class),
() -> method.getName() + " 还带着 @Select:注解 + XML 同名会让启动期抛重复语句");
assertFalse(method.isAnnotationPresent(org.apache.ibatis.annotations.Insert.class),
() -> method.getName() + " 还带着 @Insert:注解 + XML 同名会让启动期抛重复语句");
}
}
@Test
void upsertExpandsOneValueTuplePerRowAndCarriesNoInjection() throws Exception {
Configuration configuration = parseXml();
MappedStatement statement = configuration.getMappedStatement(NS + ".upsertBatch");
BoundSql boundSql = statement.getBoundSql(param(rows(2)));
String sql = boundSql.getSql().replaceAll("\\s+", " ");
assertTrue(sql.startsWith("INSERT INTO biz_asin_result_cache "), "仍是整行 upsert 形态: " + sql);
assertTrue(sql.contains("ON DUPLICATE KEY UPDATE"), () -> "upsert 退化成纯 INSERT 会插重复行: " + sql);
assertEquals(28, boundSql.getParameterMappings().size(),
"14 列 x 2 行的占位符数(列清单被改动过就要重新核对): " + sql);
assertFalse(sql.contains("$"), "不得出现 ${} 拼接面");
}
@Test
void columnLevelInheritanceSurvivesTheMove() throws Exception {
Configuration configuration = parseXml();
String sql = configuration.getMappedStatement(NS + ".upsertBatch")
.getBoundSql(param(rows(1))).getSql().replaceAll("\\s+", " ");
String updateClause = sql.substring(sql.indexOf("ON DUPLICATE KEY UPDATE"));
for (String column : INHERITED_COLUMNS) {
assertTrue(updateClause.contains("COALESCE(VALUES(" + column + "), " + column + ")"),
() -> column + " 丢了列级继承:一条变体记录会把关键词记录里的卖家信息抹成空");
}
for (String column : OVERWRITTEN_COLUMNS) {
assertTrue(updateClause.contains(column + " = VALUES(" + column + ")"),
() -> column + " 不再直接覆盖:404 就清不掉旧价格了");
assertFalse(updateClause.contains("COALESCE(VALUES(" + column + ")"),
() -> column + " 不该参与继承: " + column);
}
assertEquals(INHERITED_COLUMNS.size(), countOccurrences(updateClause, "COALESCE("),
"COALESCE 列数变了——继承清单被悄悄加/减过");
}
@Test
void selectStaysOnTheCountryPrefixAndMapsToTheEntity() throws Exception {
Configuration configuration = parseXml();
MappedStatement statement = configuration.getMappedStatement(NS + ".selectByCountryAndAsins");
String sql = statement.getBoundSql(Map.of("country", "DE", "asins", List.of("B01", "B02")))
.getSql().replaceAll("\\s+", " ");
assertSame(AsinResultCacheEntity.class, statement.getResultMaps().get(0).getType());
// country 必须是等值:放进 (country,asin) IN ((..),(..)) 在 MySQL 上用不上 uk_asin_cache_country_asin
assertTrue(sql.contains("WHERE country = ? AND asin IN"),
() -> "国家维度的等值形状变了,唯一键前缀会失配: " + sql);
assertEquals(3, sql.chars().filter(c -> c == '?').count(), "1 个 country + 2 个 asin");
}
@Test
void mapperLocationsStillPointsAtTheXmlDirectory() throws Exception {
String yml;
try (InputStream in = Resources.getResourceAsStream("application.yml")) {
yml = new String(in.readAllBytes(), java.nio.charset.StandardCharsets.UTF_8);
}
assertTrue(yml.replaceAll("\\s+", " ").toLowerCase().contains("mapper/**/*.xml"),
"application.yml 的 mapper-locations 不含 mapper/**/*.xml —— XML 会被静默忽略,"
+ "调用时才报 no statement");
}
/** 生产走 @Param("rows"),MyBatis 会包成 ParamMap;测试要照这个形状喂,直接给 List 会命中 CollectionWrapper。 */
private static Map<String, Object> param(List<AsinResultCacheEntity> rows) {
Map<String, Object> parameter = new HashMap<>();
parameter.put("rows", rows);
return parameter;
}
private static List<AsinResultCacheEntity> rows(int count) {
List<AsinResultCacheEntity> rows = new ArrayList<>(count);
for (int i = 0; i < count; i++) {
AsinResultCacheEntity row = new AsinResultCacheEntity();
row.setCountry("DE");
row.setAsin("B00000000" + i);
row.setAvailability(AsinResultCacheEntity.AVAILABILITY_OK);
rows.add(row);
}
return rows;
}
private static Configuration parseXml() throws Exception {
MybatisConfiguration configuration = new MybatisConfiguration();
try (InputStream in = Resources.getResourceAsStream(XML)) {
new XMLMapperBuilder(in, configuration, XML, configuration.getSqlFragments()).parse();
}
return configuration;
}
private static int countOccurrences(String haystack, String needle) {
int at = 0;
int count = 0;
while ((at = haystack.indexOf(needle, at)) >= 0) {
count++;
at += needle.length();
}
return count;
}
}