diff --git a/backend-java/src/main/java/com/nanri/aiimage/config/ApiGuardCoverageAuditor.java b/backend-java/src/main/java/com/nanri/aiimage/config/ApiGuardCoverageAuditor.java index 8ab9314b0..e35ea567e 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/config/ApiGuardCoverageAuditor.java +++ b/backend-java/src/main/java/com/nanri/aiimage/config/ApiGuardCoverageAuditor.java @@ -1,13 +1,21 @@ package com.nanri.aiimage.config; import lombok.extern.slf4j.Slf4j; +import org.springframework.beans.factory.SmartInitializingSingleton; import org.springframework.beans.factory.annotation.Qualifier; +import org.springframework.beans.factory.annotation.Value; import org.springframework.boot.context.event.ApplicationReadyEvent; import org.springframework.context.event.EventListener; +import org.springframework.core.io.ClassPathResource; import org.springframework.stereotype.Component; import org.springframework.web.servlet.mvc.method.RequestMappingInfo; import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping; +import java.io.BufferedReader; +import java.io.IOException; +import java.io.InputStream; +import java.io.InputStreamReader; +import java.nio.charset.StandardCharsets; import java.util.ArrayList; import java.util.Collection; import java.util.LinkedHashSet; @@ -33,15 +41,35 @@ import java.util.Set; * 主机A/B 的巡检(scripts/_prod_watch.py 的 SIGNATURES)把它计入告警。 * * - *
自检只读不拦:不参与任何请求的放行判定,所以开它没有可用性风险。 + *
自检只读不拦:不参与任何请求的放行判定,所以开它没有可用性风险。**但 profile=server 时它会拦启动**—— + * 见 {@link #afterSingletonsInstantiated()}:快照里不存在的新 uncovered 端点直接拒绝启动, + * 判据形状照 {@code JwtService#requireSecretInServerProfile()}(全树唯一一处"不安全即拒绝启动"的先例)。 */ @Slf4j @Component -public class ApiGuardCoverageAuditor { +public class ApiGuardCoverageAuditor implements SmartInitializingSingleton { /** 巡检锚点:_prod_watch.py 按这个字面量 grep,改名要同时改那条签名。 */ public static final String ALERT_ANCHOR = "API_GUARD_UNCOVERED"; + /** + * 增量未设防端点的拒起锚点。异常消息与拒起前的 WARN 都带这一串(含方括号,逐字)。 + * + *
和 {@link #ALERT_ANCHOR} 分开是有意的:后者是"现网有匿名可达端点"的长期告警, + * 前者是"这一版比上一版多了一个"的发布闸门。两个混用会让人分不清是欠账还是新增。 + */ + public static final String BREACH_ANCHOR = "[api-guard-coverage-breach]"; + + /** + * 存量 uncovered 快照(进版本控制的基线文件,classpath 资源)。 + * + *
为什么放 {@code src/main/resources/inspection/} 而不是 {@code src/test/resources/}:
+ * 判增量的是**启动时的审计器**,它跑在生产 jar 里,读不到测试类路径;
+ * 放 test/resources 等于把基线留在开发机上,现网拿到空基线就会把全部存量报成新增=两台同时起不来。
+ * {@code inspection/} 已是本模块"可巡检产物"的落位(01–06 号只读报表 SQL 在同目录)。
+ */
+ public static final String BASELINE_RESOURCE = "inspection/api-guard-uncovered-baseline.txt";
+
/** 设计上匿名可达的基路径。 */
static final Set 为什么用 {@link SmartInitializingSingleton} 而不是沿用下面那个 {@code ApplicationReadyEvent}:
+ * {@code afterSingletonsInstantiated()} 在 {@code preInstantiateSingletons()} 收尾时触发,
+ * 早于 {@code finishRefresh()} 里 Web 服务器绑定端口——抛出去就等价于 {@code JwtService} 的
+ * {@code @PostConstruct}:容器 refresh 失败、进程非零退出,端口一次都没开。
+ * 放在 ApplicationReadyEvent 上则要先.listen 再 close,两台同时滚动时等于开了一个匿名可达的窗口。
+ * 此刻所有单例已创建完,{@code RequestMappingHandlerMapping#afterPropertiesSet} 也已扫完映射,
+ * 所以 {@link #mappedPaths()} 拿到的是终态集合。
+ */
+ @Override
+ public void afterSingletonsInstantiated() {
+ enforceIncrementalCoverage(audit(mappedPaths()).uncovered(),
+ readBaselineSnapshot(),
+ isServerProfile(activeProfiles));
+ }
+
+ /**
+ * 判增量:存量(快照里已登记的)不报错,快照里没有的才拒起。
+ *
+ * 拆成静态纯方法是为了能被单测直接喂集合——否则"拒起"这条只能靠起真容器验,
+ * 而那正是本仓库 4035 例全绿却把起不来的 jar 推上线的缺口。
+ *
+ * @param uncovered 本轮审计出的未设防端点(已按路径模式去重)
+ * @param baseline 存量快照里的端点集合
+ * @param serverProfile 是否按生产口径硬拦
+ * @throws IllegalStateException 增量非空且 serverProfile ⇒ 消息含 {@link #BREACH_ANCHOR} 与增量清单
+ */
+ static void enforceIncrementalCoverage(Collection 这里刻意不做前缀匹配:快照记的是端点(路径模式)而不是前缀。
+ * 若按前缀豁免,登记一条 {@code /api/yolo/list} 就会连带掩护同前缀后来挂上的任何新处理器,
+ * 而"往没人看守的前缀下再挂一个方法"恰恰是这条护栏唯一要拦的动作。
+ */
+ static List 刻意 fail-closed:基线不在 classpath 上就抛、拒绝启动,而不是"读不到就跳过增量判定"。
+ * 后者等于把闸门的开关做成一个可删除的文件——{@code git rm} 掉基线就能让新端点匿名可达,
+ * 那是"声称保护但其实不保护"的第九种形状。今天现网 uncovered=0,
+ * 所以这条抛法不会误伤两台(文件随 jar 打包,{@code baselineSnapshotShipsOnTheMainClasspath} 钉着)。
+ *
+ * 读出来却解析不了同样抛:IOException 走重抛,不静默当成空快照。
+ */
+ static Set 四个判据分别对应四种会让这条闸门静默失效的方式:
+ * 容器用 {@code AnnotationConfigApplicationContext}(不起 Web 服务器、不连库),
+ * 但 {@code afterSingletonsInstantiated} 的触发时机与真实 Boot 启动一致,
+ * 所以"忘了实现接口 / 方法名写错 / 判据没接上容器"这类接线故障会被这条抓到。
+ */
+ @Test
+ void bootRefusesWhenAnUncoveredEndpointIsNew() {
+ try (AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext()) {
+ ctx.getEnvironment().getPropertySources().addFirst(new MapPropertySource(
+ "test-active-profile", Map.of("spring.profiles.active", "server")));
+ ctx.registerBean("requestMappingHandlerMapping", RequestMappingHandlerMapping.class,
+ () -> mappingOf(NEW_UNCOVERED));
+ ctx.register(ApiGuardCoverageAuditor.class);
+
+ IllegalStateException breach = assertThrows(IllegalStateException.class, ctx::refresh,
+ "profile=server 下新增未设防端点竟然还能启动,这条闸门是装饰");
+ String message = breach.getMessage();
+ assertNotNull(message, "拒起却不给消息,值班只能靠猜");
+ assertTrue(message.contains(ApiGuardCoverageAuditor.BREACH_ANCHOR),
+ () -> "异常消息没有巡检锚点 " + ApiGuardCoverageAuditor.BREACH_ANCHOR + ":" + message);
+ assertTrue(message.contains(NEW_UNCOVERED),
+ () -> "异常消息没带增量清单,报了也不知道是哪条端点:" + message);
+ // 锚点必须逐字含方括号:ops 侧 grep 的是 "[api-guard-coverage-breach]" 整串
+ assertTrue(message.contains("[api-guard-coverage-breach]"),
+ () -> "锚点字面量变了,巡检 grep 不到:" + message);
+ }
+ }
+
+ /** 上一条的反证:同一个容器、同一个审计器,只是把 profile 换掉 ⇒ 不许抛(本地/测试要能起)。 */
+ @Test
+ void sameEndpointDoesNotBlockBootOutsideServerProfile() {
+ try (AnnotationConfigApplicationContext ctx = new AnnotationConfigApplicationContext()) {
+ ctx.getEnvironment().getPropertySources().addFirst(new MapPropertySource(
+ "test-active-profile", Map.of("spring.profiles.active", "local")));
+ ctx.registerBean("requestMappingHandlerMapping", RequestMappingHandlerMapping.class,
+ () -> mappingOf(NEW_UNCOVERED));
+ ctx.register(ApiGuardCoverageAuditor.class);
+
+ ctx.refresh(); // 不抛即为通过:抛了本地开发就无法启动
+ assertTrue(ctx.getBeansOfType(ApiGuardCoverageAuditor.class).containsKey(
+ ctx.getBeanNamesForType(ApiGuardCoverageAuditor.class)[0]));
+ }
+ }
+
+ /**
+ * 存量必须放行:同一条 uncovered,只要快照里有,就不许拦启动。
+ *
+ * 这条是整个设计里最贵的一条——现网两台如果因为"存量也被当成新增"而起不来,
+ * 就是 2026-10-07 那次 41 分钟宕机的重演。
+ */
+ @Test
+ void stockUncoveredEndpointsDoNotBlockBoot() {
+ Set 新增一个 {@code @RestController} 挂在没人看守的前缀下 ⇒ 这条红,不必等现网重启。
+ * 分母来自 {@link MappedPathProbe}(Spring 自己的映射发现),不是正则扫源码。
+ */
+ @Test
+ void currentMappingsAddNoUncoveredEndpointBeyondTheSnapshot() {
+ Set 放进 src/test/resources 的话,测试读得到、jar 里没有 ⇒ 现网拿到空基线,
+ * 会把全部存量报成新增=两台同时起不来。这里直接查 src/main/resources 那份文件。
+ */
+ @Test
+ void baselineSnapshotShipsOnTheMainClasspath() {
+ ClassPathResource resource = new ClassPathResource(ApiGuardCoverageAuditor.BASELINE_RESOURCE);
+ assertTrue(resource.exists(),
+ () -> "基线不在 classpath 上:" + ApiGuardCoverageAuditor.BASELINE_RESOURCE);
+ java.nio.file.Path inSource = java.nio.file.Path.of("src/main/resources",
+ ApiGuardCoverageAuditor.BASELINE_RESOURCE.replace('/', java.io.File.separatorChar));
+ assertTrue(java.nio.file.Files.isRegularFile(inSource),
+ () -> "基线文件必须进版本控制且落在 src/main/resources(不是 src/test/resources):" + inSource);
+ assertFalse(java.nio.file.Files.exists(
+ java.nio.file.Path.of("src/test/resources", ApiGuardCoverageAuditor.BASELINE_RESOURCE)),
+ "同一份基线在 test/resources 里又落了一份,两份迟早不一致,判的是哪份就说不清了");
+ }
+
+ /**
+ * 基线不可用 ⇒ 照样拒起(fail-closed)。
+ *
+ * 这条钉的是"闸门不能被人顺手关掉":如果读不到基线就跳过增量判定,那么
+ * {@code git rm} 掉基线文件就等于给以后所有未设防端点开绿灯,而且注释里一行痕迹都不会留。
+ * 反支读一次真基线,证明那个"抛"确实是因为文件缺失、不是方法本身坏。
+ */
+ @Test
+ void deletingTheBaselineFileDisablesNothing() {
+ IllegalStateException missing = assertThrows(IllegalStateException.class,
+ () -> ApiGuardCoverageAuditor.readBaselineSnapshot("inspection/__not_a_real_baseline__.txt"),
+ "基线文件不在却静默当空快照 —— 删文件就能关掉这条闸门");
+ assertTrue(missing.getMessage().contains(ApiGuardCoverageAuditor.BREACH_ANCHOR),
+ () -> "缺基线时的消息没有锚点,巡检分不清『闸门被删了』和『新增了端点』:"
+ + missing.getMessage());
+
+ assertNotNull(ApiGuardCoverageAuditor.readBaselineSnapshot(),
+ "真基线读不出来,那上面的『抛』就不是因为文件缺失,本测试就没验到东西");
+ assertFalse(ApiGuardCoverageAuditor.readBaselineSnapshot().contains(NEW_UNCOVERED),
+ "进版本控制的基线里出现了测试用的假路径,等于提前给一条真实欠账发通行证");
+ }
+
+ /**
+ * profile 口径不许和 {@code JwtService} 那处先例漂移。
+ *
+ * 逐串比对两边判据:{@code JwtService#requireSecretInServerProfile()} 是 private,
+ * 用反射调它,喂同一个 profile 串,看两边是否同时认为"这是生产"。
+ */
+ @Test
+ void serverProfilePredicateAgreesWithJwtService() throws Exception {
+ Method jwtCheck = JwtService.class.getDeclaredMethod("requireSecretInServerProfile");
+ jwtCheck.setAccessible(true);
+ Field jwtProfilesField = JwtService.class.getDeclaredField("activeProfiles");
+ jwtProfilesField.setAccessible(true);
+
+ for (String profiles : List.of("server", "local", "server,local", "local,server", "", "prod")) {
+ boolean jwtThinksServer;
+ try {
+ AuthProperties props = new AuthProperties();
+ props.setJwtSecret(null); // 密钥"不安全",于是抛不抛完全由 profile 判据决定
+ JwtService jwt = new JwtService(props);
+ jwtProfilesField.set(jwt, profiles);
+ jwtCheck.invoke(jwt);
+ jwtThinksServer = false;
+ } catch (java.lang.reflect.InvocationTargetException e) {
+ assertTrue(e.getCause() instanceof IllegalStateException,
+ () -> "JwtService 抛的不是 IllegalStateException:" + e.getCause());
+ jwtThinksServer = true;
+ }
+ assertEquals(ApiGuardCoverageAuditor.isServerProfile(profiles), jwtThinksServer,
+ () -> "profile=\"" + profiles + "\" 两边判据不一致——会出现"
+ + "『密钥闸门认为是生产、覆盖闸门认为不是』的半拦半放");
+ }
+ assertFalse(ApiGuardCoverageAuditor.isServerProfile(null), "null profile 被判成生产,本地就会起不来");
+ }
+
+ /** 锚点自证:两个锚点必须不同,否则巡检分不清"欠账"和"这版多了一个"。 */
+ @Test
+ void breachAnchorIsDistinctFromTheWatchAnchor() {
+ assertFalse(ApiGuardCoverageAuditor.BREACH_ANCHOR.contains(ApiGuardCoverageAuditor.ALERT_ANCHOR),
+ "拒起消息里带上 ALERT_ANCHOR 会让同一条日志被两支判据命中,值班看到两个故障");
+ assertFalse(ApiGuardCoverageAuditor.ALERT_ANCHOR.contains("breach"));
+ }
+
+ /**
+ * 生成/复核基线快照用(平时不产生断言,跑它把当前增量打到标准输出)。
+ *
+ * {@code mvn -o test -Dtest=ApiGuardCoverageBreachTest#printBaselineSnapshot}
+ */
+ @Test
+ void printBaselineSnapshot() {
+ Set 为什么不用正则扫源码:{@link ApiGuardCoverageAuditor} 判的是 {@code handlerMapping.getPatternValues()},
+ * 类级 {@code @RequestMapping} 与方法级路径的拼接、{@code {"/a","/b"}} 多值、方法级空路径这些细节由 Spring 自己算。
+ * 自己抄一份正则就会和真实映射慢慢脱钩——而存量快照一旦比真实集合少一条,
+ * 现网就变成"新增未设防端点 ⇒ 拒绝启动"的假事故(两台同时起不来=重启窗口事故重演)。
+ *
+ * 做法:把控制器注册成 bean 定义 并标成懒加载,再让真实的
+ * {@link RequestMappingHandlerMapping#afterPropertiesSet()} 去发现它们。
+ * {@code preInstantiateSingletons} 跳过懒加载定义 ⇒ 控制器不被实例化(它们的构造器要 DataSource/Redis),
+ * 登记的 HandlerMethod 只持 beanName ⇒ 不需要 DB / Redis / RocketMQ,也不需要 {@code @SpringBootTest}。
+ *
+ * 这里刻意只用 {@code getMethod().getDeclaringClass()},不碰 {@code HandlerMethod#getBeanType()}——
+ * 后者会把 bean 解析出来,就把"不实例化"这个前提破坏了。
+ */
+final class MappedPathProbe {
+
+ static final String BASE_PACKAGE = "com.nanri.aiimage";
+
+ private MappedPathProbe() {
+ }
+
+ /** Spring 登记的全部映射(路径模式 × 处理器方法),与现网 handlerMapping.getHandlerMethods() 同口径。 */
+ static Map
+ *
+ */
+class ApiGuardCoverageBreachTest {
+
+ /** 一个肯定不落进 covered/public/methodGuarded/pending 任一格的路径。 */
+ private static final String NEW_UNCOVERED = "/api/yolo-brand-new/list";
+
+ /** 返回只登记指定路径的 handlerMapping(值用 null:审计器只读 keySet 里的路径模式)。 */
+ private static RequestMappingHandlerMapping mappingOf(String... patterns) {
+ return new RequestMappingHandlerMapping() {
+ @Override
+ public void afterPropertiesSet() {
+ // 不扫 bean,测试自己喂映射
+ }
+
+ @Override
+ public Map