每年到这个时间点Spring Boot 的大版本更新就像年度保留节目。上周我还在帮团队把几个服务从 3.2 往 3.3 上挪这周 Spring Boot 3.4 正式版就发布了。这次更新的核心关键词之一就是结构化日志于我而言这比什么新特性都来得实在。做后端的人应该都有这种体会服务一多日志就变成灾难现场。文本日志在本地看还行一到 Kibana 或者 Loki 里正则写到怀疑人生更别提按 traceId 把一次请求的链路串起来——全挤在一行行自由文本里机器根本没法高效解析。Spring Boot 3.4 把结构化日志做成了内置能力这是让我决定把升级排期提前的最大理由。这篇文章我会站在一个正在维护多个微服务、被日志折腾过的从业者角度聊聊 3.4 到底改了哪些核心的东西结构化日志怎么配置、怎么对接 ELK以及升级过程中会遇到哪些坑。适合正在用 3.2/3.3、准备评估升级的团队也适合那些早想统一日志格式却一直没动手的人。1. 3.4 到底带来了什么先说全局再谈日志1.1 构建坐标的变化Maven/Gradle 都要动以前升级 Spring Boot无非改个 parent 版本号再用 IDE 刷新一下就完事。3.4 这次在构建层面有个比较大的变化Maven 的坐标体系做了调整。官方把原来放在spring-boot-dependencies里的 BOM 管理和构建逻辑重新梳理了一轮你需要在pom.xml里做对应调整。对大多数用 parent 方式的项目来说改动其实很小parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.4.0/version relativePath/ /parent如果你是用dependencyManagement导入 BOM 的方式要换成新坐标dependencyManagement dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-dependencies/artifactId version3.4.0/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagementGradle 用户则需要注意版本目录的变化。Spring Boot 3.4 发布了一个独立的Spring Boot Versions工具用来集中管理依赖版本核心目的就是把框架升级和依赖版本管理这两件事解耦避免每次升级都要手工翻 release notes 找兼容版本。我个人的理解是官方想把依赖版本的维护工作从 Spring Boot 主干里抽出去走成一个独立更新的项目这样 BOM 的更新节奏可以更快不再受制于框架本身的发版周期。plugins { java id(org.springframework.boot) version 3.4.0 id(io.spring.dependency-management) version 1.1.6 }这一块说实话对老项目不算什么大负担但如果你是那种整仓维护几十个微服务、用脚本统一升级依赖的团队大概率会喜欢 Spring Boot Versions 这套思路。1.2 依赖基线整体抬升不是白升级的3.4 不只是给 Spring Boot 自身做加法连带的基础组件也集体升了一轮Spring Framework 6.2、Micrometer 1.14、Jackson 2.18、Kotlin 2.1。这里面我多说两句。Spring Framework 6.2 是 3.4 能稳定跑起来的地基它带来了一些更细粒度的 HTTP 客户端配置能力以及对RestClient的进一步完善。Micrometer 1.14 则影响所有用到 Micrometer Tracing 和指标导出的项目。Jackson 2.18 是单纯让你序列化性能更好、对 Java 21 虚拟线程的支持更完整。另外3.4 还增强了对应用可用性的探针支持。以前你要做 Readiness Probe 存活探针基本靠 Spring Boot Actuator 自带的 health 端点这次把可用性状态跟 K8s 的 startup/liveness/readiness 探针结合的更紧密了应用在启动过程中各个阶段的存活状态可以被更精确地暴露出来。如果你那边规范比较严格默认强制要求通过 K8s 探针做发布判断那这个增强省了你不少事。2. 结构化日志3.4 最值得你动手做的一件事2.1 结构化日志到底解决什么聊结构化日志之前先做个类比。你开了一个仓库每天进出货。早期你拿个本子手写记录今天进了 50 箱苹果这是给人看的后来仓库规模大了你需要拿扫码枪录入系统每一箱都要打上条码入库时间、存放货架、供应商、保质期全部记录在数据库里。这个录入系统的过程就是结构化日志在做的事。传统文本日志就是手写本子人眼一看就懂可一旦要统计、过滤、告警、关联分析效率就非常低。结构化日志把每一条日志变成一组有固定字段的键值对机器解析起来零成本。举个例子一条典型的结构化日志长这样{ timestamp: 2024-11-21T10:15:30.123Z, version: 1, message: Order created successfully, logger_name: com.example.OrderService, thread_name: http-nio-8080-exec-3, level: INFO, level_value: 20000, traceId: a1b2c3d4e5f6a7b8, spanId: a1b2c3d4e5f6a7b8, serviceName: order-service, orderId: ORD-20241121-001 }你不用正则去抠订单号是什么、耗时多少毫秒JSON 里字段直接躺在那里。这就是结构化日志最大的价值让日志从给人看变成既给人看也给机器看。Spring Boot 3.4 内置支持三种业界常用的结构化日志格式格式说明适合场景Logstash经典 ELK 栈格式字段丰富兼容 Logstash 直接解析已有 ELK 体系的团队ECSElastic Common SchemaElastic 官方统一字段规范想长期用 Elastic 生态、追求字段标准化的团队GELFGraylog Extended Log Format早期 Graylog 生态常用正在用 Graylog 的场景这里有个很关键的点3.4 的结构化日志不依赖具体日志实现。以前你想输出 JSON 日志要么自己引入logstash-logback-encoder要么针对 Logback 或者 Log4j2 分别做配置。现在 Spring Boot 在统一抽象层实现了结构化输出无论底层是 Logback 还是 Log4j2产出的 JSON 结构是一致的。这属于改命级的体验提升。2.2 开箱即用的 JSON 输出两个配置项Spring Boot 3.4 里结构化日志的配置非常简单。你只要在application.yml里加上logging: structured: format: console: logstash启动应用控制台的日志立刻从自由文本变成单行 JSON。没有额外依赖没动任何 XML。如果想让输出到文件的日志也变成 JSON再加一行logging: structured: format: console: logstash file: ecs注意console和file是两套独立的格式配置。也就是说你可以控制台保持普通文本方便开发调试文件里输出 JSON 方便采集端读取。这在很多团队里是特别实用的组合避免开发的时候被一行一长串的 JSON 刷屏刷到眼瞎。日志框架的切换也顺手验证了一下。默认依赖里如果用的是 Logback上述配置直接生效你要是换了 Log4j2dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-log4j2/artifactId /dependency照样配这两个属性输出格式不变。这是 3.4 结构化日志设计的巧妙之处——对业务代码和配置文件来说底层日志框架被透明化了。下面是我实测的一段真实输出已脱敏{timestamp:2024-11-21T02:15:30.320Z,version:1,message:Started Application in 2.1 seconds,logger_name:com.example.Application,thread_name:main,level:INFO,level_value:20000,application:order-service,serviceName:order-service}Logstash 格式会自动带上timestamp、version、logger_name、thread_name、level、level_value同时 Spring Boot 会往里塞application、serviceName这类标识字段——多个服务汇聚到同一套采集链路时这种字段能直接区分日志来源非常实用。2.3 自定义格式化器不够用的时候自己写内置格式适用于大多数场景但如果你有特殊需求比如希望日志里默认带一个部署环境字段envprod或者业务字段单独收敛到一个biz对象里Spring Boot 3.4 也留了口子。实现方式是在配置里定义一个StructuredLogFormatterILoggingEvent的 Bean以 Logback 为例。我举个例子我想在每行日志里加上当前环境名import org.springframework.boot.logging.structured.StructuredLogFormatter; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import ch.qos.logback.classic.spi.ILoggingEvent; Configuration public class StructuredLoggingConfig { Bean StructuredLogFormatterILoggingEvent customStructuredLogFormatter() { return event - { String env System.getenv().getOrDefault(APP_ENV, dev); return String.format( {\timestamp\:\%s\,\level\:\%s\,\logger\:\%s\,\message\:\%s\,\env\:\%s\,\traceId\:\%s\}, event.getTimeStamp(), event.getLevel(), event.getLoggerName(), event.getFormattedMessage(), env, event.getMDCPropertyMap().getOrDefault(traceId, ) ); }; } }如果你用 Log4j2泛型参数换成org.apache.logging.log4j.core.LogEvent即可接口是一致的。这种自定义方案适合对输出格式有强约束、或需要对接内部自研日志平台的情况。2.4 从 logstash-logback-encoder 迁移的注意点很多团队之前为了 JSON 日志在logback-spring.xml里手动配过net.logstash.logback.encoder.LogstashEncoder。Spring Boot 3.4 出来之后这个问题就变成了两条路打架。如果你还在用logstash-logback-encoder同时又把logging.structured.format.console配成了logstash日志可能会出现两次结构化输出或者自定义 encoder 直接覆盖掉 Boot 的默认行为。这里我的建议是如果你的需求只是输出 JSON 到控制台或文件直接删掉自带的logstash-logback-encoder依赖交给 Boot 内置处理最省心。如果项目里用了 logstash-logback-encoder 那些很特定的能力比如CustomFields、ShortenedThrowableConverter可以考虑调整一下先评估这些能力是否真的还在用再用 3.4 的自定义StructuredLogFormatter去等价实现。提示迁移时用git diff去对比更新前后的日志输出差异重点关注时间戳格式、异常堆栈的展示形式、MDC 字段是否完整。肉眼对比几行日志比看文档猜要高效得多。3. 实测迁移流程普通项目升级到 3.4 结构化日志3.1 升级前的检查清单Spring Boot 3.4 要求 JDK 17 起最高支持 Java 23。如果你的服务还跑在 JDK 8 或 11 上先别想 3.4把 Java 版本升上来再说。我整理了一份清单照着过一遍基本不会漏检查项说明是否强制JDK 版本17推荐 21 LTS强制Spring Boot 版本3.2/3.3 升级到 3.4强制Maven 版本3.6.3建议 3.9建议Gradle 版本7.5建议 8.4建议自定义 logback-spring.xml检查是否使用自定义 encoder必须检查监控依赖micrometer-registry-prometheus 等版本兼容性建议已废弃配置management.wavefront、旧配置属性必须检查升级之前务必先把环境准备好尤其是本地的 Docker、K8s 测试环境。日志改造虽然不大但涉及 YAML 和日志库的调整没有一条独立的验证链路很容易翻车。3.2 配置文件和代码调整我以一个典型的 Spring Boot 3.3 项目为例说说升级到 3.4 的实操路径。第一步改pom.xml的 parent 版本号parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.4.0/version /parent第二步检查application.yml。3.4 对管理端点的一些属性做了重新整理比如management.wavefront相关的配置整个移除了。如果之前配置了 Wavefront直接删掉。第三步处理结构化日志。备案logback-spring.xml如果没有自定义 encoder直接在application.yml里加配置logging: structured: format: console: logstash file: ecs如果项目里用了logback-spring.xml先看看里面有没有appender自定义了encoder有的话建议注释掉让 Boot 的自动配置接管。第四步代码层面一般不需要大改。3.4 对ConfigurationProperties的绑定更严格了一点如果你的配置类里有那种没在 prefix 下声明、却硬塞进去的字段启动时会看到绑定失败的报错。这个多见于历史遗留项目按报错信息清理即可。3.3 对接 ELK/Loki 的实操配置日志格式换成 JSON 之后采集端的工作量能少一大半。以 Filebeat 采集日志文件并转发到 Logstash 为例Filebeat 配置里直接声明json.keys_under_root: true就能把日志按字段展开filebeat.inputs: - type: filestream enabled: true paths: - /var/log/order-service/*.log parsers: - ndjson: target: Logstash 这边如果接收的是 Filebeat 过来的 JSON根本不需要再写grok正则直接用jsonfilter 就能展开filter { json { source message target structured } }这套配合下来业务日志从 Spring Boot 到 Elasticsearch 的链路上几乎不再有格式解析的挫败感。链路追踪的traceId、spanId都变成字段了Kibana 里点几下就能按 traceId 过滤出整个调用链。注意采集端的时间戳字段建议单独映射成date类型。Logstash 格式输出的timestamp是标准 ISO 8601 格式Elasticsearch 可以直接识别但如果你的索引模板不认timestamp这个字段名需要在 mapping 里指定timestamp字段并 format 成epoch_millis或dateOptionalTime。4. 升级兼容性与常见问题排查4.1 兼容性变更扫雷3.4 作为一个大版本肯定有一些行为变化。这里挑重点说一下我关注到的。首先是配置属性的整理。Spring Boot 3.4 对配置属性做了一轮瘦身不少已经废弃的配置项被移除或改名。这里面最典型的是management.wavefront.*如果你之前用过升级必挂。另外spring.http.client.*和spring.http.clientfactory.*也有调整官网的配置属性索引页可以直接搜旧属性名看迁移到哪儿。其次是自动配置文件的改动。以前你在META-INF/spring.factories里注册自动配置3.4 进一步强化了新的注册方式META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports如果还在用老方式启动会有 warning建议顺手改掉。然后是错误信息展示层面的改进。3.4 改进了启动失败的错误报告比如数据源连接失败时提示信息会直接告诉你项目里有没有DataSource相关的依赖、URL 配置是否符合预期。虽然这不算日志核心功能但对拉高团队排障效率很有帮助。最后是 SBOM 工具的演进。3.4 把 SBOM 生成能力独立成了专门的 API 支持Spring Boot 3.3 是 CLI 方式如果你有软件供应链合规需求升级后 CI 脚本里生成 SBOM 的方式要同步调整。4.2 常见问题速查表这里我整理一份我在升级过程中实际踩过的坑以及对应的排查思路现象可能原因解决方案升级后控制台日志变成一长串 JSON开发时看不惯开了logging.structured.format.console开发环境去掉 console 配置只保留 file 配置JSON 日志里没有 traceId没引入micrometer-tracing或没配 bridge引入 micrometer-tracing 和 zipkin/otel bridge确保 MDC 里有 traceId日志出现了两份 JSON 输出自定义的logstash-logback-encoder和内置结构化配置同时生效移除 or 屏蔽自定义 encoder交给 Boot 管理启动报Configuration property name xxx is not valid配置项被改名或移除去官方配置属性索引查新名称logback-spring.xml被忽略3.4 在结构化日志开启时不加载自定义 appender要么关闭结构化配置要么把自定义逻辑迁移到StructuredLogFormatter升级后 K8s 探针失效3.4 对可用性状态判定更严格检查management.endpoint.health.probes.enabled配置确保 readiness 组已开启日志采集端出现解析失败JSON 字符串里包含未转义字符或非法占位符检查自定义 formatter 有没有正确转义双引号建议用 JSON 库序列化对象4.3 踩坑实录开发环境保持人读模式说一个我自己的血泪经验。刚开始启用console: logstash时控制台输出每行日志都带一个巨大的 JSON 串开发联调时看一眼都费劲。后面我把配置拆开了开发环境只保留file: ecs生产环境控制台也输出 JSON这样本地开发看文本线上采集读 JSON两边都不耽误。具体实现上用 profile 区分就行# application-dev.yml logging: structured: format: file: ecs # application-prod.yml logging: structured: format: console: logstash file: ecs常见问题补充跟 Slack、钉钉通知类 Appender 的兼容很多团队会配一个往钉钉或 Slack 发通知的 Appender。这种自定义 Appender 在 3.4 开启结构化日志之后要注意一下它继承的是 Logback 里的事件对象有自己的格式化逻辑。如果你的通知内容依赖 JSON 格式去解析必须确保它拿到的ILoggingEvent默认字段没有被内置结构化逻辑破坏。目前看不会有直接冲突但如果 Appender 内部用了getEncodedMessage之类跟输出格式耦合的方法建议升级前跑一遍关键发送链路。一个小技巧用 jq 实时看结构化日志本地调试想验证 JSON 日志是否合法我一般直接接个管道过滤tail -f logs/order-service.log | jq .如果某一行日志 JSON 不合法jq 会立刻报错提醒你这边的结构化配置或者业务日志里有非法的占位符。这个技巧平时用来排查日志字段缺失特别顺手。再聊聊后续扩展的方向3.4 内置的结构化日志目前是给了 Logstash、ECS、GELF 三种格式的默认实现。如果你的日志平台不是这些或者想往 OpenTelemetry 的日志语义上靠就自己写StructuredLogFormatter。我试过直接把 OTel 的TraceId和SpanId塞到 MDC 里在自定义 formatter 中输出整条链路从采集到关联分析都非常顺畅。这波结构化日志的上手成本极低收益却非常明显。升级前我在生产环境排查问题点开 Kibana 还要先写正则升级后字段索引全都结构化点个 traceId 就能把一次请求的上下游拉齐观感完全是两个时代的东西。如果你正在为日志采集和排障效率头疼3.4 这波真值得安排上。