175. Java 注释 - 预定义的注释类型

Java SE API 提供了一些预定义的注释类型，这些注释有助于增强代码的可读性、可维护性，并提供编译器、JVM 或其他工具的额外信息。常见的注释类型包括 @Deprecated、@Override 和 @SuppressWarnings，它们用于特定的场景，如标记弃用的代码、覆盖超类方法以及禁用编译器警告等。

📝 常用的 `Java` 注释类型

1. `@Deprecated` 注释

@Deprecated 注释标记某个类、方法或字段为弃用，这意味着该元素不再建议使用，未来的版本中可能会删除它。当使用带有 @Deprecated 注释的元素时，编译器会发出警告。

// Javadoc 注释中的使用说明
/**
 * @deprecated
 * This method is no longer recommended for use due to performance issues.
 */
@Deprecated
static void deprecatedMethod() {
    // Method logic here
}

Java SE 9 新增的功能： @Deprecated 注释现在支持一个 forRemoval 属性，指示该元素是否计划在未来的版本中删除。如果 forRemoval = true，则表示该元素将被删除；默认值是 false。

@Deprecated(forRemoval = true)
void oldMethod() {
    // This method is marked for future removal
}

2. `@Override` 注释

@Override 注释告知编译器该方法重写了超类中的一个方法。尽管这不是强制性的，但它有助于防止意外错误——如果方法签名不匹配，编译器将给出错误提示，确保方法确实覆盖了超类的方法。

@Override
int overriddenMethod() {
    // This method overrides a method from the superclass
    return 0;
}

3. `@SuppressWarnings` 注释

@SuppressWarnings 注释指示编译器禁用特定类型的警告，从而避免显示默认会出现的警告。例如，如果使用了已弃用的方法，通常会收到弃用警告，但我们可以通过 @SuppressWarnings("deprecation") 来禁止这些警告显示。

@SuppressWarnings("deprecation")
void useDeprecatedMethod() {
    deprecatedMethod();  // This method call is deprecated, but no warning will be shown
}

多个警告类别可以一起使用：

@SuppressWarnings({"unchecked", "deprecation"})
void processLegacyCode() {
    // Suppress both unchecked and deprecation warnings
}

4. `@SafeVarargs` 注释

@SafeVarargs 注释用于指示方法或构造函数安全地使用可变参数（varargs），并且没有执行任何不安全的操作。该注释可以避免与 varargs 使用相关的未选中警告。

@SafeVarargs
public static <T> void safeMethod(T... elements) {
    // Safe use of varargs parameter
}

5. `@FunctionalInterface` 注释

@FunctionalInterface 注释表明一个接口是功能接口，即该接口仅包含一个抽象方法。Java SE 8 引入了此注释类型，用于明确标识这些接口，以便可以在 lambda 表达式中使用。

@FunctionalInterface
public interface MyFunctionalInterface {
    void myMethod();  // Single abstract method (SAM)
}

📝 元注释：注释的注解

元注释（meta-annotations）是应用于其他注释的注释。它们用于控制注释的行为，定义注释的适用范围和作用等。常见的元注释包括 @Retention、@Target 和 @Documented 等。

1. `@Retention` 注释

@Retention 注释用于指定注释的保留策略，即注释在哪个阶段可用。它有三个选项：

RetentionPolicy.SOURCE：注释仅在源代码中可见，编译器将忽略该注释。
RetentionPolicy.CLASS：注释在编译后的 .class 文件中保留，但 JVM 会忽略它。
RetentionPolicy.RUNTIME：注释在运行时仍然可用，JVM 会保留它，可以通过反射访问。

@Retention(RetentionPolicy.RUNTIME)
@interface MyRuntimeAnnotation {
    String value();
}

2. `@Documented` 注释

@Documented 注释指示该注释应包含在 Javadoc 中。当应用于某个注释类型时，Javadoc 工具将生成包含该注释的文档。

@Documented
@interface MyAnnotation {
    String description() default "No description";
}

3. `@Target` 注释

@Target 注释用于指定该注释可应用的Java 元素类型。例如，@Target 可以限制注释仅应用于方法、字段、类或其他 Java 元素。

@Target(ElementType.METHOD)  // This annotation can only be applied to methods
@interface MyMethodAnnotation {
    String description();
}

4. `@Inherited` 注释

@Inherited 注释表示注释可以从超类继承。这意味着如果在父类中定义了注释，子类也会继承该注释。该注释仅适用于类级注释。

@Inherited
@interface MyInheritedAnnotation {
    String value();
}

5. `@Repeatable` 注释

@Repeatable 注释允许同一个注释类型可以多次应用于同一声明或类型使用。Java SE 8 引入了这一特性，允许在类、方法或字段上多次使用相同的注释类型。

@Repeatable(MyAnnotations.class)
@interface MyAnnotation {
    String value();
}

@interface MyAnnotations {
    MyAnnotation[] value();
}

📌 总结

@Deprecated 用于标记不再推荐使用的代码元素，并在使用时生成警告。
@Override 用于标识方法是覆盖超类的方法，并有助于防止错误。
@SuppressWarnings 用于抑制特定类型的编译警告。
@SafeVarargs 用于指示方法安全地使用可变参数（varargs）。
@FunctionalInterface 用于声明功能接口，表明该接口是可以用作 Lambda 表达式的目标接口。

元注释（如 @Retention、@Target 和 @Documented）是控制注释行为的工具，它们帮助定义注释的作用范围和生命周期。