Spring Boot常用注解速查表(30个必会注解+实战案例)

package com.liu;
import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@MapperScan("com.liu.mapper")  // 扫描Mapper接口
@SpringBootApplication         // 核心注解
public class SimpleAccountingApplication {
    public static void main(String[] args) {
        SpringApplication.run(SimpleAccountingApplication.class, args);
    }
}

// 错误：启动类放在子包里，扫描不到其他组件
package com.liu.config;  // 错误位置
@SpringBootApplication
public class Application { }
// 正确：启动类放在根包
package com.liu;  // 正确位置
@SpringBootApplication
public class Application { }

@Component
public class JwtUtil {
    @Value("${jwt.secret}")
    private String secret;
    public String generateToken(Long userId, Integer role, String username) {
        // 生成JWT Token
    }
}

@Service
public class UserServiceImpl implements UserService {
    @Autowired
    private UserMapper userMapper;  // 自动注入Mapper
    @Autowired
    private JwtUtil jwtUtil;  // 自动注入工具类
    public User login(String username, String password) {
        return userMapper.selectByUsername(username);
    }
}

@Service
@RequiredArgsConstructor  // Lombok注解，自动生成构造器
public class UserServiceImpl implements UserService {
    private final UserMapper userMapper;  // final修饰
    private final JwtUtil jwtUtil;
    // Lombok自动生成构造器，Spring自动注入
}

@Component
public class JwtUtil {
    @Value("${jwt.secret}")
    private String secret;  // 注入配置：jwt.secret
    @Value("${jwt.expiration}")
    private Long expiration;  // 注入配置：jwt.expiration
}

jwt:
  secret: my-secret-key-12345
  expiration: 7200000  # 2小时

// 错误：配置文件中没有这个key
@Value("${jwt.secretKey}")  // 配置文件是jwt.secret，不是jwt.secretKey
private String secret;
// 正确：设置默认值
@Value("${jwt.secret:default-secret}")  // 如果没有配置，使用default-secret
private String secret;

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Autowired
    private JwtInterceptor jwtInterceptor;
    // 注册拦截器
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(jwtInterceptor)
                .addPathPatterns("/**");
    }
    // 配置跨域
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOriginPatterns("*")
                .allowedMethods("GET", "POST", "DELETE", "PUT");
    }
}

@RestController
@RequestMapping("/user")
public class UserController {
    @PostMapping("/login")
    public Result<String> login(@RequestParam String username, 
                                @RequestParam String password) {
        // 返回JSON：{"code":200,"msg":"登录成功","data":"token"}
        return Result.success("登录成功", token);
    }
}

@RestController
@RequestMapping("/user")  // 类级别：所有方法的URL前缀
public class UserController {
    // 方法级别：完整URL = /user/login
    @RequestMapping(value = "/login", method = {RequestMethod.GET, RequestMethod.POST})
    public Result<String> login() {
        // 支持GET和POST请求
    }
}

@GetMapping("/list")     // 等价于 @RequestMapping(method = RequestMethod.GET)
@PostMapping("/add")     // 等价于 @RequestMapping(method = RequestMethod.POST)
@PutMapping("/update")   // 等价于 @RequestMapping(method = RequestMethod.PUT)
@DeleteMapping("/delete")// 等价于 @RequestMapping(method = RequestMethod.DELETE)

@PostMapping("/login")
public Result<String> login(@RequestParam String username, 
                            @RequestParam String password) {
    // 请求：POST /user/login?username=admin&password=123456
    // username = "admin"
    // password = "123456"
}

@GetMapping("/list")
public Result<List<Bill>> list(
    @RequestParam(required = false) String keyword,  // 可选参数
    @RequestParam(defaultValue = "1") Integer page   // 默认值
) {
    // 请求：GET /bill/list
    // keyword = null
    // page = 1
}

@PostMapping("/register")
public Result<User> register(@RequestBody User user) {
    // 请求体：{"username":"admin","password":"123456"}
    // 自动转换为User对象
    // user.getUsername() = "admin"
    // user.getPassword() = "123456"
}

// 错误：GET请求不能用@RequestBody
@GetMapping("/list")
public Result<List<Bill>> list(@RequestBody Map<String, Object> params) {
    // GET请求没有请求体，会报错
}
// 正确：GET请求用@RequestParam
@GetMapping("/list")
public Result<List<Bill>> list(@RequestParam String keyword) {
    // 正确
}

@DeleteMapping("/delete/{id}")
public Result<Boolean> delete(@PathVariable Long id) {
    // 请求：DELETE /bill/delete/123
    // id = 123
    billService.deleteById(id);
    return Result.success("删除成功");
}
@GetMapping("/user/{userId}/bill/{billId}")
public Result<Bill> getBill(@PathVariable Long userId, 
                            @PathVariable Long billId) {
    // 请求：GET /user/10/bill/20
    // userId = 10
    // billId = 20
}

@Controller  // 注意：不是@RestController
@RequestMapping("/user")
public class UserController {
    @GetMapping("/toLogin")
    public String toLogin() {
        return "redirect:/login.html";  // 返回视图
    }
    @ResponseBody  // 单独使用，返回JSON
    @PostMapping("/login")
    public Result<String> login() {
        return Result.success("登录成功");  // 返回JSON
    }
}

// 实体类（User.java）
@Data
public class User {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度必须在3-20个字符之间")
    private String username;
    @NotBlank(message = "密码不能为空")
    @Size(min = 6, max = 10, message = "密码长度必须在6-10个字符之间")
    @Pattern(regexp = "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)[a-zA-Z\\d]{6,10}$", 
             message = "密码必须包含大小写字母和数字")
    private String password;
    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
    private String phone;
}
// 控制器
@PostMapping("/register")
public Result<User> register(@RequestBody @Valid User user) {
    // 如果校验失败，自动返回400错误，不会执行方法体
    // 如果校验成功，继续执行
    return userService.register(user);
}

@RestControllerAdvice  // 全局异常处理
public class GlobalExceptionHandler {
    // 处理参数校验异常
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<String> handleValidException(MethodArgumentNotValidException e) {
        String message = e.getBindingResult().getFieldError().getDefaultMessage();
        return Result.fail(message);  // 返回：{"code":400,"msg":"用户名不能为空"}
    }
    // 处理业务异常
    @ExceptionHandler(RuntimeException.class)
    public Result<String> handleRuntimeException(RuntimeException e) {
        return Result.fail(e.getMessage());
    }
    // 处理数据库唯一约束异常
    @ExceptionHandler(SQLIntegrityConstraintViolationException.class)
    public Result<String> handleSQLException(SQLIntegrityConstraintViolationException e) {
        if (e.getMessage().contains("Duplicate entry")) {
            return Result.fail("数据已存在");
        }
        return Result.fail("数据库操作失败");
    }
}

@Service
@RequiredArgsConstructor//Lombok注解，自动生成构造器,构造器注入，避免字段注入
public class UserServiceImpl implements UserService {
    private final UserMapper userMapper;
    @Override
    public User login(String username, String password) {
        // 业务逻辑
        User user = userMapper.selectByUsername(username);
        if (user == null) {
            throw new RuntimeException("用户不存在");
        }
        if (!user.getPassword().equals(password)) {
            throw new RuntimeException("密码错误");
        }
        return user;
    }
}

@Service
public class AnnouncementServiceImpl implements AnnouncementService {
    @Transactional  // 开启事务
    public void publishAnnouncement(Announcement announcement) {
        // 1. 保存公告
        announcementMapper.insert(announcement);
        // 2. 记录操作日志
        logMapper.insert(new Log("发布公告", announcement.getId()));
        // 如果第2步失败，第1步会自动回滚
    }
}

// 错误：@Transactional只对public方法有效
@Transactional
private void saveUser(User user) {
    // 事务不生效
}

// 正确：必须是public方法
@Transactional
public void saveUser(User user) {
    // 事务生效
}

@Data
@TableName("user")  // 对应数据库的user表
public class User {
    private Long userId;
    private String username;
}

@Data
@TableName("user")
public class User {
    @TableId(type = IdType.AUTO)  // 主键自增
    private Long userId;
}

@Data
@TableName("user")
public class User {
    @TableId(type = IdType.AUTO)
    private Long userId;
    // 自动填充：插入时填充
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;
    // 自动填充：插入和更新时都填充
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;
}

@Component
public class MyMetaObjectHandler implements MetaObjectHandler {
    @Override
    public void insertFill(MetaObject metaObject) {
        this.strictInsertFill(metaObject, "createTime", LocalDateTime.class, LocalDateTime.now());
        this.strictInsertFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
    }
    @Override
    public void updateFill(MetaObject metaObject) {
        this.strictUpdateFill(metaObject, "updateTime", LocalDateTime.class, LocalDateTime.now());
    }
}

@Data
@TableName("user")
public class User {
    @TableId(type = IdType.AUTO)
    private Long userId;
    @Version  // 乐观锁
    private Integer version;
}

-- 更新时自动加上version条件
UPDATE user SET username = ?, version = version + 1 
WHERE user_id = ? AND version = ?
-- 如果version不匹配（被其他线程修改了），更新失败

@Data
@TableName("user")
public class User {
    @TableId(type = IdType.AUTO)
    private Long userId;
    @TableLogic  // 逻辑删除：0=正常，1=已删除
    private Integer deleted;
}

// 调用删除方法
userMapper.deleteById(1);
// 实际执行的SQL（不是真删除）
UPDATE user SET deleted = 1 WHERE user_id = 1 AND deleted = 0
// 查询时自动过滤已删除的数据
SELECT * FROM user WHERE deleted = 0

@MapperScan("com.liu.mapper")  // 扫描mapper包下的所有接口
@SpringBootApplication
public class SimpleAccountingApplication {
    public static void main(String[] args) {
        SpringApplication.run(SimpleAccountingApplication.class, args);
    }
}

@Mapper
public interface UserMapper extends BaseMapper<User> {
    @Select("SELECT * FROM user WHERE username = #{username}")
    User selectByUsername(String username);
    @Update("UPDATE user SET status = #{status} WHERE user_id = #{userId}")
    int updateStatus(@Param("userId") Long userId, @Param("status") Integer status);
}

// 多参数需标注@Param
@Select("SELECT * FROM t_user WHERE username = #{name} AND age = #{age}")
User selectByUsernameAndAge(@Param("name") String username, @Param("age") Integer age);

@Aspect
@Component
@Slf4j
public class RoleCheckAspect {
    @Before("@annotation(requireRole)")//在切点之前运行的代码
    public void checkRole(JoinPoint joinPoint, RequireRole requireRole) {
        // 权限验证逻辑
        int[] allowedRoles = requireRole.value();
        int userRole = TokenHelper.getRole(request);
        boolean hasPermission = Arrays.stream(allowedRoles)
                .anyMatch(role -> role == userRole);
        if (!hasPermission) {
            throw new RuntimeException("无权限访问");
        }
    }
}

@Service
public class UserService {
    // 无切面增强的方法
    public void test() {
        this.saveUser(); // 内部自调用，saveUser的切面逻辑失效
    }
    // 有切面增强的方法（如@Transactional/@Around）
    public void saveUser() {
        // 业务逻辑
    }
}

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

import org.springframework.stereotype.Service;
@Service
public class UserService {
    // 正常方法：返回结果
    public String getUserById(Long id) throws InterruptedException {
        Thread.sleep(80); // 模拟业务执行耗时
        return "查询到用户ID：" + id;
    }
    // 异常方法：抛出运行时异常
    public void deleteUserById(Long id) {
        throw new RuntimeException("模拟删除失败：用户不存在");
    }
}

import org.aspectj.lang.JoinPoint;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;
import java.util.Arrays;
// 1. 标记为切面类  2. 注册为Spring Bean（必须，否则AOP失效）
@Aspect
@Component
public class AopAdviceDemoAspect {
    private static final Logger log = LoggerFactory.getLogger(AopAdviceDemoAspect.class);
    // 定义公共切入点：匹配UserService类的所有公共方法（精准增强目标）
    @Pointcut("execution(public * com.example.demo.service.UserService.*(..))")
    public void userServicePointcut() {
        // 切入点方法：仅做标识，无需编写任何逻辑
    }
    // ==================== 1. @Before 前置通知 ====================
    @Before("userServicePointcut()")
    public void doBefore(JoinPoint joinPoint) {
        // 获取方法信息：类名.方法名
        String methodFullName = joinPoint.getSignature().getDeclaringTypeName() + "." + joinPoint.getSignature().getName();
        // 获取方法入参
        Object[] args = joinPoint.getArgs();
        // 前置逻辑：记录方法开始执行 + 入参
        log.info("【@Before 前置通知】方法{}开始执行，入参：{}", methodFullName, Arrays.toString(args));
    }
    // ==================== 2. @After 最终通知 ====================
    @After("userServicePointcut()")
    public void doAfter(JoinPoint joinPoint) {
        String methodName = joinPoint.getSignature().getName();
        // 最终逻辑：标记方法执行结束（无论是否异常，都会打印）
        log.info("【@After 最终通知】方法{}执行结束（必执行）", methodName);
    }
    // ==================== 3. @Around 环绕通知 ====================
    @Around("userServicePointcut()")
    public Object doAround(ProceedingJoinPoint joinPoint) throws Throwable {
        // ① 执行前逻辑：记录开始时间 + 获取方法信息（等效@Before）
        long startTime = System.currentTimeMillis();
        String methodFullName = joinPoint.getSignature().getDeclaringTypeName() + "." + joinPoint.getSignature().getName();
        Object[] args = joinPoint.getArgs();
        log.info("【@Around 执行前】方法{}入参：{}", methodFullName, Arrays.toString(args));
        Object result = null;
        try {
            // ② 手动执行目标方法（核心：必须调用，否则目标方法不执行）
            result = joinPoint.proceed();
            // ③ 执行成功后逻辑：记录返回值 + 耗时
            long costTime = System.currentTimeMillis() - startTime;
            log.info("【@Around 执行成功】方法{}返回值：{}，耗时：{}ms", methodFullName, result, costTime);
        } catch (Throwable e) {
            // ④ 执行异常时逻辑：记录异常信息 + 耗时
            long costTime = System.currentTimeMillis() - startTime;
            log.error("【@Around 执行异常】方法{}执行失败，耗时：{}ms，异常：{}", methodFullName, costTime, e.getMessage());
            throw e; // 重新抛出异常，让全局异常处理器处理（不可省略）
        }
        // ⑤ 返回目标方法结果（核心：必须返回，否则调用方获取不到返回值）
        return result;
    }
}

@Aspect
@Component
public class LogAspect {
    // 前置通知：方法执行前
    @Before("execution(* com.liu.controller.*.*(..))")
    public void before(JoinPoint joinPoint) {
        log.info("方法执行前：{}", joinPoint.getSignature().getName());
    }
    // 后置通知：方法执行后
    @After("execution(* com.liu.controller.*.*(..))")
    public void after(JoinPoint joinPoint) {
        log.info("方法执行后：{}", joinPoint.getSignature().getName());
    }
    // 环绕通知：方法执行前后
    @Around("execution(* com.liu.controller.*.*(..))")
    public Object around(ProceedingJoinPoint joinPoint) throws Throwable {
        long start = System.currentTimeMillis();
        Object result = joinPoint.proceed();  // 执行方法
        long end = System.currentTimeMillis();
        log.info("方法执行耗时：{}ms", end - start);
        return result;
    }
}

// 1. 定义注解
@Target(ElementType.METHOD)  // 作用在方法上
@Retention(RetentionPolicy.RUNTIME)  // 运行时有效
public @interface RequireRole {
    int[] value() default {};  // 允许的角色
}
// 2. 使用注解
@RestController
@RequestMapping("/admin")
public class AdminController {
    @RequireRole({Constants.ROLE_ADMIN})  // 只允许管理员访问
    @GetMapping("/users")
    public Result<List<User>> getAllUsers() {
        return Result.success(userService.list());
    }
}
// 3. 切面处理注解
@Aspect
@Component
public class RoleCheckAspect {
    @Before("@annotation(requireRole)")
    public void checkRole(JoinPoint joinPoint, RequireRole requireRole) {
        // 验证权限
    }
}

<!-- Maven 依赖（与其他 Lombok 注解共用） -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.30</version>
    <scope>provided</scope>
</dependency>

@Data
public class User {
    private Long userId;
    private String username;
    private String password;
}
// 等价于手写：
public class User {
    private Long userId;
    private String username;
    private String password;
    public Long getUserId() { return userId; }
    public void setUserId(Long userId) { this.userId = userId; }
    // ... 其他getter/setter
    @Override
    public String toString() { ... }
    @Override
    public boolean equals(Object o) { ... }
    @Override
    public int hashCode() { ... }
}

@Data
@NoArgsConstructor  // 无参构造器
@AllArgsConstructor  // 全参构造器
public class User {
    private Long userId;
    private String username;
}
// 等价于：
public class User {
    public User() {}  // 无参构造器
    public User(Long userId, String username) {  // 全参构造器
        this.userId = userId;
        this.username = username;
    }
}

@Service
@RequiredArgsConstructor  // 自动生成构造器
public class UserServiceImpl implements UserService {
    private final UserMapper userMapper;  // final修饰,依赖注入
    private final JwtUtil jwtUtil;
    // Lombok自动生成：
    // public UserServiceImpl(UserMapper userMapper, JwtUtil jwtUtil) {
    //     this.userMapper = userMapper;
    //     this.jwtUtil = jwtUtil;
    // }
}

@Service
@Slf4j  // 自动生成log对象
public class UserServiceImpl implements UserService {
    public User login(String username, String password) {
        log.info("用户登录：{}", username);  // 直接使用log
        log.error("登录失败：{}", username);
        log.debug("调试信息：{}", username);
    }
}
// 等价于：
public class UserServiceImpl implements UserService {
    private static final Logger log = LoggerFactory.getLogger(UserServiceImpl.class);
}

@Data
@Builder
public class User {
    private Long userId;
    private String username;
    private String password;
}
// 使用：
User user = User.builder()
    .userId(1L)
    .username("admin")
    .password("123456")
    .build();

@RestController
@RequestMapping("/user")
@RequiredArgsConstructor
@Slf4j
public class UserController {
    private final UserService userService;
    @PostMapping("/login")
    public Result<String> login(@RequestParam String username, 
                                @RequestParam String password) {
        log.info("用户登录：{}", username);
        return userService.login(username, password);
    }
}

@Data
@NoArgsConstructor
@AllArgsConstructor
@TableName("user")
public class User {
    @TableId(type = IdType.AUTO)
    private Long userId;
    @NotBlank(message = "用户名不能为空")
    private String username;
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;
    @Version
    private Integer version;
    @TableLogic
    private Integer deleted;
}

@Service
@RequiredArgsConstructor
@Slf4j
public class UserServiceImpl implements UserService {
    private final UserMapper userMapper;
    @Transactional
    public void saveUser(User user) {
        log.info("保存用户：{}", user.getUsername());
        userMapper.insert(user);
    }
}

// 错误：没有@Service注解，Spring不会管理这个类
public class UserServiceImpl implements UserService {
    @Autowired
    private UserMapper userMapper;  // 注入失败，userMapper为null
}
// 正确：加上@Service
@Service
public class UserServiceImpl implements UserService {
    @Autowired
    private UserMapper userMapper;  // 注入成功
}

// 错误：UserMapper没有被Spring管理
public interface UserMapper {  // 缺少@Mapper注解
    User selectById(Long id);
}
// 正确：加上@Mapper或在启动类加@MapperScan
@Mapper
public interface UserMapper {
    User selectById(Long id);
}

// 错误：private方法，事务不生效
@Transactional
private void saveUser(User user) {
    userMapper.insert(user);
}
// 正确：必须是public方法
@Transactional
public void saveUser(User user) {
    userMapper.insert(user);
}

// 错误：不能同时使用
@PostMapping("/add")
public Result<Boolean> add(@RequestBody Bill bill, 
                           @RequestParam Long userId) {
    // 报错
}
// 正确：要么全用@RequestBody，要么全用@RequestParam
@PostMapping("/add")
public Result<Boolean> add(@RequestBody Map<String, Object> params) {
    Long userId = (Long) params.get("userId");
    Bill bill = (Bill) params.get("bill");
}