Spring Boot on 牛哥聊技术

Spring Boot 配置加载机制详解

Thu, 14 Aug 2025 15:00:00 +0800

几乎每个 Spring Boot 项目都遇到过

排查问题时最让人崩溃的一类故障是——

配置改了重启了，行为还是老的。

经验稍丰富的开发会立刻反应过来：它从别处加载了更高优先级的配置，覆盖了你的修改。但这"别处"具体是哪里？覆盖顺序是什么？为什么有些配置改了没生效，有些反而立刻生效？

Spring Boot 的配置加载体系在文档里写得相对分散，本文把它完整拉直说一遍——从 application.yml 到环境变量、从 bootstrap.yml 到 EnvironmentPostProcessor、从 --server.port=8080 到 K8s ConfigMap，把所有渠道按优先级排成一张图。

一、Spring Boot 配置的"位置"全集

Spring Boot 能从这些地方读取配置（优先级从高到低）：

flowchart TD
 A["1. 命令行参数
--server.port=8080"]
 B["2. SPRING_APPLICATION_JSON
JSON 串注入"]
 C["3. ServletConfig / ServletContext 参数"]
 D["4. JNDI 属性"]
 E["5. Java System Properties
-Dxxx=yyy"]
 F["6. OS 环境变量
SERVER_PORT=8080"]
 G["7. RandomValuePropertySource
random.*"]
 H["8. 外部 application.yml
(jar 包外)"]
 I["9. 外部 application-{profile}.yml"]
 J["10. 内部 application.yml
(jar 包内)"]
 K["11. 内部 application-{profile}.yml"]
 L["12. @PropertySource 注解"]
 M["13. 默认值
SpringApplication.setDefaultProperties"]

 A --> B --> C --> D --> E --> F --> G --> H --> I --> J --> K --> L --> M

优先级越靠上的源覆盖越靠下的源——同一个 key 多处定义时，最高优先级的值生效。

记住一个原则：

“外部覆盖内部、命令行覆盖文件、Profile 覆盖默认”——这三句话覆盖了 95% 的优先级问题。

二、为什么命令行优先级最高

Spring Boot 把命令行优先级设到最高，是为了给运维一个『不需要改代码也能改配置』的口子：

1

java -jar app.jar --server.port=9999 --spring.datasource.url=...

无论 jar 包里 application.yml 写了什么，命令行说了算。

K8s 里也是这个意思——通过 ConfigMap 传环境变量，环境变量优先级高于 jar 内配置，就实现了"同一个 jar 部署到不同环境"。

三、application.yml 在哪些位置会被找到

Spring Boot 启动时按以下顺序查找配置文件（Spring Boot 2.3+ 默认）：

1
2
3
4
5


1. file:./config/*/ (运行目录 config 下的一级子目录,2.3+ 起最高优先级)
2. file:./config/ (运行目录的 config 子目录)
3. file:./ (运行目录)
4. classpath:/config/ (jar 内的 config/)
5. classpath:/ (jar 内根目录)

file: 开头表示文件系统位置
classpath: 是 jar 包内
越靠前的位置优先级越高
file:./config/*/ 经常被忽视——K8s 把多个 ConfigMap 分别挂到 config/redis/、config/db/ 等子目录时，就靠这一项被加载

这就是为什么"jar 同级目录放 application.yml"能覆盖 jar 内配置——是 #2 覆盖 #4 的体现。

文件名默认是 application，可以通过 spring.config.name 改：

1

java -jar app.jar --spring.config.name=myapp

会去找 myapp.yml / myapp.properties。

spring.config.location 能完全自定义查找路径：

1

java -jar app.jar --spring.config.location=file:/etc/myapp/

四、Profile 机制：环境维度切换

激活 Profile

1

java -jar app.jar --spring.profiles.active=prod

或者环境变量：

1

SPRING_PROFILES_ACTIVE=prod java -jar app.jar

Profile 文件命名

1
2
3
4


application.yml ← 共享配置
application-dev.yml ← dev profile 独占
application-test.yml ← test profile 独占
application-prod.yml ← prod profile 独占

激活某个 profile 时，application.yml 和 application-{profile}.yml 都会被加载，profile 文件覆盖通用文件。

多 Profile 同时激活

1

--spring.profiles.active=prod,monitoring,debug

按数组顺序加载，后面的覆盖前面的。这是做"基础 prod 配置 + 加监控 + 加调试日志"组合的标准姿势。

`spring.profiles.include`

不同于 active 是"激活什么"，include 是"再附加什么"：

1
2
3
4


# application-prod.yml
spring:
 profiles:
 include: monitoring

激活 prod 时自动也加载 application-monitoring.yml——保证一组配置成套生效，不用每次写命令行参数。

五、`bootstrap.yml` vs `application.yml`

Spring Cloud 项目里还会出现 bootstrap.yml——它是 Spring Cloud 引入的，比 application.yml 更早加载。

flowchart LR
 A[bootstrap.yml
加载阶段 1] --> B[拉取远程配置中心]
 B --> C[application.yml
加载阶段 2]
 C --> D[最终 Environment]

bootstrap.yml 的典型用途——配置"配置中心客户端本身"：

1
2
3
4
5
6
7
8
9


# bootstrap.yml
spring:
 application:
 name: user-service
 cloud:
 nacos:
 config:
 server-addr: nacos.internal:8848
 namespace: prod

为什么必须更早加载？因为 Nacos / Apollo / Spring Cloud Config 的客户端要先连上配置中心，才能拉到 application.yml 里的业务配置——鸡生蛋、蛋生鸡的问题。

Spring Cloud 2020.0 之后官方推荐用 spring.config.import 替代 bootstrap.yml：
1
2
3
spring:
 config:
 import: optional:nacos:application.yml
但 bootstrap.yml 仍然兼容，且大量老项目还在用。

六、外部化配置：12-Factor 的最佳实践

12-Factor App 第三条：“Store config in the environment”——配置应当从环境而来，而不是写死在代码里。Spring Boot 的设计完全贴合这个理念：

1
2
3
4
5
6


# application.yml
spring:
 datasource:
 url: ${DB_URL:jdbc:mysql://localhost:3306/test}
 username: ${DB_USER:root}
 password: ${DB_PASS:}

${VAR:default} 语法——先看环境变量，没有就用默认值。这种写法的好处：

同一个 jar 在 dev/test/prod 三套环境跑
K8s 里通过 ConfigMap / Secret 注入
本地开发不需要 Secret，用默认值

K8s 部署时：

1
2
3
4
5
6
7
8


env:
 - name: DB_URL
 value: jdbc:mysql://prod-mysql:3306/order
 - name: DB_PASS
 valueFrom:
 secretKeyRef:
 name: db-secret
 key: password

七、`@Value` vs `@ConfigurationProperties`

业务代码注入配置有两种主流方式。

`@Value`：单字段注入

1
2


@Value("${server.port:8080}")
private int port;

简单直接，但有几个限制：

不支持类型校验——拼写错了运行时才发现
不支持嵌套对象——只能拿单个值
不便于测试——要在 test 里 mock 整个 Environment

`@ConfigurationProperties`：批量映射

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@Component
@ConfigurationProperties(prefix = "feature")
@Validated
public class FeatureConfig {
 @NotBlank
 private String name;
 @Min(0) @Max(100)
 private int threshold;
 private Map<String, String> tags;

 // getters / setters
}

1
2
3
4
5
6


feature:
 name: my-feature
 threshold: 50
 tags:
 region: cn
 env: prod

@ConfigurationProperties 是生产推荐姿势——类型安全、能 @Validated 校验、IDE 提示完整、便于单元测试。

`@RefreshScope`

配置中心场景下，要让配置变更立刻生效需要加 @RefreshScope：

1
2
3
4


@Component
@RefreshScope
@ConfigurationProperties(prefix = "feature")
public class FeatureConfig { ... }

但记住：

@RefreshScope 不要加在 @Configuration 上
@ConfigurationProperties 自带的刷新已经够多数场景用，不一定需要 @RefreshScope
复杂业务的"动态配置"建议直接通过事件订阅，而不是依赖 @RefreshScope 重建 Bean

八、调试技巧：搞清楚配置从哪里来

1. Actuator 的 `/actuator/env`

1
2
3
4
5


management:
 endpoints:
 web:
 exposure:
 include: env,configprops

调用 /actuator/env 能看到每个 PropertySource、每个 key 的来源和最终值——是排查"配置不生效"的最快办法。

1
2
3
4
5
6


{
 "name": "applicationConfig: [classpath:/application.yml]",
 "properties": {
 "server.port": { "value": 8080 }
 }
}

2. 启动日志 DEBUG

1

java -jar app.jar --debug

会打出每个 starter 的自动配置生效情况。

3. 启动参数检查

如果你怀疑有命令行参数在覆盖配置，看启动脚本里的所有 -D 和 --，再看环境变量：

1

env | grep -i SPRING

很多"诡异覆盖"是 K8s ConfigMap 里悄悄塞了同名变量。

九、几个最常被踩的坑

坑 1：YAML 缩进与冒号后空格

1
2


server:
 port:8080  # ❌ 冒号后没空格 → 当作字符串

1
2


server:
 port: 8080 # ✓

坑 2：Profile 里的相对路径

1
2
3
4


# application-prod.yml
logging:
 file:
 name: logs/app.log  # 相对路径，相对于"工作目录"，不是项目目录

部署到容器后工作目录可能不是你以为的位置——生产路径写绝对路径。

坑 3：环境变量大小写转换

YAML 里的 spring.datasource.url 对应环境变量是 SPRING_DATASOURCE_URL——点变下划线、全大写。写成 spring.datasource.url 当环境变量是不会被认到的（虽然 Spring Boot 现在支持驼峰转 kebab，但环境变量必须全大写）。

坑 4：占位符递归

1
2


foo: ${bar}
bar: ${foo}  # ❌ 死循环

启动直接报错。但更隐蔽的是：

1
2
3


prefix: app
fullName: ${prefix}-${name:default}
name: ${prefix}-suffix

会展开成预期之外的字符串，自己看不出来。复杂占位符建议拉直写。

坑 5：`@ConfigurationProperties` 没生效

最常见原因是没加 @Component 或 @EnableConfigurationProperties：

1
2
3


@Component
@ConfigurationProperties(prefix = "feature")
public class FeatureConfig { ... }

或者：

1
2
3


@Configuration
@EnableConfigurationProperties(FeatureConfig.class)
public class AppConfig { ... }

二者选其一。

十、生产 Checklist

部署前过一遍：

不在代码 / yml 里硬编码密钥、数据库密码
敏感配置通过环境变量 / Secret 注入
不同环境分别有 application-{env}.yml
--spring.profiles.active 在启动脚本明确传入
业务代码用 @ConfigurationProperties + @Validated
路径相关配置写绝对路径
Actuator env 和 configprops 在生产环境关闭或加权限
大型项目的全局配置走 bootstrap.yml 或 spring.config.import
启动后用 /actuator/env 抽查关键配置的来源

小结

把全文压一句：

Spring Boot 配置加载的本质是『多个 PropertySource 按优先级合并』——只要把『谁覆盖谁』这件事弄明白，所有"配置不生效"的问题都能 5 分钟定位。

记住几条核心规则：

优先级：命令行 > 环境变量 > 外部文件 > 内部文件 > 默认值
Profile：通用 + profile 配置都加载，profile 覆盖通用
业务用 @ConfigurationProperties，少用 @Value
配置中心走 bootstrap.yml / spring.config.import
排查用 /actuator/env

把这些吃透，配置层基本不会再出意外。

Spring Boot 中被低估的扩展点——EnvironmentPostProcessor

Fri, 12 Nov 2021 15:30:00 +0800

一个真实的烦恼

每个上规模的项目都会遇到这种需求：

启动时要从某个外部源（密钥管理系统、配置中心、加密的 KMS）拿配置
配置要在 Spring 启动最早期就生效，因为后面的 Bean 初始化都依赖它
不能改业务代码——业务代码里只想看到普通的 @Value("${db.password}")

最常见的几种做法：

@Value：太晚，只能取已经加载好的属性
@PropertySource：能加载文件，但支持不了复杂逻辑（解密、调远程服务）
手动在 main 里 set：丑陋且和 Spring 配置体系脱节
写一个 @PostConstruct：太晚——很多 Bean（如数据源）已经基于错误密码初始化失败了

正确答案是 Spring Boot 提供的一个相对"冷门但极其关键"的扩展点——EnvironmentPostProcessor。

它是什么，处于什么位置

Spring Boot 的启动过程里，最早能干预配置的扩展点就是它：

flowchart TD
 A[SpringApplication.run] --> B[加载 spring.factories / SPI]
 B --> C[准备 Environment]
 C --> D["应用 EnvironmentPostProcessor
(每个 Processor 拿到 Environment 都能读、能加、能改)"]
 D --> E["@PropertySource 加载、application.yml 加载"]
 E --> F[ApplicationContext 创建]
 F --> G[Bean 初始化（含 @Value / @ConfigurationProperties）]

关键时机：

比 application.yml 加载完之后（你能读到已有配置）
比 Bean 初始化之前（你的修改对 @Value 全部生效）

也就是说——它是 Spring 配置体系的最后一道"前置插入点"。

一个最小可运行的例子

我们假设要做一件事：启动时根据 spring.profiles.active 自动注入一组运行时元数据（机器名、IP、构建版本号等）。

步骤 1：写一个 EnvironmentPostProcessor

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


public class RuntimeMetaPostProcessor implements EnvironmentPostProcessor, Ordered {

 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 Map<String, Object> meta = new HashMap<>();
 meta.put("runtime.host", getHostName());
 meta.put("runtime.ip", getHostAddress());
 meta.put("runtime.startedAt", LocalDateTime.now().toString());
 meta.put("runtime.jvmVersion", System.getProperty("java.version"));

 // 把这些值作为最高优先级 PropertySource 注入
 env.getPropertySources().addFirst(new MapPropertySource("runtime-meta", meta));
 }

 @Override public int getOrder() { return Ordered.HIGHEST_PRECEDENCE + 10; }

 private String getHostName() {
 try { return InetAddress.getLocalHost().getHostName(); }
 catch (Exception e) { return "unknown"; }
 }
 private String getHostAddress() {
 try { return InetAddress.getLocalHost().getHostAddress(); }
 catch (Exception e) { return "unknown"; }
 }
}

步骤 2：注册

src/main/resources/META-INF/spring.factories（Spring Boot 2.x）：

1
2


org.springframework.boot.env.EnvironmentPostProcessor=\
com.app.config.RuntimeMetaPostProcessor

Spring Boot 3.x 改用 META-INF/spring/org.springframework.boot.env.EnvironmentPostProcessor.imports：

1

com.app.config.RuntimeMetaPostProcessor

步骤 3：业务里随便用

1
2
3
4
5


@Value("${runtime.host}")
private String host;

@Value("${runtime.ip}")
private String ip;

启动看到效果：

1
2
3


runtime.host=DESKTOP-ABC123
runtime.ip=192.168.1.101
runtime.startedAt=2021-11-12T15:30:11

它最有价值的几个真实场景

场景 1：数据库密码从 KMS / Vault 解密

业务里 application.yml 写的是密文，启动时解密后塞回去：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public class DecryptPostProcessor implements EnvironmentPostProcessor {

 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 String encrypted = env.getProperty("spring.datasource.password");
 if (encrypted != null && encrypted.startsWith("ENC(")) {
 String decrypted = decryptFromKms(encrypted);
 Map<String, Object> map = Map.of("spring.datasource.password", decrypted);
 env.getPropertySources().addFirst(new MapPropertySource("decrypted", map));
 }
 }
}

业务代码完全不知道密码加密过——这是它最干净的姿势。

场景 2：从配置中心拉配置

虽然 Spring Cloud Config / Nacos / Apollo 都有自己的 starter，但它们底层就是基于 EnvironmentPostProcessor / BootstrapContext 实现的。理解这个扩展点，你就能看懂这些组件的源码逻辑。

例如自己写一个最小的"远程配置中心客户端"：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


public class RemoteConfigPostProcessor implements EnvironmentPostProcessor {
 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 String app_id = env.getProperty("app.id");
 String env_name = env.getProperty("spring.profiles.active", "dev");

 Map<String, Object> remote = fetchFromRemote(app_id, env_name);
 env.getPropertySources().addLast(new MapPropertySource("remote-config", remote));
 }
}

addLast 的语义是"远程配置优先级低于本地"——本地能覆盖远程；反过来 addFirst 是"远程覆盖本地"。位置选择是核心设计决策。

场景 3：开发/测试自动开启功能开关

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


public class DevModePostProcessor implements EnvironmentPostProcessor {
 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 String[] active = env.getActiveProfiles();
 if (Arrays.asList(active).contains("dev")) {
 Map<String, Object> overrides = Map.of(
 "logging.level.com.app", "DEBUG",
 "spring.jpa.show-sql", "true",
 "feature.mock-payment", "true"
 );
 env.getPropertySources().addFirst(new MapPropertySource("dev-overrides", overrides));
 }
 }
}

业务代码都不需要看到这些开关，开发模式自动开启。

场景 4：从环境变量适配老配置 key 名

公司迁移老系统时，老的 K8s ConfigMap 用的是 DB_USER、DB_PASSWORD，新的 Spring Boot 期望 spring.datasource.username、spring.datasource.password：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


public class LegacyEnvAdapter implements EnvironmentPostProcessor {
 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 Map<String, Object> map = new HashMap<>();
 if (env.getProperty("DB_USER") != null) {
 map.put("spring.datasource.username", env.getProperty("DB_USER"));
 }
 if (env.getProperty("DB_PASSWORD") != null) {
 map.put("spring.datasource.password", env.getProperty("DB_PASSWORD"));
 }
 if (!map.isEmpty()) {
 env.getPropertySources().addFirst(new MapPropertySource("legacy-adapter", map));
 }
 }
}

老的 ConfigMap 不动，新代码跑得起来。

与其他扩展点的对比

扩展点	触发时机	适用场景
`EnvironmentPostProcessor`	Environment 准备完之后	配置加载/改写
`ApplicationContextInitializer`	Context 创建之前	给 Context 注册 BeanDefinition
`BeanFactoryPostProcessor`	BeanDefinition 加载完	修改/新增 BeanDefinition
`BeanPostProcessor`	Bean 初始化前后	对 Bean 做增强（AOP 基础）
`ApplicationListener`	各种生命周期事件	监听启动/关闭
`@PostConstruct`	Bean 初始化完成	单 Bean 的初始化逻辑

只关心配置时，永远用 EnvironmentPostProcessor，其它扩展点就不要拿来挪用。

几个关键细节

1. Order 决定多个 Processor 的执行顺序

如果项目里有多个 Processor（比如解密 + 远程拉取 + 适配老配置），它们的执行顺序由 getOrder() 决定，值小的先执行。

1

@Override public int getOrder() { return Ordered.HIGHEST_PRECEDENCE + 10; }

业务自己的 Processor 应该排在框架的 Processor 之后——HIGHEST_PRECEDENCE 是 Integer.MIN_VALUE，加一点偏移避免和框架抢顺序。

2. PropertySource 的优先级

Environment 维护了一个有序的 PropertySource 列表：

flowchart LR
 A["addFirst
最高优先级"] --> B["命令行参数"] --> C["application.yml"] --> D["environment 变量"] --> E["addLast
最低优先级"]

加自定义 source 时关键决策是 addFirst 还是 addLast：

解密类、Override 类 → addFirst（自己的值优先）
远程 fallback 配置 → addLast（被本地优先）

写错位置会导致"为什么我设置了配置不生效？“这种排查噩梦。

3. 不要在 Processor 里依赖 Spring Bean

EnvironmentPostProcessor 触发时整个 ApplicationContext 还没建好——你不能 @Autowired，不能用 Spring Bean。需要的工具类要么自己 new，要么用静态工厂方法。

4. 异常处理

Processor 里抛异常会让整个应用启动失败。像"远程配置中心拉取失败"这种外部依赖应该有 fallback 行为：

1
2
3
4
5
6
7


try {
 Map<String, Object> remote = fetchFromRemote(...);
 env.getPropertySources().addLast(...);
} catch (Exception e) {
 log.warn("remote config unavailable, fallback to local", e);
 // 不重抛，让应用用本地配置启动
}

5. 日志：Processor 太早，标准 logback 还没初始化

Processor 触发时 logback / log4j2 通常还没初始化好，写日志可能丢失。一个 workaround 是用 DeferredLog：

1
2
3
4
5
6
7
8


private static final DeferredLog log = new DeferredLog();

@Override
public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 log.info("decrypting config...");
 // ...
 app.addInitializers(ctx -> log.replayTo(MyProcessor.class));
}

DeferredLog 把日志先缓存起来，等 logging 体系准备好后回放。生产代码里强烈建议用它。

调试技巧

启动时把 Environment 的所有 PropertySource 打出来看一下：

1
2
3


((ConfigurableEnvironment) env).getPropertySources().forEach(ps -> {
 log.info("PropertySource: {}", ps.getName());
});

更简单的办法是开 Spring Boot Actuator 的 /actuator/env，能看到每个 key 的来源——调试配置加载顺序，没有比这更快的方法。

小结

一句话总结：

EnvironmentPostProcessor 是 Spring Boot 配置体系的最后一道前置插入点——业务代码里看到的每一个 @Value，最终值都可以由它在最早期被改写。

什么时候用：

启动时要做"配置改写、解密、远程拉取、key 适配”
业务代码不应该感知这些"配置层操作"
触发时机必须早于 Bean 初始化

写 Processor 的几个原则：

addFirst vs addLast 看清楚——这是最大的坑
不依赖 Spring Bean，触发时还没有 ApplicationContext
用 DeferredLog，正常 logger 不一定准备好
异常要有 fallback，别让外部依赖卡死启动
用 getOrder() 控制多 Processor 顺序

把这个扩展点用熟，你就能优雅地解决很多原本只能"在 main 里 hack"的奇葩需求。

JUnit 4 到 JUnit 5：Java 测试框架的迁移与实战

Mon, 14 Sep 2020 15:30:00 +0800

为什么要从 JUnit 4 升级到 JUnit 5

很多团队的 pom.xml 里至今还躺着 junit:junit:4.x。JUnit 4 已经停止主线维护多年，但因为足够"够用"，迟迟没人动。

升级到 JUnit 5 不是为了赶时髦，而是它解决了 JUnit 4 时代积攒的几个核心痛点：

架构臃肿：JUnit 4 把整个框架塞在一个 jar 里，运行器（Runner）和扩展点（Rule）冲突，不能叠加
没有原生参数化测试：要靠 Parameterized Runner，写法别扭
嵌套测试丑陋：要用 @RunWith(Enclosed.class)
断言能力弱：复合断言、异常断言要靠第三方库
不支持 Java 8+ Lambda：很多优雅写法用不上

JUnit 5 推倒重来，拆成三个模块：

flowchart LR
 Platform["JUnit Platform
(运行平台)"]
 Jupiter["JUnit Jupiter
(JUnit 5 编程模型)"]
 Vintage["JUnit Vintage
(兼容跑 JUnit 3/4)"]

 Platform --> Jupiter
 Platform --> Vintage

Platform：测试引擎的标准接口，IDE/Maven/Gradle 都对它编程
Jupiter：你写的 @Test 用的就是它
Vintage：让 JUnit 4 测试在 Platform 上继续跑，平滑迁移

下面我们用一个个能跑的例子，把 JUnit 5 的常用与进阶用法过一遍。

一、最小可运行例子

1
2
3
4
5
6


<dependency>
 <groupId>org.junit.jupiter</groupId>
 <artifactId>junit-jupiter</artifactId>
 <version>5.10.0</version>
 <scope>test</scope>
</dependency>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class CalculatorTest {
 @Test
 void add_should_return_sum() {
 Calculator c = new Calculator();
 assertEquals(5, c.add(2, 3));
 }
}

注意——类和方法都不再需要 public，包私有就够了，因为 JUnit 5 用反射访问。这是个微小但很贴心的改进。

二、生命周期注解

JUnit 4 → JUnit 5 注解对照：

JUnit 4	JUnit 5
`@Before`	`@BeforeEach`
`@After`	`@AfterEach`
`@BeforeClass`	`@BeforeAll`
`@AfterClass`	`@AfterAll`
`@Ignore`	`@Disabled`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


class LifecycleTest {

 @BeforeAll
 static void beforeAll() { /* 整个测试类前执行一次 */ }

 @BeforeEach
 void beforeEach() { /* 每个 @Test 前执行 */ }

 @Test
 void test1() { /* ... */ }

 @AfterEach
 void afterEach() { /* 每个 @Test 后执行 */ }

 @AfterAll
 static void afterAll() { /* 整个测试类后执行一次 */ }
}

@BeforeAll/@AfterAll 默认必须 static。如果不想写 static，把测试类加上 @TestInstance(Lifecycle.PER_CLASS)，整个类用一个实例，方法就不必 static 了——但要注意此时测试方法之间会共享实例字段。

三、断言：丰富又优雅

JUnit 5 的 Assertions 是终于"现代化"了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


@Test
void richAssertions() {
 User u = userService.get(1L);

 // 基础
 assertNotNull(u);
 assertEquals("张三", u.getName());

 // 带 message（lambda 形式，断言失败前才计算字符串）
 assertEquals(20, u.getAge(), () -> "用户 " + u.getId() + " 年龄异常");

 // 一次性断言多个条件，全部都要执行
 assertAll("user properties",
 () -> assertEquals("张三", u.getName()),
 () -> assertEquals(20, u.getAge()),
 () -> assertTrue(u.getEmail().endsWith("@example.com"))
 );

 // 异常断言
 Exception ex = assertThrows(IllegalArgumentException.class,
 () -> userService.get(-1L));
 assertEquals("id must be positive", ex.getMessage());

 // 不抛异常断言
 assertDoesNotThrow(() -> userService.get(1L));

 // 超时断言（同步）
 assertTimeout(Duration.ofMillis(500), () -> userService.heavyTask());
 // 超时断言（一旦超时立刻终止任务）
 assertTimeoutPreemptively(Duration.ofMillis(500), () -> userService.heavyTask());
}

四、参数化测试：JUnit 5 的杀手锏

参数化测试是 JUnit 5 最值得单独学的特性。一个测试方法，多套输入，输出是多个独立测试用例——失败时 IDE 里能看到每个用例的结果。

需要额外依赖：

1
2
3
4
5
6


<dependency>
 <groupId>org.junit.jupiter</groupId>
 <artifactId>junit-jupiter-params</artifactId>
 <version>5.10.0</version>
 <scope>test</scope>
</dependency>

1. `@ValueSource` 单参数

1
2
3
4
5


@ParameterizedTest
@ValueSource(strings = {" ", "\t", "\n"})
void blank_strings_should_be_blank(String input) {
 assertTrue(StringUtils.isBlank(input));
}

2. `@CsvSource` 多参数

1
2
3
4
5
6
7
8
9


@ParameterizedTest(name = "[{index}] {0} + {1} = {2}")
@CsvSource({
 "1, 1, 2",
 "2, 3, 5",
 "10, 20, 30"
})
void add(int a, int b, int expected) {
 assertEquals(expected, calculator.add(a, b));
}

name 属性让每个用例在 IDE 里有清晰的标签，强烈推荐。

3. `@CsvFileSource` 从 CSV 文件读

1
2
3
4
5


@ParameterizedTest
@CsvFileSource(resources = "/test-cases.csv", numLinesToSkip = 1)
void fromCsv(int a, int b, int expected) {
 assertEquals(expected, calculator.add(a, b));
}

适合和测试人员协作——他们维护 CSV，开发不动代码。

4. `@MethodSource` 复杂数据

参数复杂时用方法源：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


@ParameterizedTest
@MethodSource("userTestData")
void create(UserDTO input, boolean expectedValid) {
 assertEquals(expectedValid, userValidator.isValid(input));
}

static Stream<Arguments> userTestData() {
 return Stream.of(
 Arguments.of(new UserDTO("张三", 20), true),
 Arguments.of(new UserDTO("", 20), false),
 Arguments.of(new UserDTO("李四", -1), false)
 );
}

5. `@EnumSource` 遍历枚举

1
2
3
4
5


@ParameterizedTest
@EnumSource(value = OrderStatus.class, mode = Mode.EXCLUDE, names = {"DELETED"})
void allActiveStatusesShouldDisplayCorrectly(OrderStatus s) {
 assertNotNull(s.getDisplayName());
}

五、嵌套测试：让用例分组更优雅

@Nested 让测试类按场景分层，IDE 里看上去就是一棵树：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


class UserServiceTest {

 @Nested
 @DisplayName("当用户已存在时")
 class WhenUserExists {
 @BeforeEach void setup() { /* 准备已存在用户 */ }

 @Test void getById_returns_user() { ... }
 @Test void update_should_succeed() { ... }
 }

 @Nested
 @DisplayName("当用户不存在时")
 class WhenUserNotFound {
 @Test void getById_returns_null() { ... }
 @Test void update_should_throw() { ... }
 }
}

@DisplayName 把测试名换成中文/句子式描述，让测试报告读起来像需求文档。

六、条件执行：根据环境跳过

JUnit 5 提供了一组 @EnabledOn* / @DisabledOn*：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@Test
@EnabledOnOs(OS.LINUX)
void only_on_linux() { ... }

@Test
@EnabledIfSystemProperty(named = "env", matches = "ci")
void only_on_ci() { ... }

@Test
@DisabledIfEnvironmentVariable(named = "SKIP_HEAVY", matches = "true")
void heavy_test() { ... }

比 @Ignore 灵活得多。

七、扩展模型：替代 JUnit 4 的 Rule

JUnit 4 的 @Rule 不能多个叠加、不能跨类复用。JUnit 5 用统一的 Extension 模型替代：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@ExtendWith(MockitoExtension.class)
class UserServiceTest {

 @Mock UserRepository repo;
 @InjectMocks UserService service;

 @Test
 void getById_returns_user() {
 when(repo.findById(1L)).thenReturn(Optional.of(new User()));
 assertNotNull(service.getById(1L));
 }
}

@ExtendWith 可以叠加多个，也可以在方法级生效，灵活性远超 @Rule。

自定义 Extension 实现各种生命周期接口（BeforeEachCallback、AfterEachCallback、ParameterResolver 等），可以做到"在每个测试方法前自动初始化数据"、“自动清理数据库”、“自动注入参数"等。

八、Spring Boot 测试整合

Spring Boot 2.2+ 默认就用 JUnit 5。不需要任何额外配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


@SpringBootTest
@AutoConfigureMockMvc
class UserControllerIT {

 @Autowired MockMvc mvc;
 @MockBean UserService service;

 @Test
 void getUser_should_return_200() throws Exception {
 when(service.get(1L)).thenReturn(new User(1L, "张三"));

 mvc.perform(get("/users/1"))
 .andExpect(status().isOk())
 .andExpect(jsonPath("$.name").value("张三"));
 }
}

值得一提的几个 Spring Boot 测试切片注解（瘦身的 @SpringBootTest）：

注解	用途
`@WebMvcTest`	只加载 Controller 层
`@DataJpaTest`	只加载 JPA 仓库
`@JsonTest`	只测试 JSON 序列化
`@DataRedisTest`	只加载 Redis 相关 Bean
`@RestClientTest`	测试 RestTemplate / FeignClient

切片测试启动快得多，单测就用切片，集成测试再用 @SpringBootTest。

九、JUnit 4 兼容：渐进式迁移

老项目里两套测试可以共存——保留 junit:junit 作为 Vintage 引擎，新增测试用 Jupiter：

1
2
3
4
5
6


<dependency>
 <groupId>org.junit.vintage</groupId>
 <artifactId>junit-vintage-engine</artifactId>
 <version>5.10.0</version>
 <scope>test</scope>
</dependency>

迁移建议：

先把 BUILD 配置好，让两套都能跑
新写的测试一律 Jupiter
改老代码时顺手把对应测试迁移过去
一两个迭代后，老测试全部迁完，移除 vintage 依赖

十、踩坑提醒

@BeforeAll/@AfterAll 默认要 static——除非用 @TestInstance(PER_CLASS)
@Test 不要再带 expected = Xxx.class——JUnit 5 没有这个属性，用 assertThrows
包还是 org.junit.jupiter.api——别混用 org.junit.*
Maven Surefire 要 ≥ 2.22，否则跑不起来 Jupiter 测试
参数化测试单独依赖 junit-jupiter-params
@SpringBootTest 不要乱用——它会启动整个上下文，单测应该用切片

小结

JUnit 5 不是"JUnit 4 的小升级”，是为 Lambda、模块化、现代 Java 重新设计的测试框架。

把这一篇压一句：

写新测试用 Jupiter，老测试靠 Vintage 兼容，慢慢迁；高频场景吃透 assertAll / 参数化 / @Nested，这三个特性能把单测写得像文档。

测试本身不是负担，写得好的测试是最准确的需求说明书。JUnit 5 给了你写出这种文档的工具，能不能用好是另一回事。

服务端到客户端的进度推送：SSE 与 WebSocket 选型

Thu, 12 Mar 2020 16:00:00 +0800

一个看似简单的需求

用户在管理后台点"导出报表"——服务端要生成一个 200MB 的 Excel，前端等 30 秒。最差的体验是这样：

点了按钮，前端转圈圈。30 秒过去——用户以为卡住了，开始连点。后端被点出三次重复任务，最后崩了。

合格的体验应该是：

点了按钮，立刻看到"正在生成 Excel…12%"，每秒进度条往上跳，用户安心等待。

实现这种"实时进度反馈"看起来不复杂——但坑很多：

HTTP 是请求-响应模型，服务端没法主动告诉前端"现在 20% 了"
进度怎么从生成 Excel 的线程"流"到 HTTP 响应里
浏览器有 Range 请求、有 chunked 编码、有 SSE、有 WebSocket——该选哪个

本文把三种主流方案讲清楚——HTTP 流式响应、SSE、WebSocket。各自的优劣、代码、踩坑都覆盖。

一、需求拆解：什么叫"下载进度"

要讲清进度反馈，先把"下载"分两类：

类型 A：纯文件传输

文件已存在，浏览器直接下载——进度信息浏览器自己能算（Content-Length / 已接收字节）。前端不需要服务端告诉，可以自己监听 progress 事件。这种场景根本不需要后端反馈。

1
2
3
4
5
6
7
8


const xhr = new XMLHttpRequest();
xhr.responseType = 'blob';
xhr.onprogress = e => {
 const percent = (e.loaded / e.total * 100).toFixed(1);
 setProgress(percent); // 浏览器自己算
};
xhr.open('GET', '/file/download/1');
xhr.send();

这种是大部分场景——多数情况下不需要后端介入，避免加不必要的复杂度。

类型 B：服务端要先"做事"才有文件

真正复杂的——服务端先生成 Excel（30 秒）、再让前端下载。生成过程中浏览器看到的是 0 字节、Content-Length 还没确定。进度只有服务端知道。

类型 B 才是本文的主场。

二、方案 1：HTTP 流式响应（chunked）

最简单的姿势——把"任务进度"和"最终文件"塞到一个 HTTP 响应里。

服务端用 StreamingResponseBody，每行输出一个 JSON（NDJSON / JSON-Lines）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


@GetMapping("/export")
public ResponseEntity<StreamingResponseBody> export() {
 StreamingResponseBody stream = output -> {
 for (int i = 0; i <= 100; i += 10) {
 // 输出一行 JSON + \n
 String line = String.format("{\"progress\":%d}\n", i);
 output.write(line.getBytes(StandardCharsets.UTF_8));
 output.flush();
 Thread.sleep(500); // 模拟工作
 }
 output.write("{\"done\":true,\"url\":\"/file/123\"}\n".getBytes(StandardCharsets.UTF_8));
 };
 return ResponseEntity.ok()
 .contentType(MediaType.parseMediaType("application/x-ndjson"))
 .body(stream);
}

这里故意不用 SSE 的 data: …\n\n 协议格式——避免和方案 2 混淆。要 SSE 就直接用 SseEmitter（见方案 2），这里就是普通的"按行 JSON 流"。

前端用 fetch + ReadableStream 读：

1
2
3
4
5
6
7
8


const resp = await fetch('/export');
const reader = resp.body.getReader();
while (true) {
 const { done, value } = await reader.read();
 if (done) break;
 const text = new TextDecoder().decode(value);
 // 解析进度
}

优点：

实现简单，一个接口搞定
浏览器原生支持

缺点：

进度信息和文件内容混在一个流里，前端要自己解析协议
不是标准协议，每个项目都可能不一样

适合简单场景——不推荐做复杂业务。

三、方案 2：SSE（Server-Sent Events）

SSE 是 HTML5 的标准——专门为"服务端推送给客户端"设计，比 WebSocket 简单一半。

服务端

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


@GetMapping(value = "/export/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter exportStream() {
 SseEmitter emitter = new SseEmitter(60_000L); // 60s 超时

 executor.execute(() -> {
 try {
 for (int i = 0; i <= 100; i += 5) {
 emitter.send(SseEmitter.event()
 .name("progress")
 .data(Map.of("percent", i, "msg", "处理中...")));
 Thread.sleep(500);
 }
 // 最终输出文件下载链接
 emitter.send(SseEmitter.event()
 .name("done")
 .data(Map.of("url", "/file/12345")));
 emitter.complete();
 } catch (Exception e) {
 emitter.completeWithError(e);
 }
 });
 return emitter;
}

前端

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


const evt = new EventSource('/export/stream');

evt.addEventListener('progress', e => {
 const data = JSON.parse(e.data);
 setProgress(data.percent);
});

evt.addEventListener('done', e => {
 const data = JSON.parse(e.data);
 window.location.href = data.url;
 evt.close();
});

evt.onerror = err => {
 console.error('SSE error', err);
 evt.close();
};

SSE 的特点

服务端 → 客户端单向——客户端不能用同一通道发消息
基于 HTTP——不需要握手协议升级，CDN 能转发
自动重连——网络断了浏览器自动重连
协议极简——event 名 + data 行
比 WebSocket 轻量——但功能少一半

一个常被忽视的细节

很多 PaaS / Nginx 默认 buffer 响应，SSE 推送的消息要等 buffer 满了才到前端。要在 nginx 里关闭：

1
2
3
4
5
6


location /export/ {
 proxy_pass http://backend;
 proxy_buffering off; # ★ 关键
 proxy_read_timeout 3600s;
 chunked_transfer_encoding on;
}

不开就是"明明代码 emit 了但前端 30 秒后才一次性收到所有进度"。

四、方案 3：WebSocket

最重量级的——双向通信，服务端推前端、前端发命令到服务端都行。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


@Component
public class ExportWebSocketHandler extends TextWebSocketHandler {

 @Override
 public void handleTextMessage(WebSocketSession session, TextMessage msg) throws Exception {
 // 收到前端"开始导出"指令后启动任务
 ExportRequest req = JSON.parseObject(msg.getPayload(), ExportRequest.class);
 executor.execute(() -> doExport(session, req));
 }

 private void doExport(WebSocketSession session, ExportRequest req) {
 try {
 for (int i = 0; i <= 100; i += 5) {
 session.sendMessage(new TextMessage(JSON.toJSONString(
 Map.of("type", "progress", "percent", i))));
 Thread.sleep(500);
 }
 session.sendMessage(new TextMessage(JSON.toJSONString(
 Map.of("type", "done", "url", "/file/123"))));
 } catch (Exception e) {
 log.error("export error", e);
 }
 }
}

适用场景：

同一连接里要前端 → 后端发指令（如取消任务、调整参数）
已经有 WebSocket 长连接复用
复杂双向交互（如客服聊天 + 文件传输）

但单纯做"进度反馈"上 WebSocket 是杀鸡用牛刀——SSE 已经够了。

五、三方案对比

	StreamingResponseBody	SSE	WebSocket
实现复杂度	极简	简单	中
协议	HTTP	HTTP（standard）	HTTP Upgrade
双向	✗	✗ 单向	✓
自动重连	✗	✓	✗（要自己写）
Nginx 兼容	△	△（要关 buffer）	△（要 upgrade 配置）
浏览器支持	✓ 全部	✓ 全部	✓ 全部
适用场景	进度+文件混合	单向进度反馈	双向交互

给一个直接的建议：

类型 A（纯文件下载）：浏览器原生 progress；类型 B（服务端做事 + 进度）：99% 用 SSE 就够。WebSocket 留给真正的双向场景。

六、生产细节

1. 进度的"真实性"

1
2
3
4


for (int i = 0; i <= 100; i += 5) {
 emit(i);
 Thread.sleep(500);
}

写成这样的进度是假进度——看着舒服但和真实工作进度无关。生产代码进度要从真实业务里取：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public void doExport(SseEmitter emitter, List<User> users) {
 int total = users.size();
 for (int i = 0; i < total; i++) {
 process(users.get(i));
 if (i % 100 == 0 || i == total - 1) { // 每 100 条推一次
 emitter.send(SseEmitter.event()
 .name("progress")
 .data(Map.of("percent", i * 100 / total)));
 }
 }
}

2. 异常处理

1

emitter.send(...); // 客户端断开会抛 IllegalStateException

客户端关页面、断网、超时——服务端继续 send 会异常。要 catch 后调 emitter.completeWithError(e)，并停止剩余工作（节省服务器资源）。

3. 资源清理

SseEmitter 是要释放的——onCompletion、onTimeout、onError 三个回调要注册：

1
2
3


emitter.onCompletion(() -> log.info("client disconnected"));
emitter.onTimeout(() -> log.warn("session timeout"));
emitter.onError(err -> log.error("session error", err));

4. 不要在 SSE 通道传文件本体

进度通道传进度元数据，文件本体走单独下载链接：

1
2


SSE 推送 → 任务完成时给一个临时下载 URL
前端拿到 URL → 触发标准下载

不要硬塞 base64 文件到 SSE，体积和性能都差。

5. 限流

SseEmitter 是长连接——大流量场景要限连接数（防止有人开 1 万个连接）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


@RestController
public class ExportController {
 private final Semaphore connections = new Semaphore(100); // 最多 100 并发

 @GetMapping("/export/stream")
 public SseEmitter export() {
 if (!connections.tryAcquire()) {
 throw new BusinessException("服务繁忙");
 }
 SseEmitter emitter = new SseEmitter();
 emitter.onCompletion(connections::release);
 emitter.onTimeout(connections::release);
 emitter.onError(e -> connections.release());
 // ...
 return emitter;
 }
}

6. 跨进程任务进度

如果导出任务是异步发到 MQ 或别的进程执行——进度数据要走 Redis：

flowchart LR
 Front --> SSE[SSE Endpoint]
 SSE -.poll.-> Redis[(Redis)]
 Worker[(异步 Worker)] -.write.-> Redis

SSE 通道每秒查一次 Redis 拿进度推给前端，Worker 进度写 Redis。进度生产和消费解耦。

小结

把全文压一句：

HTTP 是请求响应模型，要做"实时进度反馈"，就要打开一个『可以持续推送』的通道——单向选 SSE，双向选 WebSocket，文件本体永远走标准 HTTP 下载。

工程要点：

浏览器原生 progress 能算的进度，别让后端反馈
后端进度反馈优先 SSE
真实进度比假进度重要
Nginx proxy_buffering off 是 SSE 必配
进度和文件本体分离

把这套方案吃透，“导出报表"这种烦人功能能瞬间从 1 星体验变成 5 星。

Spring Boot 项目打包：War 与 Jar 的区别和注意事项

Tue, 30 Oct 2018 17:00:00 +0800

写在前面

新人接触 Spring Boot 时常困惑一个问题——明明同样是 Java Web 项目，为什么有的项目用 mvn package 出来是个 jar，有的项目却出来一个 war，部署方式还截然不同？

答案要从 Spring Boot 的设计哲学说起。Spring Boot 提倡"内嵌容器、可执行 jar"的方式——一个 java -jar app.jar 就跑起来，再也不用 Tomcat 这样的外部容器。但传统的 Java EE 时代，war 包 + 外部容器才是标准玩法。Spring Boot 也兼容这种做法，让老项目能平滑迁移。

这两种打包方式选错了，轻则启动姿势别扭，重则配置失效、监控失灵。本文把它们的区别、坑、和实操要点一次讲清楚。

War 与 Jar 的本质区别

	Jar 包	War 包
用途	通用 Java 库、可执行应用	Java Web 应用归档（Web Application Archive）
入口	`META-INF/MANIFEST.MF` 的 Main-Class	`WEB-INF/web.xml` 或 `ServletContainerInitializer`
部署	`java -jar app.jar`	拷到 Tomcat/Jetty 的 `webapps` 目录
容器	内嵌（Tomcat/Jetty/Undertow）	外部
静态资源	`BOOT-INF/classes/static`	项目根目录或 `webapp` 下
类加载顺序	由 Spring Boot Loader 控制	由外部容器控制

最关键一句话——jar 把容器装进了应用，war 把应用装进了容器。这条决定了两者后续所有差异。

Spring Boot 默认推荐 Jar，原因是什么

Spring Boot 默认 jar 不是凭感觉，是经过权衡的。

Jar 的好处：

零运维：不需要装 Tomcat，不需要管 server.xml，部署=拷贝 jar 包
环境一致：开发、测试、生产用的是同一个内嵌 Tomcat，行为一致
容器版本可控：升级 Tomcat 只是改 pom 依赖
天然适合容器化：一个 jar 就是一个 Docker 镜像的核心
每个应用独立运行：互不影响，Crash 隔离

War 的传统优势在云原生时代逐渐弱化：

原本"一个 Tomcat 跑多个应用"的模式，被 Kubernetes 一个 Pod 一个应用替代了
原本"运维统一管 Tomcat"的优势，被容器编排取代了
原本"war 包小，复用容器"的优势，对几百 MB 起步的 Spring 应用根本不算优势

所以现在的工程默认建议：除非有明确历史包袱或合规要求，新项目一律 jar。

怎么打 Jar 包

Spring Boot 项目默认就是 jar。pom.xml 里：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<packaging>jar</packaging>

<build>
 <plugins>
 <plugin>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-maven-plugin</artifactId>
 </plugin>
 </plugins>
</build>

spring-boot-maven-plugin 的 repackage 目标会把项目打成"可执行 jar"——里面包含一个特殊的 BOOT-INF/lib/ 装所有依赖，外层有 Spring Boot 自己的 JarLauncher：

1
2
3
4
5
6
7
8


app.jar
├── META-INF/
│ └── MANIFEST.MF ← Main-Class: org.springframework.boot.loader.JarLauncher
├── org/springframework/boot/loader/ ← Spring Boot 启动类加载器
└── BOOT-INF/
 ├── classes/ ← 你的代码
 ├── lib/ ← 所有第三方依赖 jar
 └── classpath.idx

启动方式：

1
2


java -jar app.jar
java -Xms512m -Xmx2g -jar app.jar --spring.profiles.active=prod

怎么打 War 包

把同一个项目改成 war 输出，需要四步：

1. 改 packaging

1

<packaging>war</packaging>

2. 排除内嵌 Tomcat

外部容器已经提供了 Servlet 容器，再带一份会冲突：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-web</artifactId>
 <exclusions>
 <exclusion>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-tomcat</artifactId>
 </exclusion>
 </exclusions>
</dependency>

<dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-tomcat</artifactId>
 <scope>provided</scope> <!-- 编译用，不打进 war -->
</dependency>

3. 启动类继承 `SpringBootServletInitializer`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@SpringBootApplication
public class Application extends SpringBootServletInitializer {

 @Override
 protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
 return builder.sources(Application.class);
 }

 public static void main(String[] args) {
 SpringApplication.run(Application.class, args);
 }
}

SpringBootServletInitializer 会让 war 既能 java -jar 跑，也能丢进 Tomcat 跑。保留 main 方法是个好习惯——本地调试还是 java -jar 最方便。

4. 部署

把生成的 app.war 拷贝到 $TOMCAT_HOME/webapps/ 下，Tomcat 自动解压并启动：

1

http://host:port/app/... ← context path 默认是 war 包名

七个最常见的 War 部署坑

坑 1：context path 不一致

java -jar 启动时，Spring Boot 默认 context path 是 /；war 部署到 Tomcat 时，context path 默认是 war 文件名。前端写死接口路径的话，部署完所有请求 404。

对策：要么把 war 重命名为 ROOT.war（context path = /），要么前端通过相对路径拼接。

坑 2：内嵌 Tomcat 没排干净

如果忘了 <scope>provided</scope>，war 里会带一份 Tomcat。在外部 Tomcat 里跑会出现 ClassLoader 冲突——NoSuchMethodError、LinkageError 各种奇葩报错。

对策：用 mvn dependency:tree 检查 war 里没有 tomcat-embed-*。

坑 3：`server.port` 配置失效

application.yml 里的 server.port: 8081 在 war 部署里完全无效——端口由外部 Tomcat 决定。同理 server.servlet.context-path 也无效。

对策：明确知道这些"server.*“配置只对内嵌容器生效。

坑 4：`@PropertySource` 找不到外部配置

java -jar 时 Spring Boot 会自动加载 jar 同级目录的 application.yml 覆盖内置；war 部署时没有"jar 同级目录"这个概念，外部配置要显式放在 Tomcat 的 lib 或者通过 -Dspring.config.location= 指定。

对策：

1
2


# 在 Tomcat 启动参数里加
-Dspring.config.location=file:/etc/myapp/application.yml

坑 5：日志文件路径混乱

Spring Boot 的 logging.file.name=app.log 是相对当前工作目录的，war 部署时这个目录是 Tomcat 的 bin/，不是你以为的项目目录。

对策：日志路径永远写绝对路径。

坑 6：JSP 默认不支持

Spring Boot 的可执行 jar 不支持 JSP（这也是为什么老项目改造时会被卡）。war 部署时虽然支持，但前提是：

1
2
3
4
5


<dependency>
 <groupId>org.apache.tomcat.embed</groupId>
 <artifactId>tomcat-embed-jasper</artifactId>
 <scope>provided</scope>
</dependency>

对策：新项目用 Thymeleaf / Freemarker / 前后端分离，远离 JSP。

坑 7：Filter / Listener 触发顺序

外部 Tomcat 加载 war 时，@WebFilter 等注解的扫描机制和 Spring Boot 自带容器有差异。某些 Filter 可能比 Spring 容器还早初始化，导致 @Autowired 是 null。

对策：用 FilterRegistrationBean 显式注册 Filter，由 Spring 控制生命周期。

镜像化时代的最佳实践

如果你的项目要打 Docker 镜像，强烈推荐用 jar：

1
2
3


FROM eclipse-temurin:17-jre
COPY target/app.jar /app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

简单、清晰、可复制。war + Tomcat 的镜像虽然也能跑，但要装 Tomcat、改 server.xml、暴露端口，且镜像体积更大、启动更慢。

进一步的优化是用 Spring Boot 的 Layered Jar 把不变的依赖和频繁变化的业务代码分层，加速 Docker 镜像构建：

1
2
3
4
5
6
7
8
9


<plugin>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-maven-plugin</artifactId>
 <configuration>
 <layers>
 <enabled>true</enabled>
 </layers>
 </configuration>
</plugin>

1
2
3
4
5
6


FROM eclipse-temurin:17-jre
WORKDIR /app
COPY target/app.jar app.jar
RUN java -Djarmode=layertools -jar app.jar extract
# Spring Boot 3.2+ 路径
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

版本注意：ENTRYPOINT 类路径在 Boot 3.2 处发生过迁移——Boot 3.2+ 用 org.springframework.boot.loader.launch.JarLauncher，3.1 及以下是 org.springframework.boot.loader.JarLauncher。两者写错都会启动报 ClassNotFoundException，按你实际的 Boot 版本选。

选择决策树

flowchart TD
 Start([新项目还是老项目?])
 Start -->|新项目| Jar1[直接用 Jar]
 Start -->|老项目| Old{有外部 Tomcat 集群?}
 Old -->|没有| Jar2[迁移成 Jar]
 Old -->|有| Reason{为什么用外部 Tomcat?}
 Reason -->|历史习惯| Migrate[评估迁移成本，建议慢慢转 Jar]
 Reason -->|多应用共享容器| Docker[考虑 K8s 替代]
 Reason -->|合规/审计要求| War[继续用 War]
 Reason -->|JSP/老旧依赖| War

小结

War 与 Jar 的选择，本质上是"跟着 Java EE 时代的部署模式走，还是跟着云原生的部署模式走”。

给一句决策建议：

新项目优先用 Jar。老项目能改就改。除非有合规/历史/JSP 强约束，否则没有理由再用 War。

Spring Boot 仍然完整支持 war 是为了向后兼容，不是推荐方向。把这点拎清楚，后面所有选择就都顺了。