Spring MVC 备忘清单

@RestController 和 @GetMapping 的组合构成了最基础的 API 接口。

// @RestController 是 @Controller 和 @ResponseBody 的组合注解。
// 1. @Controller：将类声明为 Spring IoC 容器中的一个控制器 Bean。
// 2. @ResponseBody：告知 Spring MVC，此类所有方法返回的都是数据，
//    需要直接写入 HTTP 响应体，通常是 JSON 格式。
@RestController
public class HelloController {

    // @GetMapping("/hello") 将 HTTP GET 请求映射到此方法。
    // 它是 @RequestMapping(method = RequestMethod.GET, path = "/hello") 的简写。
    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, Spring MVC!";
    }
}

所有请求都由 DispatcherServlet (前端控制器) 统一调度，流程简化如下：

1. 接收请求: Tomcat 等服务器将请求转交给 DispatcherServlet。
2. 查找处理器: DispatcherServlet 询问 HandlerMapping (处理器映射器)，找到能处理当前请求的 Controller 方法。
3. 调用方法: 通过 HandlerAdapter (处理器适配器) 调用目标 Controller 方法。
4. 处理返回: Controller 方法执行并返回数据。
5. 写入响应: HttpMessageConverter (消息转换器) 将返回的 Java 对象序列化为 JSON 等格式，写入 HTTP 响应体。

在 Service 层进行 PO、DTO、VO 之间的转换是核心业务之一。

场景: 将 User (PO) 转换为 UserVO (VO)。

// PO
@Data
public class User {
    private Long id;
    private String username;
    private Integer status; // 1-正常, 2-禁用
}

// VO
@Data
public class UserVO {
    private Long id;
    @Alias("username") // Hutool 注解，解决 username -> name 的名称不一致问题
    private String name;
    private String statusText;
}

// Service 层转换逻辑
private UserVO convertToVO(User user) {
    UserVO userVO = new UserVO();
    // 1. 使用 BeanUtil 拷贝同名/有@Alias注解的属性
    BeanUtil.copyProperties(user, userVO);
    // 2. 手动处理需要逻辑转换的属性
    if (user.getStatus() != null) {
        userVO.setStatusText(user.getStatus() == 1 ? "正常" : "已禁用");
    }
    return userVO;
}

标准的后端项目通常采用三层架构，职责清晰。

. 📂 src/main/java/com/example
├── 📂 controller      <- Controller层: Web入口, 参数校验, 调用Service
├── 📂 service         <- Service层: 业务核心, 事务管理, 组合Mapper
│   └── 📂 impl
└── 📂 mapper          <- Mapper层: 数据持久层, 与数据库交互

pom.xml 中必须添加 validation 启动器。

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

使用 jakarta.validation.constraints.* 下的注解为 DTO 字段添加校验规则。

@Data
public class UserSaveDTO {
    @NotBlank(message = "用户名不能为空")
    private String username;

    @NotBlank(message = "密码不能为空")
    @Size(min = 6, max = 20, message = "密码长度必须在6-20位之间")
    private String password;

    @Email(message = "邮箱格式不正确")
    private String email;
}

在 Controller 方法中，使用 @Validated 注解激活对 DTO 的校验。

@RestController
@Validated // 可在类上添加，以支持方法级别的参数校验
public class UserController {
    @PostMapping("/users")
    public void saveUser(@Validated @RequestBody UserSaveDTO dto) {
        // ... 如果校验失败，Spring MVC会抛出 MethodArgumentNotValidException
    }
}

校验失败的异常，应由全局异常处理器统一捕获并返回友好的错误信息。

使用 @Validated 的分组功能，可以用一个 DTO 应对不同场景（如新增、修改）的校验规则。

1. 定义分组接口:

   public interface ValidationGroups {
       interface Save {}
       interface Update {}
   }
   

2. 在 DTO 中使用 groups 属性:

   public class UserEditDTO {
       @NotNull(groups = ValidationGroups.Update.class)
       private Long id;
       @NotBlank(groups = ValidationGroups.Save.class)
       private String username;
   }
   

3. 在 Controller 中指定分组:

   @PostMapping
   public void saveUser(@Validated(ValidationGroups.Save.class) @RequestBody UserEditDTO dto) {}
   
   @PutMapping
   public void updateUser(@Validated(ValidationGroups.Update.class) @RequestBody UserEditDTO dto) {}
   

JWT (JSON Web Token) 是现代 API 中主流的无状态认证方案。

认证流程:

1. 登录: 用户提供凭证调用登录接口。
2. 签发 Token: 服务器验证成功后，生成一个包含用户信息的 JWT Token 并返回给客户端。
3. 携带 Token: 客户端在后续每次请求的 Authorization 请求头中携带 Token (格式: Bearer <token>)。
4. 拦截校验: 服务器端的 AuthInterceptor 拦截请求，验证 Token 的合法性。

登录接口 (签发 Token)

@PostMapping("/login")
public Result<String> login(@RequestBody LoginDTO dto) {
    // 1. 验证用户名密码...
    // 2. 验证成功，生成 Token
    Map<String, Object> payload = new HashMap<>();
    payload.put("userId", userId);
    payload.put("username", username);
    payload.put(JWTPayload.EXPIRES_AT, System.currentTimeMillis() + 1000 * 60 * 60 * 24); // 24小时过期

    String token = JWTUtil.createToken(payload, jwtSecret.getBytes());
    return Result.success(token);
}

拦截器 (校验 Token)

@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
    String token = request.getHeader("Authorization");
    if (StrUtil.isBlank(token) || !token.startsWith("Bearer ")) {
        throw new BusinessException(ResultCode.UNAUTHORIZED);
    }
    token = token.substring(7);

    // 使用 Hutool-JWT 验证 Token
    if (!JWTUtil.verify(token, jwtSecret.getBytes())) {
        throw new BusinessException(ResultCode.UNAUTHORIZED);
    }
    // 还可以进一步校验payload中的过期时间等
    JWTValidator.of(token).validateDate();

    return true;
}

让 Swagger UI 支持 Token 认证，方便测试。

1. 定义安全方案:

   @Configuration
   @SecurityScheme(
       name = "bearerAuth", // 方案名称
       type = SecuritySchemeType.HTTP,
       scheme = "bearer",
       bearerFormat = "JWT"
   )
   public class SpringDocConfig {}
   

2. 应用安全方案: 在需要认证的 Controller 上添加 @SecurityRequirement。

   @RestController
   @RequestMapping("/users")
   @SecurityRequirement(name = "bearerAuth")
   public class UserController {
       // ...
   }