Java 内置注解使用说明大全

1. @Override

java.lang.Override

@Override 是 JDK1.5 中加入的标准注解之一。用于限定某个方法是重写父类的方法，该注解只能用于方法。

@Override 表示指定重写父类的方法（程序会从编译层面验证是否真的重写了父类方法），如果父类没有对应重写的方法，则会报错。

如果子类重写父类方法后，不写 @Override 注解，而父类仍有对应重写的方法，仍然构成重写。

2. @Deprecated

java.lang.Deprecated

@Deprecated 是 JDK1.5 中加入的标准注解之一。可以标注在包、类、字段、方法、参数、构造方法，以及局部变量上。用于表示某个程序元素已经过时，即不推荐使用程序元素，但仍然可以继续使用。

使用 @Deprecated 可以做到新旧版本的兼容和过渡。

3. @SuppressWarnings

java.lang.SuppressWarnings

@SuppressWarnings 是 JDK1.5 中加入的标准注解之一。可以标注在类、字段、方法、参数、构造方法，以及局部变量上。作用是告诉编译器忽略指定的警告，不在编译完成后出现警告信息。

格式：

@SuppressWarnings("")
@SuppressWarnings({})
@SuppressWarnings(value={})

@SuppressWarnings() 中可传入一个字符串数组，数组中列出需要忽略的情况。如果传入多种情况，这几种情况的处理同时执行。

@SuppressWarnings({"unchecked", "serial"})
public void test(){     
}

若是只忽略一种情况的话，就可以写成这样：

@SuppressWarnings("unchecked")
public void test(){
}

以下是所有抑制警告的关键字：

关键字	用途
all	抑制所有警告
boxing	抑制装箱、拆箱操作时候的警告
cast	抑制映射相关的警告
dep-ann	抑制启用注释的警告
deprecation	抑制过期方法警告
fallthrough	抑制在 switch 中缺失 breaks 的警告
finally	抑制 finally 模块没有返回的警告
hiding	抑制与隐藏变量的局部变量相关的警告
incomplete-switch	忽略没有完整的 switch 语句
nls	忽略非 nls 格式的字符
null	忽略对 null 的操作
path	在类路径、源文件路径等中有不存在的路径时的警告
rawtypes	使用泛型时忽略没有指定相应的类型
restriction	忽略使用不推荐或禁止的引用的警告
serial	忽略实现了 Serializable 接口的类没有声明 serialVersionUID 字段的警告
static-access	抑制不正确的静态访问方式警告
synthetic-access	抑制子类没有按最优方法访问内部类的警告
unchecked	抑制没有进行类型检查操作的警告
unqualified-field-access	抑制没有权限访问的域的警告
unused	抑制没被使用过的代码的警告

4. @SafeVarargs

java.lang.SafeVarargs

@SafeVarargs 是 JDK1.7 中加入的标准注解之一。可以标注在方法、构造方法上。用于抑制抑制编译器警告。在声明具有模糊类型（比如：泛型）的可变参数的构造函数或方法时，Java 编译器会报 unchecked 警告。

@SafeVarargs 注解不适用于非 static 或非 final 声明的方法。

由 Java 源代码声明我们了解到：@SafeVarargs 注解，只能用于标记构造函数和方法，由于保留策略声明为RUNTIME，所以此注解可以在运行时生效。

@SafeVarargs
public static void m(List<String>... lists) {
    // 先会存储到 array[0] 的位置
    Object[] array = lists;
    List<Integer> tmpList = Arrays.asList(42);
    // array[0] 又保存了 tmpList(Integer) 进行覆盖
    // tmpList 是一个 List 对象（类型已经擦除），赋值给 Object 类型的对象是允许的（向上转型），能够编译通过
    array[0] = tmpList;
    // 实际取出来的应该是 42
    String s = lists[0].get(0);
}

public static void main(String[] args) {
    List<String> list = Arrays.asList("one", "two");
    m(list);
}

执行上面的 main 方法，会报下面的异常，如果 m 方法上不添加 @SafeVarargs 注解，编译器会发出红色警告，但是添加了该注解后，编译器不会发出警告了。

Exception in thread "main" java.lang.ClassCastException: java.lang.Integer cannot be cast to java.lang.String
	at com.example.demo.mytest.Test.m(Test.java:91)
	at com.example.demo.mytest.Test.main(Test.java:96)

5. @FunctionalInterface

java.lang.FunctionalInterface

@FunctionalInterface 是 JDK1.8 中加入的标准注解之一。

@FunctionalInterface 即 Functional Interface (函数式接口)。

函数式接口的定义是：如果接口中只有一个抽象方法（可以包含多个默认方法或多个 static 方法），那么该接口就是函数式接口。

@FunctionalInterface 就是用来指定某个接口必须是函数式接口，所以 @FunctionalInterface 注解只能修饰接口，不能修饰其它程序元素。

@FunctionalInterface 注解的作用只是告诉编译器检查这个接口，保证该接口只能包含一个抽象方法，如果出现多个会报错。

这个注解适用于 Lambda 表达式创建函数式接口。

这个注解不是必须的，当接口满足函数式接口时，不使用该注解也会被编译器视为函数式接口。

6. 文档注解

在注释里面使用，辅助文档说明：

@author  标明开发该类模块的作者，多个作者之间使用,分割
@version 标明该类模块的版本
@see     参考转向，也就是相关主题
@since   从哪个版本开始增加的
@param   对方法中某参数的说明，如果没有参数就不能写
@return  对方法返回值的说明，如果方法的返回值类型是 void 就不能写
@exception 对方法可能抛出的异常进行说明 ，如果方法没有用 throws 显式抛出的异常就不能写

7. 元注解

JDK1.5 在 java.lang.annotation 包定义了 4 个标准的 meta-annotation 类型，它们被用来提供对其它 annotation 类型作说明。

（1）@Target：用于描述注解的使用范围。

可以通过枚举类型 ElementType 的 10 个常量对象来指定： TYPE，METHOD，CONSTRUCTOR，PACKAGE…

（2）@Retention：用于描述注解的生命周期。

可以通过枚举类型 RetentionPolicy 的 3 个常量对象来指定： SOURCE（源代码）、CLASS（字节码）、RUNTIME（运行时）。 唯有 RUNTIME 阶段才能被反射读取到。

（3）@Documented：表明这个注解应该被 javadoc 工具记录。

（4）@Inherited：允许子类继承父类中的注解。

自定义注解

一个完整的注解应该包含三个部分：
（1）声明
（2）使用
（3）读取和处理

声明自定义注解

【元注解】
【修饰符】 @interface 注解名{
    【成员列表】
}

• 自定义注解可以通过四个元注解 @Retention、@Target、@Inherited、@Documented，分别说明它的生命周期，使用位置，是否被继承，是否被生成到 API 文档中。
• Annotation 的成员在 Annotation 定义中以无参数有返回值的抽象方法的形式来声明，我们又称为配置参数。返回值类型只能是八种基本数据类型、String类型、Class类型、enum类型、Annotation类型、以上所有类型的数组。
• 可以使用 default 关键字为抽象方法指定默认返回值。
• 如果定义的注解含有抽象方法，那么使用时必须指定返回值，除非它有默认值。格式是 “方法名 = 返回值”，如果只有一个抽象方法需要赋值，且方法名为 value，可以省略 “value=”，所以如果注解只有一个抽象方法成员，建议使用方法名 value。
• 数组赋值的时候，值使用{}包裹，如果数组中只有一个值，那么{}可以省略
• 注解的本质其实就是一个接口，继承 Annotation 父接口。

/**
 * 自定义注解
 * 该注解表示要执行哪个类中的哪个方法
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface InvokAnno {
    String className();
    String methodName();
}

public class Student {
    public void show(){
        System.out.println("student show ....");
    }
}

使用自定义注解

@InvokAnno(className = "com.example.demo.model.Student", methodName = "show")
public class MyTest {
}

注解本质是接口，上面的声明类似于下面的接口实现代码：

public class MyInvokAnno implements InvokAnno{

    String className(){
        return "com.example.demo.model.Student";
    }
    String methodName(){
        return "show";
    }
}
 

读取和处理自定义注解

自定义注解必须配上注解的信息处理流程才有意义。

我们自己定义的注解，只能使用反射的代码读取。所以自定义注解的生命周期必须是RetentionPolicy.RUNTIME。

public static void main(String[] args) throws Exception {
    // 获取类对象
    Class<MyTest> clazz = MyTest.class;
    // 获取类对象中的注解
    InvokAnno an = clazz.getAnnotation(InvokAnno.class);
    // 获取注解中对应的属性
    String className = an.className();
    String methodName = an.methodName();
    System.out.println(className);
    System.out.println(methodName);
    // 通过反射的方式实现接口的功能
    Class<?> aClass = Class.forName(className);
    Method show = aClass.getDeclaredMethod("show");
    // 方法的执行
    Object o = aClass.newInstance();
    // 执行对应的方法
    show.invoke(o); 
}

8. @Resource

@Resource 是 JavaEE 标准中提供的一种注解，用于进行依赖注入。@Resource 注解可以用于字段、方法、构造函数等地方，用于标识需要注入的资源或依赖项。通过使用 @Resource 注解，可以在类中标识需要注入的资源或依赖项，并由容器自动进行注入。

注解示例：

@Resource
private DataSource dataSource;

在上述示例中，dataSource 被标记为一个需要注入的资源，使用 @Resource 注解告知容器进行注入。

@Resource 和 @Autowired 的区别

@Resource 和 @Autowired 都是 bean 注入时使用，其实 @Resource 并不是 Spring 的注解，它的包是 javax.annotation.Resource，需要导入，但是 Spring 支持该注解的注入。

两者都可以写在字段和 setter 方法上。两者如果都写在字段上，那么就不需要再写 setter 方法。

@Autowired

@Autowired 为 Spring 提供的注解，需要导入包org.springframework.beans.factory.annotation.Autowired;

@Autowired 注解是按照类型(byType)装配依赖对象，默认情况下它要求依赖对象必须存在，如果允许 null 值，可以设置它的 required 属性为 false。

public class TestServiceImpl { 
    //下面两种@Autowired只要使用一种即可 
    //用于字段上 
    @Autowired 
    private UserDao userDao; 
    //用于属性的setter方法上 
    @Autowired 
    public void setUserDao(UserDao userDao) { 
        this.userDao = userDao; 
    } 
}

如果我们想使用按照名称(byName)来装配，可以结合 @Qualifier 注解一起使用。如下：

public class TestServiceImpl { 
    @Autowired 
    @Qualifier("userDao") 
    private UserDao userDao; 
}

@Autowired 注解可以用于 Setter 方法、构造函数、字段， 甚至普通方法，前提是方法必须有至少一个参数。

@Autowired 可以用于数组和使用泛型的集合类型。然后 Spring 会将容器中所有类型符合的 Bean 注入进来。例如 @Autowired 标注作用于 Map 类型时，如果 Map 的 key 为 String 类型，则 Spring 会将容器中所有类型符合 Map 的 value 对应的类型的 Bean 增加进来，用 Bean 的 id 或 name 作为 Map 的 key。当标注了 @Autowired 后，自动注入不能满足，则会抛出异常。

@Resource

@Resource 默认按照 byName 自动注入，由 J2EE 提供，需要导入包：javax.annotation.Resource;

@Resource 有两个重要的属性：name 和 type，而 Spring 将 @Resource 注解的 name 属性解析为 bean 的名字，而 type 属性则解析为 bean 的类型。所以，如果使用 name 属性，则使用 byName 自动注入策略，而使用 type 属性时则使用 byType 自动注入策略。如果既不指定 name 也不指定 type 属性，这时将通过反射机制使用 byName 自动注入策略。

public class TestServiceImpl { 
    //下面两种@Resource只要使用一种即可 
    //用于字段上 
    @Resource(name="userDao") 
    private UserDao userDao; 
    //用于属性的setter方法上 
    @Resource(name="userDao") 
    public void setUserDao(UserDao userDao) { 
        this.userDao = userDao; 
    } 
}

注：最好是将 @Resource 放在 setter 方法上，因为这样更符合面向对象的思想，通过 set、get 去操作属性，而不是直接去操作属性。

@Resource 装配顺序：

• 如果同时指定了 name 和 type，则从 Spring 上下文中找到唯一匹配的 bean 进行装配，找不到则抛出异常。
• 如果只指定了 name，则从上下文中查找名称(id)匹配的 bean 进行装配，找不到则抛出异常。
• 如果只指定了 type，则从上下文中找到类型匹配的唯一 bean 进行装配，找不到或是找到多个，都会抛出异常。
• 如果既没有指定 name，又没有指定 type，则自动按照 byName 方式进行装配；如果没有匹配，则回退为一个原始类型进行匹配，如果匹配则自动装配。

@Resource 的作用相当于 @Autowired，只不过 @Autowired 按照 byType 自动注入。@Resource 不指定属性的情况下默认按照 byName 自动注入。

9. @PostConstruct 和 @PreDestroy

javax.annotation.PostConstruct

javax.annotation.PreDestroy

@PostConstruct 该注解被用来修饰一个非静态的 void() 方法。被 @PostConstruct 修饰的方法会在服务器加载 Servlet 的时候运行，并且只会被服务器执行一次。通常我们会是在 Spring 框架中使用到 @PostConstruct 注解。

@PreDestroy 该注解被用来修饰一个非静态的 void() 方法。被 @PreDestroy 修饰的方法会在服务器卸载 Servlet 的时候运行，并且只会被服务器执行一次。

bean 初始化时各方法执行顺序：

静态代码块 -> Constructor（构造方法） -> @Autowired（依赖注入） -> @PostConstruct 注释的方法 -> 服务关闭时执行：@PreDestroy 注释的方法

示例代码：

package com.example.demo.compont;

import com.example.demo.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;

@Component
public class TestCompont {
    public TestCompont() {
        System.out.println("构造方法执行了...");
    }

    @PostConstruct
    public void postConstruct1() {
        System.out.println("第一个postConstruct方法执行了...");
    }

    static {
        System.out.println("静态代码块执行了...");
    }

    //随机
    @PostConstruct
    public void postConstruct2() {
        System.out.println("第二个postConstruct方法执行了...");
    }

    @PostConstruct
    public void postConstruct3() {
        System.out.println("第三个postConstruct方法执行了...");
    }

    @Autowired
    private UserService userService;

    @PreDestroy
    public void preDestroy() {
        System.out.println("preDestroy方法执行了...");
    }
}

注意一个类中多个方法都添加了 @PostConstruct 注解，则这些方法按照随机顺序执行。

package com.example.demo.service;

public interface UserService {
}

package com.example.demo.service.impl;

import com.example.demo.service.UserService;
import org.springframework.stereotype.Service;

@Service
public class UserServiceImpl implements UserService {
    public UserServiceImpl() {
        System.out.println("AutoWired 的 UserServiceImpl 的构造函数执行了...");
    }
}

启动服务后的日志如下：

.   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::               (v2.7.16)

2024-07-19 16:38:22.988  INFO 196260 --- [           main] com.example.demo.DemoApplication         : Starting DemoApplication using Java 1.8.0_401 on wbpc with PID 196260 (D:\Project\2022IdeaProject\demo\target\classes started by wangb in D:\Project\2022IdeaProject\demo)
2024-07-19 16:38:22.990  INFO 196260 --- [           main] com.example.demo.DemoApplication         : The following 1 profile is active: "dev"
2024-07-19 16:38:23.515  INFO 196260 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port(s): 8080 (http)
2024-07-19 16:38:23.518  INFO 196260 --- [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2024-07-19 16:38:23.519  INFO 196260 --- [           main] org.apache.catalina.core.StandardEngine  : Starting Servlet engine: [Apache Tomcat/9.0.80]
2024-07-19 16:38:23.609  INFO 196260 --- [           main] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2024-07-19 16:38:23.609  INFO 196260 --- [           main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 596 ms
静态代码块执行了...
构造方法执行了...
AutoWired 的 UserServiceImpl 的构造函数执行了...
第三个postConstruct方法执行了...
第一个postConstruct方法执行了...
第二个postConstruct方法执行了...
2024-07-19 16:38:24.016  INFO 196260 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2024-07-19 16:38:24.021  INFO 196260 --- [           main] com.example.demo.DemoApplication         : Started DemoApplication in 1.244 seconds (JVM running for 1.693)
preDestroy方法执行了...

进程已结束，退出代码为 130