Java 后端 / 知识点
Spring Boot 开发速查手册
手册条目
快速选择合适的 Java 版本、构建工具和项目依赖。
创建 Spring Boot 项目
用于从零生成一个可构建、可启动、可验证的 Spring Boot 服务。默认组合采用 Java 21、Maven Wrapper 和最小依赖集;已有系统受运行环境或第三方库限制时,再降到 Java 17。
版本与依赖选择
Spring Boot 4.1.x 至少需要 Java 17。新项目优先选 Java 21;团队已有 Maven 规范时选 Maven,只有确实需要复杂构建逻辑或 Kotlin DSL 时再选 Gradle。Spring MVC 项目使用 spring-boot-starter-webmvc,再按实际需要增加 Validation、Actuator 等能力。
| 选择项 | 建议 |
|---|---|
| Spring Boot | 绿地项目优先选择当前稳定的 4.1.x;已有 3.x 生态约束时保持兼容的 3.5.x |
| Java | 默认 21;必须兼容旧运行环境时选 17 |
| 打包 | 服务端应用通常选 Jar |
| 基础依赖 | Web MVC、Validation、Actuator 按需选择 |
| 扩展依赖 | 数据库、安全、消息队列确认使用后再添加 |
不要一次勾选所有 Starter。多余依赖会引入额外自动配置,可能带来无用连接、默认安全配置或新的启动约束。
命令创建
通过 Spring Initializr 生成 Maven 项目,并固定 Java 与 Spring Boot 版本,便于团队复现。版本固定并不意味着永久不升级,后续应在统一依赖升级流程中更新。
curl -fsSLG "https://start.spring.io/starter.zip" \
--data-urlencode "type=maven-project" \
--data-urlencode "language=java" \
--data-urlencode "bootVersion=4.1.0" \
--data-urlencode "javaVersion=21" \
--data-urlencode "groupId=com.example" \
--data-urlencode "artifactId=demo-service" \
--data-urlencode "name=demo-service" \
--data-urlencode "packageName=com.example.demo" \
--data-urlencode "version=0.0.1-SNAPSHOT" \
--data-urlencode "packaging=jar" \
--data-urlencode "dependencies=webmvc,validation,actuator" \
-o demo-service.zip
unzip -q demo-service.zip -d demo-service
cd demo-service
test -f pom.xml && test -f mvnw && echo "project generated: demo-service"预期输出
project generated: demo-service目录中应至少包含 pom.xml、mvnw、mvnw.cmd 和 src。若下载结果不是有效 ZIP,可执行 file demo-service.zip 检查,常见原因是版本参数无效、代理返回错误页或网络重定向。
构建与启动验证
使用项目自带的 Maven Wrapper 构建,再启动应用并检查 Actuator 健康端点。下面的轮询只用于本地验证,实际端口可能不同。
./mvnw -q clean package
./mvnw -q spring-boot:run > app.log 2>&1 &
APP_PID=$!
READY=false
for i in {1..60}; do
if curl -fsS "http://127.0.0.1:8080/actuator/health"; then
echo
READY=true
break
fi
sleep 1
done
kill "$APP_PID"
test "$READY" = "true"预期输出
{"status":"UP"}若在 60 秒内没有返回,先查看 app.log。优先检查 JDK 版本、8080 端口占用、依赖下载失败,以及是否额外加入了数据库 Starter 却没有配置连接信息。
风险与边界
固定 bootVersion 可以保证脚本可复现,但会让项目停留在旧补丁版本;安全做法是由依赖升级任务统一修改,并配合完整测试。Spring Boot 主版本升级还可能带来 Spring Framework、Spring Cloud、监控 Agent 或第三方 Starter 的兼容性变化,因此上线前应检查对应兼容矩阵,而不是只看“能够编译”。
Windows 使用 mvnw.cmd,PowerShell 可用 Expand-Archive 解压。生产项目应提交 Maven Wrapper 文件,避免不同开发机因 Maven 版本不同产生构建差异。
使用 Spring Boot 父工程管理依赖并配置构建插件。
配置 Maven 项目
用于让 Spring Boot 统一管理依赖版本、编译 Java 21 代码,并把应用打成可直接运行的 Jar。核心是让父工程负责依赖与构建默认值,并按需声明 Spring Boot Maven Plugin 以获得运行和打包能力。
完整 POM
继承 spring-boot-starter-parent 后,受管依赖通常不需要单独填写版本。java.version 统一编译目标;spring-boot-maven-plugin 提供 spring-boot:run 等能力,并支持将应用打包为可执行 Jar。
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.1.0</version>
<relativePath/>
</parent>
<groupId>com.example</groupId>
<artifactId>demo-service</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>demo-service</name>
<description>Demo Spring Boot service</description>
<properties>
<!-- 统一编译目标,CI 与运行环境应使用兼容 JDK -->
<java.version>21</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<!-- 显式声明插件,同时支持 spring-boot:run 与可执行 Jar 构建 -->
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>生效后,java.version 统一 Java 编译目标;父工程负责 Spring Boot 管理范围内的依赖版本与常用 Maven 默认值;插件负责 Spring Boot 专用运行和打包能力。
构建验证
先确认实际继承的父版本,再执行测试和打包。成功后检查制品是否包含 BOOT-INF/,这比只判断 Jar 文件存在更能证明它是可执行的 Spring Boot 制品。
./mvnw help:evaluate \
-Dexpression=project.parent.version \
-q -DforceStdout
./mvnw -q clean verify
test -f target/demo-service-0.0.1-SNAPSHOT.jar \
&& echo "BUILD SUCCESS"预期输出
4.1.0
BUILD SUCCESS继续检查可执行结构:
jar tf target/demo-service-0.0.1-SNAPSHOT.jar \
| grep -q '^BOOT-INF/' \
&& echo "executable jar: BOOT-INF present"预期输出
executable jar: BOOT-INF present若没有 BOOT-INF/,检查插件是否声明、构建目标是否为可启动应用,以及当前模块是否其实是公共库。公共库通常不应该被重打包成 Spring Boot 可执行 Jar。
常用调整
需要修改最终文件名时,可以在 build 下增加 <finalName>demo-service</finalName>,制品变为 target/demo-service.jar。多模块项目通常只在可启动应用模块声明 Boot 插件,公共模块保持普通 Jar。
企业项目不能继承 Spring Boot 父工程时,可以改用 dependencyManagement 导入 spring-boot-dependencies BOM,再单独管理需要的构建插件版本。只导入 BOM 不会自动获得父工程提供的全部 Maven 默认配置。
风险与排障
不要给 Spring Framework、Jackson、Tomcat 等受管依赖随意覆盖版本。Spring Boot 针对一组经过验证的依赖组合进行发布,强制覆盖可能造成方法签名不兼容或运行期类加载失败。排查时优先使用 ./mvnw dependency:tree 找出冲突来源,并优先考虑升级 Spring Boot 补丁版本。
构建失败时依次检查 java -version、./mvnw -version、私服或代理配置、企业 BOM 覆盖情况,以及测试本身是否失败。不要长期使用 -DskipTests 作为修复方式,它只是跳过验证。
使用 Spring Boot Gradle 插件管理依赖和构建任务。
配置 Gradle 项目
用于把 Java 项目配置为可运行、可测试、可打包的 Spring Boot 工程。下面以 Groovy DSL、Java 17 和 Spring Boot 3.5.16 为例,并建议使用项目自带的 Gradle Wrapper,避免本机与构建环境的 Gradle 版本不一致。
基本配置
项目名写入 settings.gradle:
rootProject.name = 'demo'build.gradle 应用 Java、Spring Boot 和依赖管理插件。受 Spring Boot 依赖管理覆盖的依赖通常不需要单独声明版本:
plugins {
id 'java'
id 'org.springframework.boot' version '3.5.16'
id 'io.spring.dependency-management' version '1.1.7'
}
group = 'com.example'
version = '0.0.1-SNAPSHOT'
java {
toolchain {
languageVersion = JavaLanguageVersion.of(17)
}
}
repositories {
mavenCentral()
}
dependencies {
implementation 'org.springframework.boot:spring-boot-starter'
testImplementation 'org.springframework.boot:spring-boot-starter-test'
}
tasks.named('test') {
useJUnitPlatform()
}最小启动类放在 src/main/java/com/example/demo/DemoApplication.java:
package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}构建验证
在项目根目录执行测试并生成 Spring Boot 可执行 Jar:
./gradlew clean test bootJar预期输出:
> Task :test
> Task :bootJar
BUILD SUCCESSFUL in <TIME>产物通常位于 build/libs/demo-0.0.1-SNAPSHOT.jar。<TIME> 会随机器和依赖缓存状态变化,实际文件名还会受 project.name 与 version 影响。
常用任务
| 任务 | 什么时候用 |
|---|---|
./gradlew bootRun |
开发时直接启动应用 |
./gradlew test |
只运行测试 |
./gradlew bootJar |
生成可执行 Spring Boot Jar |
./gradlew dependencies |
查看依赖树 |
./gradlew dependencyInsight --dependency <NAME> |
定位依赖来源和版本冲突 |
风险与排障
优先使用项目 Wrapper,不要让构建依赖开发机预装的 Gradle。Linux 或 macOS 出现 Permission denied 时可执行 chmod +x gradlew;Windows 使用 gradlew.bat。
出现 Unsupported class file major version 时,先检查 java -version 以及 Gradle 实际使用的 JVM。出现 Could not resolve 时,检查 Maven Central、代理和企业私服配置。出现找不到主类时,确认启动类位于源码目录并带有 @SpringBootApplication,同时确认包名与目录结构一致。
根据 Web、数据库、校验或监控需求选择 Starter。
添加 Starter 依赖
根据应用能力添加 Starter,可以一次引入一组经过 Spring Boot 依赖管理协调的库。官方 Starter 通常采用 spring-boot-starter-* 命名,受 Spring Boot 管理的 Starter 一般不需要单独声明版本。
常用选择
| 需求 | Starter | 关键边界 |
|---|---|---|
| REST 或 Spring MVC | spring-boot-starter-web |
默认使用内嵌 Tomcat |
| 参数校验 | spring-boot-starter-validation |
参数上还需使用 @Valid 或 @Validated |
| JPA 数据访问 | spring-boot-starter-data-jpa |
还需数据库驱动和数据源配置 |
| 运行监控 | spring-boot-starter-actuator |
生产环境应限制端点暴露范围 |
| 自动化测试 | spring-boot-starter-test |
通常放在 testImplementation |
依赖配置
下面的片段放入已经应用 Spring Boot 插件的 build.gradle。H2 用于本地启动验证,生产环境应替换为实际数据库驱动:
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-validation'
implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
implementation 'org.springframework.boot:spring-boot-starter-actuator'
runtimeOnly 'com.h2database:h2'
testImplementation 'org.springframework.boot:spring-boot-starter-test'
}这些依赖分别提供 MVC、Bean Validation、JPA、Actuator 和测试能力。配置本身不会产生控制台输出,可通过依赖树验证是否解析成功。
验证依赖
在项目根目录执行:
./gradlew dependencies --configuration runtimeClasspath预期输出节选:
runtimeClasspath - Runtime classpath of source set 'main'.
+--- org.springframework.boot:spring-boot-starter-web -> 3.5.16
+--- org.springframework.boot:spring-boot-starter-validation -> 3.5.16
+--- org.springframework.boot:spring-boot-starter-data-jpa -> 3.5.16
+--- org.springframework.boot:spring-boot-starter-actuator -> 3.5.16
\\--- com.h2database:h2 -> <VERSION>重点检查 Starter 是否被正常解析,以及同一 Spring Boot 依赖管理下是否出现不符合预期的版本覆盖。H2 的具体版本以实际依赖解析结果为准。
风险与边界
不要为了同时获得两套编程模型而随意加入 spring-boot-starter-web 和 spring-boot-starter-webflux。两者分别对应 Servlet MVC 与响应式 Web 栈,选型应与应用运行模型一致。
加入 JPA 后,如果缺少数据库驱动、连接地址或可用数据库,应用可能在启动阶段因数据源初始化失败而退出。本地可先使用 H2,生产环境再提供对应驱动和 spring.datasource.* 配置。
Actuator 不应直接向公网暴露所有管理端点。只开放实际需要的端点,并通过安全认证、网关或独立管理端口限制访问。
第三方 Starter 不一定属于 Spring Boot 官方依赖管理范围,添加前应确认其支持的 Spring Boot 主版本及 Spring Framework、Jakarta API 等兼容性。
排障清单
依赖显示 FAILED 时检查仓库、网络和代理。出现多个版本时使用 dependencyInsight 定位引入路径。添加 Starter 后功能未生效时,确认依赖位于正确配置中:运行依赖通常使用 implementation 或 runtimeOnly,测试依赖使用 testImplementation,避免误放到 compileOnly。
通过 IDE、Maven、Gradle 或可执行 JAR 启动应用。
启动 Spring Boot 应用
用于开发、调试、故障复现或部署验证时启动 Spring Boot 应用。优先使用项目自带的 Maven Wrapper 或 Gradle Wrapper,避免本机构建工具版本与项目要求不一致。
使用时机
IDE 启动适合断点调试,直接运行带有 @SpringBootApplication 的主类。命令行启动适合复现环境问题和自动化验证;已打包的应用则使用 java -jar 启动。
项目根目录存在 mvnw 时使用 Maven Wrapper,存在 gradlew 时使用 Gradle Wrapper。Windows 分别使用 mvnw.cmd 和 gradlew.bat。
基本语法
Maven 项目:
./mvnw spring-boot:run预期结果:应用保持前台运行,启动日志出现类似 Started DemoApplication in <SECONDS> seconds;实际类名、端口和耗时以项目配置为准。
Gradle 项目:
./gradlew bootRun预期结果:任务持续运行且不返回命令提示符,启动日志出现 Started <ApplicationClass> in <SECONDS> seconds。
已经完成打包时,可直接运行可执行 JAR:
java -jar target/<APP_JAR>.jar预期结果:应用启动并持续监听配置的服务端口,日志出现类似 Started <ApplicationClass> in <SECONDS> seconds。
常用参数
开发环境需要临时切换 Profile 时,可以覆盖 Spring Boot Run 插件参数:
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev预期结果:启动日志出现 The following 1 profile is active: "dev" 或等价的活动 Profile 信息。
需要临时修改端口时,也可以直接传入应用参数:
./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=<PORT>预期结果:应用监听 <PORT>;实际启动日志可能显示 Tomcat started on port <PORT> (http),若使用其他 Web 容器则日志文本不同。
风险与恢复
不要把 spring-boot:run 或 bootRun 直接当作正式生产托管方式。这些方式依赖源码和构建工具,终止前台进程后应用也会停止。生产环境通常运行经过验证的可执行 JAR,并交给 systemd、容器平台或其他进程管理器托管。
构建时使用 -DskipTests 会跳过测试执行,不等于代码已经通过测试。发布前应先完成必要测试,再构建发布包。
启动失败时先定位第一处明确错误,尤其关注首个 Caused by。端口冲突检查监听者,配置问题检查当前 Profile 和环境变量;若出现 UnsupportedClassVersionError,核对运行时 JDK 与项目要求的 Java 版本。
兼容性
Linux 和 macOS 的 Wrapper 如果没有执行权限,可运行 chmod +x mvnw gradlew。Spring Boot 3.x 应用需要 Java 17 或更高版本;实际项目仍应以自身构建配置声明的 Java 版本为准。
在配置文件、环境变量或启动参数中修改监听端口。
修改 Spring Boot 服务端口
用于解决默认 8080 端口冲突、让同机多个实例分别监听不同端口,或满足部署平台的端口约定。最常见的入口是 server.port,可由配置文件、环境变量或启动参数提供。
配置方式
在 application.yml 中固定端口:
server:
port: 8081预期结果:应用重启后监听 8081。若使用 Tomcat,启动日志通常包含 Tomcat started on port 8081;其他 Web 容器的日志文本会不同。
使用 application.properties 时:
server.port=8081预期结果:效果与 YAML 配置相同。同一生效范围内不要维护互相冲突的两份配置。
临时覆盖
通过环境变量启动:
SERVER_PORT=8082 ./mvnw spring-boot:run预期结果:应用监听 8082。Spring Boot 的环境变量绑定会把 server.port 映射为大写下划线形式的 SERVER_PORT。
通过启动参数覆盖:
./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8083预期结果:应用监听 8083,仓库中的配置文件不会被修改。
运行已经打包的 JAR 时可直接传应用参数:
java -jar target/<APP_JAR>.jar --server.port=<PORT>预期结果:应用监听 <PORT>,实际端口以命令行参数和其他更高优先级配置共同决定。
验证监听
Linux 环境可在应用启动后检查监听状态:
ss -lntp | grep ':8081'预期结果:看到类似下面的监听记录;PID 和文件描述符会因环境不同而变化。
LISTEN 0 100 *:8081 *:* users:(("java",pid=<PID>,fd=<FD>))没有输出时,检查应用是否启动成功、是否监听其他端口,以及当前用户是否有权限查看进程信息。
优先级与排障
同一属性存在多个来源时,命令行参数通常可以覆盖环境变量和配置文件中的值。排查“端口未生效”时,应优先检查启动参数,再检查环境变量、当前 Profile 及配置文件。
若出现 Port <PORT> was already in use,先确认占用者,再停止明确属于自己的旧实例或选择新的端口,不要直接终止来源不明的生产进程。
Docker、Compose 或其他部署平台还需要同步检查端口映射。应用监听 8081 并不自动意味着宿主机也暴露 8081。
特殊场景
集成测试或并行启动多个实例时,可以让系统分配随机可用端口:
server:
port: 0预期结果:应用启动后使用系统分配的临时端口,实际端口可从启动日志或运行时环境中获取;因此不适合依赖固定地址的普通生产服务。
Linux 中使用低于 1024 的端口通常需要额外权限。不要为了直接监听 80 或 443 而让 Java 应用以 root 身份运行,更常见的做法是由反向代理或负载均衡器接收外部流量,再转发到应用的非特权端口。
使用 Profile 隔离开发、测试和生产环境配置。
切换运行环境
使用 Profile 将开发、测试和生产配置分开,启动时只激活目标环境。Spring Boot 会先读取通用配置,再叠加当前 Profile 的 application-{profile}.yml;命令行参数还能覆盖配置文件中的同名设置。
配置文件组织
通用项放在 application.yml,只有环境差异项才放入 Profile 文件,避免复制整份配置。
# application.yml
spring:
application:
name: demo-service
server:
port: 8080
# application-dev.yml
app:
payment-base-url: http://localhost:9000
# application-test.yml
app:
payment-base-url: https://test-pay.example.com
# application-prod.yml
app:
payment-base-url: https://pay.example.com激活 test 后,最终生效的 app.payment-base-url 为 https://test-pay.example.com,而 server.port 继续使用通用配置中的 8080。
基本语法
部署平台通常使用环境变量,临时排障适合命令行参数;JVM 系统属性必须写在 -jar 之前。
# 命令行参数:适合临时切换
java -jar app.jar --spring.profiles.active=test
# 环境变量:适合容器、CI/CD 和 systemd
SPRING_PROFILES_ACTIVE=prod java -jar app.jar
# JVM 系统属性:-D 参数必须位于 -jar 前
java -Dspring.profiles.active=dev -jar app.jar预期输出
<TIME> INFO <PID> --- [main] ... : The following 1 profile is active: "test"以上输出以第一条命令为例;另外两条会分别显示 prod 和 dev。<TIME>、<PID> 及日志前缀会随运行环境变化,读取时只需确认 active profile 名称。
高频用法
生产部署应显式设置 SPRING_PROFILES_ACTIVE=prod,不要依赖开发机上的默认值。一次启用多个 Profile 时使用逗号分隔,例如 --spring.profiles.active=prod,metrics,并确保同名配置不会产生含义不清的覆盖。
仅需临时改一个配置时,不必新建 Profile,可在激活环境后追加参数,例如 --server.port=9090。命令行属性通常优先于文件配置,因此适合验证问题,但不应长期替代正式部署配置。
风险与边界
不要把生产密码、密钥或令牌直接提交到 application-prod.yml。一旦代码仓库、构建产物或镜像泄露,凭据也会同时暴露;安全替代方案是通过环境变量、挂载文件或密钥管理服务注入。
Profile 不只会切换属性,标记了 @Profile("prod") 的 Bean 也会随环境启停。错误激活可能连接真实数据库、消息队列或支付通道,因此上线脚本应固定环境值,并在启动日志和健康检查中验证。
排障清单
先看启动日志是否出现预期 Profile。若日志正确但配置未生效,再检查文件是否被打入 JAR:
jar tf app.jar | grep -E 'application-(dev|test|prod)\.ya?ml'预期输出
BOOT-INF/classes/application-dev.yml
BOOT-INF/classes/application-test.yml
BOOT-INF/classes/application-prod.yml没有输出通常表示文件未放在 src/main/resources、被构建规则排除,或文件名拼写错误。仍有异常时,继续检查 YAML 缩进、外部配置文件覆盖、环境变量残留以及启动脚本中是否重复设置 spring.profiles.active。
兼容性
application-{profile}.yml 和 spring.profiles.active 适用于常见的 Spring Boot 2.x、3.x 项目。Spring Boot 2.4 及以后在多文档 YAML 中可使用 spring.config.activate.on-profile;为减少版本差异,速查场景优先采用独立 Profile 文件。
使用 Value 或 Environment 获取单个配置值。
读取配置属性
读取少量固定配置时使用 @Value,需要按键动态查询或自行处理缺省值时使用 Environment。两者都读取 Spring 的外部化配置;属性较多或具有层级结构时,应改用 @ConfigurationProperties。
完整示例
先在 src/main/resources/application.yml 中定义属性:
app:
region: ap-southeast-1
timeout-seconds: 10
endpoint: https://api.example.com
max-retries: 5下面的启动类可直接放入 Spring Boot 项目。@Value 在 Bean 创建时注入固定键,Environment 在运行时读取键并完成类型转换。
package com.example.configread;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.core.env.Environment;
@SpringBootApplication
public class ConfigReadApplication implements CommandLineRunner {
@Value("${app.region:unknown}")
private String region;
@Value("${app.timeout-seconds:5}")
private int timeoutSeconds;
private final Environment environment;
public ConfigReadApplication(Environment environment) {
this.environment = environment;
}
public static void main(String[] args) {
SpringApplication.run(ConfigReadApplication.class, args);
}
@Override
public void run(String... args) {
// 关键配置缺失时立即失败,避免应用带错误地址继续运行
String endpoint = environment.getRequiredProperty("app.endpoint");
int maxRetries = environment.getProperty(
"app.max-retries", Integer.class, 3);
System.out.println("region=" + region);
System.out.println("timeoutSeconds=" + timeoutSeconds);
System.out.println("endpoint=" + endpoint);
System.out.println("maxRetries=" + maxRetries);
}
}预期输出
region=ap-southeast-1
timeoutSeconds=10
endpoint=https://api.example.com
maxRetries=5日志前后可能还有 Spring Boot 启动信息,读取时只需核对这四行属性值。
常用语法
@Value("${app.region}") 表示必填属性,找不到时通常会导致 Bean 创建失败;@Value("${app.region:unknown}") 使用冒号后的默认值。默认值应只用于允许降级的配置,数据库地址、签名密钥等关键项不应静默回退。
environment.getProperty("app.max-retries", Integer.class, 3) 会按指定类型读取,并在属性不存在时返回默认值;getRequiredProperty("app.endpoint") 在缺失时抛出异常,适合必须在启动阶段校验的配置。
选择方法
| 场景 | 推荐方式 | 原因 |
|---|---|---|
| 注入一两个固定键 | @Value |
写法短,字段使用直接 |
| 根据变量决定查询键 | Environment |
可在运行时决定查询键 |
| 读取当前激活的 Profile | Environment#getActiveProfiles() |
直接访问环境状态 |
| 一组层级配置并需要校验 | @ConfigurationProperties |
类型安全,便于批量绑定和校验 |
@Value 属于通用容器能力,不具备 @ConfigurationProperties 的完整类型安全和批量绑定体验;配置项持续增长时应及时迁移,避免大量散落字符串键。
覆盖与验证
命令行可以临时覆盖示例中的重试次数:
java -jar app.jar --app.max-retries=8预期输出
region=ap-southeast-1
timeoutSeconds=10
endpoint=https://api.example.com
maxRetries=8如果实际输出仍为 5,检查启动的是否为最新 JAR、参数是否写在 JAR 文件名之后,以及是否有脚本吞掉或重写了参数。
风险与排障
出现 Could not resolve placeholder 时,先核对键名、当前 Profile、配置文件路径和 YAML 缩进。Environment#getProperty 默认可能返回 null,若随后自动拆箱或调用方法会触发空指针;安全替代是提供默认值、显式判空,或对关键项使用 getRequiredProperty。
不要打印密码、令牌和私钥来验证配置。生产排障可记录“是否存在”、来源类别或脱敏后的末尾字符;若启用了 Actuator 的 env 端点,还必须限制访问范围并确认敏感值已被脱敏。
兼容性
示例使用的 @Value、Environment 和构造器注入适用于常见 Spring Boot 2.x、3.x 项目。若配置对象包含列表、Map、时间长度或嵌套结构,优先使用 @ConfigurationProperties,不要继续扩展大量 @Value 字段。
使用 ConfigurationProperties 绑定结构化配置。
绑定配置对象
当一组配置具有固定层级或多个字段时,使用 @ConfigurationProperties 一次性绑定为类型安全对象,避免在业务代码中重复读取 @Value。这个方式尤其适合包含 URI、Duration、重试策略等相关字段的配置。
基本写法
在配置类型上声明前缀,并用 @ConfigurationPropertiesScan 自动注册。下面的完整示例把 app.storage 配置绑定到一个 record,应用启动后直接注入该对象。
package com.example.demo;
import java.net.URI;
import java.time.Duration;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
import org.springframework.context.annotation.Bean;
@SpringBootApplication
@ConfigurationPropertiesScan
public class DemoApplication {
@ConfigurationProperties("app.storage")
public record StorageProperties(
URI endpoint,
Duration timeout,
Retry retry) {
// 嵌套 record 对应 app.storage.retry.*,保持配置结构与代码一致。
public record Retry(int maxAttempts, Duration backoff) {}
}
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
@Bean
CommandLineRunner printStorageConfig(StorageProperties properties) {
return args -> System.out.printf(
"endpoint=%s, timeout=%s, retries=%d%n",
properties.endpoint(),
properties.timeout(),
properties.retry().maxAttempts());
}
}预期结果:应用成功启动后输出类似下面的内容,具体启动日志会因 Spring Boot 版本和环境不同而变化。
endpoint=https://storage.example.com, timeout=PT5S, retries=3对应配置文件可以写成:
app:
storage:
endpoint: https://storage.example.com
timeout: 5s
retry:
max-attempts: 3
backoff: 1s预期结果:endpoint 转换为 URI,timeout 和 backoff 转换为 Duration;max-attempts 可以宽松匹配到 maxAttempts。
注册方式
应用代码通常使用 @ConfigurationPropertiesScan 扫描启动类所在包及其子包。如果配置类型不在扫描路径中,可以改用 @EnableConfigurationProperties(StorageProperties.class) 精确注册。两种方式选择一种即可,避免同一个配置类型被重复注册。
风险与边界
绑定对象中包含密码、令牌或私钥时,不要直接打印整个对象。生产环境应只记录非敏感字段,敏感配置优先通过环境变量、密钥管理服务或挂载的 Secret 文件注入。
关键配置不要依赖隐式的 null、0 或 false 默认值。需要强约束时,可在配置类型上结合 @Validated 与 Jakarta Validation 注解,让应用在启动阶段发现非法配置。
高频排障
- 属性为空:检查
app.storage前缀与 YAML 层级是否一致,并确认配置类型已注册。 - 嵌套字段未绑定:检查嵌套类型的构造参数和 YAML 缩进。
- 类型转换失败:优先使用带单位的值,例如
5s、2m、10MB。 - 测试中找不到 Bean:确认测试上下文也注册了对应的
@ConfigurationProperties类型。
Spring Boot 3 中基于构造器的
record配置类型通常不需要额外添加@ConstructorBinding。
通过环境变量覆盖应用配置并避免硬编码。
配置环境变量
环境变量适合覆盖端口、Profile、外部服务地址以及敏感配置,使同一个 JAR 可以在不同环境运行,而不必修改或重新打包应用。
命名规则
Spring Boot 对环境变量使用宽松绑定规则:配置键中的点号转换为下划线,短横线被移除,最后整体转为大写。因此 server.port 对应 SERVER_PORT,spring.profiles.active 对应 SPRING_PROFILES_ACTIVE。
自定义变量如果需要更清晰的命名,可以在配置文件中显式建立映射。例如使用 ${APP_API_BASE_URL:...},让部署脚本直接控制 app.api-base-url。
主示例
在 application.yml 中保留非敏感默认值,并要求生产密钥通过外部变量提供:
server:
port: ${APP_PORT:8080}
spring:
profiles:
active: ${APP_PROFILE:local}
app:
api-base-url: ${APP_API_BASE_URL:https://sandbox.example.com}
api-key: ${APP_API_KEY}启动前设置环境变量。将 <PATH> 替换为 JAR 所在目录,将 <SECRET> 替换为真实密钥:
export APP_JAR="<PATH>/demo.jar"
export APP_PORT=9090
export APP_PROFILE=prod
export APP_API_BASE_URL="https://api.example.com"
export APP_API_KEY="<SECRET>"
java -jar "$APP_JAR"预期输出:应用会使用 prod Profile,并监听 9090 端口;其他启动日志可能因 Spring Boot 版本和部署环境不同而变化。
The following 1 profile is active: "prod"
Tomcat started on port 9090 (http)验证自定义配置时只记录地址、模式等非敏感字段,不要把 APP_API_KEY 打入日志。
覆盖优先级
命令行参数通常可以继续覆盖环境变量。例如同时指定 SERVER_PORT=9090 和 --server.port=9191 时,最终端口为 9191:
export APP_JAR="<PATH>/demo.jar"
SERVER_PORT=9090 java -jar "$APP_JAR" --server.port=9191预期结果:应用最终监听 9191 端口,而不是环境变量中的 9090。
Tomcat started on port 9191 (http)排查变量未生效时,应同时检查实际启动进程收到的环境变量,以及启动参数、容器参数或其他更高优先级配置是否覆盖了它。
风险与边界
环境变量并不是绝对保密存储;同一主机上的进程检查、容器诊断信息或运维平台都可能暴露其内容。数据库密码和访问令牌不要提交到代码仓库、镜像或普通启动脚本中,生产环境优先使用密钥管理服务或只读挂载的 Secret 文件。
也不要把敏感值直接写进 java -jar ... --app.api-key=<SECRET>。命令行参数更容易出现在进程列表或 Shell 历史中。
高频排障
printenv APP_PORT看不到值:确认变量设置在启动应用的同一个 Shell 或服务环境中。- 修改环境变量后没有变化:需要重启 Java 进程,运行中的 Spring Boot 应用不会自动重新读取操作系统环境。
- systemd 配置发生变化:更新
Environment=或EnvironmentFile=后执行systemctl daemon-reload,再重启服务。 - Docker 或 Kubernetes 中:检查变量是否实际注入应用容器,而不是只设置在宿主机。
- 值包含空格、
$等特殊字符:按照对应 Shell 的规则正确引用,避免在启动前被提前展开。
Windows PowerShell 可使用
$env:SERVER_PORT="9090"设置当前会话变量;关闭该终端后,这个临时变量不会继续保留。
在部署时从指定目录或文件加载应用配置。
加载外部配置
用于在不重新打包 JAR 的情况下,从部署目录或指定文件加载并覆盖应用配置。常规部署优先使用 spring.config.additional-location;只有确实要替换默认配置搜索位置时才使用 spring.config.location。
基本语法
java -jar app.jar --spring.config.additional-location=optional:file:/etc/myapp/这里假设已经有可运行的 app.jar。file:/etc/myapp/ 末尾的 / 表示目录;optional: 表示该位置不存在时继续启动。目录中可放置 application.yml、application.properties 或与激活 Profile 对应的配置文件。
高频示例
外部目录提供生产配置,并通过 Profile 读取 application-prod.yml:
# /etc/myapp/application-prod.yml
server:
port: 9090
spring:
datasource:
url: jdbc:mysql://db.example.internal:3306/appjava -jar app.jar --spring.profiles.active=prod --spring.config.additional-location=file:/etc/myapp/预期结果:
Tomcat started on port 9090 (http)
Started <APP> in <TIME> seconds实际应用名和启动耗时会不同;关键验证点是应用以 9090 端口启动,并读取了 prod 对应外部配置。
也可以追加一个明确的配置文件:
java -jar app.jar --spring.config.additional-location=file:/etc/myapp/runtime.yml预期结果:
Started <APP> in <TIME> seconds该文件会作为额外配置位置参与配置数据加载,其中与默认配置重名的属性可能形成覆盖。
关键选项
| 选项 | 作用 | 边界 |
|---|---|---|
spring.config.additional-location |
在默认搜索位置之外追加配置位置 | 默认配置仍参与加载 |
spring.config.location |
指定配置搜索位置 | 会替换默认搜索位置 |
optional: |
配置位置不存在时不因该位置直接失败 | 不适合掩盖本应存在的关键配置 |
spring.profiles.active |
指定当前激活 Profile | 必须与外部 Profile 文件匹配 |
风险与边界
spring.config.location 与 spring.config.additional-location 的语义不同。使用前者可能让 JAR 内默认配置不再参与搜索,进而出现端口、数据源或日志配置缺失;常规部署覆盖场景更适合后者。
未加 optional: 时,目标位置不存在通常会导致启动失败。生产环境若要求关键配置必须存在,应保留失败行为;只有确实允许目录暂时缺失时才使用 optional:。
外部配置可能包含密码、令牌等敏感信息。不要提交到代码仓库,也不要扩大文件读取权限;敏感值更适合由环境变量或密钥管理系统注入。
速查提示:追加部署配置用 spring.config.additional-location,只有需要替换默认搜索位置时才考虑 spring.config.location。
在应用启动阶段检查必填配置和参数范围。
校验配置参数
用于在应用启动阶段校验必填项、数值范围和格式。校验失败时阻止应用继续启动,避免错误配置进入运行期后才暴露。
基本配置
Spring Boot 3.x 使用 jakarta.validation 约束注解,可先加入校验依赖:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>在一个已经创建好的 Maven Spring Boot 项目中执行:
./mvnw dependency:tree -Dincludes=org.springframework.boot:spring-boot-starter-validation预期输出的关键行:
org.springframework.boot:spring-boot-starter-validation:jar:<VERSION>:compile主示例
配置属性类使用 @ConfigurationProperties 绑定配置,并在类上使用 @Validated 开启校验。下面是需要放入现有 Spring Boot 项目的片段示例。
package com.example.demo.config;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;
@Validated
@ConfigurationProperties(prefix = "app.payment")
public class PaymentProperties {
@NotBlank
private String merchantNo;
@Min(1)
@Max(60)
private int timeoutSeconds = 10;
public String getMerchantNo() {
return merchantNo;
}
public void setMerchantNo(String merchantNo) {
this.merchantNo = merchantNo;
}
public int getTimeoutSeconds() {
return timeoutSeconds;
}
public void setTimeoutSeconds(int timeoutSeconds) {
this.timeoutSeconds = timeoutSeconds;
}
}片段示例依赖该配置属性类已经注册为 Spring Bean,例如在启动类使用 @EnableConfigurationProperties(PaymentProperties.class)。配置文件使用短横线形式即可完成绑定:
app:
payment:
merchant-no: M10001
timeout-seconds: 15预期结果:
Started DemoApplication in <TIME> seconds将 timeout-seconds 改为 0 后重新启动应用:
app:
payment:
merchant-no: M10001
timeout-seconds: 0预期输出的关键片段:
Binding to target ... failed
Field error in object 'app.payment' on field 'timeoutSeconds': rejected value [0]
must be greater than or equal to 1具体异常类名和日志格式可能因 Spring Boot 小版本不同而变化,但应用应启动失败,并指出属性路径、错误值或约束原因。
常用约束
@NotNull:值不能为null,但空字符串仍可能通过。@NotBlank:字符串不能为null、空串或纯空白。@Min、@Max:限制数值下限和上限。@Pattern:按正则约束字符串格式。- 嵌套配置对象需要在对应字段上添加
@Valid,才能继续校验内部约束。
风险与边界
只添加约束注解而没有 @Validated,配置绑定可以成功但不会按这些约束执行启动校验。因此需要在承担启动校验职责的 @ConfigurationProperties 类上显式启用 @Validated。
基本类型 int 缺失时可能得到默认值 0,这会把“未配置”和“明确配置为零”混在一起。若两者必须区分,可改用 Integer 并配合 @NotNull。
错误日志可能包含被拒绝的配置值。密码、令牌等敏感配置不要依赖详细绑定日志输出明文,必要时减少日志详细程度并避免把敏感字段直接打印出来。
排障清单
- 约束完全不生效:检查校验依赖、
@Validated以及配置属性注册方式。 - 属性没有绑定:检查
prefix、YAML 层级和属性命名。 - 嵌套对象未校验:检查父字段是否添加
@Valid。 - 发现默认值掩盖缺失配置:检查是否误用了基本类型,而不是可空包装类型。
速查提示:@ConfigurationProperties 负责绑定,@Validated 启用启动校验,具体失败条件由约束注解决定。
使用组件扫描或 Bean 方法将对象交给容器管理。
注册 Spring Bean
需要让对象参与依赖注入、生命周期回调、AOP 或配置管理时,先把它注册到 Spring 容器。项目自己维护的业务类优先使用组件扫描;第三方类或需要自定义创建过程的对象使用 @Bean。
基本语法
组件扫描适合项目内的业务类,常用注解包括 @Component、@Service、@Repository 和 @Controller。@SpringBootApplication 默认从启动类所在包向下扫描组件。
@Bean 通常写在 @Configuration 类中,方法返回值成为容器管理的 Bean;默认情况下,方法名就是 Bean 名称。
高频用法
下面只保留一个主示例,同时验证组件扫描和 @Bean 两种注册方式。示例中的类分别保存到注释标明的文件中。
// src/main/java/com/example/demo/DemoApplication.java
package com.example.demo;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
@Bean
CommandLineRunner verifyBeanRegistration(
ScanRegisteredService scanRegisteredService,
ManualRegisteredClient manualRegisteredClient) {
return args -> System.out.println(
scanRegisteredService.source() + " | " + manualRegisteredClient.source());
}
}
// src/main/java/com/example/demo/ScanRegisteredService.java
package com.example.demo;
import org.springframework.stereotype.Service;
@Service
public class ScanRegisteredService {
public String source() {
return "component-scan";
}
}
// src/main/java/com/example/demo/ManualBeanConfig.java
package com.example.demo;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class ManualBeanConfig {
@Bean
ManualRegisteredClient manualRegisteredClient() {
// 这里适合集中处理第三方客户端的构造参数与初始化逻辑。
return new ManualRegisteredClient("bean-method");
}
}
// src/main/java/com/example/demo/ManualRegisteredClient.java
package com.example.demo;
public class ManualRegisteredClient {
private final String source;
public ManualRegisteredClient(String source) {
this.source = source;
}
public String source() {
return source;
}
}预期输出
component-scan | bean-method读取方法:出现该行,说明扫描注册的 ScanRegisteredService 和 @Bean 注册的 ManualRegisteredClient 都已经由 Spring 创建并成功注入到 CommandLineRunner。
选择方式
- 项目内无特殊构造逻辑的业务类:使用
@Service、@Repository等语义化注解。 - 第三方库对象、需要选择具体实现、需要读取配置后创建的客户端:使用
@Bean。 - 同一类型需要多个实例时:为 Bean 设置稳定名称,并在注入处使用
@Qualifier;也可以用@Primary指定默认候选。
风险与边界
启动类包层级过深,或组件位于默认扫描范围之外时,Bean 不会被发现,依赖它的组件可能启动失败。通常把启动类放在项目根包;确需跨包时再显式配置 scanBasePackages。
同一类型存在多个候选 Bean,而注入点没有进一步限定时,会触发 NoUniqueBeanDefinitionException。不要依赖类名碰巧匹配,应使用 @Primary 或 @Qualifier 明确选择。
通过普通 new 创建的对象不会自动获得 Spring 的依赖注入、生命周期管理或基于容器代理的 AOP 能力。需要这些能力时,应让 Spring 创建对象,或把创建逻辑放进 @Bean。
排障清单
- 确认类是否带组件注解,或配置方法是否带
@Bean。 - 确认包路径位于组件扫描范围内。
- 检查
@Profile、@ConditionalOnProperty等条件是否导致 Bean 未注册。 - 启动时可增加
--debug查看条件评估报告;仍不明确时检查ApplicationContext#getBeanDefinitionNames()。
速查提示:能用语义化组件注解就优先使用组件扫描;构造过程需要控制或对象来自第三方库时,再使用 @Bean。
使用构造器注入声明组件依赖。
注入 Bean
组件需要调用另一个组件时,优先通过构造器声明依赖。构造器注入让必需依赖在对象创建时一次性就绪,也便于单元测试直接传入替身对象。
基本语法
类只有一个构造器时,Spring Framework 会自动使用它进行依赖注入,无需额外标注 @Autowired。依赖字段通常声明为 final,避免实例创建后被替换。
如果一个类存在多个构造器,需要明确告诉 Spring 使用哪一个构造器,例如在目标构造器上添加 @Autowired。
高频用法
下面的 OrderFacade 通过构造器依赖 PaymentService。应用启动时,Spring 先准备 PaymentService,再创建 OrderFacade 并把依赖传入构造器。
// src/main/java/com/example/demo/DemoApplication.java
package com.example.demo;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
@Bean
CommandLineRunner verifyInjection(OrderFacade orderFacade) {
return args -> System.out.println(orderFacade.submit("ORDER-1001"));
}
}
// src/main/java/com/example/demo/PaymentService.java
package com.example.demo;
import org.springframework.stereotype.Service;
@Service
public class PaymentService {
public String pay(String orderNo) {
return "paid:" + orderNo;
}
}
// src/main/java/com/example/demo/OrderFacade.java
package com.example.demo;
import org.springframework.stereotype.Service;
@Service
public class OrderFacade {
private final PaymentService paymentService;
public OrderFacade(PaymentService paymentService) {
// 必需依赖在实例创建阶段完成注入。
this.paymentService = paymentService;
}
public String submit(String orderNo) {
return paymentService.pay(orderNo);
}
}预期输出
paid:ORDER-1001读取方法:出现该行,说明 OrderFacade 已成功创建,且其构造器参数 PaymentService 已由 Spring 注入。
多实现选择
同一接口存在多个实现时,需要在注入点进一步限定候选。常见方式是给某个 Bean 加 @Primary 作为默认实现,或在构造器参数上使用 @Qualifier 指定具体 Bean 名称。
public OrderFacade(@Qualifier("onlinePaymentService") PaymentService paymentService) {
this.paymentService = paymentService;
}这是片段示例,依赖上下文中存在名为 onlinePaymentService 的 Bean;项目代码还需要导入对应的 @Qualifier。启动后没有 NoUniqueBeanDefinitionException,即可说明候选冲突已被消除。
风险与边界
字段注入会隐藏必需依赖,而且普通 new 创建对象时不会由 Spring 自动填充这些字段。更稳妥的方式是使用构造器注入,让依赖成为对象创建契约。
两个组件互相通过构造器依赖会形成循环依赖,应用通常在启动阶段失败。不要把开启循环依赖作为长期方案,更合适的处理是抽取共同职责、调整调用方向,或改为事件通知。
构造器参数过多通常意味着类承担了过多职责。不要把大量服务集中注入一个“万能类”,应按业务能力拆分协作对象。
排障清单
NoSuchBeanDefinitionException:检查依赖类型是否已注册、包是否被扫描、条件注解是否生效。NoUniqueBeanDefinitionException:检查是否有多个候选 Bean,并使用@Qualifier或@Primary。BeanCurrentlyInCreationException:检查构造器依赖链是否形成循环。- 测试中依赖为空:确认是否绕过 Spring 直接
new了对象;构造器注入可以直接传入 mock 或 fake。
速查提示:必需依赖优先使用单一构造器和 final 字段;多实现要显式选择,循环依赖应从设计上消除。
使用 Primary 或 Qualifier 解决多实现注入问题。
选择同类型 Bean
当容器中存在多个相同接口的实现时,使用 @Primary 指定默认实现,使用 @Qualifier 精确选择某个 Bean,避免启动时出现注入歧义。
选择规则
@Primary 适合为某个类型设置默认实现。注入点只声明类型时,Spring 会优先选择带有 @Primary 的候选 Bean。@Qualifier 用于在注入点进一步指定目标;当限定条件匹配时,可以避免多个候选之间的歧义。
| 注入方式 | 适用场景 | 选择结果 |
|---|---|---|
| 仅按类型注入 | 大多数调用方使用同一默认实现 | 选择 @Primary Bean |
@Qualifier("beanName") |
当前调用方需要特定实现 | 选择指定名称的 Bean |
| 容器中只有一个实现 | 无需额外标记 | 直接注入唯一 Bean |
可运行示例
以下示例注册邮件和短信两个 Notifier,默认按类型注入邮件实现,同时通过 @Qualifier 精确获取短信实现。
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Primary;
@SpringBootApplication
public class BeanSelectionApplication {
public static void main(String[] args) {
SpringApplication.run(BeanSelectionApplication.class, args);
}
interface Notifier {
String send(String message);
}
@Bean
@Primary
Notifier emailNotifier() {
return message -> "email:" + message;
}
@Bean
Notifier smsNotifier() {
return message -> "sms:" + message;
}
@Bean
CommandLineRunner demo(
Notifier defaultNotifier,
@Qualifier("smsNotifier") Notifier smsNotifier) {
return args -> {
System.out.println(defaultNotifier.send("order-paid"));
System.out.println(smsNotifier.send("order-paid"));
};
}
}预期输出:第一行来自 @Primary 指定的默认实现,第二行来自 @Qualifier("smsNotifier") 指定的 Bean。
email:order-paid
sms:order-paid常用写法
在组件类上,可以把 @Primary 与 @Component、@Service 等组件注解一起使用;在配置类中,也可以直接标记 @Bean 方法。需要为某个注入点指定实现时,可在构造器参数上使用 @Qualifier。
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Service;
@Service
class OrderService {
private final Notifier notifier;
OrderService(@Qualifier("smsNotifier") Notifier notifier) {
this.notifier = notifier;
}
}该代码是片段示例,依赖前述 Notifier 接口和名为 smsNotifier 的 Bean。应用启动成功且 OrderService 创建成功,说明限定注入已生效。
风险与排障
同时存在多个同类型 Bean,且没有唯一候选、有效的 @Primary 或合适的 @Qualifier 时,应用可能因 NoUniqueBeanDefinitionException 启动失败。通常让通用实现成为默认候选,再在特殊调用点使用 @Qualifier。
同一类型存在多个 @Primary 时仍然不能确定唯一候选,因此不要把 @Primary 当作普通分类标签使用。
@Qualifier 指定的值与实际 Bean 名称或限定信息不匹配时,通常会导致依赖无法解析。排查时先确认 Bean 名称、限定值以及组件扫描范围。
重构 @Bean 方法名可能改变默认 Bean 名称。需要稳定名称时,可以显式声明 @Bean("smsNotifier");复杂项目还可以使用自定义限定注解,减少对方法名的耦合。
根据配置、类或环境条件决定是否注册组件。
按条件创建 Bean
使用 Spring Boot 条件注解,根据配置值、类路径、现有 Bean 或运行环境决定是否注册组件,常用于功能开关、可选依赖和可替换的默认实现。
常用条件注解
| 注解 | 条件满足时注册 | 常见用途 |
|---|---|---|
@ConditionalOnProperty |
配置项满足指定条件 | 功能开关、实现切换 |
@ConditionalOnClass |
类路径中存在指定类 | 可选依赖集成 |
@ConditionalOnMissingBean |
容器中不存在指定 Bean | 提供可被业务覆盖的默认实现 |
@ConditionalOnBean |
容器中已存在指定 Bean | 在基础组件之上注册扩展组件 |
@Profile |
指定 Profile 已激活 | 区分开发、测试和生产环境 |
Boot 条件注解位于 org.springframework.boot.autoconfigure.condition 包中;@Profile 属于 Spring Framework。
按配置选择实现
以下示例根据 app.notice.type 注册邮件或短信通知器。配置为 sms 时注册短信实现;缺少该配置时通过 matchIfMissing=true 让邮件实现作为默认分支。
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
@SpringBootApplication
public class ConditionalBeanApplication {
public static void main(String[] args) {
SpringApplication.run(ConditionalBeanApplication.class, args);
}
interface Notifier {
String type();
}
@Bean
@ConditionalOnProperty(
prefix = "app.notice",
name = "type",
havingValue = "sms")
Notifier smsNotifier() {
return () -> "sms";
}
@Bean
@ConditionalOnProperty(
prefix = "app.notice",
name = "type",
havingValue = "email",
matchIfMissing = true)
Notifier emailNotifier() {
return () -> "email";
}
@Bean
CommandLineRunner verify(Notifier notifier) {
return args -> System.out.println("notifier=" + notifier.type());
}
}将配置设置为短信模式:
app:
notice:
type: sms预期输出:sms 条件成立,邮件条件不成立,因此容器中的 Notifier 为 smsNotifier。
notifier=sms删除 app.notice.type 后,emailNotifier 的 matchIfMissing=true 生效。
notifier=email关键参数
prefix 与 name 会组合为完整属性名,例如 prefix="app.notice"、name="type" 对应 app.notice.type。havingValue 用于匹配指定属性值,不满足条件时对应 Bean 不会注册。
matchIfMissing=true 表示配置项不存在时条件也成立,适合明确需要默认分支的场景。对于默认关闭的高风险功能,不应仅依赖缺省配置来启用。
其他高频用法
可选依赖集成通常使用 @ConditionalOnClass。只有目标类存在于类路径时,相关配置才会参与注册,从而避免在依赖缺失时创建不完整组件。
自动配置提供默认实现时,常使用 @ConditionalOnMissingBean。业务项目声明自己的同类型 Bean 后,默认 Bean 不再创建,从而保留覆盖能力。
环境级差异可以使用 @Profile("dev") 或 @Profile("prod")。单个功能开关通常更适合 @ConditionalOnProperty,避免为少量开关创建过多 Profile。
风险与排障
多个条件可能同时成立,导致相同接口注册多个 Bean,随后出现 NoUniqueBeanDefinitionException。条件设计应尽量互斥;无法互斥时,再配合 @Primary 或 @Qualifier 明确注入目标。
所有条件都不成立时,依赖该类型的组件会因缺少 Bean 而启动失败。需要可选依赖时,可以改用 ObjectProvider<Notifier>,由调用方处理 Bean 缺失的情况。
误用 matchIfMissing=true 可能在配置中心未加载或属性名写错时意外启用默认分支。涉及外部调用、数据修改或收费能力时,更适合默认关闭并显式配置启用值。
条件未按预期生效时,可使用 --debug 启动应用查看条件评估报告:
java -jar app.jar --debug预期结果:启动日志中出现 CONDITIONS EVALUATION REPORT,其中可以查看已匹配和未匹配的条件及其原因。
============================
CONDITIONS EVALUATION REPORT
============================
Positive matches:
-----------------
Negative matches:
-----------------实际报告会包含应用中的条件类和匹配原因;生产排障完成后应关闭调试输出,避免长期产生大量自动配置明细。
推迟非关键组件的创建以缩短启动过程。
延迟初始化 Bean
当启动阶段存在大量暂时不会使用的组件时,可让 Bean 在首次被请求时再创建。这样可以缩短启动过程,但会把部分初始化耗时和异常推迟到首次访问。
全局启用
在 application.yml 中开启全局延迟初始化:
spring:
main:
lazy-initialization: true启动应用:
java -jar app.jar预期输出:
Started Application in <TIME> seconds实际启动耗时取决于项目;开启延迟初始化后,部分 Bean 不再在启动阶段创建。框架启动必需的组件仍可能提前创建,其他 Bean 会在首次获取时执行构造方法、依赖注入和初始化回调。
按 Bean 启用
只想推迟少量非关键组件时,可使用 @Lazy。下面示例适用于已有 Spring Boot Web 项目:服务自身标记为延迟 Bean,同时在构造器注入点使用 @Lazy,避免控制器创建时立即解析真实对象。
package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Lazy;
import org.springframework.stereotype.Service;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
@Lazy
@Service
class ReportService {
ReportService() {
System.out.println("ReportService initialized");
}
String generate() {
return "report-ready";
}
}
@RestController
class ReportController {
private final ReportService reportService;
ReportController(@Lazy ReportService reportService) {
this.reportService = reportService;
}
@GetMapping("/report")
String report() {
return reportService.generate();
}
}预期结果:应用启动阶段不会因为 ReportController 的注入而主动创建 ReportService;首次请求 /report 时才触发初始化。
curl http://localhost:<PORT>/report预期输出:
ReportService initialized
report-ready实际端口可能不同,以应用配置为准。
风险与边界
全局延迟初始化只改变创建时机,不会减少 Bean 数量。配置错误、缺失依赖、连接失败等问题可能被推迟到运行期,线上首个请求也可能因此变慢或失败。
延迟 Bean 的首次创建可能发生在并发请求中。Spring 会保证单例 Bean 只创建一次,但其他请求可能等待初始化完成,因此不要在构造方法或 @PostConstruct 中执行长时间网络调用。
生产环境通常优先对报表、低频适配器、非核心缓存等组件局部使用 @Lazy;关键链路仍应在启动期完成必要校验。
排障清单
- 启动时间没有下降:检查耗时是否主要来自数据库迁移、配置中心、Web 容器或其他非 Bean 初始化。
- Bean 仍在启动时创建:检查是否被非延迟单例直接注入、被启动任务调用,或被框架提前使用。
- 首次请求明显变慢:取消关键 Bean 的延迟,或在接入流量前主动预热。
- 初始化异常延后暴露:对关键依赖增加启动期检查,不要依赖全局延迟初始化掩盖配置问题。
速查:生产环境优先局部 @Lazy;全局开关适合评估启动收益,不应替代启动期健康检查。
在应用启动完成后执行初始化或检查逻辑。
执行启动任务
需要在 Spring 容器初始化后执行数据预热、配置检查或一次性初始化时,可使用 CommandLineRunner、ApplicationRunner 或监听 ApplicationReadyEvent。选择哪一种,主要看参数形式和任务需要等待到哪个启动阶段。
使用 CommandLineRunner
CommandLineRunner 接收原始字符串参数,适合不需要专门解析启动参数的简单任务。下面示例可直接放入已有 Spring Boot 项目:
package com.example.demo;
import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;
@Component
public class CacheWarmupRunner implements CommandLineRunner {
@Override
public void run(String... args) {
System.out.println("cache warmup completed");
}
}预期结果:应用启动过程中执行 run,并输出:
cache warmup completedCommandLineRunner 的执行发生在 ApplicationReadyEvent 发布之前;因此它适合必须在应用被报告为就绪前完成的初始化任务。
使用 ApplicationRunner
ApplicationRunner 会把 --name、--name=value 等选项参数解析为 ApplicationArguments,适合根据启动标记决定是否执行任务。
package com.example.demo;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.stereotype.Component;
@Component
public class ImportRunner implements ApplicationRunner {
@Override
public void run(ApplicationArguments args) {
boolean enabled = args.containsOption("import");
System.out.println("import enabled: " + enabled);
}
}启动命令:
java -jar app.jar --import预期输出:
import enabled: true选项参数必须以 -- 开头;普通位置参数可通过 getNonOptionArgs() 读取。
等待应用完全就绪
任务必须等所有 Runner 执行完成后再运行时,可监听 ApplicationReadyEvent。它适合最终检查、预热完成通知或注册就绪状态。
package com.example.demo;
import org.springframework.boot.context.event.ApplicationReadyEvent;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;
@Component
public class ReadyCheck {
@EventListener(ApplicationReadyEvent.class)
public void verify() {
System.out.println("application is ready");
}
}预期结果:只有在 Spring Boot 完成启动流程并执行完启动 Runner 后,才会出现:
application is ready执行顺序
存在多个 Runner 时,使用 @Order 或实现 Ordered 明确顺序,数值越小越先执行。不要依赖 Bean 扫描顺序。多个任务存在强依赖时,优先用一个编排器统一安排执行顺序并集中处理失败。
风险与排障
启动任务默认同步执行。外部服务超时、无限重试或大批量处理都会延长启动时间,甚至让容器编排平台判定启动失败。只有启动前必须完成的检查才适合放在同步启动路径;非必需工作应考虑消息队列、调度系统或受控线程池。
- Runner 没有执行:确认类位于组件扫描范围内,且没有被 Profile 或条件注解排除。
- 参数读取不到:
ApplicationRunner的选项参数使用--name或--name=value;位置参数使用getNonOptionArgs()。 - 多个任务顺序不稳定:添加
@Order,不要依赖类名或声明顺序。 - 应用启动失败:检查 Runner 是否抛出未处理异常,以及外部依赖是否超时。
速查:原始参数用 CommandLineRunner,结构化参数用 ApplicationRunner,必须等启动 Runner 全部完成后再执行时用 ApplicationReadyEvent。
使用控制器和请求映射公开 HTTP 接口。
创建 REST 接口
用于在 Spring Boot 应用中公开 HTTP 地址,并把 Java 返回值自动序列化为 JSON。最常见组合是 @RestController、类级 @RequestMapping 和方法级 @GetMapping。
基本语法
项目需已引入 spring-boot-starter-web。下面把启动入口和控制器放在同一个类中,可直接保存为 src/main/java/com/example/demo/DemoApplication.java。
package com.example.demo;
import java.util.Map;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
@RestController
@RequestMapping("/api")
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
// 返回对象会由 Spring MVC 自动转换为 JSON。
@GetMapping("/health")
public Map<String, String> health() {
return Map.of("status", "UP");
}
}@RestController 等价于 @Controller 加 @ResponseBody;类级路径与方法级路径拼接后,最终地址为 /api/health。
高频用法
启动应用:
mvn spring-boot:run预期输出会包含以下关键行,日志时间和版本可能不同:
Tomcat started on port 8080 (http)
Started DemoApplication调用接口:
curl -i http://localhost:8080/api/health预期输出:
HTTP/1.1 200
Content-Type: application/json
{"status":"UP"}读取时先确认状态码为 200,再检查响应体中的 status。若项目配置了 server.port=<PORT>,请求地址中的端口也要同步修改。
常用映射
@GetMapping 用于查询,@PostMapping 用于创建,@PutMapping 用于整体更新,@PatchMapping 用于局部更新,@DeleteMapping 用于删除。多个接口有共同前缀时,把前缀放到类级 @RequestMapping,避免每个方法重复书写。
风险与边界
控制器直接返回实体对象时,可能把密码、内部状态或审计字段一并序列化。触发条件是实体新增字段后接口自动暴露;后果是数据泄露和接口结构失控。安全做法是返回专用 DTO,并只保留对外字段。
不要在控制器中执行长事务或阻塞调用。慢 SQL、远程超时或大文件处理会占满 Web 线程;应把业务放入服务层,并为外部调用设置连接和读取超时。
排障清单
出现 404 时,确认启动类包路径覆盖控制器、请求方法与映射一致,并检查是否配置了 server.servlet.context-path。出现 406 或响应不是 JSON 时,确认已引入 Web Starter,且返回对象可被 Jackson 序列化。
从 URL 路径中读取资源标识或业务参数。
接收路径参数
用于从 URL 路径中读取资源标识,例如 /api/users/42 中的 42。Spring MVC 使用 @PathVariable 将占位符绑定到方法参数,并可自动完成基础类型转换。
基本语法
下面示例可直接保存为 src/main/java/com/example/demo/DemoApplication.java,运行后提供用户查询接口。
package com.example.demo;
import java.util.Map;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
@RestController
@RequestMapping("/api/users")
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
// 显式写出变量名,避免参数名编译信息缺失时绑定失败。
@GetMapping("/{userId}")
public Map<String, Object> getUser(@PathVariable("userId") long userId) {
return Map.of("userId", userId, "name", "demo-user");
}
}路径模板中的 {userId} 必须与 @PathVariable("userId") 一致。参数声明为 long 后,Spring 会把数字文本转换为整数。
高频用法
启动后请求指定用户:
curl -i http://localhost:8080/api/users/42预期输出:
HTTP/1.1 200
Content-Type: application/json
{"userId":42,"name":"demo-user"}读取时确认响应中的 userId 与 URL 一致。实际字段顺序可能不同,不应依赖 JSON 属性顺序。
测试类型转换失败:
curl -i http://localhost:8080/api/users/abc预期结果为 400 Bad Request;默认错误响应字段会随 Spring Boot 版本和错误配置变化,因此应以 HTTP 状态码为主要判断依据。
HTTP/1.1 400常用写法
一个路径可包含多个参数,例如 /orders/{orderId}/items/{itemId},方法中分别声明两个 @PathVariable。参数可使用 String、long、UUID、枚举等可转换类型;业务不存在通常应由服务层返回 404,而不是返回空对象和 200。
风险与边界
不要把令牌、手机号、证件号等敏感数据放入路径。路径通常会进入网关、代理、浏览器历史和访问日志,容易扩大泄露范围;敏感凭据应放在授权头中,敏感查询条件按接口设计放入请求体。
路径参数默认只匹配单个 / 分隔段。业务值本身包含斜杠时,直接拼接可能导致路由不匹配或被代理拒绝;优先改用查询参数、请求体或安全编码后的稳定标识,不要依赖放宽服务器对编码斜杠的限制。
排障清单
出现 404 时,检查 URL 是否缺少路径段、类级和方法级映射是否正确拼接。出现 400 时,检查参数类型是否可转换。启动时报路径变量名称无法解析时,显式填写 @PathVariable("userId"),不要只依赖 Java 参数名保留配置。