常用注解

Swagger注解
@Api: 用在类上，表示对类的说明。例如：Controller
@ApiModel: 用在类上。例如：entity、DTO、VO
@ApiModelProperty: 用在属性上，描述属性信息
@ApiOperation: 用在方法上，说明方法的用途作用

Lombok注解
@Slf4j: 自动为类生成一个名为 log 的 SLF4J 日志对象。
可以通过log.info()、log.debug()等方法记录日志
@Data: @Data是一个组合注解，包含以下Lombok注解的功能：

@Getter：自动生成所有字段的getter方法。
@Setter：自动生成所有非final字段的setter方法。
@ToString：自动生成toString()方法。
@EqualsAndHashCode：自动生成equals()和hashCode()方法。
@RequiredArgsConstructor：为所有final字段或标记为@NonNull的字段生成构造方法。

例如：编译后，下述代码会自动生成getter、setter、toString()、equals()和hashCode()方法。

import lombok.Data;
@Data
public class User {
    private String name;
    private int age;
}

@Builder: 自动生成一个建造者模式的构造器类，用于通过链式调用逐步构建对象。适用于需要灵活设置对象属性的场景，尤其当类有多个可选参数时。
例如：

@Builder
public class User {
    private String name;
    private int age;
}
// 使用方式
User user = User.builder().name("Alice").age(25).build();

@NoArgsConstructor: 自动生成一个无参构造函数。若类中存在 final 字段且未初始化，需配合 @NoArgsConstructor(force = true) 使用，此时 final 字段会被强制初始化为默认值（如 null 或 0）
例如：

@NoArgsConstructor
public class User {
    private String name;
}
// 等价于手动生成
public User() {}

@AllArgsConstructor:自动生成一个全参构造函数，参数顺序与类中字段声明顺序一致。
例如：

@AllArgsConstructor
public class User {
    private String name;
    private int age;
}
// 等价于手动生成
public User(String name, int age) {
    this.name = name;
    this.age = age;
}

Spring Framework注解
@RequestMapping: 定义请求的 URL 映射规则。例如 @RequestMapping(“/admin/shop”) 表示该控制器下所有方法的请求路径以 /admin/shop 为根路径。支持细化到方法级别的路径、请求方法（GET/POST 等）和其他条件。
@GetMapping :映射GET请求。用途：获取资源，通常用于查询操作。
@PostMapping :映射POST请求。用途：提交数据或创建资源，常用于表单提交或新增操作。
@PutMapping :映射PUT请求。用途：更新完整资源。
@DeleteMapping :映射DELETE请求。用途：删除指定资源。
@PathVariable： 用于接收路径参数
例如：将路径参数id绑定到userId上

@GetMapping("/users/{id}")
public String getUser(@PathVariable("id") Long userId) {
    return "User ID: " + id;
}

@RequestParam： 接收查询参数
例如：请求路径为/search?keyword=1;

@GetMapping("/search")
public String search(@RequestParam String keyword) {
    return "Search keyword: " + keyword;
}

注：
1.@RequestParam默认要求参数必须传递，若请求中缺少keyword参数（如/search），会抛出MissingServletRequestParameterException。可通过设置required = false改为非必传;
2.可通过defaultValue指定默认值，避免处理null

@RequestBody： 用于接收JSON格式的参数
例如：
需配合Content-Type: application/json等头信息使用。

@PostMapping("/create")
public String createUser(@RequestBody User user) {
    return "User created: " + user.getName();
}

@RestController： 标记一个类为Spring MVC控制器（Controller），专门用于处理HTTP请求。
@Service： 标记一个类为业务逻辑层（Service层）组件，由Spring容器管理。

@Configuration: 主要用于标记一个类为 Spring 应用上下文的配置类.

1.定义 Bean
在 @Configuration 类中，可以通过 @Bean 注解的方法来声明 Spring 容器管理的 Bean。这些方法返回的对象会被注册为 Spring 应用上下文中的 Bean 实例。

2.组件扫描
结合 @ComponentScan 注解，可以自动扫描指定包路径下的组件（如 @Component、@Service、@Repository 等），并将它们注册为 Bean。

3.配置类代理
Spring 会通过 CGLIB 代理增强 @Configuration 类，确保多次调用 @Bean 方法时返回同一个实例（单例模式）。

4.导入其他配置
通过 @Import 注解可以引入其他配置类，实现模块化配置。

注： 在Spring框架中，如果不显式配置@ComponentScan注解，Spring Boot的默认行为会根据启动类的位置自动确定扫描范围。具体规则如下：Spring Boot会自动扫描主启动类（带有@SpringBootApplication的类）所在包及其所有子包。默认行为仅适用于Spring Boot项目，传统Spring项目需手动配置@ComponentScan。

@EnableCaching: 添加该注解后，框架会自动创建必要的拦截器(通常加在启动类上)，通过 AOP 动态代理拦截带有 @Cacheable、@CachePut 等注解的方法，实现缓存逻辑。

1.@Cacheable:在方法执行前查询缓存中是否有数据，若有数据就直接返回缓存数据；若无缓存数据则调用方法并将方法的返回值放到缓存中。
2.@CachePut:将方法的返回值放到缓存中
3.@CacheEvict:将一条或多条数据从缓存中删除

    // 查询用户：优先从缓存获取
    @Cacheable(value = "users", key = "#userId")
    public User getUserById(Long userId) {
        // 模拟数据库查询
        System.out.println("查询数据库用户: " + userId);
        return new User(userId, "用户" + userId);
    }

    // 更新用户：更新数据库并同步缓存
    @CachePut(value = "users", key = "#user.id")
    public User updateUser(User user) {
        System.out.println("更新数据库用户: " + user.getId());
        return user; // 返回值会覆盖缓存
    }

    // 删除用户：删除数据库并清除缓存
    @CacheEvict(value = "users", key = "#userId")
    public void deleteUser(Long userId) {
        System.out.println("删除数据库用户: " + userId);
    }

    // 清空全部用户缓存（例如批量操作后）
    @CacheEvict(value = "users", allEntries = true)
    public void clearAllCache() {
        System.out.println("清空users缓存");
    }

@EnableScheduling： 用于启用Spring的任务调度功能，允许开发者通过简单的配置实现定时任务。
@Scheduled标注具体方法，定义执行规则（如每5秒执行一次）。
cron在线生成器

1.启用定时任务支持
添加该注解后，Spring会扫描带有@Scheduled注解的方法，并根据配置的时间表达式自动调度执行。

2.简化定时任务配置
无需手动编写复杂的线程或任务调度代码，只需在启动类上添加@EnableScheduling，并在方法上标注@Scheduled即可实现定时任务。

3.支持多种调度表达式
支持Cron表达式、固定延迟（fixedDelay）、固定速率（fixedRate）等多种调度方式。

@Component：用于标识一个类为Spring容器的组件（Bean）

1.自动扫描与注册
配合@ComponentScan使用，Spring会在类路径下扫描被@Component标注的类，并将其注册为Bean，纳入IOC容器管理。

2.通用组件标识
作为其他派生注解（如@Controller、@Service、@Repository）的元注解，适用于所有层次的组件。

3.依赖注入支持
通过@Autowired等注解，Spring会自动注入被@Component标注的类及其依赖。

@Bean: 用于显式声明一个方法的返回值作为 Spring 容器管理的 Bean。

1.将方法返回值注册为 Bean
标注在方法上时，方法返回值会被 Spring IoC 容器托管，默认以方法名作为 Bean 名称。

2.替代 XML 配置
在基于 Java 的配置类（@Configuration 类）中使用，替代传统 XML 中的 <bean> 标签。

3.控制 Bean 的生命周期
可通过 initMethod 和 destroyMethod 属性指定初始化和销毁方法。

4.依赖注入
方法参数会自动注入其他已存在的 Bean，无需显式调用 new。

注：
1.默认单例模式，可通过 @Scope 修改作用域。
2.标注 @Bean 的类本身需被 Spring 管理（如添加 @Configuration）。
3.方法名默认作为 Bean 的 ID，可通过 name 或 value 属性自定义。

@Autowired:用于实现依赖注入。
自动装配 Spring 容器中的 Bean，无需手动编写 new 或显式调用 getBean()。它可以用在以下位置：

• 字段（Field）上
• 构造方法（Constructor）上
• Setter 方法上

注：

• required 属性：默认为 true，表示必须注入 Bean，否则报错；设为 false 时允许注入 null；
• 配合 @Qualifier：当同一类型有多个 Bean 时，可用 @Qualifier 指定具体 Bean。

@ControllerAdvice: 用于定义全局控制器增强类。
@ResponseBody: 用于将方法返回值直接序列化为 HTTP 响应体（如 JSON/XML）

@RestControllerAdvice: 该注解结合了@ControllerAdvice和@ResponseBody的功能，用于全局处理控制器层（Controller）的异常、绑定参数验证错误或统一响应格式。

1.全局异常处理
捕获控制器中抛出的异常，返回结构化的错误信息（如JSON格式）。例如处理NullPointerException或自定义业务异常。

2.数据绑定验证
拦截@Valid注解的参数验证错误（如JSR-303校验），返回校验失败的详情。

3.统一响应封装
对所有控制器返回的数据进行统一包装（如添加状态码、消息字段）。

@ExceptionHandler：该注解用于标记一个方法，使其能够处理特定类型的异常。当控制器方法抛出异常时，Spring 会查找匹配的 @ExceptionHandler 方法来处理异常，并返回适当的响应。
例如：

@RestController
public class ExampleController {

    @GetMapping("/example")
    public String example() {
        throw new wzxgException("Example error");
    }

    @ExceptionHandler(RuntimeException.class)
    public ResponseEntity<String> handleRuntimeException(wzxgException ex) {//会检测到wzxgException
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(ex.getMessage());
    }
}

@ConditionalOnMissingBean： 该注解用于条件化地注册 Bean，仅在当前 Spring 容器中不存在指定类型的 Bean 时才会生效。

• 提供默认配置：当用户未自定义某个 Bean 时，自动配置类通过该注解提供默认实现。
• 避免冲突：确保用户自定义的 Bean 优先于自动配置的 Bean。

注: 该注解需配合 @Configuration 类使用。

@ConfigurationProperties: 该注解用于将外部配置文件（如 application.yml 或 application.properties）中的属性值批量绑定到 Java 对象的字段上，简化配置管理。
核心功能

1.属性绑定：自动将配置文件中的属性映射到类的字段，支持嵌套属性、集合类型等复杂结构。
2.类型安全：通过类字段的类型校验配置值，避免手动解析和类型转换错误。
3.前缀匹配：通过 prefix 参数指定配置项的前缀，仅绑定符合前缀的属性。

例如：

@ConfigurationProperties(prefix = "app.mail")
public class MailConfig {
    private String host;
    private int port;
    private List<String> Email;
}

对应的配置文件（application.yml）:

app:
  mail:
    host: smtp.example.com
    port: 587
    Email: ["wzxg@qq.com", "zhc@qq.com"]

@Value： 主要用于从外部配置（如属性文件、环境变量、系统属性等）注入值到 Spring 管理的 Bean 中。
例如：
1.直接注入字面量值

@Value("默认值")
private String text;

2.注入配置文件中的属性

@Value("${app.name}")
private String appName;

3.默认值设置
当配置缺失时可指定备用值：

@Value("${app.port:8080}")
private int port;

@Transactional:用于声明式事务管理，标注在类或方法上，表示该方法或类中的所有方法需要事务支持。
默认情况下，@Transactional 仅在未捕获的 RuntimeException 或 Error 时触发回滚。使用 rollbackFor = Exception.class 后，任何 Exception（包括受检异常如 IOException、SQLException）均会触发回滚。
@EnableTransactionManagement:启用 Spring 的注解驱动事务管理功能，通常标注在启动类上。

MyBatis注解
@Mapper： 标记接口为MyBatis的映射器（Mapper），用于定义数据库操作。
方法通过XML或注解（如@Select）配置SQL语句，实现ORM映射。

1.@Insert:用于插入操作，替代XML中的< insert >标签。

@Insert("INSERT INTO user(name, age) VALUES(#{name}, #{age})")
int insertUser(User user);

2.@Delete:用于删除操作，替代XML中的< delete >标签。

@Delete("DELETE FROM user WHERE id=#{id}")
int deleteUser(int id);

3.@Update:用于更新操作，替代XML中的< update >标签。

@Select("SELECT * FROM user WHERE name = #{name}")
User selectUserByName(String name);

4.@Select:用于直接在方法上编写查询SQL语句，替代XML中的< select >标签。

@Update("UPDATE user SET name=#{name} WHERE id=#{id}")
int updateUser(User user);

注：
1.SQL语句中可以用#{参数名}绑定方法参数
2.简单SQL推荐使用注解，复杂SQL（如动态多表关联）建议仍用XML。
3.注解方式无法直接使用< if >、< foreach >等标签
4.注解与XML可混合使用，但同一方法不能重复定义。

WebSocket注解

@ServerEndpoint: 用于将Java类标记为WebSocket服务的端点。

主要作用：

1.定义WebSocket服务端点
通过注解标注的类会被视为WebSocket服务端，处理客户端连接的建立、消息收发及关闭等事件。

2.配置端点路径
通过value属性指定WebSocket的访问路径，例如:

@ServerEndpoint("/ws/chat")  
public class ChatEndpoint { ... }  

3.支持参数化路径
支持路径模板，例如/ws/chat/{room}，可通过@PathParam获取路径参数：

@OnMessage  
public void onMessage(@PathParam("room") String room, String message) { ... }  

4.声明生命周期方法
结合其他注解（如@OnOpen、@OnMessage）定义连接的生命周期回调：

@OnOpen  
public void onOpen(Session session) { ... } // 连接建立时触发  

java.lang注解

@Target: 用于指定注解可以应用的代码元素类型（如类、方法、字段等），通过 ElementType 枚举参数定义范围。
例如：

@Target(ElementType.METHOD) // 表示该注解只能用于方法
public @interface CustomAnnotation {}

@Retention: 控制注解的生命周期，通过 RetentionPolicy 枚举指定注解在何时有效。

• SOURCE：仅保留在源码中，编译时丢弃。
• CLASS：保留到编译后的字节码，但运行时不可见（默认行为）。
• RUNTIME：运行时可通过反射读取，常用于框架（如Spring）。

例如：

@Retention(RetentionPolicy.RUNTIME)  
public @interface RuntimeAnnotation {}  

aspectj.lang注解
@Aspect: 标记一个类为切面类
@Pointcut: 定义切点表达式，用于指定在哪些连接点（如方法调用、异常抛出等）应用通知逻辑。切点表达式支持多种匹配规则（如方法签名、注解等）。
例如：

@Pointcut("execution(* com.example.service.*.*(..))")
public void serviceLayer() {} // 切点名称

1.@Around:环绕通知，该注解标注的通知方法在目标方法前、后都被执行
2.@Before:前置通知，该注解标注的通知方法在目标方法前被执行
3.@After:后置通知，该注解标注的通知方法在目标方法后被执行，无论是否有异常都会执行
4.@AfterReturning: 返回后通知，该注解标注的通知方法在目标方法后被执行，有异常不会执行
5.@AfterThrowing: 异常后通知，该注解标注的通知方法发送异常后执行

注：
1.@Around需要自己调用ProceedingJoinPoint.proceed()来让原始方法执行，其他通知不需要考虑目标方法执行
2.@Around的返回值，必须指定为Object来接收原始方法的返回值