172. Java 注释 - 使用方式及常见类型

🎯 注释的用途

在 Java 中，注释具有多种用途，主要包括以下几种：

1. 编译器信息：注释可以用来向编译器提供信息，例如检测错误或抑制警告。
2. 编译时间和部署时间处理：工具可以读取注释中的信息，生成代码、配置文件（如 XML）、文档等。
3. 运行时处理：某些注释可以在运行时被反射读取，用于动态处理（例如依赖注入框架）。

📝 注释的格式

注释在 Java 中通常以 @ 符号开头，后跟注释名称和可选的元素。它们可以附加到类、方法、字段等代码元素上。

1. 基本注释结构：

• 注释没有元素：例如 @Override，指示该方法覆盖了父类的方法。

@Override
void mySuperMethod() { 
    // 方法实现
}

• 注释带有元素：例如 @Author 注释，可以包含元素和对应的值。

@Author(name = "Benjamin Franklin", date = "3/27/2003")
class MyClass { 
    // 类实现
}

• 只有一个元素的注释：如果只有一个命名元素，可以省略元素名。例如 @SuppressWarnings 注释：

@SuppressWarnings("unchecked")
void myMethod() { 
    // 方法实现
}

2. 多个注释的使用：

Java 允许在同一声明上使用多个注释。例如：

@Author(name = "Jane Doe")
@EBook
class MyClass { 
    // 类实现
}

3. 重复注释：

从 Java SE 8 开始，支持重复注释，即在同一个元素上使用多次相同类型的注释。例如：

@Author(name = "Jane Doe")
@Author(name = "John Smith")
class MyClass { 
    // 类实现
}

重复注释对于某些场景非常有用，比如在框架开发中，允许为同一类或方法添加多个注释来描述不同的特性。

🧑💻 预定义注释类型

Java SE 提供了一些常用的预定义注释类型，这些注释在编译时、运行时或者文档生成过程中起着重要作用：

• @Override：表示当前方法是对父类方法的重写。

  @Override
  void mySuperMethod() {
      // 重写方法实现
  }
  

• @SuppressWarnings：用于抑制特定的编译器警告，例如抑制“unchecked”警告。

  @SuppressWarnings("unchecked")
  void myMethod() {
      // 方法实现
  }
  

• @Entity（通常在 JPA 中使用）：表示当前类是一个实体类，映射到数据库表。

  @Entity
  public class User { 
      // 类实现
  }
  

📝 自定义注释类型

除了 Java 提供的预定义注释类型外，开发者还可以自定义注释类型。自定义注释通常用于框架或库中，用于标注特殊行为或配置。例如：

public @interface Author {
    String name();
    String date();
}

@Author(name = "Benjamin Franklin", date = "3/27/2003")
class MyClass { 
    // 类实现
}

📌 常用注释类型

• @Entity：用于标识数据库实体类（常见于 JPA）。
• @Autowired：在 Spring 中，用于标注自动注入的依赖。
• @Transactional：表示方法或类需要在事务中执行（Spring 中使用）。

📍 注释与类型系统的结合

Java 注释可以与类型系统结合，提供更强的类型检查。例如，在泛型类型中，我们可以使用类型注释来增强类型信息：

@NonNull String myString;

这种类型注释可以被工具或库（如 Android Lint、Eclim）用来检测代码中的潜在问题。

🔁 结论

• 注释是 Java 编程中一个非常重要的部分，不仅用于文档和代码的描述，还能够帮助编译器和工具进行处理。
• Java 提供了多种注释类型，包括标准注释和自定义注释。
• 使用注释时要注意可读性和可维护性，避免注释过多导致代码混乱。
• 重复注释从 Java 8 开始得到支持，这使得开发者可以更加灵活地描述不同的特性和行为。