Java 后端 / 知识点
Spring Boot 开发速查手册
手册条目
读取分页、筛选和排序等查询字符串参数。
接收查询参数
用于读取 URL 中 ?page=2&size=10&keyword=book 这类查询参数。参数较少时优先使用 @RequestParam;参数较多时可封装为查询对象,避免控制器方法过长。
基本语法
@RequestParam 用于把查询字符串绑定到方法参数。生产代码建议显式指定参数名,避免依赖编译后的 Java 参数名。
| 写法 | 行为 |
|---|---|
@RequestParam("page") int page |
必传;缺失或无法转换为整数时返回 400 |
@RequestParam(defaultValue = "20") int size |
缺失时使用默认值,不再视为必传 |
@RequestParam(required = false) String keyword |
可选;缺失时为 null |
@RequestParam("tag") List<String> tags |
接收重复参数,如 ?tag=java&tag=spring |
主示例
下面的示例接收页码、每页数量、关键字和排序规则,并限制分页边界,避免一次请求拉取过多数据。
package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;
@SpringBootApplication
public class QueryParamApplication {
public static void main(String[] args) {
SpringApplication.run(QueryParamApplication.class, args);
}
@RestController
static class ProductController {
@GetMapping("/api/products")
QueryResult list(
@RequestParam(name = "page", defaultValue = "1") int page,
@RequestParam(name = "size", defaultValue = "20") int size,
@RequestParam(name = "keyword", required = false) String keyword,
@RequestParam(name = "sort", defaultValue = "createdAt,desc") String sort) {
// 限制分页参数,避免非法值直接进入数据库查询。
if (page < 1 || size < 1 || size > 100) {
throw new ResponseStatusException(
HttpStatus.BAD_REQUEST,
"page must be >= 1 and size must be between 1 and 100"
);
}
return new QueryResult(page, size, keyword, sort);
}
}
record QueryResult(int page, int size, String keyword, String sort) {
}
}预期结果:应用启动后,GET /api/products 可以访问;缺少 page、size 或 sort 时分别使用 1、20 和 createdAt,desc。
curl 'http://localhost:8080/api/products?page=2&size=10&keyword=book&sort=price,asc'预期输出:
{"page":2,"size":10,"keyword":"book","sort":"price,asc"}读取方法:page 和 size 控制分页,keyword 用于筛选,sort 可在服务层拆成字段与方向。命令中的 URL 使用单引号包裹,可避免 Shell 把 & 解释为后台执行符。
高频用法
当参数超过约 5 个时,可以定义 ProductQuery 并使用 @ModelAttribute ProductQuery query 自动绑定同名查询参数。日期、枚举等类型建议配合 @DateTimeFormat 或自定义 Converter,不要在控制器中手工解析字符串。
多值筛选可使用重复参数,例如 ?status=PAID&status=REFUNDED,对应 @RequestParam("status") List<String> statuses。是否支持逗号拆分应由接口契约明确约定,不要依赖客户端的隐式行为。
风险与边界
未限制 size 时,大结果集请求可能导致数据库慢查询、内存上涨或接口超时。安全做法是设置默认值和最大值,并在数据访问层继续使用分页查询。
不要把外部传入的排序字段直接拼入 SQL。应将字段映射到固定白名单,例如只允许 createdAt、price,方向只允许 asc、desc,再交给 ORM 或查询构造器处理。
排障清单
出现 400 时先检查参数是否缺失、名称是否一致,以及数字或日期格式是否可转换。参数始终为 null 时,确认请求使用的是 URL 查询字符串,而不是 JSON 请求体。
筛选未生效时,检查控制器是否把参数继续传到服务层,以及空字符串是否需要归一化为 null。分页异常时,再确认前端页码约定是从 0 开始还是从 1 开始。
将请求体中的 JSON 数据转换为 Java 对象。
接收 JSON 请求
用于把 Content-Type: application/json 请求体反序列化为 Java 对象。控制器参数使用 @RequestBody;需要字段校验时配合 @Valid,让非法请求在进入业务逻辑前返回 400。
基本语法
核心写法是 public Result create(@Valid @RequestBody OrderRequest request)。JSON 字段名默认与 Java 属性名对应,请求头应声明 application/json;缺少或不匹配时通常会得到 415。
使用 Spring Boot 3 时,Bean Validation 注解来自 jakarta.validation。除 Web 依赖外,还需要校验依赖。
<!-- 片段示例:放入现有 Spring Boot 项目的 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>生效行为:项目可以处理 JSON 请求,并在参数使用 @Valid 时执行 Bean Validation。刷新 Maven 依赖后,jakarta.validation 相关导入应能正常解析。
主示例
下面的单文件应用接收商品编号和数量,校验通过后返回 201。record 适合承载这种字段固定的请求 DTO,字段通过 productId() 和 quantity() 访问。
package com.example.demo;
import jakarta.validation.Valid;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
public class JsonRequestApplication {
public static void main(String[] args) {
SpringApplication.run(JsonRequestApplication.class, args);
}
@RestController
static class OrderController {
@PostMapping("/api/orders")
ResponseEntity<OrderResponse> create(
@Valid @RequestBody OrderRequest request) {
// 订单号由服务端生成;这里用固定值保持示例可复现。
OrderResponse response = new OrderResponse(
"ORDER-1001",
request.productId(),
request.quantity()
);
return ResponseEntity.status(HttpStatus.CREATED).body(response);
}
}
record OrderRequest(
@NotBlank String productId,
@Min(1) int quantity) {
}
record OrderResponse(
String orderNo,
String productId,
int quantity) {
}
}预期结果:应用启动后,请求体先反序列化为 OrderRequest,再执行字段校验;校验通过后才进入 create 方法。
curl -i -X POST 'http://localhost:8080/api/orders' \
-H 'Content-Type: application/json' \
-d '{"productId":"P-1001","quantity":2}'预期输出:
HTTP/1.1 201
Content-Type: application/json
{"orderNo":"ORDER-1001","productId":"P-1001","quantity":2}状态码 201 表示创建成功。orderNo 是服务端结果,productId 和 quantity 来自完成反序列化与校验的请求对象;日期、连接等附加响应头会因运行环境而变化。
高频用法
字段名不一致时,可使用 @JsonProperty("product_id") 映射外部 JSON;日期时间建议使用明确的 ISO 8601 格式,并在 DTO 上声明所需规则。嵌套对象可继续定义嵌套 DTO,集合字段使用 List<ItemRequest>,不要用原始 Map<String, Object> 代替稳定的接口契约。
请求 DTO 与数据库实体建议分离。DTO 负责接口字段和校验,实体负责持久化结构,可避免客户端直接覆盖 id、状态或创建时间等服务端字段。
风险与边界
缺少 Content-Type: application/json 时通常返回 415;JSON 语法错误、类型不匹配或请求体缺失通常返回 400。客户端应固定发送正确请求头,服务端再通过统一异常处理返回稳定的错误格式。
仅使用 @RequestBody 不会自动执行字段校验。遗漏 @Valid 时,空商品编号或非法数量可能进入业务层,因此接口层应保留 DTO 约束和 @Valid,业务规则与数据库约束继续作为后续防线。
排障清单
出现 415 时检查请求头,以及网关是否改写了 Content-Type。出现 400 时检查 JSON 双引号、字段类型和请求体是否存在,并确认 DTO 的字段能够被 Jackson 正常绑定。
对象字段全部是默认值时,检查 JSON 字段名与 DTO 是否一致;命名不同则使用 @JsonProperty。校验始终不生效时,确认已加入校验依赖、参数前存在 @Valid,并在 Spring Boot 3 中使用 jakarta.validation。
使用统一响应对象封装状态码、消息和业务数据。
统一接口响应
用于让前端、日志和调用方以固定字段读取业务结果。推荐统一业务响应体,但不要把所有 HTTP 状态都强制改成 200。
响应对象
统一响应对象可以固定业务码、消息、数据和链路标识。下面示例使用 Spring Boot 3.x 与 JDK 17+ 的 record,放入已引入 spring-boot-starter-web 的项目即可使用。
package com.example.demo.api;
public record ApiResponse<T>(
String code,
String message,
T data,
String traceId
) {
public static <T> ApiResponse<T> success(T data, String traceId) {
return new ApiResponse<>("0", "OK", data, traceId);
}
public static <T> ApiResponse<T> failure(
String code, String message, String traceId) {
return new ApiResponse<>(code, message, null, traceId);
}
}字段约定应保持稳定:code 表示业务结果,message 面向调用方说明原因,data 承载业务数据,traceId 用于串联日志。无业务数据时返回 null,不要用空字符串伪装对象。
控制器用法
控制器只负责组装成功结果和必要的链路标识,不要在每个接口里重复实现响应格式。
package com.example.demo.web;
import com.example.demo.api.ApiResponse;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;
import java.util.UUID;
@RestController
@RequestMapping("/api/profile")
public class ProfileController {
@GetMapping
public ApiResponse<Map<String, Object>> profile(
@RequestHeader(value = "X-Trace-Id", required = false) String traceId) {
String actualTraceId = traceId == null || traceId.isBlank()
? UUID.randomUUID().toString()
: traceId;
return ApiResponse.success(
Map.of("userId", 1001, "nickname", "Alice"),
actualTraceId
);
}
}将 <PORT> 替换为应用实际端口,Spring Boot 默认端口通常为 8080。
curl -i -H 'X-Trace-Id: trace-demo-001' http://localhost:<PORT>/api/profile预期输出:
HTTP/1.1 200
Content-Type: application/json
{"code":"0","message":"OK","data":{"userId":1001,"nickname":"Alice"},"traceId":"trace-demo-001"}Map 的字段顺序不属于接口契约,实际 JSON 中 userId 与 nickname 的先后可能不同。
失败结果与异常处理
成功查询使用 ApiResponse.success(data, traceId);失败结果使用稳定业务码,例如 INVALID_ARGUMENT、RESOURCE_NOT_FOUND。鉴权失败、资源不存在等场景仍应由正确的 HTTP 状态码表达,而不是全部包装成 200。
参数校验、业务异常和未知异常应在 @RestControllerAdvice 中统一转换,避免每个控制器重复 try-catch。日志记录完整异常,对外响应只暴露稳定消息和 traceId。
风险与边界
不要把鉴权失败、资源不存在、服务异常全部包装成 HTTP 200。这样会导致网关、监控和客户端重试逻辑误判;更安全的做法是同时使用正确的 HTTP 状态码和统一响应体。
不要直接把异常堆栈、SQL、密钥或内部类名写入 message。对外返回稳定错误信息,并通过 traceId 定位服务端日志。
业务码一旦被客户端依赖就属于接口契约。随意改名会造成前端分支失效;应集中定义、保持唯一,并为废弃码保留迁移周期。
兼容性
record 适用于 JDK 16 及以上,Spring Boot 3.x 通常运行在 JDK 17 或更高版本。旧项目可改为普通 Java Bean,并保持相同字段和序列化契约。
根据创建成功、参数错误或无权限等场景返回状态码。
设置 HTTP 状态码
根据请求结果返回准确的 HTTP 状态码,让浏览器、网关、监控和 SDK 能正确判断成功、客户端错误或权限错误。
常用状态码
| 场景 | 状态码 | Spring 写法 |
|---|---|---|
| 查询或更新成功 | 200 OK |
ResponseEntity.ok(body) |
| 创建成功 | 201 Created |
ResponseEntity.created(location).body(body) |
| 删除成功且无响应体 | 204 No Content |
ResponseEntity.noContent().build() |
| 参数格式或校验失败 | 400 Bad Request |
ResponseEntity.badRequest().body(body) |
| 未登录或凭证无效 | 401 Unauthorized |
由 Spring Security 认证入口处理 |
| 已登录但无权限 | 403 Forbidden |
由 Spring Security 拒绝处理 |
| 资源不存在 | 404 Not Found |
ResponseEntity.status(HttpStatus.NOT_FOUND).body(body) |
| 服务端异常 | 500 Internal Server Error |
由全局异常处理器统一返回 |
创建资源返回 201
创建成功时同时返回 201、新资源地址和响应体。下面示例使用 ResponseEntity.created(...),并保留完整的请求与返回类型定义。
package com.example.demo.web;
import org.springframework.http.ResponseEntity;
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 java.net.URI;
@RestController
@RequestMapping("/api/users")
public class UserController {
@PostMapping
public ResponseEntity<ApiResult<UserView>> create(
@RequestBody CreateUserRequest request) {
long userId = 1001L;
UserView data = new UserView(userId, request.name());
// Location 指向新资源,状态码明确为 201。
return ResponseEntity
.created(URI.create("/api/users/" + userId))
.body(new ApiResult<>("0", "OK", data));
}
public record CreateUserRequest(String name) {}
public record UserView(long id, String name) {}
public record ApiResult<T>(String code, String message, T data) {}
}将 <PORT> 替换为应用实际端口。
curl -i -X POST http://localhost:<PORT>/api/users -H 'Content-Type: application/json' -d '{"name":"Alice"}'预期输出:
HTTP/1.1 201
Location: /api/users/1001
Content-Type: application/json
{"code":"0","message":"OK","data":{"id":1001,"name":"Alice"}}参数错误返回 400
参数校验失败时,优先在 @RestControllerAdvice 中集中处理,而不是在控制器中手工判断后返回 200。为了让 MethodArgumentNotValidException 产生,控制器参数需要使用 @Valid。
package com.example.demo.web;
import jakarta.validation.Valid;
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;
@RestController
@RequestMapping("/api/users")
class ValidatingUserController {
@PostMapping
ResponseEntity<String> create(@Valid @RequestBody CreateUserRequest request) {
return ResponseEntity.ok(request.name());
}
record CreateUserRequest(
@jakarta.validation.constraints.NotBlank String name) {}
}
@RestControllerAdvice
class ApiExceptionHandler {
@ExceptionHandler(MethodArgumentNotValidException.class)
ResponseEntity<ErrorResponse> handleValidation(
MethodArgumentNotValidException ex) {
String message = ex.getBindingResult().getFieldErrors().stream()
.findFirst()
.map(error -> error.getField() + ": " + error.getDefaultMessage())
.orElse("请求参数不合法");
return ResponseEntity.badRequest()
.body(new ErrorResponse("INVALID_ARGUMENT", message));
}
record ErrorResponse(String code, String message) {}
}预期结果:当请求体缺少或提交空的 name 时,校验失败并进入全局异常处理器,返回 HTTP 400;具体错误文案取决于 Bean Validation 提供的默认消息与配置。
风险与边界
401 表示未通过认证,403 表示身份已确认但权限不足。混用会导致前端错误跳转登录页或隐藏真实权限问题;应让 Spring Security 的 AuthenticationEntryPoint 和 AccessDeniedHandler 分别处理。
返回 204 No Content 时不得再写响应体。需要返回业务信息时改用 200,否则客户端可能无法按预期解析响应内容。
不要在业务代码中直接返回 500 掩盖可预期的参数或资源错误。这样会污染告警并触发无效重试;可识别异常应映射为 400、404 或 409,未知异常再统一返回 500。
排障清单
状态码始终为 200 时,检查控制器是否直接返回普通对象、全局异常处理器是否错误吞掉异常,以及网关是否重写响应。出现“状态码正确但响应体为空”时,确认是否返回了 204,并检查异常处理器是否在写出响应后再次抛错。
使用 Jakarta Validation 校验请求对象字段。
校验请求参数
用于在 Controller 接收请求时统一拦截空值、格式和长度错误。Spring Boot 3 使用 jakarta.validation 注解;请求体校验失败时通常返回 HTTP 400,业务方法不会继续执行。
基本配置
项目需要显式引入 Validation Starter。spring-boot-starter-web 不应视为 Validation 实现的来源,因此生产项目应明确声明该依赖。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>生效后,Controller 参数上的 @Valid 或 @Validated 才能触发 Bean Validation。依赖是否生效可通过后面的非法请求验证。
请求对象与接口
请求对象使用包装类型 Integer,这样缺少 age 时可以由 @NotNull 明确区分“没有传值”和“数值过小”。
package com.example.demo.user;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;
public record CreateUserRequest(
@NotBlank(message = "用户名不能为空")
@Size(min = 3, max = 20, message = "用户名长度必须为 3~20")
String username,
@NotNull(message = "年龄不能为空")
@Min(value = 18, message = "年龄不能小于 18")
Integer age,
@NotBlank(message = "邮箱不能为空")
@Email(message = "邮箱格式不正确")
String email
) {
}片段示例:下面的 Controller 依赖上面的请求类型和 Spring Web 环境。
package com.example.demo.user;
import jakarta.validation.Valid;
import java.util.LinkedHashMap;
import java.util.Map;
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;
@RestController
@RequestMapping("/users")
public class UserController {
@PostMapping
public Map<String, Object> create(@Valid @RequestBody CreateUserRequest request) {
Map<String, Object> result = new LinkedHashMap<>();
result.put("username", request.username());
result.put("age", request.age());
result.put("email", request.email());
return result;
}
}@Valid 是触发 @RequestBody Bean Validation 的关键;遗漏后,DTO 上的约束不会在该参数绑定时执行。嵌套对象还需要在字段上继续标注 @Valid,才能进入下一层校验。
统一返回校验错误
全局异常处理器可以把字段错误整理成稳定 JSON,便于前端按字段展示。下面保留同一字段的第一条错误,避免响应结构过于复杂。
package com.example.demo.user;
import java.util.LinkedHashMap;
import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;
@RestControllerAdvice
public class ValidationExceptionHandler {
@ExceptionHandler(MethodArgumentNotValidException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
public Map<String, Object> handle(MethodArgumentNotValidException exception) {
Map<String, String> errors = new LinkedHashMap<>();
for (FieldError error : exception.getBindingResult().getFieldErrors()) {
errors.putIfAbsent(error.getField(), error.getDefaultMessage());
}
Map<String, Object> body = new LinkedHashMap<>();
body.put("code", "VALIDATION_FAILED");
body.put("errors", errors);
return body;
}
}发送一个用户名长度不符合约束的请求:
curl -i -X POST http://localhost:8080/users \
-H 'Content-Type: application/json' \
-d '{"username":"ab","age":20,"email":"user@example.com"}'预期输出:
HTTP/1.1 400
Content-Type: application/json
{"code":"VALIDATION_FAILED","errors":{"username":"用户名长度必须为 3~20"}}实际响应头可能包含额外字段,JSON 字段顺序也可能不同。验证重点是状态码为 400,且 errors.username 存在。
常用注解与边界
@NotNull 只检查非空;@NotBlank 适用于字符串并拒绝空白;@Size 校验字符串、集合或数组长度;@Min、@Max 校验数值;@Email 只检查格式,不验证邮箱真实存在。
请求 JSON 类型不匹配,例如把年龄传成 "abc",会在反序列化阶段抛出 HttpMessageNotReadableException,不会进入 Bean Validation。生产接口应为这类异常单独返回“请求格式错误”,避免把解析失败误报成字段校验失败。
速查:请求体字段校验使用 @Valid @RequestBody;方法参数分组校验或方法级校验可使用 @Validated。
为业务字段创建可复用的校验注解和校验器。
自定义校验规则
用于把重复出现的业务格式校验封装成可复用注解,例如商户号、渠道编码或订单号格式。自定义约束由“注解定义”和 ConstraintValidator 两部分组成,可以像内置约束一样挂到请求对象字段上。
定义校验注解
下面创建 @ValidMerchantNo,要求商户号为字母 M 加 10 位数字。message、groups 和 payload 是自定义约束需要提供的标准属性。
package com.example.demo.validation;
import jakarta.validation.Constraint;
import jakarta.validation.Payload;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Documented
@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = MerchantNoValidator.class)
public @interface ValidMerchantNo {
String message() default "商户号格式不正确";
Class<?>[] groups() default {};
Class<? extends Payload>[] payload() default {};
}编写校验器
校验器实现 ConstraintValidator<ValidMerchantNo, String>。这里把 null 交给 @NotBlank 处理,职责更清晰,也避免一个空值同时产生两类格式错误。
package com.example.demo.validation;
import jakarta.validation.ConstraintValidator;
import jakarta.validation.ConstraintValidatorContext;
import java.util.regex.Pattern;
public class MerchantNoValidator
implements ConstraintValidator<ValidMerchantNo, String> {
private static final Pattern PATTERN = Pattern.compile("M\\d{10}");
@Override
public boolean isValid(String value, ConstraintValidatorContext context) {
return value == null || PATTERN.matcher(value).matches();
}
}验证器应保持无状态、线程安全,不要把单次请求的数据写入实例字段。
在请求对象中使用
下面的请求类型与 Controller 共同组成主示例;项目需先引入 spring-boot-starter-validation,并确保请求参数带有 @Valid。
package com.example.demo.merchant;
import com.example.demo.validation.ValidMerchantNo;
import jakarta.validation.constraints.NotBlank;
public record BindMerchantRequest(
@NotBlank(message = "商户号不能为空")
@ValidMerchantNo
String merchantNo
) {
}片段示例:Controller 依赖上面的 BindMerchantRequest 和 Spring Web 环境。
package com.example.demo.merchant;
import jakarta.validation.Valid;
import java.util.Map;
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;
@RestController
@RequestMapping("/merchant-bindings")
public class MerchantBindingController {
@PostMapping
public Map<String, String> bind(@Valid @RequestBody BindMerchantRequest request) {
return Map.of("merchantNo", request.merchantNo(), "status", "BOUND");
}
}如果项目已经采用统一的 MethodArgumentNotValidException 处理器,可直接复用,无需再为每个自定义约束复制一份异常处理逻辑。
验证不符合规则的商户号:
curl -i -X POST http://localhost:8080/merchant-bindings \
-H 'Content-Type: application/json' \
-d '{"merchantNo":"A123"}'预期输出:
HTTP/1.1 400
Content-Type: application/json
{"code":"VALIDATION_FAILED","errors":{"merchantNo":"商户号格式不正确"}}适用边界
适合放在校验器中的规则应当快速、确定且无副作用,例如格式、校验位、枚举范围和简单字段关系。校验一次请求时,同一个校验器可能被多次调用,因此不要依赖可变实例状态。
不要在校验器中执行远程调用或高延迟数据库查询。这样会放大请求延迟,并可能在依赖故障时把业务问题误报成参数错误。商户是否存在、是否唯一等依赖外部状态的判断应放在 Service 层,并返回明确的业务错误码。
如果规则可以直接由 @Pattern、@Size 等内置约束表达,优先使用内置约束,减少自定义注解和测试成本。
速查:空值约束与格式约束分开写;自定义校验器保持无状态;外部状态校验放到业务层。
统一捕获控制器异常并转换为标准响应。
处理全局异常
使用 @RestControllerAdvice 集中捕获进入 Spring MVC 控制器调用链的异常,再由 @ExceptionHandler 转换为统一 HTTP 状态码和 JSON 响应。业务异常返回可读错误信息,未知异常只记录服务端堆栈,避免向客户端泄露内部实现。
基本做法
以下为片段示例,放入已有的 Spring Boot Web 项目。业务异常与兜底异常分开处理,避免把所有失败都返回 200。
import jakarta.servlet.http.HttpServletRequest;
import java.time.Instant;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RestControllerAdvice;
record ApiError(String code, String message, String path, Instant timestamp) {}
class BizException extends RuntimeException {
BizException(String message) {
super(message);
}
}
@RestController
class DemoController {
@GetMapping("/demo/fail")
String fail() {
throw new BizException("订单状态不允许当前操作");
}
}
@RestControllerAdvice
public class GlobalExceptionHandler {
private static final Logger log =
LoggerFactory.getLogger(GlobalExceptionHandler.class);
@ExceptionHandler(BizException.class)
ResponseEntity<ApiError> handleBiz(
BizException ex, HttpServletRequest request) {
return ResponseEntity.badRequest().body(
new ApiError("BIZ_ERROR", ex.getMessage(),
request.getRequestURI(), Instant.now()));
}
@ExceptionHandler(Exception.class)
ResponseEntity<ApiError> handleUnknown(
Exception ex, HttpServletRequest request) {
// 日志保留完整堆栈,客户端只拿到稳定错误码和通用提示。
log.error("Unhandled request exception, path={}",
request.getRequestURI(), ex);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(
new ApiError("INTERNAL_ERROR", "系统繁忙,请稍后重试",
request.getRequestURI(), Instant.now()));
}
}验证结果
启动应用后请求演示接口:
curl -i http://localhost:8080/demo/fail预期输出如下,<TIME> 为实际响应时间,JSON 字段顺序可能不同:
HTTP/1.1 400
Content-Type: application/json
{"code":"BIZ_ERROR","message":"订单状态不允许当前操作","path":"/demo/fail","timestamp":"<TIME>"}客户端优先依据 HTTP 状态码和稳定的 code 做程序分支;message 用于展示,path 与服务端日志用于定位请求。
风险与边界
@ExceptionHandler(Exception.class) 只应作为最后兜底。不要直接把 ex.getMessage() 或堆栈返回客户端,否则可能泄露 SQL、文件路径、内部地址和依赖信息。
过滤器、Spring Security 认证链中发生且未进入 Spring MVC 的异常,以及响应已经提交后的流式输出异常,可能无法由该 Advice 改写,应分别在对应边界处理。
排障清单
- Advice 未生效:确认处理器位于启动类组件扫描范围内,并使用
@RestControllerAdvice。 - 返回了别的内容:检查控制器是否定义了更具体的本地
@ExceptionHandler。 - 错误都变成 500:检查异常映射是否过于宽泛,并为业务异常、资源不存在、权限异常分别设置状态码。
- 日志缺少上下文:至少记录请求路径、异常堆栈和 traceId,禁止只打印异常消息。
Spring Boot 3.x 使用 jakarta.servlet;旧版项目仍使用 javax.servlet,迁移时不要混用。
提取字段校验错误并返回可读的错误信息。
处理参数校验异常
对 @RequestBody DTO 和控制器方法参数的校验失败统一返回字段级错误,让客户端能够直接定位不合法的参数。示例面向 Spring Boot 3.x,并要求项目已引入 spring-boot-starter-validation。
校验与异常处理
MethodArgumentNotValidException 用于处理 @Valid @RequestBody DTO 的字段校验错误;Spring Framework 6.1 及以上还可用 HandlerMethodValidationException 处理 @RequestParam、@PathVariable 等方法参数校验错误。
import jakarta.validation.Valid;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Optional;
import java.util.stream.Collectors;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.method.annotation.HandlerMethodValidationException;
record CreateUserRequest(
@NotBlank(message = "name不能为空") String name,
@Email(message = "email格式不正确") String email,
@NotNull(message = "age不能为空")
@Min(value = 18, message = "age不能小于18") Integer age) {}
record ValidationErrorResponse(
String code, Map<String, String> errors) {}
@RestController
class UserController {
@PostMapping("/users")
ResponseEntity<Void> create(@Valid @RequestBody CreateUserRequest request) {
return ResponseEntity.noContent().build();
}
@GetMapping("/users/page")
String page(@RequestParam
@Min(value = 1, message = "page必须大于等于1") int page) {
return "page=" + page;
}
}
@RestControllerAdvice
public class ValidationExceptionHandler {
@ExceptionHandler(MethodArgumentNotValidException.class)
ResponseEntity<ValidationErrorResponse> handleBody(
MethodArgumentNotValidException ex) {
// 同一字段可能命中多个约束,此处只保留第一条,便于前端展示。
Map<String, String> errors = ex.getBindingResult().getFieldErrors()
.stream()
.collect(Collectors.toMap(
FieldError::getField,
error -> Optional.ofNullable(error.getDefaultMessage())
.orElse("参数不合法"),
(first, ignored) -> first,
LinkedHashMap::new));
return ResponseEntity.badRequest().body(
new ValidationErrorResponse("VALIDATION_ERROR", errors));
}
@ExceptionHandler(HandlerMethodValidationException.class)
ResponseEntity<ValidationErrorResponse> handleMethod(
HandlerMethodValidationException ex) {
Map<String, String> errors = new LinkedHashMap<>();
ex.getParameterValidationResults().forEach(result -> {
String name = result.getMethodParameter().getParameterName();
String key = name != null
? name
: "arg" + result.getMethodParameter().getParameterIndex();
String message = result.getResolvableErrors().stream()
.map(error -> Optional.ofNullable(error.getDefaultMessage())
.orElse("参数不合法"))
.findFirst()
.orElse("参数不合法");
errors.putIfAbsent(key, message);
});
return ResponseEntity.badRequest().body(
new ValidationErrorResponse("VALIDATION_ERROR", errors));
}
}验证结果
发送包含三个非法字段的请求:
curl -i -X POST http://localhost:8080/users \
-H 'Content-Type: application/json' \
-d '{"name":"","email":"bad","age":16}'预期输出如下,JSON 字段顺序可能不同:
HTTP/1.1 400
Content-Type: application/json
{"code":"VALIDATION_ERROR","errors":{"name":"name不能为空","email":"email格式不正确","age":"age不能小于18"}}客户端读取 errors 的键定位表单字段,读取值作为提示文本;不要依赖字段返回顺序。
风险与边界
缺少 @Valid 时,@RequestBody 只完成反序列化,不会触发字段约束。@Min 等约束默认允许 null,必填字段仍需 @NotNull、@NotBlank 等约束。
JSON 语法错误、类型转换失败和缺少必需请求参数,可能分别抛出 HttpMessageNotReadableException、MethodArgumentTypeMismatchException 或 MissingServletRequestParameterException,不能只靠本条目的两个处理器覆盖。
不要把 rejected value 原样写入响应或日志;密码、令牌和身份证件等字段可能因此泄露。若需要返回同一字段的全部错误,可改用 Map<String, List<String>>,避免后续消息被覆盖。
排障清单
- DTO 校验不触发:检查是否引入 validation starter,以及控制器参数是否标注
@Valid。 - 方法参数校验不触发:Spring Framework 6.1 及以上优先使用 MVC 内置方法校验;控制器类上额外使用类级
@Validated时,应确认版本和校验链行为。 - 错误信息为空:约束配置
message,或通过MessageSource提供国际化消息。 - 只返回第一个字段错误:检查收集逻辑是否错误地对整个结果使用了
findFirst()。
HandlerMethodValidationException 从 Spring Framework 6.1 开始提供;较早版本或基于 AOP 的类级 @Validated 方案通常需要额外处理 ConstraintViolationException。
为指定来源、请求方法和请求头配置 CORS。
配置跨域访问
用于前端页面从 https://app.example.com 调用后端 /api/**。配置完成后,浏览器只放行指定来源、方法和请求头;CORS 只处理浏览器跨域限制,不能替代登录鉴权和接口权限控制。Spring MVC 可通过 WebMvcConfigurer#addCorsMappings 配置全局 URL 映射。

全局配置
将下列类放入 Spring Boot 的组件扫描路径,并把示例域名替换为真实前端来源。来源必须包含协议和端口,不能写路径或末尾斜杠。
package com.example.demo.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class CorsConfig implements WebMvcConfigurer {
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/api/**")
// 生产环境应列出可信来源,不要直接开放任意网站
.allowedOrigins(
"https://app.example.com",
"https://admin.example.com"
)
.allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
.allowedHeaders("Authorization", "Content-Type", "X-Request-Id")
.exposedHeaders("X-Request-Id")
.allowCredentials(true)
.maxAge(3600);
}
}预期结果:应用启动成功后,对 /api/** 的跨域请求会按上述来源、方法和请求头进行匹配;不匹配的来源不会得到允许跨域所需的响应头。
allowedHeaders 控制浏览器可发送的非简单请求头,exposedHeaders 控制前端 JavaScript 可读取的响应头,maxAge 是预检结果的浏览器缓存秒数。只有使用 Cookie、HTTP 认证或客户端证书等浏览器凭证时才需要 allowCredentials(true);启用凭证后应配置有限的可信来源。
验证预检请求
先确认 /api/orders 是应用中真实存在的接口,再执行:
curl -i -X OPTIONS 'http://localhost:8080/api/orders' \
-H 'Origin: https://app.example.com' \
-H 'Access-Control-Request-Method: POST' \
-H 'Access-Control-Request-Headers: Authorization,Content-Type'预期输出中的关键响应头如下,实际状态行、顺序、大小写和其他服务器头可能不同:
HTTP/1.1 200
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS
Access-Control-Allow-Headers: Authorization,Content-Type
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 3600重点检查 Access-Control-Allow-Origin 是否与请求的 Origin 完全一致。响应中没有该头,通常表示来源、路径、方法或请求头未匹配配置。
Spring Security 场景
项目启用 Spring Security 时,预检请求可能先经过安全过滤器。出现 OPTIONS 返回 401 或 403,可显式启用 Security 的 CORS 支持,让其复用 Spring MVC 配置:
package com.example.demo.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
@Configuration
public class SecurityConfig {
@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http.cors(Customizer.withDefaults())
.authorizeHttpRequests(auth -> auth
.anyRequest().authenticated());
return http.build();
}
}预期结果:Spring Security 启用 CORS 支持后,预检可以进入 CORS 处理链;这不会自动放开业务接口权限,也不会关闭 CSRF。
风险与排障
不要在生产环境把任意来源与凭证组合使用。恶意网站可能诱导已登录用户发起请求,后果可能是敏感数据泄露或未授权操作;安全替代方案是精确列出可信域名,并按环境维护白名单。
排查时优先确认服务端实际收到的 Origin、请求方法和请求头,再检查:
- 浏览器报错但
curl正常:继续检查响应头,因为 CORS 由浏览器执行。 - 预检返回 404 或 405:确认网关、反向代理和应用允许
OPTIONS,且测试路径存在。 - 预检返回 401 或 403:检查 Spring Security、网关鉴权或自定义过滤器是否提前拦截。
- 域名已配置仍失败:核对协议、子域名和端口;
http://与https://属于不同来源。 - 响应头重复或冲突:避免 Nginx、网关和应用同时添加 CORS,优先统一到一层管理。
速查提示:先用预检命令验证服务端响应头,再处理浏览器缓存和前端请求配置。
接收文件并限制上传大小和内容类型。
上传文件
用于通过 multipart/form-data 接收单个文件,同时限制请求大小、内容类型和落盘路径。示例返回随机存储名,不直接使用客户端文件名,可降低路径穿越、重名覆盖和特殊字符带来的风险。

限制上传大小
在 application.yml 中设置单文件上限和整个 multipart 请求上限。max-file-size 约束每个文件,max-request-size 约束包含文件与普通表单字段在内的整个请求。
spring:
servlet:
multipart:
max-file-size: 10MB
max-request-size: 12MB
app:
upload-dir: <PATH>/uploads预期结果:应用重启后,单个文件超过 10MB 时会触发上传大小限制;整个 multipart 请求超过 12MB 时同样会被拒绝。max-request-size 通常应略大于 max-file-size,以容纳 multipart 边界和其他字段。
接收并保存文件
片段示例:以下类依赖 spring-boot-starter-web。上传目录在启动时创建,文件名由 UUID 生成,并只允许 PNG、JPEG 和 PDF。实际生产环境还应增加文件内容校验和恶意文件扫描。
package com.example.demo.upload;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardOpenOption;
import java.util.Map;
import java.util.Set;
import java.util.UUID;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestPart;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.multipart.MaxUploadSizeExceededException;
import org.springframework.web.multipart.MultipartFile;
import org.springframework.web.server.ResponseStatusException;
@RestController
@RequestMapping("/api/files")
public class UploadController {
private static final Set<String> ALLOWED_TYPES = Set.of(
MediaType.IMAGE_PNG_VALUE,
MediaType.IMAGE_JPEG_VALUE,
MediaType.APPLICATION_PDF_VALUE
);
private final Path uploadRoot;
public UploadController(@Value("${app.upload-dir:uploads}") String uploadDir)
throws IOException {
this.uploadRoot = Path.of(uploadDir).toAbsolutePath().normalize();
Files.createDirectories(this.uploadRoot);
}
@PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<UploadResponse> upload(
@RequestPart("file") MultipartFile file) throws IOException {
if (file.isEmpty()) {
throw new ResponseStatusException(
HttpStatus.BAD_REQUEST, "文件为空");
}
String contentType = file.getContentType();
if (contentType == null || !ALLOWED_TYPES.contains(contentType)) {
throw new ResponseStatusException(
HttpStatus.UNSUPPORTED_MEDIA_TYPE, "不支持的文件类型");
}
// 不使用原始文件名,避免路径穿越、重名覆盖和非法字符
String storedName = UUID.randomUUID() + extensionOf(contentType);
Path target = uploadRoot.resolve(storedName).normalize();
if (!target.startsWith(uploadRoot)) {
throw new ResponseStatusException(
HttpStatus.BAD_REQUEST, "非法存储路径");
}
// CREATE_NEW 保证目标已存在时直接失败,不静默覆盖文件
try (InputStream input = file.getInputStream();
OutputStream output = Files.newOutputStream(
target, StandardOpenOption.CREATE_NEW,
StandardOpenOption.WRITE)) {
input.transferTo(output);
}
UploadResponse body =
new UploadResponse(storedName, file.getSize(), contentType);
return ResponseEntity.status(HttpStatus.CREATED).body(body);
}
private static String extensionOf(String contentType) {
return switch (contentType) {
case MediaType.IMAGE_PNG_VALUE -> ".png";
case MediaType.IMAGE_JPEG_VALUE -> ".jpg";
case MediaType.APPLICATION_PDF_VALUE -> ".pdf";
default -> throw new IllegalArgumentException("未知文件类型");
};
}
}
record UploadResponse(String storedName, long size, String contentType) {
}
@RestControllerAdvice
class UploadExceptionHandler {
@ExceptionHandler(MaxUploadSizeExceededException.class)
ResponseEntity<Map<String, String>> handleMaxSize(
MaxUploadSizeExceededException exception) {
return ResponseEntity.status(HttpStatus.PAYLOAD_TOO_LARGE)
.body(Map.of("message", "上传文件超过大小限制"));
}
}预期结果:合法的 PNG、JPEG 或 PDF 被写入配置目录,响应状态为 201;空文件返回 400,类型不允许时返回 415,超过上传限制时进入大小异常处理。
MultipartFile#getContentType() 来自请求头,只能作为第一层过滤。面对不可信上传,还应校验文件签名字节、尝试安全解码,并按业务需要执行恶意文件扫描。
调用与预期结果
将 <PATH>/demo.png 替换为本机真实图片路径:
curl -i -X POST 'http://localhost:8080/api/files' \
-F 'file=@<PATH>/demo.png;type=image/png'预期输出:
HTTP/1.1 201
Content-Type: application/json
{"storedName":"<ID>.png","size":<BYTES>,"contentType":"image/png"}<ID> 为每次生成的 UUID,<BYTES> 为实际文件字节数。验证时还应确认 <PATH>/uploads 下出现同名文件,且文件大小与响应一致。
超过 10MB 时,应用的异常处理器预期返回:
HTTP/1.1 413
Content-Type: application/json
{"message":"上传文件超过大小限制"}若前置 Nginx 或网关的请求体上限更小,请求会在到达 Spring Boot 前被拒绝,此时响应格式由前置组件决定。
风险与排障
不要把原始文件名直接拼接到存储目录。文件名含 ../、绝对路径或同名文件时,可能产生越权写入或覆盖风险;更安全的做法是生成随机存储名,并单独保存展示文件名。
上传目录应位于 Web 根目录之外,并使用最小文件系统权限。容器重建或多实例部署时,本地磁盘可能丢失或节点间不可见;需要持久化、扩容或跨节点读取时,应改用对象存储并记录对象键。
排查时依次检查:
- 返回 400:确认表单字段名是
file,且文件不为空。 - 返回 413:同时核对 Spring Boot、Nginx、网关和云负载均衡的请求体限制。
- 返回 415:核对客户端声明类型,并检查服务端允许列表;不要仅通过扩展名放行。
- 返回 500 或无法落盘:检查目录是否存在、运行用户是否有写权限、磁盘是否已满。
- 上传成功但后续无法访问:不要直接暴露磁盘目录,使用受鉴权的下载接口或对象存储临时签名地址。
速查提示:大小限制负责拒绝超量请求,类型与内容校验负责阻止伪装文件,两者都必须配置。
以流式响应返回文件并设置下载名称。
下载文件
用于从 Spring Boot 接口流式返回服务器文件,并通过 Content-Disposition 指定浏览器保存名称。示例不会先把整个文件读入 byte[],适合报表、日志包和中大型导出文件。
基本用法
接口从固定导出目录读取 CSV。路径检查、文件存在性和文件大小读取都在响应开始写出前完成,正文通过 StreamingResponseBody 按流传输。
package com.example.demo;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import org.springframework.http.ContentDisposition;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody;
@RestController
public class FileDownloadController {
private static final Path EXPORT_DIR = Path.of("/opt/app/exports");
@GetMapping("/api/files/report")
public ResponseEntity<StreamingResponseBody> download() throws IOException {
Path file = EXPORT_DIR.resolve("daily-report.csv").normalize();
// 先校验目标文件,再开始写响应,避免发送一半后才发现文件不可读
if (!file.startsWith(EXPORT_DIR) || !Files.isRegularFile(file)) {
throw new ResponseStatusException(HttpStatus.NOT_FOUND);
}
long size = Files.size(file);
StreamingResponseBody body = outputStream -> {
try (InputStream inputStream = Files.newInputStream(file)) {
inputStream.transferTo(outputStream);
}
};
ContentDisposition disposition = ContentDisposition.attachment()
.filename("daily-report.csv")
.build();
return ResponseEntity.ok()
.header(HttpHeaders.CONTENT_DISPOSITION, disposition.toString())
.contentType(MediaType.parseMediaType("text/csv"))
.contentLength(size)
.body(body);
}
}预期结果:请求 /api/files/report 成功后返回文件字节流,浏览器按 daily-report.csv 保存。
HTTP/1.1 200
Content-Type: text/csv
Content-Length: <SIZE>
Content-Disposition: attachment; filename="daily-report.csv"<SIZE> 为实际文件字节数。需要中文文件名时可使用 filename("交易报表.csv", StandardCharsets.UTF_8),不要手工拼接 Content-Disposition。
关键设置
Content-Type 应与文件类型一致;未知二进制文件可使用 application/octet-stream。已知文件大小时设置 Content-Length,便于客户端显示进度。动态生成内容时,也可在 StreamingResponseBody 回调中边生成边写出。
风险与边界
当文件名或路径来自请求参数时,可能发生目录穿越,后果是泄露服务器任意可读文件。更安全的做法是只接收业务文件 ID,由服务端映射到固定目录,并在 normalize() 后校验 startsWith()。
响应开始写出后才发生异常,通常无法再改成统一 JSON 错误体。因此鉴权、文件存在性、大小和业务状态检查应尽量提前完成,并记录 traceId、文件 ID 和失败原因。
排障清单
- 返回
404:确认文件存在、进程用户有读取权限,并检查容器挂载路径。 - 下载中断:检查反向代理超时、客户端断开以及磁盘 I/O 异常。
- 内存上涨:确认没有使用
Files.readAllBytes()或先构造完整byte[]。 - 文件名乱码:优先使用
ContentDisposition的文件名重载,不要手工拼接响应头。
速查:固定目录、写流前校验、流式传输三项同时满足,才适合生产下载接口。
自定义日期格式、空值处理和字段输出规则。
配置 JSON 序列化
用于统一 Spring Boot 返回 JSON 时的日期格式、空值策略和字段输出规则。以下写法通过 Jackson2ObjectMapperBuilderCustomizer 增量调整自动配置的 ObjectMapper,避免直接替换 Spring Boot 的默认对象映射器。
全局配置与字段规则
示例把 LocalDateTime 输出为 yyyy-MM-dd HH:mm:ss,全局省略 null,并通过字段级注解重命名、隐藏字段和省略空字符串。
package com.example.demo;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import com.fasterxml.jackson.annotation.JsonIgnore;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
import com.fasterxml.jackson.datatype.jsr310.ser.LocalDateTimeSerializer;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer;
import org.springframework.context.annotation.Bean;
@SpringBootApplication
public class JsonDemoApplication {
private static final DateTimeFormatter DATE_TIME_FORMATTER =
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
public static void main(String[] args) {
SpringApplication.run(JsonDemoApplication.class, args);
}
@Bean
Jackson2ObjectMapperBuilderCustomizer jsonCustomizer() {
return builder -> {
JavaTimeModule module = new JavaTimeModule();
module.addSerializer(
LocalDateTime.class,
new LocalDateTimeSerializer(DATE_TIME_FORMATTER)
);
// 全局只省略 null;空字符串通过字段级 NON_EMPTY 控制
builder.modulesToInstall(module);
builder.serializationInclusion(JsonInclude.Include.NON_NULL);
};
}
@Bean
CommandLineRunner verify(com.fasterxml.jackson.databind.ObjectMapper mapper) {
return args -> {
UserView value = new UserView(
1001L,
"",
null,
"server-only",
LocalDateTime.of(2026, 8, 2, 10, 30, 0)
);
System.out.println(mapper.writeValueAsString(value));
};
}
record UserView(
@JsonProperty("user_id") Long userId,
@JsonInclude(JsonInclude.Include.NON_EMPTY) String nickname,
String email,
@JsonIgnore String internalToken,
LocalDateTime createdAt
) {
}
}预期输出:
{"user_id":1001,"createdAt":"2026-08-02 10:30:00"}nickname 是空字符串,被字段级 NON_EMPTY 省略;email 为 null,被全局 NON_NULL 省略;internalToken 被 @JsonIgnore 隐藏;userId 输出为 user_id。
常用规则
@JsonProperty("name"):修改 JSON 字段名。@JsonIgnore:禁止字段参与序列化和反序列化。@JsonInclude(NON_EMPTY):省略null、空字符串和空集合等空值。@JsonFormat(pattern = "..."):适合只覆盖单个日期字段格式。
全局约定放在 customizer 中,少数字段例外放在 DTO 注解中。不要直接把数据库实体作为公开接口响应,否则字段新增或内部状态可能意外暴露。
风险与边界
直接声明新的 ObjectMapper Bean 可能替换或绕过 Spring Boot 已配置的模块、命名策略和消息转换器,导致日期、分页对象或第三方类型的序列化行为变化。优先使用 customizer;确需自建时,应完整注册所需模块并执行接口回归测试。
修改全局日期格式或空值策略会影响全部接口,可能造成前端解析失败、签名字段变化或缓存键不一致。上线前应执行 JSON 契约测试,并优先为新增接口创建独立 DTO。
排障清单
- 配置不生效:检查是否存在自定义
ObjectMapper或HttpMessageConverter。 - 日期仍为默认格式:确认
jackson-datatype-jsr310模块已生效。 - 某字段仍输出
null:检查字段或类上的@JsonInclude是否覆盖全局规则。 - 字段意外消失:检查
@JsonIgnore、访问级别以及字段与属性名称。 - 测试与接口运行结果不同:确认测试使用的是 Spring 上下文中的
ObjectMapper。
速查:统一规则用 customizer,字段差异用 DTO 注解,全局变更必须经过契约测试。
在控制器执行前后处理鉴权、日志或上下文信息。
添加请求拦截器
当请求已经进入 Spring MVC、但还未执行控制器方法时,可以用 HandlerInterceptor 统一做鉴权、访问日志、请求上下文或耗时统计。它位于 DispatcherServlet 的处理链中,适合围绕控制器调用扩展行为,而不是处理原始 Servlet 请求流。
执行位置
正常请求先执行 preHandle,返回 true 后才进入控制器;控制器完成后可进入 postHandle,请求最终结束时调用 afterCompletion。如果 preHandle 返回 false,当前拦截器会阻止后续 Handler 执行。

postHandle 不适合修改已经写出的 @ResponseBody 内容;需要包装请求体、响应体或处理更底层的 Servlet 行为时,应优先考虑过滤器。
注册与验证
前置条件是项目已经引入 Spring MVC,例如 Spring Boot Web Starter。下面的单文件示例同时注册拦截器和测试端点,可直接放入常规 Spring Boot Web 项目中运行。
package com.example.demo;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
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;
import org.springframework.web.servlet.HandlerInterceptor;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@SpringBootApplication
@RestController
@RequestMapping("/api")
public class DemoApplication implements WebMvcConfigurer {
private final HandlerInterceptor loggingInterceptor = new HandlerInterceptor() {
@Override
public boolean preHandle(HttpServletRequest request,
HttpServletResponse response,
Object handler) {
System.out.println("interceptor before " + request.getRequestURI());
return true;
}
@Override
public void afterCompletion(HttpServletRequest request,
HttpServletResponse response,
Object handler,
Exception ex) {
// 请求完成后记录最终状态,异常请求也会走这里。
System.out.println("interceptor after " + response.getStatus());
}
};
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
// 只覆盖业务 API,并显式排除健康检查。
registry.addInterceptor(loggingInterceptor)
.addPathPatterns("/api/**")
.excludePathPatterns("/api/health");
}
@GetMapping("/ping")
public String ping() {
return "pong";
}
}预期结果:应用能够正常启动,/api/ping 会经过拦截器,/api/health 不在该拦截规则内。启动后执行:
curl -sS http://localhost:<PORT>/api/ping将 <PORT> 替换为应用实际监听端口;未配置 server.port 时 Spring Boot 默认使用 8080。
预期输出:
pong控制台还会出现与该请求对应的关键日志:
interceptor before /api/ping
interceptor after 200日志前缀可能因本地配置不同,但这两段自定义文本和状态码应与示例一致。
鉴权与上下文处理
鉴权失败时,应在 preHandle 中设置合适的 HTTP 状态码并返回 false,同时确保失败响应已经完整写出。拦截器通常是单例,不要把请求级数据放进可变成员字段,否则并发请求会共享同一个实例。
如果当前拦截器自己创建了 ThreadLocal 数据后又返回 false,应在返回前主动清理,因为它自己的 afterCompletion 不会再执行。需要确保无论控制器是否抛异常都清理线程上下文时,Servlet 过滤器中的 try/finally 往往更稳妥。
风险与边界
HandlerInterceptor 适合“围绕 MVC 控制器”的横切逻辑;请求或响应包装、字符编码等更靠近 Servlet 容器的需求更适合过滤器。注册时优先用明确的 addPathPatterns 与 excludePathPatterns 控制范围,避免无意覆盖健康检查或不需要拦截的资源。
在 Servlet 层统一处理请求、响应和包装逻辑。
添加 Servlet 过滤器
需要在请求进入 Spring MVC 之前统一处理请求头、响应头、请求包装、链路标识或底层访问日志时,可以使用 Servlet Filter。在 Spring Boot 3 中相关 API 位于 jakarta.servlet 包,过滤器通常比 MVC 拦截器更早执行。
请求链位置
过滤器位于 Servlet 容器与 DispatcherServlet 之间。进入链路时先执行过滤器前半段,调用 filterChain.doFilter 后把控制权交给下一个过滤器或 Servlet,返回时再继续执行过滤器后半段,因此适合用 try/finally 做清理和耗时统计。

与 HandlerInterceptor 相比,过滤器能处理更原始的 HttpServletRequest 和 HttpServletResponse,但不知道最终会匹配到哪个控制器方法,因此不适合依赖 Spring MVC Handler 元数据做精细判断。
注册过滤器
下面使用 FilterRegistrationBean 显式注册 OncePerRequestFilter,既能控制顺序和 URL 范围,又不会依赖 Servlet 注解扫描。前置条件是项目已经引入 Spring Boot Web Starter。
package com.example.demo;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.core.Ordered;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;
import java.util.UUID;
@SpringBootApplication
@RestController
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
@Bean
FilterRegistrationBean<RequestIdFilter> requestIdFilter() {
FilterRegistrationBean<RequestIdFilter> registration =
new FilterRegistrationBean<>();
registration.setFilter(new RequestIdFilter());
registration.addUrlPatterns("/*");
registration.setOrder(Ordered.HIGHEST_PRECEDENCE);
return registration;
}
@GetMapping("/ping")
String ping() {
return "pong";
}
static class RequestIdFilter extends OncePerRequestFilter {
@Override
protected void doFilterInternal(HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain)
throws ServletException, IOException {
String requestId = request.getHeader("X-Request-Id");
if (requestId == null || requestId.isBlank()) {
requestId = UUID.randomUUID().toString();
}
response.setHeader("X-Request-Id", requestId);
System.out.println("filter before " + request.getRequestURI());
try {
filterChain.doFilter(request, response);
} finally {
// 下游异常时也要完成清理和结束日志。
System.out.println("filter after " + response.getStatus());
}
}
}
}预期结果:过滤器对 /* 生效,并在响应中回写请求 ID;排序值使它尽量靠前进入 Spring Boot 的过滤器链。
验证请求与响应
发送固定请求 ID,可直接核对响应体与自定义响应头:
headers=$(mktemp)
curl -sS -D "$headers" -H "X-Request-Id: demo-123" "http://localhost:<PORT>/ping"
grep -i '^X-Request-Id:' "$headers"
rm -f "$headers"将 <PORT> 替换为应用实际监听端口;未配置 server.port 时 Spring Boot 默认使用 8080。
预期输出:
pong
X-Request-Id: demo-123控制台关键日志为:
filter before /ping
filter after 200HTTP 头名称大小写可能由容器调整,但应能看到请求 ID 为 demo-123。
顺序、包装与清理
多个过滤器同时存在时,顺序会影响认证、请求包装和异常处理结果。FilterRegistrationBean 的 setOrder 用于控制本过滤器的相对顺序;只需要全局简单过滤时,也可以选择组件扫描注册,但不要用多种方式重复注册同一个过滤器。
如果要多次读取请求体或响应体,不能直接重复消费原始流。应使用合适的 HttpServletRequestWrapper、HttpServletResponseWrapper 或 Spring 的缓存包装器,并评估大请求场景的内存成本。
风险与恢复
除非明确要短路请求,否则不要省略 filterChain.doFilter,否则请求会停在当前过滤器中。过滤器里创建的 ThreadLocal、MDC 或其他线程上下文应在 finally 中清理,避免线程池复用导致上下文泄漏到后续请求。
记录请求路径、耗时、状态码和追踪标识。
记录请求日志
用于在每次 HTTP 请求结束后统一记录请求方法、路径、状态码、耗时和追踪标识,适合定位慢接口、异常请求和跨服务调用。过滤器只读取请求头和请求元数据,不读取请求体,避免影响流式请求和大文件上传。
请求链路
OncePerRequestFilter 适合承载这类横切日志逻辑:进入过滤器时解析或生成追踪标识,设置 MDC 和响应头;业务处理完成后统一记录最终状态码和耗时。

基本实现
过滤器复用合法的 X-Trace-Id,不合法或缺失时生成新的随机标识。日志放在 finally 中,确保正常返回和未被处理器接管的异常都能执行收尾记录。
package com.example.demo.web;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;
import java.util.UUID;
import java.util.regex.Pattern;
@Component
public class RequestLogFilter extends OncePerRequestFilter {
private static final Logger log = LoggerFactory.getLogger(RequestLogFilter.class);
private static final String TRACE_HEADER = "X-Trace-Id";
private static final Pattern SAFE_TRACE_ID =
Pattern.compile("[A-Za-z0-9._-]{1,64}");
@Override
protected void doFilterInternal(
HttpServletRequest request,
HttpServletResponse response,
FilterChain filterChain) throws ServletException, IOException {
String traceId = resolveTraceId(request);
long startNanos = System.nanoTime();
MDC.put("traceId", traceId);
response.setHeader(TRACE_HEADER, traceId);
try {
filterChain.doFilter(request, response);
} finally {
long durationMs = (System.nanoTime() - startNanos) / 1_000_000;
log.info(
"method={} path={} status={} durationMs={} traceId={}",
request.getMethod(),
request.getRequestURI(),
response.getStatus(),
durationMs,
traceId
);
MDC.remove("traceId");
}
}
private String resolveTraceId(HttpServletRequest request) {
String incoming = request.getHeader(TRACE_HEADER);
if (incoming != null && SAFE_TRACE_ID.matcher(incoming).matches()) {
return incoming;
}
return UUID.randomUUID().toString().replace("-", "");
}
}预期输出:
<TIME> INFO <THREAD> com.example.demo.web.RequestLogFilter : method=GET path=/api/orders status=200 durationMs=18 traceId=<ID><TIME>、<THREAD> 和 <ID> 会随运行环境变化。排查时先按 traceId 串联同一次调用,再看 status 判断结果,最后用 durationMs 筛选慢请求。
高频用法
客户端主动传递追踪标识,网关、应用和下游服务可以围绕同一个值串联日志。
curl -i http://localhost:<PORT>/api/orders -H 'X-Trace-Id: order-query-001'预期结果:
HTTP/1.1 200
X-Trace-Id: order-query-001
Content-Type: application/json
<RESPONSE_BODY><PORT> 和 <RESPONSE_BODY> 会随运行环境变化。健康检查、静态资源或高频探针不需要逐条记录时,可覆盖 shouldNotFilter 按固定路径排除,避免使用模糊包含匹配误跳过业务接口。
风险与边界
不要默认记录请求体、响应体、Cookie、Authorization、银行卡号或身份证号。直接打印完整业务对象可能造成敏感信息泄露、日志量暴涨和序列化开销增加,更稳妥的做法是只记录字段白名单,并对手机号、账号等做脱敏。
生产环境把全部请求固定记录为 INFO 会增加磁盘和日志平台成本。高流量场景可排除健康检查,并对成功请求采样,同时保留异常和慢请求的完整记录。
排障清单
没有日志时先确认过滤器位于 Spring 扫描路径内,并检查该包日志级别是否允许 INFO。状态码与业务结果不一致时,检查统一异常处理器是否在请求返回前设置了正确状态。追踪标识断链时,继续检查网关和 HTTP 客户端是否透传 X-Trace-Id。
注意:不要依赖过滤器捕获异常后手工把状态码改成
500来判断业务失败;异常可能已经由 Spring 的异常处理机制转换为最终响应,日志应以过滤器结束时的实际response.getStatus()为准。
按包名或环境调整日志输出级别。
配置日志级别
用于按包名控制日志详细程度,并通过 Profile 为不同环境设置不同级别。常用做法是先配置 root 默认级别,再对业务包或排障包做更具体的覆盖。
基本配置
在 application.yml 中设置通用默认值,在 application-prod.yml 中覆盖生产环境。Logger 名称越具体,匹配到的配置越具体。
# application.yml
logging:
level:
root: INFO
com.example.pay: DEBUG
org.springframework.web: INFO# application-prod.yml
logging:
level:
root: WARN
com.example.pay: INFO
com.example.pay.integration: DEBUG以生产 Profile 启动:
java -jar <PATH>/app.jar --spring.profiles.active=prod预期结果:
com.example.pay.integration -> DEBUG
com.example.pay -> INFO
其他未单独配置的包 -> WARN<PATH> 替换为实际 JAR 路径。生产配置生效后,com.example.pay.integration 输出 DEBUG 及以上,com.example.pay 的其他类输出 INFO 及以上,未单独配置的 Logger 按 WARN 及以上输出。
高频配置
容器或 systemd 场景可以用环境变量临时覆盖某个包的级别,不修改配置文件:
LOGGING_LEVEL_COM_EXAMPLE_PAY_INTEGRATION=TRACE java -jar <PATH>/app.jar --spring.profiles.active=prod预期结果:
com.example.pay.integration -> TRACE这种方式适合包级 Logger。包含特殊字符、大小写敏感语义或需要精确表达类名的 Logger,应优先使用配置文件或其他明确的属性来源。
启用 Spring Boot Actuator 并暴露 loggers 端点后,可以查询当前生效级别:
curl -s http://localhost:<PORT>/actuator/loggers/com.example.pay.integration预期输出:
{"configuredLevel":"DEBUG","effectiveLevel":"DEBUG"}需要短时在线排障时,可以动态调整,不重启应用:
curl -i -X POST http://localhost:<PORT>/actuator/loggers/com.example.pay.integration -H 'Content-Type: application/json' -d '{"configuredLevel":"TRACE"}'预期结果:
HTTP/1.1 204 No Content排障结束后可清除运行时覆盖:
curl -i -X POST http://localhost:<PORT>/actuator/loggers/com.example.pay.integration -H 'Content-Type: application/json' -d '{"configuredLevel":null}'预期结果:
HTTP/1.1 204 No Content运行时修改通常只影响当前应用实例,重启后重新按配置属性确定级别。
风险与边界
生产环境长时间开启 DEBUG 或 TRACE,可能增加磁盘写入、日志采集成本和线程开销,并暴露 SQL 参数、请求头或第三方响应。更稳妥的做法是只提升最小范围的业务包,并设置明确的恢复时间。
把 root 直接降到 ERROR 可能隐藏连接池告警、重试和降级信息。生产默认通常保留在 WARN,再按需要为核心业务包设置 INFO 或更低级别。
Actuator 的 loggers 端点支持运行时修改,因此必须结合鉴权和网络访问控制使用,不应直接暴露到公网。
排障清单
配置未生效时,先确认激活的 Profile 和文件名是否匹配,再检查启动参数、环境变量以及配置中心是否覆盖本地 YAML。某个类仍无日志时,确认实际 Logger 名称通常是完整类名,并检查父包级别是否限制了输出。日志突然暴涨时,优先查询运行时 configuredLevel,排除临时动态修改尚未清除。
配置日志文件路径、滚动策略和保留周期。
输出日志到文件
用于将 Spring Boot 日志写入固定文件,并按日期和文件大小滚动压缩,避免单个日志文件无限增长。以下配置适用于 Spring Boot 默认的 Logback 日志实现。
基本配置
在 application.yml 中同时配置日志文件名和滚动策略:
logging:
file:
# 相对路径基于应用启动时的工作目录
name: ./logs/application.log
level:
root: INFO
com.example: INFO
logback:
rollingpolicy:
file-name-pattern: ./logs/application.%d{yyyy-MM-dd}.%i.log.gz
max-file-size: 100MB
max-history: 30
total-size-cap: 3GB
clean-history-on-start: false日志首先写入 logs/application.log。当天文件超过 100MB 时递增 %i,跨天后按日期归档并压缩;历史文件最多保留 30 天,同时受 3GB 总容量限制。
关键参数
logging.file.name 指定完整文件名;logging.file.path 只指定目录,两者同时配置时以 name 为准。生产环境建议明确配置 name,避免工作目录变化导致日志路径不符合预期。
max-file-size 控制单个归档文件大小,max-history 控制保留周期,total-size-cap 控制全部归档文件的总容量。容量上限生效时,旧文件可能在达到保留周期前被删除。
file-name-pattern 用于定义归档文件名,其中 %d 表示日期、%i 表示同一天内的滚动索引。只按日期滚动时,当天日志可能持续变大;同时使用 %d 和 %i 可以按日期及大小双重切分。
启动与验证
在项目根目录创建日志目录并启动应用:
mkdir -p logs
./mvnw spring-boot:run预期输出:
<TIME> INFO <PID> --- [main] <APPLICATION_CLASS> : Started <APPLICATION_NAME> in <SECONDS> seconds启动后检查文件及最后几行日志:
ls -lh logs
tail -n 3 logs/application.log预期输出:
-rw-r--r-- 1 <USER> <GROUP> <SIZE> <TIME> application.log
<TIME> INFO <PID> --- [main] <APPLICATION_CLASS> : Started <APPLICATION_NAME> in <SECONDS> seconds<TIME>、<PID>、<SIZE> 和应用类名会随实际运行环境变化。能够看到 application.log 且其中包含启动日志,说明文件输出已经生效。
需要验证滚动时,可让日志量超过 max-file-size 或跨过日期边界,再检查是否出现带日期和索引的 .log.gz 归档文件。
预期结果:超过滚动条件后,归档文件按 file-name-pattern 命名,例如 application.<DATE>.1.log.gz;具体索引和日期取决于实际滚动次数与时间。
风险与边界
应用用户对日志目录没有写权限时,文件日志可能初始化失败,导致启动报错或只保留控制台日志。生产部署前应创建目录并将其授权给应用运行用户;容器环境通常更适合输出到标准输出,再由日志采集器统一持久化。
将根日志级别长期设为 DEBUG 或 TRACE 会显著增加磁盘写入量,还可能记录请求参数、令牌或个人信息。排障时应只提高目标包的级别,并在问题确认后恢复为 INFO。
磁盘空间耗尽可能造成日志丢失、I/O 延迟,甚至影响同磁盘上的数据库或应用文件。应同时设置 total-size-cap、磁盘告警和外部日志采集,不要只依赖保留天数。
排障清单
日志文件未生成时,先执行 pwd 确认工作目录,再检查 logs 目录权限。若项目存在 logback-spring.xml 或其他自定义 Logback 配置,其中的 Appender 可能改变或覆盖默认配置行为。
日志未滚动时,确认文件是否已超过 max-file-size 或日期是否已经变化。使用 Log4j2 替换默认 Logback 后,logging.logback.rollingpolicy 不再控制滚动策略,需要改用 Log4j2 对应配置。
配置 JDBC 地址、账号、驱动和连接池参数。
配置数据源
用于为 Spring Boot 应用配置 JDBC 连接信息和 HikariCP 连接池。下面以 MySQL 为例,账号和密码通过环境变量注入,避免敏感信息进入配置仓库。
依赖与基本配置
项目至少需要 JDBC Starter 和对应数据库的 JDBC 驱动。Maven 项目可使用以下依赖:
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
<groupId>com.mysql</groupId>
<artifactId>mysql-connector-j</artifactId>
<scope>runtime</scope>
</dependency>
</dependencies>预期结果:
BUILD SUCCESS在 application.yml 中配置连接地址、账号、驱动和连接池参数:
spring:
datasource:
url: jdbc:mysql://${DB_HOST:127.0.0.1}:${DB_PORT:3306}/${DB_NAME:appdb}?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Kuala_Lumpur&connectTimeout=5000&socketTimeout=30000
username: ${DB_USERNAME}
password: ${DB_PASSWORD}
driver-class-name: com.mysql.cj.jdbc.Driver
hikari:
pool-name: AppHikariPool
maximum-pool-size: 10
minimum-idle: 2
connection-timeout: 30000
validation-timeout: 5000
idle-timeout: 600000
max-lifetime: 1800000
keepalive-time: 120000Spring Boot 的 JDBC 自动配置默认使用 HikariCP(在 HikariCP 位于 classpath 时)。驱动存在时通常可以根据 JDBC URL 自动识别,显式配置 driver-class-name 则便于依赖或驱动配置错误时尽早暴露问题。
连接池参数
maximum-pool-size 是单个应用实例可同时持有的最大连接数。部署多个实例时,总连接上限约为实例数乘以该值,还必须为数据库管理连接、任务程序和其他客户端保留余量。
connection-timeout 是业务线程从连接池获取连接时的最长等待时间,不等同于建立数据库网络连接的超时。示例中的 connectTimeout 和 socketTimeout 属于 MySQL JDBC 驱动参数,分别控制建立连接和读取响应的超时。
max-lifetime 应小于数据库、代理或防火墙主动回收连接的时间,并预留一定安全余量。keepalive-time 应小于 max-lifetime,用于定期检查空闲连接,不能替代合理的生命周期设置。
启动与验证
先设置实际环境变量,再启动应用:
export DB_HOST=127.0.0.1
export DB_PORT=3306
export DB_NAME=appdb
export DB_USERNAME=appuser
export DB_PASSWORD='<PASSWORD>'
./mvnw spring-boot:run预期输出:
<TIME> INFO <PID> --- [main] com.zaxxer.hikari.HikariDataSource : AppHikariPool - Starting...
<TIME> INFO <PID> --- [main] com.zaxxer.hikari.pool.HikariPool : AppHikariPool - Added connection <CONNECTION>
<TIME> INFO <PID> --- [main] com.zaxxer.hikari.HikariDataSource : AppHikariPool - Start completed.<PASSWORD> 需要替换为真实密码;日志时间、进程号和连接对象会因环境不同而变化。出现 Start completed 表示连接池已经完成初始化并至少成功建立了一个连接。
也可以在启动应用前使用 MySQL 客户端验证网络、账号和数据库名称:
mysql --host="$DB_HOST" --port="$DB_PORT" --user="$DB_USERNAME" --password --database="$DB_NAME" --execute='SELECT 1 AS ok;'预期输出:
Enter password:
+----+
| ok |
+----+
| 1 |
+----+该命令成功但应用仍连接失败时,应继续检查 JDBC URL 参数、驱动版本和应用实际读取的 Profile。
风险与边界
账号密码直接写入 application.yml 并提交仓库会造成凭据泄露。应使用环境变量、容器 Secret 或集中密钥服务,并为应用账号授予最小数据库权限。
盲目增大连接池会让数据库连接数、线程和内存压力快速上升,可能造成所有应用同时超时。应根据数据库最大连接数、应用实例数和实际并发压测结果分配连接,而不是按请求并发数一比一配置。
多数据源场景不能只复制多组 spring.datasource 属性。通常需要分别声明 DataSourceProperties、DataSource 和事务管理器,并为默认数据源标记 @Primary,否则自动装配可能无法判断默认数据源。
排障清单
出现 Communications link failure 时检查主机、端口、防火墙、容器网络和 TLS 配置;出现 Access denied 时检查账号密码、来源主机授权和数据库权限;出现 Unknown database 时检查数据库名称及环境变量是否为空。
出现 Connection is not available, request timed out 通常表示连接池无法在超时时间内提供可用连接,应检查慢 SQL、长事务、连接泄漏和数据库响应时间。排障期间可以临时配置 leak-detection-threshold 定位长时间未归还的连接,但不宜长期使用过低阈值,以免产生大量误报日志。
执行 SQL 查询、更新和批量操作。
使用 JdbcTemplate
JdbcTemplate 适合需要直接控制 SQL 的场景,可用参数化查询完成增删改查、对象映射和批量写入。下面给出一个基于 Spring Boot 3.x + H2 的最小可运行模板。
前置配置
加入 JDBC Starter 和测试数据库驱动。生产环境将 H2 替换为 MySQL、PostgreSQL 等实际驱动,并按实际数据库配置数据源。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<scope>runtime</scope>
</dependency>创建 src/main/resources/schema.sql:
create table app_user (
id bigint generated by default as identity primary key,
name varchar(64) not null
);创建 src/main/resources/data.sql:
insert into app_user(name) values ('Alice');
insert into app_user(name) values ('Bob');对于内嵌数据库,Spring Boot 会自动执行上述初始化脚本,并注册可注入的 JdbcTemplate。
查询、更新与批量操作
所有动态值都通过 ? 绑定,不要把用户输入直接拼接到 SQL。下面代码可直接放入 Spring Boot 启动类。
package com.example.demo;
import java.util.Arrays;
import java.util.List;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.jdbc.core.JdbcTemplate;
@SpringBootApplication
public class DemoApplication implements CommandLineRunner {
private final JdbcTemplate jdbcTemplate;
public DemoApplication(JdbcTemplate jdbcTemplate) {
this.jdbcTemplate = jdbcTemplate;
}
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
@Override
public void run(String... args) {
jdbcTemplate.update(
"insert into app_user(name) values (?)",
"Carol");
int updated = jdbcTemplate.update(
"update app_user set name = ? where name = ?",
"Alice Zhang", "Alice");
int[] batchRows = jdbcTemplate.batchUpdate(
"insert into app_user(name) values (?)",
List.of(new Object[]{"Dave"}, new Object[]{"Eve"}));
List<User> users = jdbcTemplate.query(
"select id, name from app_user order by id",
(rs, rowNum) -> new User(
rs.getLong("id"),
rs.getString("name")));
System.out.println("updated=" + updated);
System.out.println("batch=" + Arrays.toString(batchRows));
users.forEach(System.out::println);
}
record User(long id, String name) {
}
}运行:
./mvnw spring-boot:run预期输出中可能夹杂 Spring Boot 启动日志,业务输出为:
updated=1
batch=[1, 1]
User[id=1, name=Alice Zhang]
User[id=2, name=Bob]
User[id=3, name=Carol]
User[id=4, name=Dave]
User[id=5, name=Eve]其中 updated=1 表示 Alice 被更新为一行;batch=[1, 1] 表示两条批量插入语句分别影响一行。示例使用全新内嵌数据库,因此 ID 从 1 开始;实际环境的 ID 取决于已有数据。
常用方法
| 方法 | 适用场景 | 返回值 |
|---|---|---|
query(...) |
查询多行并映射为对象 | List<T> |
queryForObject(...) |
查询单行或单值 | T;结果数量不符合要求时抛异常 |
update(...) |
INSERT、UPDATE、DELETE |
受影响行数 |
batchUpdate(...) |
同一 SQL 批量绑定参数 | 每条语句的影响行数 |
命名参数较多时可改用 NamedParameterJdbcTemplate,避免维护大量位置参数。
风险与边界
始终使用占位符或命名参数,避免 SQL 注入。一次性读取大量数据会增加堆内存压力,需要时改用分页、游标或流式处理。多条写操作要求原子性时,应把它们放入带 @Transactional 的业务事务中,而不是依赖每条 SQL 独立提交。
批量写入过大可能造成事务日志膨胀、锁持有时间过长或连接超时。可以按数百到数千条分批处理,再结合数据库容量和实际吞吐压测确定批次大小。
排障清单
- 找不到
JdbcTemplateBean:确认已引入spring-boot-starter-jdbc,并检查数据源 URL、用户名和驱动。 - 报
BadSqlGrammarException:检查 SQL、字段名、数据库方言以及初始化脚本是否成功执行。 - 报参数索引或类型错误:核对
?数量、绑定顺序和 Java 类型。 - 更新一直阻塞:检查长事务、未提交连接和数据库锁等待,先定位阻塞会话再决定是否终止。
queryForObject报结果数量异常:零行或多行都不符合其单结果约束,可改用query自行处理结果数量。
速查提示:需要精确控制 SQL 时使用 JdbcTemplate;复杂动态 SQL 可配合 NamedParameterJdbcTemplate 或专用 SQL 构建方案。
通过实体和 Repository 完成常见数据访问操作。
使用 Spring Data JPA
Spring Data JPA 适合用实体映射表结构,并通过 Repository 完成增删改查、派生查询和分页,减少重复的数据访问代码。下面使用 Spring Boot 3.x、H2 和 JpaRepository 演示一套可运行模板。
前置配置
加入 JPA Starter 和测试数据库驱动:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<scope>runtime</scope>
</dependency>创建 src/main/resources/application.yml:
spring:
datasource:
url: jdbc:h2:mem:demo;DB_CLOSE_DELAY=-1
username: sa
password:
jpa:
hibernate:
ddl-auto: create-drop
open-in-view: falsecreate-drop 适合演示和测试;生产环境通常使用 Flyway 或 Liquibase 管理表结构,避免应用启动时直接改动生产数据库。
定义实体与 Repository
Spring Boot 3 使用 jakarta.persistence。实体需要主键和受保护的无参构造方法,字段映射应与数据库设计保持一致。
package com.example.demo;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
@Entity
@Table(name = "app_user")
public class UserEntity {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
private String name;
private String email;
protected UserEntity() {
}
public UserEntity(String name, String email) {
this.name = name;
this.email = email;
}
public Long getId() {
return id;
}
public void rename(String name) {
this.name = name;
}
@Override
public String toString() {
return "UserEntity{id=" + id
+ ", name='" + name + "'"
+ ", email='" + email + "'}";
}
}package com.example.demo;
import java.util.List;
import org.springframework.data.jpa.repository.JpaRepository;
public interface UserRepository extends JpaRepository<UserEntity, Long> {
List<UserEntity> findByNameContainingIgnoreCaseOrderByIdAsc(String keyword);
}Containing、IgnoreCase 和 OrderByIdAsc 会被解析为包含匹配、忽略大小写和按 id 升序排序。条件复杂或需要联表时,优先使用明确的 @Query、Specification 或 Querydsl,不要无限拉长方法名。
完整运行示例
保存实体时使用 saveAll 的返回值取得实际生成的 ID,再用该实体执行更新,避免假设主键一定是 2。
package com.example.demo;
import java.util.List;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class DemoApplication implements CommandLineRunner {
private final UserRepository repository;
public DemoApplication(UserRepository repository) {
this.repository = repository;
}
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
@Override
public void run(String... args) {
List<UserEntity> saved = repository.saveAll(List.of(
new UserEntity("Alice", "alice@example.com"),
new UserEntity("Bob", "bob@example.com")));
List<UserEntity> matched =
repository.findByNameContainingIgnoreCaseOrderByIdAsc("ali");
System.out.println("matched=" + matched);
UserEntity bob = saved.get(1);
bob.rename("Bob Zhang");
repository.save(bob);
System.out.println("count=" + repository.count());
System.out.println("updated=" + repository.findById(bob.getId()).orElseThrow());
}
}运行:
./mvnw spring-boot:run预期输出中可能夹杂 Hibernate 和 Spring Boot 启动日志,业务输出类似:
matched=[UserEntity{id=1, name='Alice', email='alice@example.com'}]
count=2
updated=UserEntity{id=2, name='Bob Zhang', email='bob@example.com'}这里的示例数据库为空,因此通常会显示连续 ID;在已有数据的环境中,实际 ID 可能不同,但更新逻辑仍通过 bob.getId() 定位记录。
高频操作
| 目标 | 推荐写法 |
|---|---|
| 按主键查询 | findById(id),返回 Optional<T> |
| 新增或更新 | save(entity) |
| 批量保存 | saveAll(entities) |
| 分页查询 | findAll(PageRequest.of(page, size, sort)) |
| 删除 | deleteById(id) 或 delete(entity) |
分页参数通常从 0 开始。对外接口若使用从 1 开始的页码,应在边界层完成转换。
风险与边界
访问懒加载关联时,如果事务已经结束,可能触发 LazyInitializationException。应在事务内完成必要的数据映射,或使用 DTO 投影、实体图和精确的 join fetch。示例关闭 open-in-view,避免把数据库访问隐式延伸到 Web 层。
批量遍历关联对象容易产生 N+1 查询,使 SQL 数量随记录数增长。应检查生成 SQL、索引和查询次数,必要时使用批量加载或实体图。saveAll 也不等于数据库一定以单次批量发送;高吞吐写入还需要结合 Hibernate JDBC batch 配置,并按批次 flush、clear。
排障清单
- 启动报
Not a managed type:确认实体有@Entity,且位于默认扫描包或显式配置的扫描路径内。 - Repository 未注册:确认接口继承
JpaRepository,且接口包处于 Spring Data 扫描范围。 - 字段映射或建表失败:检查实体映射、保留字、字段长度和数据库方言。
- 修改实体未落库:确认对象处于持久化上下文中,并检查事务是否提交或回滚。
- 查询变慢:先检查生成 SQL、索引和分页,再排查 N+1、无界结果集及不必要的关联抓取。
速查提示:标准 CRUD 和实体关系优先使用 JPA;需要精细 SQL、复杂报表或极致批量性能时,可与 JdbcTemplate 并用。