From 520044c8a49481534692379309984cf6ae42b088 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=BB=84=E8=87=AA=E8=BE=BE?= <980324341@qq.com> Date: Thu, 8 Oct 2026 17:36:32 +0800 Subject: [PATCH] =?UTF-8?q?feat(=E5=8F=96=E8=AF=81):=20=E5=BC=80=E6=9C=BA?= =?UTF-8?q?=E8=87=AA=E6=8A=A5=E8=BF=99=E4=BB=BD=20jar=20=E5=87=BA=E8=87=AA?= =?UTF-8?q?=E5=93=AA=E7=AC=94=20commit?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 制品名自始没 bump 过(aiimage-backend-0.0.1-SNAPSHOT.jar),pom 也没有 git-commit-id, 所以出问题时光看线上机器答不出"在跑的是哪版代码"——10-07 那次是靠"哪个类只有那笔才有"人工认的。 不用 git-commit-id 插件:现网出包是 mvn -o 离线,新插件当场解析失败,等于给发布通道加一根 只有联网才通的管子。改成打包前由 scripts/_git_stamp.py 生成 src/main/resources/git.properties (已加进 .gitignore,入库就成孤儿构建产物,target/classes 里那个孤儿 V148 就是这么来的), 开机念 [build-info];念不到时打 [build-info-missing] 而不是静默当干净构建。 拒绝的职责不在这里:一个元数据文件读不到不该把在跑实例打死,那是发布闸门的事。 --- .gitignore | 4 + .../nanri/aiimage/config/BuildInfoLogger.java | 94 ++++++++++++ .../aiimage/config/BuildInfoLoggerTest.java | 135 ++++++++++++++++++ 3 files changed, 233 insertions(+) create mode 100644 backend-java/src/main/java/com/nanri/aiimage/config/BuildInfoLogger.java create mode 100644 backend-java/src/test/java/com/nanri/aiimage/config/BuildInfoLoggerTest.java diff --git a/.gitignore b/.gitignore index ffb204562..8a2bae1b7 100644 --- a/.gitignore +++ b/.gitignore @@ -139,3 +139,7 @@ data/logs/ # 生产库转储永不再入库(本体只留 backend-java/data/,那里已被忽略) backend-java/src/main/resources/db/aiimage.sql + +# 打包前由 scripts/_git_stamp.py write 生成,随 jar 进 BOOT-INF/classes/; +# 入库会变成"孤儿构建产物"(10-07 那笔 target/classes 里的 V148 就是这个形状造成的宕机) +backend-java/src/main/resources/git.properties diff --git a/backend-java/src/main/java/com/nanri/aiimage/config/BuildInfoLogger.java b/backend-java/src/main/java/com/nanri/aiimage/config/BuildInfoLogger.java new file mode 100644 index 000000000..251e4ab74 --- /dev/null +++ b/backend-java/src/main/java/com/nanri/aiimage/config/BuildInfoLogger.java @@ -0,0 +1,94 @@ +package com.nanri.aiimage.config; + +import java.io.IOException; +import java.io.InputStream; +import java.io.InputStreamReader; +import java.nio.charset.StandardCharsets; +import java.util.Properties; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.boot.context.event.ApplicationReadyEvent; +import org.springframework.context.event.EventListener; +import org.springframework.core.io.ClassPathResource; +import org.springframework.core.io.Resource; +import org.springframework.stereotype.Component; + +/** + * 开机把「这个 jar 是从哪一笔代码打出来的」念出来。 + * + *

存在的理由:制品名自始没 bump 过({@code aiimage-backend-0.0.1-SNAPSHOT.jar}),pom 也没接 + * git-commit-id,所以出问题时光看线上机器无法回答"现在跑的是哪版代码"——2026-10-07 那次 41 分钟 + * 宕机就是靠"哪个类只有那笔才有"人工认出来的。章由 {@code scripts/_git_stamp.py write} 在打包前 + * 生成,随 jar 落在 {@code BOOT-INF/classes/git.properties}。 + * + *

读不到时**不许静默**:打 {@link #MISSING_ANCHOR} 一行 WARN,巡检(scripts/_prod_watch.py 的 + * SIGNATURES)能按这个锚点计数。真正的拦在发布闸门({@code _git_stamp.py verify}),不在这里—— + * 这里拒绝启动会把一个只是没盖章的在跑实例打死,代价和收益不成比例。 + */ +@Component +public class BuildInfoLogger { + + static final String RESOURCE = "git.properties"; + static final String MISSING_ANCHOR = "[build-info-missing]"; + static final String INFO_ANCHOR = "[build-info]"; + + private static final Logger log = LoggerFactory.getLogger(BuildInfoLogger.class); + + /** 一份构建章。{@code commit} 为空串表示章在但没盖住。 */ + record BuildInfo(String commit, String branch, String dirty, String buildTime) { + boolean usable() { + return commit != null && !commit.isBlank(); + } + } + + /** + * 读 classpath 上的章。返回 null 代表**文件不存在**; + * 存在但内容空则返回一个 {@link #BuildInfo#usable()} 为 false 的对象—— + * 这两种情况在日志里必须分开,否则"忘了打包前盖章"和"章被清空"会混成同一条。 + */ + static BuildInfo read(Resource resource) { + if (!resource.exists()) { + return null; + } + Properties p = new Properties(); + try (InputStream in = resource.getInputStream()) { + p.load(new InputStreamReader(in, StandardCharsets.UTF_8)); + } catch (IOException ex) { + log.warn("{} 读到 {} 但解析失败:{}", MISSING_ANCHOR, RESOURCE, ex.getMessage()); + return new BuildInfo("", "", "", ""); + } + return new BuildInfo(p.getProperty("commit", "").trim(), p.getProperty("branch", "").trim(), + p.getProperty("dirty", "").trim(), p.getProperty("build_time", "").trim()); + } + + /** 一行话的描述,供日志与测试共用(测试拿它断言"脏包不会被念成干净")。 */ + static String describe(BuildInfo info) { + if (info == null) { + return "commit=unknown(jar 内无 " + RESOURCE + ",这份包是跳过 _git_stamp.py write 打出来的)"; + } + if (!info.usable()) { + return "commit=empty(" + RESOURCE + " 里 commit 键为空,等于没盖章)"; + } + return "commit=" + info.commit().substring(0, Math.min(12, info.commit().length())) + + " branch=" + (info.branch().isEmpty() ? "?" : info.branch()) + + " dirty=" + info.dirty() + + " built=" + (info.buildTime().isEmpty() ? "?" : info.buildTime()); + } + + @EventListener(ApplicationReadyEvent.class) + public void logOnBoot() { + logIt(read(new ClassPathResource(RESOURCE))); + } + + /** 与 {@link #logOnBoot()} 分开,是为了让测试能直接喂三种形状进来,不必伪造 classpath。 */ + String logIt(BuildInfo info) { + String line = describe(info); + if (info == null || !info.usable() || "true".equalsIgnoreCase(info.dirty())) { + log.warn("{} {}", MISSING_ANCHOR, line); + } else { + log.info("{} {}", INFO_ANCHOR, line); + } + return line; + } +} diff --git a/backend-java/src/test/java/com/nanri/aiimage/config/BuildInfoLoggerTest.java b/backend-java/src/test/java/com/nanri/aiimage/config/BuildInfoLoggerTest.java new file mode 100644 index 000000000..f123505eb --- /dev/null +++ b/backend-java/src/test/java/com/nanri/aiimage/config/BuildInfoLoggerTest.java @@ -0,0 +1,135 @@ +package com.nanri.aiimage.config; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.nio.charset.StandardCharsets; +import java.util.List; + +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import org.springframework.core.io.ByteArrayResource; +import org.springframework.core.io.FileSystemResource; +import org.springframework.core.io.Resource; + +import ch.qos.logback.classic.Level; +import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.spi.ILoggingEvent; +import ch.qos.logback.core.read.ListAppender; + +/** + * 构建章的读法与"念出来"的级别。 + * + *

这些用例要防的形状是:读不到章时静默当作干净构建。所以每条都同时断言 + * **说了什么**(describe)与**用什么级别说**(WARN/INFO),后者才是巡检能数到的那一部分。 + */ +class BuildInfoLoggerTest { + + private static final String STAMP = + "commit=3a49f5f8b1c2d3e4f5061728394a5b6c7d8e9f00\n" + + "branch=master\ndirty=false\nbuild_time=2026-10-08T17:00:00+08:00\n"; + + private static ByteArrayResource stamp(String body) { + return new ByteArrayResource(body.getBytes(StandardCharsets.UTF_8)); + } + + /** 挂一个 ListAppender 到本类的 logger 上,取回真实落到的事件(不是自己拼字符串)。 */ + private static List capture(Runnable body) { + Logger logger = (Logger) org.slf4j.LoggerFactory.getLogger(BuildInfoLogger.class); + ListAppender appender = new ListAppender<>(); + appender.start(); + logger.addAppender(appender); + try { + body.run(); + } finally { + logger.detachAppender(appender); + appender.stop(); + } + return appender.list; + } + + @Test + void 章不存在时read返回null而不是空对象(@TempDir java.nio.file.Path dir) { + Resource absent = new FileSystemResource(dir.resolve("nope.properties")); + assertFalse(absent.exists(), "前提:这个文件确实不存在"); + assertNull(BuildInfoLogger.read(absent)); + } + + @Test + void 章存在但commit为空要念成empty而不是unknown() { + BuildInfoLogger.BuildInfo info = BuildInfoLogger.read( + stamp("commit=\nbranch=master\ndirty=false\nbuild_time=T\n")); + assertNotNull(info); + assertFalse(info.usable()); + assertTrue(BuildInfoLogger.describe(info).contains("commit=empty"), + BuildInfoLogger.describe(info)); + } + + @Test + void 四键齐时逐个解析出来() { + BuildInfoLogger.BuildInfo info = BuildInfoLogger.read(stamp(STAMP)); + assertNotNull(info); + assertEquals("3a49f5f8b1c2d3e4f5061728394a5b6c7d8e9f00", info.commit()); + assertEquals("master", info.branch()); + assertEquals("false", info.dirty()); + String line = BuildInfoLogger.describe(info); + assertTrue(line.contains("commit=3a49f5f8b1c2"), line); + assertTrue(line.contains("dirty=false"), line); + } + + @Test + void 没章时是WARN且带missing锚点() { + List events = capture(() -> new BuildInfoLogger().logIt(null)); + assertEquals(1, events.size(), "必须正好落一条,落 0 条说明断言在对着空气打钩"); + assertEquals(Level.WARN, events.get(0).getLevel()); + assertTrue(events.get(0).getFormattedMessage().contains(BuildInfoLogger.MISSING_ANCHOR), + events.get(0).getFormattedMessage()); + } + + @Test + void commit为空也是WARN() { + BuildInfoLogger.BuildInfo info = BuildInfoLogger.read(stamp("commit=\ndirty=false\n")); + List events = capture(() -> new BuildInfoLogger().logIt(info)); + assertEquals(1, events.size()); + assertEquals(Level.WARN, events.get(0).getLevel()); + } + + /** + * 脏包(工作树有未提交内容时打的)不能念成正常上线件。 + * 这一条是"级别"上的分歧点:若有人把 dirty 判断摘掉,这里会从 WARN 变 INFO 而红。 + */ + @Test + void dirty为true必须是WARN而不是INFO() { + BuildInfoLogger.BuildInfo dirty = new BuildInfoLogger.BuildInfo( + "3a49f5f8b1c2d3e4f5061728394a5b6c7d8e9f00", "master", "true", "T"); + List events = capture(() -> new BuildInfoLogger().logIt(dirty)); + assertEquals(1, events.size()); + assertEquals(Level.WARN, events.get(0).getLevel(), "脏包念成 INFO 就等于巡检看不见"); + assertTrue(events.get(0).getFormattedMessage().contains("dirty=true")); + } + + @Test + void 干净且commit对得上才是INFO() { + BuildInfoLogger.BuildInfo clean = BuildInfoLogger.read(stamp(STAMP)); + List events = capture(() -> new BuildInfoLogger().logIt(clean)); + assertEquals(1, events.size()); + assertEquals(Level.INFO, events.get(0).getLevel()); + assertTrue(events.get(0).getFormattedMessage().contains(BuildInfoLogger.INFO_ANCHOR)); + } + + /** + * 真走一遍监听器:测试 classpath 上没有 git.properties ⇒ 必须吵出来。 + * 这条不靠反射钉注解,钉的是"开机真的会念"。 + */ + @Test + void 开机自检在没有章的classpath上会打missing() { + List events = capture(() -> new BuildInfoLogger().logOnBoot()); + assertEquals(1, events.size()); + assertEquals(Level.WARN, events.get(0).getLevel()); + assertTrue(events.get(0).getFormattedMessage().contains(BuildInfoLogger.MISSING_ANCHOR), + events.get(0).getFormattedMessage()); + } +}