Java 后端 / 知识点
Spring Boot 开发速查手册
手册条目
使用 JUnit 和 Mockito 测试独立业务组件。
编写单元测试
用于测试不依赖 Spring 容器的业务组件。JUnit 负责组织测试和断言,Mockito 隔离数据库、远程接口等外部依赖,重点验证正常分支、异常分支以及依赖调用。
基本依赖
Spring Boot 项目通常引入测试启动器即可获得 JUnit Jupiter、Mockito 和 AssertJ。测试依赖限定为 test,避免进入生产运行时。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>预期结果
依赖解析成功,测试代码可使用 JUnit Jupiter、Mockito 和 AssertJ。主示例
服务负责校验用户名、规范化输入、阻止重复注册并返回新用户 ID。仓储属于边界依赖,单元测试只模拟它,不启动 Spring、数据库或网络。
package com.example.user;
import java.util.Locale;
public class UserService {
private final UserRepository repository;
public UserService(UserRepository repository) {
this.repository = repository;
}
public long register(String rawName) {
if (rawName == null || rawName.isBlank()) {
throw new IllegalArgumentException("name must not be blank");
}
String name = rawName.trim().toLowerCase(Locale.ROOT);
if (repository.existsByName(name)) {
throw new IllegalStateException("name already exists");
}
return repository.save(name);
}
public interface UserRepository {
boolean existsByName(String name);
long save(String name);
}
}测试覆盖成功注册和重复名称两个核心行为,并检查重复名称时不会继续保存。
package com.example.user;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
@ExtendWith(MockitoExtension.class)
class UserServiceTest {
@Mock
private UserService.UserRepository repository;
@Test
void shouldNormalizeAndSaveName() {
when(repository.existsByName("alice")).thenReturn(false);
when(repository.save("alice")).thenReturn(1001L);
UserService service = new UserService(repository);
long userId = service.register(" Alice ");
assertThat(userId).isEqualTo(1001L);
verify(repository).existsByName("alice");
verify(repository).save("alice");
}
@Test
void shouldRejectDuplicateNameWithoutSaving() {
when(repository.existsByName("alice")).thenReturn(true);
UserService service = new UserService(repository);
assertThatThrownBy(() -> service.register("alice"))
.isInstanceOf(IllegalStateException.class)
.hasMessage("name already exists");
verify(repository).existsByName("alice");
verify(repository, never()).save("alice");
}
}执行指定测试:
./mvnw -Dtest=UserServiceTest test预期输出
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS编写原则
每个测试只表达一个业务行为,通常按“准备数据、执行方法、验证结果”组织。返回值和异常使用断言校验;是否调用仓储、调用参数和调用次数使用 verify。
只模拟真正的边界依赖,例如 Repository、HTTP 客户端、消息发送器或时钟。实体、集合和字符串等简单对象直接创建,避免测试本身被 Mock 配置主导。
风险与边界
过度模拟会让测试在 SQL、序列化、事务或框架配置出错时仍然通过。此时应补充切片测试或集成测试,而不是继续增加 Mock。
宽泛使用 any()、lenient(),或者只断言“不抛异常”,容易掩盖错误参数。优先匹配关键实参,并同时验证返回值、异常类型和必要副作用。
排障清单
NullPointerException:确认使用了@ExtendWith(MockitoExtension.class),或者在测试初始化阶段正确创建 Mockito Mock。UnnecessaryStubbingException:删除当前用例没有实际消费的when,不要用宽松模式掩盖多余 Stub。Wanted but not invoked:检查被测对象是否持有同一个 Mock,以及测试是否真正进入预期分支。- 测试偶发失败:排查当前时间、随机数、线程调度和静态全局状态,优先注入
Clock、ID 生成器或可控执行器。
使用 MockMvc 测试接口状态、响应和参数校验。
编写控制器测试
使用 MockMvc 在不启动真实 HTTP 端口的情况下验证 Spring MVC 控制器,包括请求反序列化、参数校验、HTTP 状态和 JSON 响应。对于只关注 Web 层行为的测试,standaloneSetup 可以避免加载数据库等无关组件。
前置依赖
示例使用 Spring Web、Bean Validation 和 Spring Boot 测试启动器。校验依赖由 spring-boot-starter-validation 提供。
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</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-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>预期结果
测试工程可以使用 MockMvc、JUnit Jupiter、Mockito、Jackson 和 Bean Validation。控制器与异常响应
控制器接收创建用户请求并返回 201。请求对象上的校验注解在进入方法前执行,异常处理器将校验失败转换成 400 响应。
package com.example.user;
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.util.Map;
import static org.springframework.http.HttpStatus.CREATED;
@RestController
@RequestMapping("/users")
public class UserController {
private final UserApplicationService service;
public UserController(UserApplicationService service) {
this.service = service;
}
@PostMapping
ResponseEntity<UserResponse> create(@Valid @RequestBody CreateUserRequest request) {
return ResponseEntity.status(CREATED)
.body(service.create(request.name()));
}
public interface UserApplicationService {
UserResponse create(String name);
}
public record CreateUserRequest(
@NotBlank(message = "name must not be blank")
@Size(max = 20, message = "name length must be <= 20")
String name) {
}
public record UserResponse(long id, String name) {
}
}
@RestControllerAdvice
class ApiExceptionHandler {
@ExceptionHandler(MethodArgumentNotValidException.class)
ResponseEntity<Map<String, String>> handleValidation(MethodArgumentNotValidException ex) {
String message = ex.getBindingResult()
.getFieldError()
.getDefaultMessage();
return ResponseEntity.badRequest().body(Map.of("message", message));
}
}预期结果
有效请求返回 201 和用户 JSON;name 为空时返回 400,并包含 message 字段。MockMvc 主示例
测试只装配当前控制器、异常处理器和校验器,同时用 Mockito 隔离应用服务。这样既能验证 MVC 层契约,又不会依赖真实数据库或网络。
package com.example.user;
import com.example.user.UserController.UserApplicationService;
import com.example.user.UserController.UserResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.validation.beanvalidation.LocalValidatorFactoryBean;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.verifyNoInteractions;
import static org.mockito.Mockito.when;
import static org.springframework.http.MediaType.APPLICATION_JSON;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import static org.springframework.test.web.servlet.setup.MockMvcBuilders.standaloneSetup;
@ExtendWith(MockitoExtension.class)
class UserControllerTest {
@Mock
private UserApplicationService service;
private MockMvc mockMvc;
private final ObjectMapper objectMapper = new ObjectMapper();
@BeforeEach
void setUp() {
LocalValidatorFactoryBean validator = new LocalValidatorFactoryBean();
validator.afterPropertiesSet();
mockMvc = standaloneSetup(new UserController(service))
.setControllerAdvice(new ApiExceptionHandler())
.setValidator(validator)
.build();
}
@Test
void shouldCreateUser() throws Exception {
when(service.create("alice"))
.thenReturn(new UserResponse(1001L, "alice"));
mockMvc.perform(post("/users")
.contentType(APPLICATION_JSON)
.content(objectMapper.writeValueAsString(
new UserController.CreateUserRequest("alice"))))
.andExpect(status().isCreated())
.andExpect(content().contentTypeCompatibleWith(APPLICATION_JSON))
.andExpect(jsonPath("$.id").value(1001))
.andExpect(jsonPath("$.name").value("alice"));
verify(service).create("alice");
}
@Test
void shouldRejectBlankName() throws Exception {
mockMvc.perform(post("/users")
.contentType(APPLICATION_JSON)
.content("{\"name\":\"\"}"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.message")
.value("name must not be blank"));
verifyNoInteractions(service);
}
}执行指定测试:
./mvnw -Dtest=UserControllerTest test预期输出
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS高频断言
接口测试至少验证状态码、响应类型和关键 JSON 字段。创建接口还应确认业务服务收到正确参数;校验失败时可使用 verifyNoInteractions 验证请求没有进入业务层。
查询参数可使用 .param("name", "alice"),请求头可使用 .header("X-Trace-Id", "<ID>")。其中 <ID> 只是测试占位值,实际用例可以替换为固定字符串。
风险与边界
standaloneSetup 不会自动加载完整 Spring MVC 环境,因此过滤器、安全配置、自定义转换器等可能与真实应用不同。若接口依赖这些组件,应补充 @WebMvcTest 或完整集成测试,避免单元测试通过而真实请求失败。
不要只断言 2xx。对外接口应固定验证核心响应契约和主要错误响应,同时避免断言时间戳、随机 ID 等动态字段的精确值。
排障清单
- 返回 415:确认使用
.contentType(APPLICATION_JSON),且请求正文是合法 JSON。 - 返回 400 且没有进入控制器:检查 JSON 字段类型、
@Valid和校验注解。 jsonPath不匹配:先检查实际响应结构,统一响应包装可能使路径变成$.data.id。- 实际项目出现 401 或 403:说明安全链路不属于当前独立装配范围,应补充 Spring Security 测试支持,而不是删除安全配置。
加载完整应用上下文验证组件协作和真实配置。
编写集成测试
当你需要确认 Spring Boot 应用能否正确启动,并验证多个组件、自动配置和 Web 调用能够协同时,使用集成测试。本文用 @SpringBootTest 加载完整上下文,并用 MockMvc 验证请求链路。
使用时机
改动涉及多个 Bean、配置绑定、事务、序列化、过滤器或数据库访问时,集成测试比单元测试更能发现装配和运行期问题。若只验证单个 Controller、Repository 或 JSON 转换,应优先考虑测试切片,避免无必要地启动完整应用上下文。
基本写法
下面的示例把最小应用配置和 Controller 放在测试类中,便于独立运行。项目需已有 spring-boot-starter-web 和 spring-boot-starter-test。
package com.example.demo;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.SpringBootConfiguration;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.annotation.Import;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@SpringBootTest(classes = HealthIntegrationTest.TestApp.class)
@AutoConfigureMockMvc
class HealthIntegrationTest {
@Autowired
MockMvc mockMvc;
@Test
void returnsApplicationHealth() throws Exception {
// MockMvc 走 Spring MVC 请求链路,但不监听真实 TCP 端口。
mockMvc.perform(get("/health"))
.andExpect(status().isOk())
.andExpect(content().string("UP"));
}
@SpringBootConfiguration
@EnableAutoConfiguration
@Import(HealthController.class)
static class TestApp {
}
@RestController
static class HealthController {
@GetMapping("/health")
String health() {
return "UP";
}
}
}预期结果:测试上下文成功启动,GET /health 返回 HTTP 200,响应体为 UP。随后执行指定测试:
./mvnw -Dtest=HealthIntegrationTest test预期结果:Maven 测试任务成功结束,失败数和错误数均为 0;具体 Surefire 日志格式会随 Maven 和插件版本变化。
常用选择
@SpringBootTest 默认使用模拟 Web 环境,配合 @AutoConfigureMockMvc 可以验证 MVC 请求链路,但不会启动真实服务器。需要验证真实端口、HTTP 客户端、压缩或容器行为时,可改用 webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT;非 Web 应用则可使用 WebEnvironment.NONE。
测试配置建议放在 src/test,用 @ActiveProfiles("test") 或测试属性隔离外部地址、密钥和消息消费开关。测试框架会缓存可复用的应用上下文;频繁切换 Profile、属性,或滥用 @DirtiesContext,都会降低复用率。
风险与排障
不要让集成测试直接连接生产地址,也不要在测试中无意开启定时任务、消息消费或真实第三方调用。优先使用独立测试 Profile,并替换不可控的外部客户端;数据库和中间件应指向隔离环境或 Testcontainers。
测试方法使用 @Transactional 时,测试线程中的事务通常会在测试结束后回滚。但 RANDOM_PORT 通过真实 HTTP 调用服务器时,请求在另一线程执行,服务端事务不会加入测试线程的事务,因此不能依赖测试方法上的回滚清理服务端数据。
上下文启动失败时,先定位最底层 Caused by,再检查缺失 Bean、配置占位符、端口占用和外部连接。仅为绕过失败而不断增加 Mock,会削弱集成测试对真实装配和协作问题的发现能力。
通过 Testcontainers 启动临时数据库或中间件。
使用测试容器
当集成测试必须验证真实 PostgreSQL、Redis 等基础设施行为时,使用 Testcontainers 为测试进程提供一次性的隔离容器。这样可以验证更接近生产的协议、SQL 和事务语义,同时避免依赖开发机上的共享服务。
使用时机
Testcontainers 适合仓储层、数据库迁移、消息中间件等集成测试,不应替代纯单元测试。由于容器启动需要额外时间,建议把这类测试集中到集成测试阶段,并避免依赖固定宿主端口。
基本配置
Spring Boot 3.1+ 可以使用 spring-boot-testcontainers 与 @ServiceConnection 自动把容器连接信息提供给应用。以下为 Maven 依赖示例,项目应使用 Spring Boot 的依赖管理,并包含 PostgreSQL JDBC 驱动。
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-testcontainers</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>junit-jupiter</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>postgresql</artifactId>
<scope>test</scope>
</dependency>
</dependencies>@ServiceConnection 会根据容器类型生成测试期连接信息,因此通常不需要把随机端口写进 application-test.yml。项目若不能使用该注解,可改用 @DynamicPropertySource 显式注册 JDBC URL、用户名和密码。
主示例
下面的测试启动 PostgreSQL 容器,并通过 Spring 注入的 JdbcTemplate 执行真实 SQL。静态容器由 @Container 管理,在当前测试类生命周期内复用。
package com.example.demo;
import static org.assertj.core.api.Assertions.assertThat;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.jdbc.core.JdbcTemplate;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
@SpringBootTest
@Testcontainers
class PostgresContainerTest {
// 使用静态容器,避免同一测试类的每个方法重复启动数据库。
@Container
@ServiceConnection
static PostgreSQLContainer<?> postgres =
new PostgreSQLContainer<>("postgres:16-alpine");
@Autowired
JdbcTemplate jdbcTemplate;
@Test
void connectsToRealPostgres() {
Integer value = jdbcTemplate.queryForObject("select 1", Integer.class);
assertThat(value).isEqualTo(1);
}
}运行指定测试:
./mvnw -Dtest=PostgresContainerTest test预期结果:测试成功结束,断言 select 1 返回 1,Maven 构建状态为成功;容器 ID、随机映射端口、启动耗时和具体日志会因环境而异。
风险与边界
首次运行通常需要拉取镜像,宿主机还必须提供 Testcontainers 可访问的容器运行时。不要依赖固定宿主端口或跨测试共享脏数据,测试数据应由测试自行创建和清理。
测试启动失败时,优先检查容器运行时是否可用、镜像是否能拉取,以及 @ServiceConnection 与 Spring Boot 版本是否匹配。测试不应把临时容器当作持久化环境,也不要把本机已有数据库的状态作为断言前提。
开放健康检查、指标和应用信息端点。
启用 Actuator
用于给 Spring Boot 应用开放健康检查、指标和应用信息端点。生产环境应只暴露明确需要的端点,并通过认证或内网限制访问。
添加依赖
在 Maven 项目中加入 Actuator Starter,版本由 Spring Boot 的依赖管理统一控制。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>这是依赖片段,需放入项目的 pom.xml 后重新构建应用。添加依赖后,Actuator 默认基础路径为 /actuator;仅添加依赖时,HTTP 暴露范围仍受默认端点暴露策略控制,非健康端点通常需要显式暴露。
开放常用端点
下面配置开放 health、info 和 metrics,同时启用环境信息贡献者,让 info.* 信息参与 /actuator/info 输出。
management:
endpoints:
web:
exposure:
include: health,info,metrics
endpoint:
health:
show-details: never
info:
env:
enabled: true
info:
app:
name: order-service
version: 1.0.0生效后可访问:
| 地址 | 用途 |
|---|---|
/actuator/health |
查看应用总体健康状态 |
/actuator/info |
查看配置的应用信息 |
/actuator/metrics |
列出可查询的指标名称 |
/actuator/metrics/jvm.memory.used |
查询指定 JVM 指标 |
验证
应用启动后执行:
curl -i "http://127.0.0.1:<PORT>/actuator/health"预期输出:
HTTP/1.1 200
Content-Type: application/vnd.spring-boot.actuator.v3+json
{"status":"UP"}实际响应的 Content-Type 可能随 Spring Boot 版本或内容协商略有不同;如果配置了 server.port、management.server.port 或自定义管理端点基础路径,应按实际配置调整请求地址。
风险与边界
不要在公网直接使用 include: "*"。未经筛选地开放全部端点可能暴露环境、配置、线程或堆转储等敏感信息;生产环境更适合使用端点白名单、独立管理端口、网络访问控制和 Spring Security 鉴权。
不要将 show-details 设为 always 后直接公开。健康组件的详细信息可能包含数据库、磁盘或依赖异常;需要排障时可使用 when-authorized,并限制运维角色访问。
独立设置 management.server.port 只提供端口隔离,不等于自动完成安全控制,仍需结合防火墙、网关或认证策略。
常见排障
- 返回
404:确认 Actuator 依赖已加入、目标端点已在management.endpoints.web.exposure.include中暴露,并检查management.endpoints.web.base-path。 - 返回
401或403:检查 Spring Security 的SecurityFilterChain、访问角色以及网关鉴权规则。 /actuator/info内容为空:确认已配置info.*,并启用需要的 InfoContributor,例如management.info.env.enabled=true。/actuator/metrics可访问但缺少某类指标:确认对应组件或 Micrometer Registry 已加入类路径,并检查management.metrics.enable.*是否禁用。
检查数据库、缓存和外部依赖的运行状态。
配置健康检查
需要让应用、编排平台或运维系统判断数据库、缓存和外部服务是否可用时,使用 Spring Boot Actuator 的健康端点。数据库和 Redis 在对应组件已配置时可自动注册健康贡献者;业务外部依赖则应补充自定义 HealthIndicator。
前置配置
先加入 Actuator,并只暴露需要的健康端点。以下为 Maven 依赖片段。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>这是配置片段,放入项目 pom.xml 后重新构建应用即可生效。为数据库、Redis 和外部服务建立单独健康组,便于编排平台只检查关键依赖。示例假设应用中已经存在名为 db、redis 和 partnerApi 的健康贡献者。
management:
endpoints:
web:
exposure:
include: health
endpoint:
health:
group:
dependencies:
include: db,redis,partnerApi
show-details: never生效行为:/actuator/health/dependencies 会聚合该健康组中的贡献者状态。项目没有 Redis 或某个贡献者名称不同,应从 include 中删除或改为实际 ID,避免引用不存在的成员。
外部依赖检查
Spring Boot 不会自动知道业务外部 API 的健康语义。下面的 HealthIndicator 使用 JDK HTTP 客户端设置 2 秒连接与请求超时;只有 HTTP 2xx 才返回 UP。
package com.example.demo.health;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.actuate.health.Health;
import org.springframework.boot.actuate.health.HealthIndicator;
import org.springframework.stereotype.Component;
@Component("partnerApi")
public class PartnerApiHealthIndicator implements HealthIndicator {
// 控制探针调用最长等待时间,避免依赖故障放大线程阻塞。
private final HttpClient client = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(2))
.build();
private final URI healthUri;
public PartnerApiHealthIndicator(
@Value("${partner.base-url}") String baseUrl) {
this.healthUri = URI.create(baseUrl + "/health");
}
@Override
public Health health() {
HttpRequest request = HttpRequest.newBuilder(healthUri)
.timeout(Duration.ofSeconds(2))
.GET()
.build();
try {
HttpResponse<Void> response = client.send(
request, HttpResponse.BodyHandlers.discarding());
int status = response.statusCode();
// 只把 2xx 视为依赖成功,其余状态进入 DOWN。
return status >= 200 && status < 300
? Health.up().build()
: Health.down().withDetail("httpStatus", status).build();
} catch (InterruptedException ex) {
Thread.currentThread().interrupt();
return Health.down(ex).build();
} catch (IOException | IllegalArgumentException ex) {
return Health.down(ex).build();
}
}
}这是片段示例,依赖已引入 Actuator、Spring Context,并要求配置 partner.base-url。例如:
partner:
base-url: http://127.0.0.1:9090生效行为:健康检查会请求 http://127.0.0.1:9090/health;实际地址应按环境配置,不要把认证密钥直接放进 URL。
验证
应用启动且 db、redis、partnerApi 均健康后执行:
curl -s "http://127.0.0.1:<PORT>/actuator/health/dependencies"预期结果:
{"status":"UP"}当健康组中任一贡献者为 DOWN 时,聚合状态也会反映该故障。实际端口若不是 8080,使用应用实际管理端口替换 <PORT>;若开启了认证,则还需要按安全配置提供凭据。
风险与边界
健康检查应快速、只读并设置严格超时。不要在探针中执行大查询、写操作或长链路调用,否则故障时可能进一步放大压力。
生产环境通常不要把 show-details 设为 always,以免把数据库、缓存或异常细节暴露给无权限调用者;需要排障时优先通过受认证的运维端点查看详细信息。
通过 Micrometer 输出 JVM、HTTP 和业务指标。
暴露应用指标
当需要从运行中的 Spring Boot 应用查看 JVM、HTTP 请求和业务计数时,使用 Actuator 接入 Micrometer,并只暴露必要的管理端点。内置 JVM 与 Web 指标可自动采集,业务指标通过 MeterRegistry 注册。
依赖与暴露范围
下面的依赖片段适用于已使用 Spring Boot 依赖管理的 Web 应用。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>在 application.yml 中只开放诊断需要的端点:
management:
endpoints:
web:
exposure:
include: "health,metrics"metrics 端点用于查看当前 MeterRegistry 中已注册的指标;生产环境不要一次性暴露所有 Actuator 端点。
注册业务指标
将下面的控制器放入已有的 Spring MVC 应用,用一个 Counter 统计成功创建订单数。
import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class OrderMetricsController {
private final Counter createdOrders;
public OrderMetricsController(MeterRegistry registry) {
// 指标在初始化阶段注册,业务请求只负责更新数值。
this.createdOrders = Counter.builder("orders.created")
.description("已创建订单数")
.register(registry);
}
@PostMapping("/demo/order")
public String createOrder() {
// 真实项目只应在订单确认创建成功后递增。
createdOrders.increment();
return "ok";
}
}指标名应保持稳定且低基数。不要把订单 ID、用户 ID、完整 URL 等高基数字段直接作为 tag,否则会快速放大时序数量和内存开销。
验证指标
应用启动后,用 curl 调用一次示例接口,再检查指标名称和 Counter。下面假设应用监听 8080 端口,并且本机已安装 curl 与 jq。
curl -s -X POST http://localhost:8080/demo/order; echo
curl -s http://localhost:8080/actuator/metrics | jq -r '.names | map(select(. == "http.server.requests" or . == "jvm.memory.used" or . == "orders.created")) | sort[]'
curl -s http://localhost:8080/actuator/metrics/orders.created | jq -r '.name, .measurements[0].statistic, (.measurements[0].value | tostring)'预期输出:
ok
http.server.requests
jvm.memory.used
orders.created
orders.created
COUNT
<VALUE><VALUE> 是当前进程累计的计数;如果应用刚启动且只调用一次示例接口,通常为 1。http.server.requests 是否出现取决于实际使用的 Web 技术与自动观测是否生效,可先访问一次业务接口再确认。
风险与边界
/actuator/metrics 更适合诊断,不应直接替代生产时序存储。需要 Prometheus 抓取时,应增加对应的 Micrometer Registry,并开放专用的 prometheus 端点;无论使用哪种后端,都应限制管理端点的网络可达范围并配置认证。
速查:Actuator 负责暴露管理端点,Micrometer 负责指标抽象,业务代码只注册并更新真正需要观测的低基数指标。
生成包含依赖并可直接运行的应用程序包。
打包可执行 JAR
用于把 Spring Boot 应用及其运行依赖打进一个可直接执行的 JAR。构建完成后,部署端通常只需要匹配的 JDK、JAR 和外部配置,不必再手工拼接 classpath。
Maven 配置
在 pom.xml 中启用 Spring Boot Maven Plugin。使用项目现有的 Spring Boot 依赖管理提供插件版本,在 package 阶段执行 repackage:
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>主启动类需要包含 public static void main,并使用 @SpringBootApplication:
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);
}
}构建与验证产物
优先使用 Maven Wrapper,避免依赖机器上的 Maven 版本:
./mvnw clean package预期输出:
[INFO] Replacing main artifact <ARTIFACT>.jar with repackaged archive
[INFO] BUILD SUCCESS构建成功后,通常可在 target/ 中看到重打包后的 JAR。文件名由项目的 artifactId 和 version 决定,实际值可能不同。
ls -lh target/*.jar预期输出:
-rw-r--r-- 1 <USER> <GROUP> <SIZE> <TIME> target/demo-0.0.1-SNAPSHOT.jar若同时出现 .jar.original,它是重打包前的普通 JAR,部署时应使用不带 .original 的文件。检查最终产物时,还可以确认包内包含 BOOT-INF/classes 和 BOOT-INF/lib。
运行与验证
以下命令假设最终产物名为 target/demo-0.0.1-SNAPSHOT.jar,实际项目应替换为真实文件名。
java -jar target/demo-0.0.1-SNAPSHOT.jar --server.port=8081预期输出:
<TIME> INFO <PID> --- [main] com.example.demo.DemoApplication : Started DemoApplication in <SECONDS> seconds看到 Started DemoApplication 表示应用完成启动。另开终端验证健康端点;该检查要求项目已加入 Actuator 并暴露 health。
curl -i http://localhost:8081/actuator/health预期输出:
HTTP/1.1 200
Content-Type: application/vnd.spring-boot.actuator.v3+json
{"status":"UP"}常用构建选项
-DskipTests:编译测试代码但跳过执行,适合前置流水线已经完成测试的场景。-Dmaven.test.skip=true:连测试编译也跳过,速度更快,但会遗漏测试源码编译问题。--spring.profiles.active=prod:运行时选择 Profile;它属于java -jar的应用参数,不是 Maven 打包参数。
使用跳过测试参数时,得到的只是“未在本次构建中执行测试”的制品。生产构建更适合先执行完整测试,再对经过验证的制品进行后续封装或发布。
风险与排障
构建 JDK 与运行 JDK 不兼容时,启动可能出现 UnsupportedClassVersionError。应统一编译和运行环境,或通过 Maven Toolchains、容器镜像固定 JDK。
不要把密钥和生产密码直接写入 application.yml 再封装进 JAR;打包后仍可解压读取。应改用环境变量、外部配置文件或密钥管理服务。
no main manifest attribute:通常运行了普通 JAR,检查插件是否执行repackage,并改用重打包后的 JAR。Unable to access jarfile:检查当前目录、文件名和读取权限。Address already in use:端口已被占用,修改server.port或停止冲突进程。- 启动后立即退出:优先查看异常栈中的
Caused by,重点检查配置、数据库连接和 Profile。
速查:可执行 JAR 应能通过 java -jar 启动,并且最终包内包含应用类与运行依赖。
使用 Dockerfile 或 Buildpacks 构建应用镜像。
构建 Docker 镜像
将 Spring Boot 可执行 JAR 打包为可部署镜像。需要精确控制基础镜像、用户和启动参数时使用 Dockerfile;希望减少镜像脚本维护并利用分层缓存时使用 Buildpacks。
Dockerfile 构建
先生成可执行 JAR。下面以 Maven 项目和 Java 21 为例,项目实际 Java 版本必须与运行时镜像匹配。
./mvnw clean package -DskipTests预期输出
[INFO] BUILD SUCCESS在项目根目录创建 Dockerfile:
FROM eclipse-temurin:21-jre
WORKDIR /app
# 使用非 root 用户,降低容器逃逸后的权限风险
RUN useradd --system --uid 10001 spring
COPY target/*.jar /app/app.jar
USER 10001
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app/app.jar"]构建镜像:
docker build -t demo-service:1.0.0 .预期输出
[+] Building <TIME> FINISHED
=> exporting to image
=> naming to docker.io/library/demo-service:1.0.0<TIME> 会随机器性能和缓存状态变化。若项目生成多个 JAR,应把 COPY target/*.jar 改为确定文件名,避免复制到错误产物。
Buildpacks 构建
Spring Boot Maven 插件可直接调用 Cloud Native Buildpacks,不需要维护 Dockerfile,但本机仍需可用的 Docker 守护进程。
./mvnw spring-boot:build-image -Dspring-boot.build-image.imageName=demo-service:1.0.0预期输出
Successfully built image 'docker.io/library/demo-service:1.0.0'Buildpacks 会按应用内容生成 OCI 镜像并复用依赖层。Gradle 项目使用 bootBuildImage 任务,镜像名应在构建脚本或任务参数中显式设置。
启动与验证
后台启动容器并检查运行状态:
docker run -d --name demo-service -p 8080:8080 demo-service:1.0.0
docker ps --filter name=demo-service --format '{{.Names}}\t{{.Status}}\t{{.Ports}}'预期输出
demo-service Up <TIME> 0.0.0.0:8080->8080/tcp端口应与应用的 server.port 一致。若容器立即退出,先执行 docker logs demo-service,重点检查 Java 版本、配置文件、数据库连接和端口绑定错误。
风险与边界
- 将密码、证书或访问令牌写入 Dockerfile、构建参数或镜像层,会导致凭据随镜像永久留存。改用运行时环境变量、只读挂载或容器平台 Secret。
- 使用
latest或未固定版本的基础镜像,重新构建时可能得到不同运行环境。生产镜像使用明确版本,关键场景固定镜像摘要并定期重建修复漏洞。 - 以 root 用户运行时,应用漏洞的影响范围更大。优先使用非 root 用户,并确认日志、临时目录和挂载目录具有写权限。
- 仅在 x86 主机构建的镜像可能无法运行于 ARM 节点。多架构部署使用
docker buildx或选择支持目标架构的 Buildpacks builder。
排障清单
Cannot connect to the Docker daemon:确认 Docker 已启动,当前用户具有访问套接字的权限。no main manifest attribute:确认产物经过 Spring Boot Maven/Gradle 插件重新打包,而不是普通 JAR。exec format error:检查镜像架构是否与运行节点一致。- 镜像体积异常:检查是否把源码、测试结果或整个构建目录复制进镜像,并配置
.dockerignore排除无关文件。
速查:Dockerfile 适合强控制,Buildpacks 适合标准化;两种方式都应使用非 root 用户、不可变版本标签和运行时 Secret。
停止接收新请求并等待正在执行的任务完成。
配置优雅停机
当应用收到正常终止信号时,优雅停机会先进入关闭流程,让已经进入服务器的请求在限定时间内完成,再结束进程。显式配置停机模式和超时时间,可以避免部署环境依赖隐含默认值。
基本配置
在 application.yml 中明确开启优雅停机,并为每个生命周期停止阶段设置上限:
server:
shutdown: graceful
spring:
lifecycle:
timeout-per-shutdown-phase: 30sserver.shutdown 决定 Web 服务器采用优雅还是立即停机;spring.lifecycle.timeout-per-shutdown-phase 是停止阶段的时间预算,不是某个 HTTP 请求的单独超时。实际拒绝新请求的方式取决于所使用的嵌入式服务器。
停机时序

部署平台还应先把实例从入口流量中摘除,再发送终止信号;这样可以减少负载均衡器继续把新请求路由到正在关闭的实例。
本地验证
片段示例:下面的控制器只用于制造一个 5 秒在途请求,依赖已有的 Spring MVC 应用,不应作为生产接口保留。
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class SlowController {
@GetMapping("/demo/slow")
public String slow() throws InterruptedException {
// 让请求跨过 SIGTERM 时刻,便于观察是否等待在途请求。
Thread.sleep(5000);
return "done";
}
}先启动应用并取得实际 Java 进程 PID,再把 <PID> 替换为该值执行:
curl -s http://localhost:8080/demo/slow > /tmp/graceful.out &
REQUEST_PID=$!
sleep 1
kill -TERM <PID>
wait "$REQUEST_PID"
cat /tmp/graceful.out
while kill -0 <PID> 2>/dev/null; do sleep 0.2; done
echo app-exited预期输出
done
app-exited看到 done 说明终止信号到达后,在途请求仍有机会完成;随后出现 app-exited 说明应用最终退出。IDE 的停止按钮可能不会发送标准 SIGTERM,因此优先用操作系统信号或实际部署平台验证。
风险与恢复
超时时间过短会截断慢请求或仍在停止的生命周期组件,过长则会拖慢发布和扩缩容。若停机长期卡住,应先定位未结束的请求、线程或 SmartLifecycle 组件,再调整时间预算;紧急回退为立即停机会牺牲在途请求,只应作为明确接受该后果的兜底方案。
定位端口冲突、Bean 创建失败和配置缺失问题。
排查应用启动失败
应用启动失败时,先从完整启动日志判断故障属于端口、Bean 创建还是配置加载,再只处理最靠近根因的一条链路。不要只看最上层的 ApplicationContextException,它通常只是包装异常。
排查入口
在包含 Maven Wrapper 的项目中先保留完整日志,并开启 Spring Boot 的调试报告;调试报告适合本地或受控环境,生产环境不要长期启用。
set -o pipefail
./mvnw spring-boot:run -Dspring-boot.run.arguments=--debug 2>&1 | tee boot-startup.log预期结果:启动成功时进程继续运行;启动失败时命令以非零状态结束,boot-startup.log 保留完整异常链和条件评估信息,具体类名、时间与路径会因项目而异。
APPLICATION FAILED TO START
...
Caused by: <VALUE>按根因分流
先找靠近异常末尾、且第一次明确指向端口、项目代码或配置键的 Caused by,再进入对应分支。

- 端口冲突:日志出现端口已被占用时,先确认占用者,不要直接结束未知进程。
- Bean 创建失败:沿
BeanCreationException或UnsatisfiedDependencyException的 cause 链向下看,优先处理第一个指向项目类、构造方法或初始化逻辑的异常。 - 配置缺失:出现占位符无法解析或配置绑定失败时,核对当前激活的 Profile、环境变量名、配置文件是否被加载,以及键名和目标类型是否一致。
主示例:确认端口冲突
假设失败日志明确指出 8080 被占用,可先只查询监听进程 PID。
lsof -t -iTCP:8080 -sTCP:LISTEN预期输出:端口被占用时输出一个或多个监听进程 PID;无输出表示当前没有匹配的监听进程。PID 会因机器而异。
<PID>确认进程确实可以停止后再正常终止,或在本地临时改用其他端口。不要把 kill -9 当作默认方案,它会跳过应用自己的优雅关闭逻辑。
验证与边界
每次只改一个变量,然后重新启动并确认原异常消失;若异常变化,继续从新的最内层有效 cause 排查。配置问题修复后还要确认实际启用的 Profile 与预期一致,Bean 问题则应补充最小上下文启动测试,避免只在本机“碰巧能启动”。
检查组件扫描、候选 Bean 和循环依赖问题。
排查 Bean 注入失败
Bean 注入失败的核心是先确认“目标类型是否进入容器、候选数量是否唯一、依赖图是否形成闭环”。按异常类型分流,比反复添加注解更快,也能避免把结构性问题掩盖成临时可启动。
先判断失败类型
常见注入失败可分成三类:没有候选 Bean、候选 Bean 过多、循环依赖。@SpringBootApplication 默认从启动类所在包向下扫描,因此组件放在包树之外、配置类未被导入,或 @Profile、条件装配未满足,都可能导致“没有候选”。

- 0 个候选:检查包结构、
@Component/@Service/@Repository、@Bean所在配置类,以及 Profile 和条件注解。 - 多个候选:需要明确业务选择。局部选择优先用
@Qualifier;确实存在全局默认实现时再考虑@Primary。 - 循环依赖:构造器依赖形成
A -> B -> A时,应调整职责边界,而不是先放宽容器限制。
主示例:显式选择候选 Bean
下面示例定义两个同类型 Bean,并在注入点用 @Qualifier 指定需要的实现。文件放在 src/main/java/com/example/demo/DemoApplication.java,项目需已包含 Spring Boot 基础依赖。
package com.example.demo;
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;
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
// 同一接口故意注册两个候选,模拟常见的多实现注入场景。
@Bean
PaymentClient stripeClient() {
return () -> "stripe";
}
@Bean
PaymentClient paypalClient() {
return () -> "paypal";
}
// 在注入点明确业务语义,避免容器仅按类型面对多个候选。
@Bean
CommandLineRunner verify(@Qualifier("stripeClient") PaymentClient client) {
return args -> System.out.println(client.name());
}
interface PaymentClient {
String name();
}
}运行应用:
./mvnw spring-boot:run预期结果:应用上下文能够完成创建,并在框架日志之外打印以下业务输出;启动时间等动态日志会因环境不同而变化。
stripe如果去掉 @Qualifier("stripeClient"),同一注入点会面对两个 PaymentClient 候选,容器无法仅按类型确定唯一对象。
组件扫描与条件装配
若异常表示完全找不到 Bean,先确认实现类是否位于启动类包或其子包。对确需跨包扫描的模块,应显式组织扫描边界或导入配置类,而不是把扫描范围扩大到过宽的顶层包。
同时检查 @Profile、@ConditionalOnProperty 等条件是否在当前环境满足。候选 Bean “代码存在”不等于“本次启动一定注册”,排查时要以实际容器条件为准。
循环依赖与恢复
构造器循环依赖通常说明职责耦合过紧。优先抽取第三个服务、调整调用方向,或改为事件等单向协作;@Lazy 只能延迟解析,适合少数确有懒加载语义的场景,不应作为通用修复。
检查配置优先级、Profile 和属性名称是否正确。
排查配置未生效
配置“写了却没生效”时,先确认应用实际读取的是哪组配置,再检查同名属性是否被更高优先级来源覆盖。推荐按“属性名 → Profile → 配置位置 → 外部覆盖 → Bean 条件”顺序排查。
排查顺序
- 核对属性名、层级和前缀。YAML 缩进错误、
@ConfigurationProperties前缀不一致,都可能让绑定结果看起来像“配置未生效”。 - 确认实际激活的 Profile。
application-dev.yml只有在dev被激活时才参与对应配置加载;不要仅凭文件存在判断它已经生效。 - 检查配置文件是否位于 Spring Boot 会搜索的位置,文件名是否为
application.properties、application.yml或对应的 Profile 变体。 - 检查命令行参数、环境变量、系统属性等外部来源。同名外部配置可能覆盖文件中的值,因此“文件内容正确”不代表最终值就是它。
- 若问题只发生在某个配置类,再确认该类是否被扫描、注册,以及相关条件注解是否成立。
主验证示例
假设打包产物为 app.jar,用命令行显式指定 Profile 和端口启动。命令行参数可作为临时的高优先级覆盖,用来快速判断问题出在配置文件/Profile,还是应用本身。
java -jar app.jar --spring.profiles.active=dev --server.port=18080预期输出:
<TIME> INFO ... The following 1 profile is active: "dev"
<TIME> INFO ... Tomcat started on port 18080 (http) ...实际日志格式会随 Spring Boot 和 Web 容器版本变化;重点是确认 dev 已激活且应用监听 18080 端口。
定位覆盖来源
如果显式参数能生效,而文件中的同名配置不能生效,优先检查启动脚本、容器环境变量和部署平台注入项。例如环境变量 SERVER_PORT 可按 Spring Boot 的宽松绑定规则对应到 server.port,从而覆盖配置文件中的端口值。
风险与恢复
命令行参数适合诊断,不宜长期当作修复方案。验证完成后移除临时的 --spring.profiles.active、--server.port 等覆盖项,从正确的配置文件或部署环境恢复配置,再重新启动确认最终值。
检查请求路径、上下文路径和控制器扫描范围。
排查接口返回 404
Spring Boot 接口返回 404 时,先确认请求是否已经到达正确应用,再把“上下文路径 + 控制器路径 + 方法路径”逐段对齐。若应用直连正常、经过代理后才 404,则重点检查网关或反向代理的路径改写。
核对最终请求路径
最终路径可能由上下文路径、控制器级路径和方法级路径共同组成。例如上下文为 /app、控制器前缀为 /api、方法路径为 /health,实际请求地址就是 /app/api/health。
假设应用确实配置了 /app 上下文,并注册了 GET /api/health,可以直接比较两个地址:
curl -o /dev/null -s -w '%{http_code}\n' http://localhost:8080/api/health
curl -o /dev/null -s -w '%{http_code}\n' http://localhost:8080/app/api/health预期输出:
404
200端口、上下文路径和接口路径应按实际项目替换。若第二个请求仍返回 404,应继续检查 Handler 是否注册,而不是反复尝试路径组合。
检查映射是否注册
确认 @RequestMapping、@GetMapping、@PostMapping 等注解声明的路径与请求一致,同时核对 HTTP 方法和媒体类型约束。同一路径存在但方法不匹配通常会得到 405;consumes 或 produces 不匹配则可能得到 415 或 406。这些状态码可以帮助缩小排查范围。
若项目已经启用并暴露 Spring Boot Actuator 的 mappings 端点,可用它核对实际注册的 Handler;否则查看启动日志或直接检查控制器映射声明,不要凭记忆拼接路径。
检查控制器扫描范围
@SpringBootApplication 默认从启动类所在包向下进行组件扫描。控制器若位于启动类包的平级包或更高层级,可能根本没有注册到 Spring MVC。
更稳妥的结构是把启动类放在项目根包;确有需要时再显式配置 scanBasePackages。不要为了修复单个 404 无限制扩大扫描范围,否则可能意外注册原本不应进入当前应用上下文的组件。
区分应用与代理层 404
如果本地直连应用端口正常,而经过 Nginx、Ingress 或 API Gateway 后才返回 404,重点检查路径重写、前缀剥离和路由规则。先验证应用直连地址,再逐层加入代理,可以确定 404 究竟产生在哪一层。
检查参数绑定、数据格式和请求体校验错误。
排查接口返回 400
接口返回 400 Bad Request 时,先判断请求是在进入 Controller 前就因 JSON 解析、类型转换或参数校验失败,还是被业务层主动拒绝。排查目标是定位失败阶段,并把错误对应到具体参数。
快速定位
先用 curl 直接复现,保留响应头和响应体,确认请求方法、路径、Content-Type 和实际发送的数据。
curl -i -X POST "http://localhost:<PORT>/api/users" -H "Content-Type: application/json" -d '{"name":"Alice","age":"not-a-number"}'预期输出
HTTP/1.1 400
Content-Type: application/json
...响应体格式取决于项目的异常处理器;重点查看状态码、错误消息、字段名和 traceId。若请求没有进入 Controller,优先检查 JSON 解析、类型转换和参数绑定。
高频原因
常见原因主要有以下几类:
- 请求体不是合法 JSON,或字段类型与 DTO 不一致,常见异常包括
HttpMessageNotReadableException。 - 查询参数或路径参数无法完成类型转换,例如把
abc绑定到Long,常见异常包括MethodArgumentTypeMismatchException。 - DTO 使用
@Valid或@Validated,字段违反@NotBlank、@Min等约束,常见异常为MethodArgumentNotValidException。 Content-Type与参数接收方式不匹配,例如接口使用@RequestBody,客户端却发送表单数据。- 参数名不一致或缺少必填参数,常见异常包括
MissingServletRequestParameterException。
对照检查
接口接收 JSON 请求体时,客户端应发送 application/json,并让字段名、JSON 层级和数据类型与 DTO 对齐。下面的代码用于说明典型绑定方式,实际项目还需要已有的 Spring Boot Web 与 Bean Validation 上下文。
@PostMapping("/api/users")
public UserRequest create(@Valid @RequestBody UserRequest request) {
return request;
}
public record UserRequest(
@NotBlank String name,
@Min(0) int age
) {}片段示例:age 无法转换为整数,或校验约束不满足时,Spring 会在进入方法体前处理请求并通常返回 400。
验证请求
curl -i -X POST "http://localhost:<PORT>/api/users" -H "Content-Type: application/json" -d '{"name":"Alice","age":18}'预期输出
HTTP/1.1 200
Content-Type: application/json
...
{"name":"Alice","age":18}实际端口、响应头和 JSON 字段顺序可能不同。
日志与异常映射
无法判断失败发生在哪一层时,可在测试环境临时提高 Web 与消息转换相关日志级别,复现一次后立即恢复。
logging:
level:
org.springframework.web: DEBUG
org.springframework.http.converter: DEBUG配置生效后重新发送同一请求,按请求时间或 traceId 查找最早出现的绑定异常。不要只看统一异常处理器最终返回的最后一行,因为真正原因可能已经被包装。
风险与恢复
生产环境长期开启 DEBUG 可能产生大量框架日志,并增加敏感信息暴露和磁盘增长风险。更稳妥的做法是缩小到相关包、限制复现窗口,并结合 traceId 定向检索。
不要为了消除 400 而放宽 DTO 类型或移除校验注解,这只会把输入错误推迟到业务层。应先修正客户端请求;确有兼容需求时,再增加明确的转换规则和可读的错误响应。
速查:400 先查“请求能否被解析并绑定”,再查校验与业务处理;最有价值的证据通常是原始请求和最早出现的 Spring 异常。
检查认证信息、令牌有效性和安全过滤链。
排查接口返回 401
接口返回 401 Unauthorized 时,优先排查“身份是否成功认证”,而不是角色或资源权限。目标是确认凭证是否到达服务、是否通过校验,以及请求是否进入预期的 Spring Security 认证链。
先确认认证请求
先绕过前端封装,用同一地址和认证信息直接请求接口。这样可以快速区分前端没有发送凭证、网关丢失请求头,还是后端认证失败。
BASE_URL="http://localhost:<PORT>"
TOKEN="<VALUE>"
curl -sS -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer ${TOKEN}" "${BASE_URL}/api/orders"预期输出
401这里假定 <VALUE> 是无效、过期或当前服务无法接受的令牌;实际端口和令牌值按环境替换。若有效令牌也稳定返回 401,继续检查认证链;若只有前端请求失败,则重点比较前端实际发送的 Authorization 请求头。
按认证链逐项检查
先确认请求头确实存在,格式与服务端认证方式匹配。例如 Bearer Token 通常使用 Authorization: Bearer <token>,不要漏掉方案名,也不要额外套引号。
然后检查令牌是否过期,以及签名算法、签名密钥或公钥是否与签发端一致。JWT 场景还应核对服务实际验证的 issuer、audience 等声明;配置不一致也会导致认证失败。
如果应用存在多条 SecurityFilterChain,检查 securityMatcher 和链顺序,确认目标请求没有落入另一套认证规则。自定义认证过滤器则要确认它能读取凭证、构造认证结果,并继续执行过滤链,而不是吞掉认证异常。
若认证位于网关或反向代理之后,还要确认代理没有移除 Authorization 请求头,并明确是网关完成认证后传递身份,还是下游 Spring Security 自己完成认证。不要假设两层的职责相同。
临时观察 Spring Security
无法判断请求在哪一步失去认证状态时,可以在测试环境临时提高安全日志级别:
logging.level.org.springframework.security=DEBUG配置生效后重新请求接口,重点观察请求匹配了哪条安全链、认证处理是否成功,以及最终是否进入认证入口点。排查结束后恢复原日志级别,避免长期产生大量安全调试日志。
验证修复
修复后至少用一组有效令牌和一组无效令牌分别验证认证边界。有效令牌应进入受保护接口的正常处理流程;无效、过期或无法验证的令牌应继续返回 401,而不是因为调试配置被意外放行。
BASE_URL="http://localhost:<PORT>"
VALID_TOKEN="<VALUE>"
INVALID_TOKEN="<VALUE>"
curl -sS -o /dev/null -w 'valid=%{http_code}\n' -H "Authorization: Bearer ${VALID_TOKEN}" "${BASE_URL}/api/orders"
curl -sS -o /dev/null -w 'invalid=%{http_code}\n' -H "Authorization: Bearer ${INVALID_TOKEN}" "${BASE_URL}/api/orders"预期结果
valid=200
invalid=401实际成功状态码可能因接口设计为 204 或其他 2xx 而不同;关键是有效凭证与无效凭证的认证边界符合预期。
风险与恢复
不要为了消除 401 直接把接口改成 permitAll(),也不要跳过 JWT 签名、过期时间或其他核心校验。正确修复应落在凭证传递、认证配置、令牌验证或过滤链匹配上。
速查:401 查“有没有认证成功”;403 才更适合继续排查“认证后是否有权限”。
检查用户权限、角色规则和跨站请求保护配置。
排查接口返回 403
接口返回 403 Forbidden 时,通常表示请求已经通过身份认证,但没有通过授权;启用 CSRF 或服务端 CORS 校验时,也可能直接返回 403。排查时先确认认证是否成立,再定位授权、CSRF 或 CORS 中哪一层拒绝了请求。
先确认 403 来自授权而不是认证
使用一个已确认有效、但不具备目标接口权限的令牌请求接口。不要用过期或无效令牌验证 403,否则更常见的结果是 401。
BASE_URL="http://localhost:<PORT>"
TOKEN="<VALUE>"
curl -sS -o /dev/null -w '%{http_code}\n' \
-H "Authorization: Bearer ${TOKEN}" \
"${BASE_URL}/api/admin/report"预期输出:当令牌有效、身份认证成功,但当前用户缺少接口要求的权限时返回 403。实际端口、令牌和路径可能不同。
403如果换成具备目标权限的身份后请求成功,优先检查角色或权限映射;如果多个有效身份都稳定返回 403,则继续检查请求匹配规则、CSRF 和 CORS。
核对角色与权限规则
比较认证对象最终拥有的 GrantedAuthority 与规则实际要求的字符串。Spring Security 中 hasRole("ADMIN") 默认按角色前缀匹配 ROLE_ADMIN,而 hasAuthority("ADMIN") 匹配的就是 ADMIN,两者不能直接互换。
JWT 场景还要检查声明到 authority 的转换逻辑。令牌中存在 roles、scope 或自定义字段,并不代表 Spring Security 会自动生成业务代码期望的权限。存在多条 requestMatchers 时,还要核对匹配范围和顺序,避免更宽泛的规则先命中请求。
检查 CSRF 与 CORS
启用 CSRF 的 Servlet 应用中,使用 Cookie 或 Session 认证的 POST、PUT、PATCH、DELETE 请求如果缺少有效 CSRF Token,可能直接得到 403。此时应正确获取并提交 CSRF Token,而不是用全局关闭 CSRF 规避问题。
对于完全无状态、仅使用 Bearer Token 且不依赖浏览器自动携带 Cookie 的 API,可以评估在对应安全链中禁用 CSRF,但要限定适用范围。若问题只在浏览器出现,还应检查预检 OPTIONS 请求以及允许的 Origin、Method 和 Header;Spring 的 CORS 校验拒绝请求时也可能返回 403。
用调试日志定位拒绝点
测试环境可以临时提高 Spring Security 日志级别:
logging.level.org.springframework.security=DEBUG该配置生效后重新发起同一请求,检查认证是否已经建立、命中了哪条授权规则,以及拒绝发生在授权、CSRF 还是其他安全过滤器。定位完成后恢复原日志级别,避免长期输出敏感或高噪声安全日志。
风险与恢复
不要通过删除 @PreAuthorize、把管理接口改成 permitAll() 或全局关闭 CSRF 来掩盖 403。修复后至少用两个身份复测:具备权限的身份能够访问,缺少权限的身份仍稳定得到 403,证明安全边界没有被意外放宽。
检查连接地址、账号权限、网络和驱动配置。
排查数据库连接失败
Spring Boot 启动或运行时出现连接拒绝、认证失败、连接超时或驱动加载失败,应按“连接配置 → 网络可达性 → 数据库账号 → 驱动与连接池 → 数据库端状态”逐层排查。先把问题归类,再处理根因,避免反复修改无关配置。
先核对数据源配置
重点检查 spring.datasource.url、用户名、密码来源和 JDBC 驱动。URL 中的主机、端口、数据库名及连接参数必须与目标环境一致;使用多数据源时,还要确认当前 Bean 实际绑定的是哪一组配置。
spring:
datasource:
url: jdbc:postgresql://db.example.internal:5432/appdb
username: app_user
password: ${DB_PASSWORD}
driver-class-name: org.postgresql.Driver这段配置会尝试使用 PostgreSQL JDBC 驱动连接 db.example.internal:5432/appdb。DB_PASSWORD 必须在应用进程可见的环境或配置源中存在。Spring Boot 通常可以从 JDBC URL 推断驱动类,但项目仍必须包含对应 JDBC 驱动依赖;验证时先查看应用启动日志是否已经创建数据源或连接池。
从应用运行位置验证网络
必须从运行 Spring Boot 的同一台主机、容器或 Pod 测试数据库端口,才能有效排除 DNS、路由、防火墙、安全组和数据库监听地址问题。
nc -z db.example.internal 5432 && echo "tcp-ok"预期输出:TCP 连接可以建立时输出以下内容;实际主机名和端口可能不同。
tcp-ok如果命令失败或超时,优先处理网络路径、数据库监听地址或访问控制,不要继续修改 Spring Boot 业务代码。
再核对账号与数据库端权限
网络可达后,检查用户名和密码是否正确、密码是否过期、目标数据库是否存在,以及账号是否允许从当前来源连接。认证失败通常会在异常链底部出现数据库原生错误,例如 PostgreSQL 的 password authentication failed 或 MySQL 的 Access denied。
如果数据库要求 TLS,还要确认 JDBC URL、证书信任链和服务端 TLS 策略一致。证书校验失败、协议版本不匹配或强制加密配置错误,都可能表现为“能连到端口但 JDBC 仍无法建立连接”。
检查驱动与连接池根因
Spring 的数据访问异常或 HikariCP 初始化失败通常只是外层包装,应继续向下找到最底层 SQLException、驱动异常或网络异常。常见归类包括:端口不可达、认证失败、数据库不存在、TLS 失败、驱动缺失和连接池耗尽。
若日志出现 ClassNotFoundException: org.postgresql.Driver,应检查 PostgreSQL JDBC 驱动是否真的进入运行时依赖;若出现连接池获取超时,则还要检查数据库最大连接数、应用池大小、长事务和连接泄漏,而不是把超时时间无限调大。
风险与恢复
不要为了快速恢复而把数据库账号改成全局高权限账号,也不要把连接池上限盲目调高。修复后应再次验证端口可达、应用能成功建立连接,并确认临时放宽的网络白名单、账号权限或日志级别已经恢复。
检查慢查询、连接泄漏、事务范围和连接池容量。
排查连接池耗尽
当请求大量卡在获取数据库连接、出现 HikariCP Connection is not available 或连接获取超时时,先判断连接是被慢 SQL 长时间占用、事务迟迟不结束,还是代码泄漏了连接,再决定是否调整连接池容量。
先看池内是否出现排队
若项目已经启用 Spring Boot Actuator、Micrometer,并暴露了 metrics 端点,可观察 HikariCP 的活动连接、等待连接和池上限。下面示例要求本机安装 curl 与 jq。
for metric in active pending max; do
value=$(curl -fsS "http://localhost:<PORT>/actuator/metrics/hikaricp.connections.${metric}" | jq -r '.measurements[0].value')
printf '%s=%s\n' "$metric" "$value"
done预期输出:
active=<VALUE>
pending=<VALUE>
max=<VALUE>实际 <PORT> 和 <VALUE> 会因环境不同而变化。若 pending 持续大于 0,且 active 长时间接近 max,说明请求正在等待连接;若指标端点返回 404,应先确认 Actuator 暴露配置和对应指标是否存在。
区分常见原因
慢查询会让连接被单次 SQL 长时间占用;过大的事务范围会让连接在业务计算、远程调用或等待期间仍不归还;连接泄漏常见于手工获取连接后未可靠关闭;池容量过小则表现为数据库仍有余量,但应用侧持续排队。
使用 Spring Data、JPA 或 JdbcTemplate 时,优先检查事务边界和慢 SQL;直接调用 DataSource#getConnection() 时,必须确保所有正常与异常路径最终都能关闭连接。
用配置辅助定位
HikariCP 可以临时启用泄漏检测,并明确连接获取超时与池大小。下面的数值只用于排查示例,不能直接当成生产推荐值。
spring:
datasource:
hikari:
maximum-pool-size: 20
connection-timeout: 30000
leak-detection-threshold: 20000预期结果:应用重启后按上述值初始化连接池;连接申请超过 connection-timeout 会失败;连接长时间未归还时,泄漏检测可能记录告警。
配置生效后,应同时结合应用日志、数据库慢查询和池指标验证,避免只根据一条告警下结论。
修复顺序
优先修复慢 SQL、缩短事务、补齐连接关闭,再根据数据库可承受并发、应用实例数和连接预算评估池大小。单纯增大 maximum-pool-size 只会把压力向数据库转移,可能把“应用排队”升级为“数据库过载”。
检查异常类型、代理调用和事务方法可见性。
排查事务未回滚
当 @Transactional 方法抛错后数据库仍保留修改时,按“代理是否生效 → 异常是否离开事务方法 → 异常是否命中回滚规则”的顺序检查。多数问题不是数据库拒绝回滚,而是事务拦截器没有接管调用,或最终看到的是可提交结果。
先确认事务是否经过代理
Spring 默认通过 AOP 代理应用声明式事务。来自其他 Bean 的代理调用能进入事务拦截器;同一对象内部使用 this.someMethod() 调用事务方法通常会绕过代理。采用 JDK 动态代理时,事务方法还应通过代理暴露的接口调用;为减少代理类型和可见性差异,事务边界通常放在 public 服务方法上。

临时打开事务日志可以先判断目标方法是否被事务基础设施接管:
java -jar app.jar --logging.level.org.springframework.transaction=TRACE预期结果:
<目标事务方法的事务创建或加入记录>
<事务提交或回滚记录>若触发业务请求后完全没有目标方法相关事务日志,优先检查 Bean 是否由 Spring 管理、调用是否经过代理,以及方法是否因 final、代理类型或调用路径而无法被增强。实际日志文案会随 Spring 版本和日志实现不同。
再检查异常和回滚规则
默认情况下,Spring 声明式事务会对 RuntimeException 和 Error 回滚;普通受检异常默认不触发回滚。确实需要对受检异常回滚时,可在事务边界使用 rollbackFor 明确声明。
还要确认异常没有在事务方法内部被 catch 后吞掉。事务拦截器只有看到异常离开事务方法,或事务状态被显式标记为 rollback-only,才会按失败路径结束事务。若配置了 noRollbackFor,它也可能有意覆盖默认回滚行为。
核对事务边界
如果外层事务调用 REQUIRES_NEW 方法,内外事务会独立提交或回滚;如果外层捕获了内层异常,最终数据库状态可能与“整段业务一起回滚”的直觉不同。排查时应确认实际生效的传播行为,而不是只看最内层方法上的注解。
对异步线程、消息监听器或手动创建线程也要单独看事务边界:事务上下文不会因为代码调用关系自动跨线程传播。
风险与恢复
事务 TRACE 日志量较大,只在短时间排障时开启并及时恢复原日志级别。遇到自调用问题,优先把事务方法拆到独立 Spring Bean 后从代理调用;不要把 AopContext.currentProxy() 当作常规修复。若业务要求受检异常也回滚,应明确配置 rollbackFor,并用失败场景集成测试验证最终数据库状态。