Классы, методы, переменные, параметры, пакеты и т. д. в языке Java могут быть аннотированы. В отличие от Javadoc, содержимое Java-аннотаций можно извлечь с помощью рефлексии. Когда компилятор генерирует файлы классов, аннотации могут быть встроены в байт-код. Виртуальная машина Java может сохранять содержимое аннотаций, и это содержимое можно извлечь во время выполнения. Конечно, она также поддерживает пользовательские Java-аннотации.
В интернете много статей о Java-аннотациях, которые могут ошеломить. Java-аннотации на самом деле довольно просты, но авторам не удалось объяснить их ясно, из-за чего читатели запутываются ещё больше.
Я систематизировал аннотации согласно собственному пониманию. Ключ к пониманию аннотаций — понять их синтаксис и использование, и я подробно это объяснил. После понимания синтаксиса и использования взгляд на схему фреймворка может дать вам более глубокое понимание. Хватит разглагольствовать; давайте начнём объяснять аннотации. Если вы найдёте в статье ошибки или недостатки, пожалуйста, укажите на них!
Встроенные аннотации
Java определяет набор аннотаций, всего 7. 3 находятся в java.lang, а остальные 4 — в java.lang.annotation.
Аннотации, действующие на код:
- @Override — проверяет, является ли метод переопределяющим. Если обнаруживается, что в родительском классе или в указанном интерфейсе нет этого метода, выдаётся ошибка компиляции.
- @Deprecated — помечает метод как устаревший. Если метод используется, выдаётся предупреждение компиляции.
- @SuppressWarnings — указывает компилятору игнорировать предупреждения, объявленные в аннотации.
Аннотации, действующие на другие аннотации (или мета-аннотации):
- @Retention — определяет, как сохраняется эта аннотация: только в коде, компилируется в файл класса или доступна через рефлексию во время выполнения.
- @Documented — указывает, включаются ли эти аннотации в пользовательскую документацию.
- @Target — указывает, к какому виду членов Java должна применяться эта аннотация.
- @Inherited — указывает, от какого класса аннотации наследуется эта аннотация (по умолчанию аннотации не наследуются никакими подклассами).
Начиная с Java 7 были добавлены 3 дополнительные аннотации:
- @SafeVarargs — поддерживается начиная с Java 7, игнорирует предупреждения, создаваемые вызовами методов или конструкторов, которые используют обобщённые параметры переменной длины.
- @FunctionalInterface — поддерживается начиная с Java 8, обозначает анонимную функцию или функциональный интерфейс.
- @Repeatable — поддерживается начиная с Java 8, указывает, что аннотацию можно использовать несколько раз в одном объявлении.
1. Архитектура аннотаций

Из этого видно:
(01) 1 Annotation связана с 1 RetentionPolicy.
Это можно понимать так: каждый объект Annotation имеет уникальный атрибут RetentionPolicy.(02) 1 Annotation связан с 1~n ElementType.
Это можно понимать так: каждый объект Annotation может иметь несколько атрибутов ElementType.
(03) У Annotation много классов реализации, включая: Deprecated, Documented, Inherited, Override и т. д.
Каждый класс реализации Annotation "связан с 1 RetentionPolicy" и "связан с 1~n ElementType".
Ниже я сначала представлю левую половину схемы фреймворка (как показано ниже), а именно Annotation, RetentionPolicy и ElementType; затем я приведу примеры, поясняющие классы реализации Annotation.

2. Компоненты Annotation
Среди компонентов аннотаций Java есть 3 очень важных базовых класса. Это:
Annotation.java
public interface Annotation {
boolean equals(Object obj);
int hashCode();
String toString();
Class<? extends Annotation> annotationType();
}
ElementType.java
public enum ElementType {
TYPE, /* Объявление класса, интерфейса (включая тип аннотации) или перечисления */
FIELD, /* Объявление поля (включая константу перечисления) */
METHOD, /* Объявление метода */
PARAMETER, /* Объявление параметра */
CONSTRUCTOR, /* Объявление конструктора */
LOCAL_VARIABLE, /* Объявление локальной переменной */
ANNOTATION_TYPE, /* Объявление типа аннотации */
PACKAGE /* Объявление пакета */
}
RetentionPolicy.java
public enum RetentionPolicy {
SOURCE, /* Информация об аннотации существует только во время обработки компилятором; после завершения работы компилятора информация об аннотации больше не существует */
CLASS, /* Компилятор сохраняет аннотацию в .class-файле, соответствующем классу. Поведение по умолчанию */
RUNTIME /* Компилятор сохраняет аннотацию в файле класса, и она может быть прочитана JVM */
}
Пояснение:
(01) Аннотация — это просто интерфейс.
«Каждая аннотация» связана с «1 RetentionPolicy» и связана с «1~n ElementType». Простыми словами: каждый объект аннотации имеет уникальный атрибут RetentionPolicy; что касается атрибута ElementType, то их 1~n.
(02) ElementType — это enum-тип, используемый для указания типа аннотации.
«Каждая аннотация» связана с «1~n ElementType». Когда аннотация связана с определённым ElementType, это означает, что аннотация имеет определённое назначение. Например, если объект аннотации имеет тип METHOD, то аннотация может использоваться только для модификации методов.
(03) RetentionPolicy — это enum-тип, используемый для указания политики аннотации. Проще говоря, аннотации с разными типами RetentionPolicy имеют разные области действия.
«Каждая аннотация» связана с «1 RetentionPolicy».
- a) Если тип аннотации — SOURCE, это означает: аннотация существует только во время обработки компилятором; после завершения обработки компилятором аннотация больше не полезна. Например, маркер «@Override» — это аннотация. Когда он модифицирует метод, это означает, что метод переопределяет метод родительского класса, и во время компиляции выполняется синтаксическая проверка! После завершения обработки компилятором «@Override» больше не оказывает никакого эффекта.
- b) Если тип аннотации — CLASS, это означает: компилятор сохраняет аннотацию в .class-файле, соответствующем классу. Это поведение аннотации по умолчанию.
- c) Если тип Annotation — RUNTIME, это означает: компилятор сохраняет Annotation в class-файле, и она может быть прочитана JVM.
На данном этапе вам просто нужно запомнить, что "каждая Annotation" связана с "1 RetentionPolicy" и связана с "1~n ElementType". После изучения последующего материала, возвращение к этому содержимому облегчит его понимание.
3. Аннотации, предоставляемые Java
Разобравшись с ролями 3 классов выше, теперь мы можем объяснить синтаксические определения классов реализации Annotation.
1) Общее определение Annotation
@Documented
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
public @interface MyAnnotation1 {
}
Пояснение:
Выше приведено определение Annotation с именем MyAnnotation1. После определения MyAnnotation1 мы можем использовать @MyAnnotation1 в коде. Остальные — @Documented, @Target, @Retention, @interface — все используются для модификации MyAnnotation1. Ниже объясним их значения соответственно:
(01) @interface
Когда @interface используется для определения аннотации, это означает, что она реализует интерфейс java.lang.annotation.Annotation, то есть аннотация является Annotation.
При определении Annotation требуется @interface.Примечание: это отличается от нашего обычного способа реализации интерфейсов с помощью "implements". Детали реализации интерфейса Annotation полностью выполняются компилятором. После определения аннотации с помощью @interface аннотация не может наследовать другие аннотации или интерфейсы.
(02) @Documented
По умолчанию Аннотации на классах и методах не появляются в javadoc. Если Annotation модифицирована с помощью @Documented, это означает, что она может появляться в javadoc.
При определении аннотации @Documented необязательна; если она не определена, аннотация не будет отображаться в javadoc.
(03) @Target(ElementType.TYPE)
Ранее мы говорили, что ElementType — это атрибут type аннотации. А роль @Target — указать атрибут type аннотации.
@Target(ElementType.TYPE) означает указание, что типом этой аннотации является ElementType.TYPE. Это означает, что MyAnnotation1 — это аннотация, используемая для изменения «класс, интерфейс (включая типы аннотаций) или объявления enum».
При определении аннотации @Target необязательна. Если @Target есть, аннотация может использоваться только в указанных ею местах; если @Target нет, аннотация может использоваться где угодно.
(04) @Retention(RetentionPolicy.RUNTIME)
Ранее мы говорили, что RetentionPolicy — это атрибут strategy аннотации, а роль @Retention — указать атрибут strategy аннотации.
@Retention(RetentionPolicy.RUNTIME) означает указание, что стратегией этой аннотации является RetentionPolicy.RUNTIME. Это означает, что компилятор сохранит информацию об аннотации в файле .class, и она может быть прочитана виртуальной машиной.
При определении аннотации @Retention необязательна. Если @Retention нет, по умолчанию используется RetentionPolicy.CLASS.
2) Аннотации, предоставляемые Java
Из приведённых выше примеров можно понять: @interface используется для объявления аннотации, @Documented используется, чтобы указать, будет ли аннотация отображаться в javadoc, @Target используется для указания типа аннотации, а @Retention — для указания стратегии аннотации.
Поняв это, мы можем легко понять классы реализации аннотаций, поставляемых с Java, то есть правую половину диаграммы архитектуры аннотаций. Как показано ниже:

Часто используемые аннотации в Java:
@Deprecated -- @Deprecated 所标注内容,不再被建议使用。 @Override -- @Override 只能标注方法,表示该方法覆盖父类中的方法。 @Documented -- @Documented 所标注内容,可以出现在javadoc中。 @Inherited -- @Inherited只能被用来标注“Annotation类型”,它所标注的Annotation具有继承性。 @Retention -- @Retention只能被用来标注“Annotation类型”,而且它被用来指定Annotation的RetentionPolicy属性。 @Target -- @Target只能被用来标注“Annotation类型”,而且它被用来指定Annotation的ElementType属性。 @SuppressWarnings -- @SuppressWarnings 所标注内容产生的警告,编译器会对这些警告保持静默。
Поскольку "@Deprecated и @Override" похожи, а "@Documented, @Inherited, @Retention, @Target" похожи; ниже мы объясним только три аннотации: @Deprecated, @Inherited и @SuppressWarnings.
2.1) @Deprecated
Определение @Deprecated выглядит следующим образом:
@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface Deprecated {
}
Пояснение:
- (01) @interface -- Используется для модификации Deprecated, то есть Deprecated реализует интерфейс java.lang.annotation.Annotation; иначе говоря, Deprecated является аннотацией. (02) @Documented -- Его роль — указывать, что эта аннотация может появляться в javadoc.
- (03) @Retention(RetentionPolicy.RUNTIME) -- Его роль — указать, что стратегия Deprecated — RetentionPolicy.RUNTIME. Это означает, что компилятор сохранит информацию о Deprecated в файле .class, и она может быть прочитана виртуальной машиной.
- (04) Содержимое, помеченное @Deprecated, больше не рекомендуется к использованию.
Например, если метод помечен @Deprecated, этот метод больше не рекомендуется использовать. Если разработчик пытается использовать или переопределить метод, помеченный @Deprecated, компилятор выдаст соответствующее предупреждающее сообщение. Пример выглядит следующим образом:

DeprecatedTest.java
import java.util.Calendar;
public class DeprecatedTest {
// @Deprecated модифицирует getString1(), указывая, что это функция, не рекомендованная к использованию
@Deprecated
private static void getString1(){
System.out.println("Устаревший метод");
}
private static void getString2(){
System.out.println("Обычный метод");
}
// Date — это класс даты/времени. Java больше не рекомендует использовать этот класс
private static void testDate() {
Date date = new Date(113, 8, 25);
System.out.println(date.getYear());
}
// Calendar — это класс даты/времени. Java рекомендует использовать Calendar вместо Date для представления "дата/время"
private static void testCalendar() {
Calendar cal = Calendar.getInstance();
System.out.println(cal.get(Calendar.YEAR));
}
public static void main(String[] args) {
getString1();
getString2();
testDate();
testCalendar();
}
}
Пояснение:
Выше приведён скриншот из Eclipse, сравнивающий "getString1() и getString2()" и "testDate() и testCalendar()" в классе.
(01) getString1() помечен @Deprecated, что означает, что getString1() больше не рекомендуется использовать; поэтому и определение, и вызов getString1() имеют зачёркивание. Это зачёркивание — способ Eclipse обрабатывать методы, помеченные @Deprecated.
getString2() не помечен @Deprecated, поэтому его отображение обычное.
(02) testDate() вызывает методы, связанные с Date, но java не рекомендует использовать Date для операций с датой/временем. Поэтому при вызове API Date генерируются предупреждающие сообщения, а именно предупреждения на рисунке.
testCalendar() вызывает API Calendar для работы с датой/временем. java рекомендует использовать Calendar вместо Date. Поэтому работа с Calendar не приведёт к появлению предупреждения.
2.2) @Inherited
Определение @Inherited выглядит следующим образом:
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.ANNOTATION_TYPE)
public @interface Inherited {
}
Пояснение:
- (01) @interface -- используется для модификации Inherited, что означает, что Inherited реализует интерфейс java.lang.annotation.Annotation; то есть Inherited является аннотацией.
- (02) @Documented -- его роль — указывать, что эта аннотация может появляться в javadoc.
- (03) @Retention(RetentionPolicy.RUNTIME) -- его роль — указать, что стратегия Inherited — RetentionPolicy.RUNTIME. Это означает, что компилятор сохранит информацию Inherited в файле .class, и она может быть прочитана виртуальной машиной.
- (04) @Target(ElementType.ANNOTATION_TYPE) -- Его роль — указать, что типом Inherited является ANNOTATION_TYPE. Это означает, что @Inherited можно использовать только для аннотирования "типов аннотаций".
- (05) Смысл @Inherited состоит в том, что аннотация, которую он аннотирует, будет иметь наследование.
MyAnnotation, тогда Base "имеет аннотацию MyAnnotation"; теперь Sub наследует Base, и поскольку MyAnnotation является @Inherited (имеет наследование), Sub также "имеет аннотацию MyAnnotation".
Пример использования @Inherited:
InheritableSon.java
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Inherited;
/**
* Пользовательская аннотация.
*/
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@interface Inheritable
{
}
@Inheritable
class InheritableFather
{
public InheritableFather() {
// Содержит ли InheritableBase аннотацию Inheritable
System.out.println("InheritableFather:"+InheritableFather.class.isAnnotationPresent(Inheritable.class));
}
}
/**
* Класс InheritableSon всего лишь наследуется от InheritableFather,
*/
public class InheritableSon extends InheritableFather
{
public InheritableSon() {
super(); // Вызвать конструктор родительского класса
// Содержит ли класс InheritableSon аннотацию Inheritable
System.out.println("InheritableSon:"+InheritableSon.class.isAnnotationPresent(Inheritable.class));
}
public static void main(String[] args)
{
InheritableSon is = new InheritableSon();
}
}
Результат выполнения:
InheritableFather:true InheritableSon:true
Теперь давайте изменим InheritableSon.java: закомментируем "@Inherited аннотацию Inheritable".
InheritableSon.java
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Inherited;
/**
* Пользовательская аннотация.
*/
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
//@Inherited
@interface Inheritable
{
}
@Inheritable
class InheritableFather
{
public InheritableFather() {
// Содержит ли InheritableBase аннотацию Inheritable
System.out.println("InheritableFather:"+InheritableFather.class.isAnnotationPresent(Inheritable.class));
}
}
/**
* Класс InheritableSon всего лишь наследуется от InheritableFather,
*/
public class InheritableSon extends InheritableFather
{
public InheritableSon() {
super(); // Вызов конструктора родительского класса
// Содержит ли класс InheritableSon аннотацию Inheritable
System.out.println("InheritableSon:"+InheritableSon.class.isAnnotationPresent(Inheritable.class));
}
public static void main(String[] args)
{
InheritableSon is = new InheritableSon();
}
}
Вывод:
InheritableFather:true InheritableSon:false
Сравнивая два приведённых выше результата, мы видим, что когда аннотация Inheritable помечена @Inherited, она обладает наследованием. В противном случае она не обладает наследованием.
2.3) @SuppressWarnings
Определение @SuppressWarnings выглядит следующим образом:
@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
public @interface SuppressWarnings {
String[] value();
}
Пояснение:
(01) @interface -- Он используется для модификации SuppressWarnings, что означает, что SuppressWarnings реализует интерфейс java.lang.annotation.Annotation; то есть SuppressWarnings является аннотацией.
(02) @Retention(RetentionPolicy.SOURCE) -- Его цель — указать, что политика SuppressWarnings — RetentionPolicy.SOURCE. Это означает, что информация SuppressWarnings существует только во время обработки компилятором; после завершения обработки компилятором SuppressWarnings не оказывает эффекта.
(03) @Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE}) -- Его цель — указать, что типы SuppressWarnings включают TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE.
- TYPE означает, что он может аннотировать "классы, интерфейсы (включая типы аннотаций) или объявления enum".
- FIELD означает, что он может аннотировать "объявления полей".
- METHOD означает, что он может аннотировать "методы".
- PARAMETER означает, что он может аннотировать "параметры".
- CONSTRUCTOR означает, что он может аннотировать "конструкторы".
- LOCAL_VARIABLE означает, что он может аннотировать "локальные переменные".
(04) String[] value(); означает, что SuppressWarnings может задавать параметры.
(05) Назначение SuppressWarnings — заставить компилятор молчать об определённых предупреждениях в аннотируемом содержимом. Например, "@SuppressWarnings(value={"deprecation", "unchecked"})" означает молчать о "предупреждениях об устаревании" и "предупреждениях о непроверенных преобразованиях" в аннотируемом содержимом. Пример:


SuppressWarningTest.java
public class SuppressWarningTest {
//@SuppressWarnings(value={"deprecation"})
public static void doSomething(){
Date date = new Date(113, 8, 26);
System.out.println(date);
}
public static void main(String[] args) {
doSomething();
}
}
Пояснение:
(01) На левом рисунке @SuppressWarnings(value={"deprecation"}) не используется, и Date — это класс, использование которого Java больше не рекомендует. Поэтому вызов API Date приведёт к предупреждению. На правом рисунке @SuppressWarnings(value={"deprecation"}) используется. Поэтому компилятор не выдаёт «предупреждение, сгенерированное при вызове API Date».
Дополнение: Таблица часто используемых ключевых слов для SuppressWarnings
deprecation -- 使用了不赞成使用的类或方法时的警告 unchecked -- 执行了未检查的转换时的警告,例如当使用集合时没有用泛型 (Generics) 来指定集合保存的类型。 fallthrough -- 当 Switch 程序块直接通往下一种情况而没有 Break 时的警告。 path -- 在类路径、源文件路径等中有不存在的路径时的警告。 serial -- 当在可序列化的类上缺少 serialVersionUID 定义时的警告。 finally -- 任何 finally 子句不能正常完成时的警告。 all -- 关于以上所有情况的警告。
4. Роль аннотаций
Аннотация — это вспомогательный класс, который широко используется в таких инструментальных фреймворках, как Junit, Struts и Spring.
Функции аннотаций, которые мы часто используем в программировании, включают:
1) Проверка во время компиляции
Аннотация обладает «функцией, позволяющей компилятору выполнять проверки при компиляции».
Например, @SuppressWarnings, @Deprecated и @Override все обладают функциями проверки при компиляции.
(01) @SuppressWarnings и @Deprecated уже подробно описаны в «Части 3». Дополнительные примеры здесь не приводятся.
(02) Если метод помечен @Override, это означает, что метод переопределяет метод с тем же именем в родительском классе. Если метод помечен @Override, но в родительском классе нет метода с тем же именем, который «помечен @Override», компилятор сообщит об ошибке. Пример:

OverrideTest.java
/**
* toString() определён в java.lang.Object;
* Следовательно, использование @Override здесь корректно.
*/
@Override
public String toString(){
return "Override toString";
}
/**
* getString() не определён ни в одном родительском классе OverrideTest;
* Однако здесь он помечен @Override, поэтому возникнет ошибка компиляции!
*/
@Override
public String getString(){
return "get toString";
}
public static void main(String[] args) {
}
}
Выше приведён скриншот программы в Eclipse. Из него видно, что функция "getString()" выдаст ошибку. Это связано с тем, что "getString() помечен @Override, но getString1() не определён ни в одном родительском классе OverrideTest".
Если закомментировать "@Override над getString()", ошибка будет устранена.
2) Использование аннотаций в рефлексии
В функциях отражения, таких как Class, Method и Field, есть много интерфейсов, связанных с Annotation.
Это также означает, что мы можем разбирать и использовать Annotation в отражении.
AnnotationTest.java
import java.lang.annotation.Target;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Inherited;
import java.lang.reflect.Method;
/**
* Пример использования Annotation в функциях отражения
*/
@Retention(RetentionPolicy.RUNTIME)
@interface MyAnnotation {
String[] value() default "unknown";
}
/**
* Класс Person. Он будет использовать аннотацию MyAnnotation.
*/
class Person {
/**
* Метод empty() помечен одновременно "@Deprecated" и "@MyAnnotation(value={"a","b"})"
* (01) @Deprecated означает, что метод empty() больше не рекомендуется использовать
* (02) @MyAnnotation означает, что значение MyAnnotation, соответствующее методу empty(), является значением по умолчанию "unknown"
*/
@MyAnnotation
@Deprecated
public void empty(){
System.out.println("\nempty");
}
/**
* sombody() помечен @MyAnnotation(value={"girl","boy"}),
* @MyAnnotation(value={"girl","boy"}) означает, что значением MyAnnotation является {"girl","boy"}
*/
@MyAnnotation(value={"girl","boy"})
public void somebody(String name, int age){
System.out.println("\nsomebody: "+name+", "+age);
}
}
public class AnnotationTest {
public static void main(String[] args) throws Exception {
// Создать новый Person
Person person = new Person();
// Получить экземпляр Class для Person
Class<Person> c = Person.class;
// Получить экземпляр Method метода somebody()
Method mSomebody = c.getMethod("somebody", new Class[]{String.class, int.класс});
// Выполнить метод
mSomebody.invoke(person, new Object[]{"lily", 18});
iteratorAnnotations(mSomebody);
// Получить экземпляр Method метода somebody()
Method mEmpty = c.getMethod("empty", new Класс[]{});
// Выполнить метод
mEmpty.invoke(person, new Object[]{});
iteratorAnnotations(mEmpty);
}
public static void iteratorAnnotations(Method method) {
// Определить, содержит ли метод somebody() аннотацию MyAnnotation
if(method.isAnnotationPresent(MyAnnotation.class)){
// Получить экземпляр аннотации MyAnnotation для метода
MyAnnotation myAnnotation = method.getAnnotation(MyAnnotation.class);
// Получить значение myAnnotation и вывести его
String[] values = myAnnotation.value();
for (String str:values)
System.out.printf(str+", ");
System.out.println();
}
// Получить все аннотации метода и вывести их
Annotation[] annotations = method.getAnnotations();
for(Annotation annotation : annotations){
System.out.println(annotation);
}
}
}
Вывод:
somebody: lily, 18 girl, boy, @com.skywang.annotation.MyAnnotation(value=[girl, boy]) empty unknown, @com.skywang.annotation.MyAnnotation(value=[unknown]) @java.lang.Deprecated()
3) Генерация справочной документации на основе аннотаций
Добавив тег @Documented к аннотации Annotation, можно сделать так, чтобы тег Annotation появлялся в javadoc.
4) Полезно для просмотра кода
С помощью @Override, @Deprecated и т. д. мы можем легко понять общую структуру программы.
Кроме того, мы также можем реализовать некоторые функции с помощью пользовательской аннотации.
Исходный адрес: https://www.cnblogs.com/skywang12345/p/3344137.html