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");
}