能启动,不代表装配成功:Spring Boot 4 升级里的静默故障
升级完那天,容器是 healthy,日志五百行没有 ERROR,登录接口返回 200。这些信号只能说明进程活着,说明不了装配成功。
所谓静默故障,就是应用起来了、日志干净、接口也通,但某块功能其实没接上。它不报错,只是不工作。这次升到 Spring Boot 4.1,我特意盯了四个地方。
1、Jackson 变成两套,配置只盖住一套
Boot 4 默认用 Jackson 3,spring.jackson.* 这套配置只作用于容器里那个 JsonMapper。问题是项目里还有五个文件在用 Jackson 2,都是 AgentScope 的 SDK 边界,它们的 ObjectMapper 是手工 new 出来、手工配的。
这就意味着,某天有人在 application.yml 里加一条全局日期格式,主接口会变,这五处不会变;反过来,SDK 边界上为了兼容外部报文开的 FAIL_ON_UNKNOWN_PROPERTIES=false,也不会传染给主接口。两边都对,但看起来像两套系统。
我的处理是接受这个现实,但把边界写清楚:SDK 的 DTO 不交给全局 mapper,进出都用字符串,各自解析。判断有没有漏改,搜 com.fasterxml.jackson.databind 就行,它只应该出现在这几个适配类里。
2、Redis 的 codec 选错,写的时候不吭声
Redisson 4.x 同时提供 TypedJsonJacksonCodec 和 TypedJsonJackson3Codec,一个给 Jackson 2,一个给 Jackson 3。两个都能注入,应用都能启动,写缓存也不报错,只有在读的时候才会告诉你类型不对。
更麻烦的是默认类型信息。开了 activateDefaultTyping,值里会写全类名,升级之后包名全变了,旧 key 反序列化直接 ClassNotFoundException。这个错不会在发版当天的冒烟里出现,往往要等到某个用户点开历史会话。
所以升级时我把 key 前缀换了一版,等于让旧缓存整体失效,比在线上边看日志边删 key 省事。这条经验跟 Jackson 没关系,任何改序列化方式的操作都适用。
3、LiteFlow 的启动失败,反而是件好事
升级过程中遇到过一次起不来,堆栈停在 Actuator 的 PathMappedEndpoints,第一眼看上去像是 Actuator 的问题。实际原因是 LiteFlow 2.16.2.1 的指标端点要靠反射取参数名,而它的字节码没带 -parameters,Boot 4 下这条链路直接初始化失败。
项目本来就没引入 micrometer,这个端点没有任何用途,把 liteflow.metrics.enabled 关掉就解决了。
我为什么说这是好事?因为它至少是显性的。启动失败会拦住你,静默故障不会。升级时真正难缠的,是那些启动成功、跑起来才发现不对的东西。
4、healthy 也可能是假的
前面三条都在应用里,这条在编排层。
部署栈的 PostgreSQL 容器原来只探 pg_isready。初始化阶段 PG 会先起一个临时 server,这时 pg_isready 已经返回成功,容器被标成 healthy,后端抢先去连,连的是还没建表的库,启动失败。日志里能看到连接错误,但容器状态是绿的,很容易误判成应用的问题。
后来改成探到 ai_agent_task 表存在才算 healthy,问题就没了。这个坑不只 PG 有,任何"端口通了就算就绪"的健康检查都有同样的毛病。
5、怎么确认装配真的生效
静默故障没法靠看日志发现,只能靠主动验证。我现在固定做三件事。
第一,启动时开一次 --debug,看 ConditionEvaluationReport,确认关键自动配置是 matched 而不是 did not match。Boot 4 拆了模块,包名和条件都变了,这一步能提前发现"starter 引了但没生效"。
第二,给两套序列化各写一条断言。主接口断言字段命名和日期格式,SDK 边界断言能容忍多余字段。这两条测试很便宜,但能挡住上面第一、第二个问题。
第三,e2e 要覆盖写—读闭环。只测写入,codec 选错了照样通过;写完再读出来比对,才会暴露。我们那 20 层 HTTP 和 18 条 UI 用例,很大一部分价值就在这里。
6、最后
升大版本,红色报错其实不可怕,改就是了。真正要盯的是绿色的东西:healthy 的容器、没有 ERROR 的日志、返回 200 的接口。它们只能说明进程活着,说明不了装配成功。
判断标准也很简单:这个功能,有没有被真实调用过一次。
关于 BizBuddy
BizBuddy 是一个全量开源(MIT)的企业级智能体平台,Spring Boot 4.1.1 + AgentScope Java Harness,前端 开源中后台底座,PostgreSQL 14 与 MySQL 8.0 双栈交付。
仓库地址:https://gitee.com/zl3624/biz-buddy
如果你也在做类似的升级,欢迎拿这套代码对照,发现问题直接提 issue。