注解

注解是关于代码元素（如类、方法或参数）的元数据。

        @Override
        public String toString() {
            return String.valueOf(id);
        }
    
 

在 Java 中，有一组内置注解。此外，许多库和框架，如 Spring 和 Lombok，定义了它们自己的注解。这些注解提供的元数据可用于编译时和运行时，例如生成样板代码或通过反射与用户类进行交互。

代码合同注解

还有一类注解描述代码语义和契约。开发者可以使用它们更好地理解使用特定 API 的影响，并帮助静态分析器识别问题区域。

            public @Nullable List<Double> getDiscounts() {
                return discounts;
            }
        
  

IntelliJ IDEA 能识别最受欢迎的的 Java 注释，并在分析代码时将其考虑在内。此类注解框架的示例有 Checker Framework 和 ErrorProne

有关 JetBrains 的 @Contract 注释信息，请参阅官方存储库。

空指针注解

空值注解是代码契约注解的一个子集。通过显式声明元素的可空性，代码将更易于维护且不易发生与可空性相关的错误。

另一方面，IntelliJ IDEA 的静态分析将使用这些注释在设计时捕捉潜在错误。例如，IntelliJ IDEA 会分析项目中的数据流并报告潜在可能为 null 的变量的解引用尝试，或者反之，建议在安全的情况下删除多余的保护条件。

配置空值注解

虽然 IntelliJ IDEA 识别最受欢迎的的空值注解，但您可能仍然希望将自定义注解添加到列表中。 IntelliJ IDEA 会然后使用它们来确定符号的空值性。

前往设置 | 编辑器 | 检查 | 可能的错误 | 可空性和数据流问题。
在选项下，选择配置注释。

默认的可空性注解

默认情况下，以下注解会被 IntelliJ IDEA 识别：

android.support.annotation.Nullable
androidx.annotation.Nullable
androidx.annotation.RecentlyNullable
com.android.annotations.Nullable
edu.umd.cs.findbugs.annotations.Nullable
io.reactivex.annotations.Nullable
io.reactivex.rxjava3.annotations.Nullable
jakarta.annotation.Nullable
javax.annotation.CheckForNull
javax.annotation.Nullable
org.checkerframework.checker.nullness.compatqual.NullableDecl
org.checkerframework.checker.nullness.compatqual.NullableType
org.checkerframework.checker.nullness.qual.Nullable
org.eclipse.jdt.annotation.Nullable
org.jetbrains.annotations.Nullable
org.jspecify.annotations.Nullable

android.support.annotation.NonNull
androidx.annotation.NonNull
androidx.annotation.RecentlyNonNull
com.android.annotations.NonNull
edu.umd.cs.findbugs.annotations.NonNull
io.reactivex.annotations.NonNull
io.reactivex.rxjava3.annotations.NonNull
jakarta.annotation.Nonnull
javax.annotation.Nonnull
lombok.NonNull
org.checkerframework.checker.nullness.compatqual.NonNullDecl
org.checkerframework.checker.nullness.compatqual.NonNullType
org.checkerframework.checker.nullness.qual.NonNull
org.eclipse.jdt.annotation.NonNull
org.jetbrains.annotations.NotNull
org.jspecify.annotations.NonNull

禁用空值检查

使用 IntelliJ IDEA 构建工具编译项目时，IDE 会为所有使用 @NotNull 注解的代码元素添加断言。如果这些元素在运行时 null ，这些断言将引发错误。这种快速失败行为可能有助于您在早期阶段诊断问题。如果这不是您想要的效果，您可以禁用这些断言。

前往设置 Ctrl+Alt+S | 构建、执行、部署 | 编译器并取消选中为 notnull 注解的方法和参数添加运行时断言选项。

推断可空性

如果您的项目缺少空值注解，完全或部分缺少，您可以让 IntelliJ IDEA 推导并插入空值注解。

确保已为您的项目配置包含注解的库。 IntelliJ IDEA 使用在用于代码生成的注解中指定的注解在设置 | 编辑器 | 检查 | 可能的错误 | 空值性和数据流问题 | 配置注解中。
如果您想使用 JetBrains annotations ，并且您正在使用 IntelliJ IDEA 构建工具，IDE 将检测到缺少的依赖并建议自动添加它
在主菜单中，前往代码 | 分析代码 | 推断为null 性。
在指定推断空值范围对话框中，请选择分析范围。如果您想包括测试 sources 或注释局部变量，请选择相应的复选框。

JetBrains 注解依赖

IntelliJ IDEA 有自己的注解集，可作为单独的依赖项。其包含用于表示空值性、范围、约定、可变性、纯度等的注释。

该包包含数十个注解。一些最常见的是：

@Nullable 和 @NotNull—— 指示一个变量、参数或返回值可以或不可以为 null。
@Nls – 表示带注释的代码元素是需要本地化的字符串。
@NonNls – 表示注释的代码元素是用户不可见的字符串，不需要本地化，且不包含需要本地化的字符串。当您使用 @NonNls 标注一个元素时，本地化工具会跳过该元素及其中的字符串。
@PropertyKey 表示方法参数接受的参数必须是特定资源包中的有效属性键。当一个不是捆绑包中属性键的字符串文本作为参数传递时，IntelliJ IDEA 将其高亮显示为错误。该注解还用于在作为参数传递的字符串文本中提供补全。
@TestOnly—— 表示方法或构造函数必须仅从测试代码中调用。
@Contract——使您可以指定方法必须遵循的一组规则（契约）。如果违反合同，IntelliJ IDEA 会报告问题。
@Language – 在 Java 字符串中注入用另一种语言编写的代码。

将 JetBrains Annotations 依赖项添加到项目中

当您在代码中使用 JetBrains 注解时，将“annotations”添加到 classpath 意图操作将帮助您快速添加所需的依赖项。
否则，您可以使用以下工件坐标手动添加它： https://central.sonatype.com/artifact/org.jetbrains/annotations/24.0.1
<dependencies> <dependency> <groupId>org.jetbrains</groupId> <artifactId>annotations</artifactId> <version>26.0.2</version> <scope>provided</scope> </dependency> </dependencies>
dependencies { compileOnly 'org.jetbrains:annotations:26.0.2' }
dependencies { compileOnly("org.jetbrains:annotations:26.0.2") }
前往项目结构 Ctrl+Alt+Shift+S | 库。点击，然后选择来自 Maven。在搜索字段中，输入 org.jetbrains:annotations:26.0.2。点击 OK。
对于 JDK 1.5 到 1.7，请使用 annotations-java5 工件。

推断注解

如果代码完全没有注释，IntelliJ IDEA 仍然可以从字节码和源代码推断出许多注释。这些注解并不会实际插入代码中，但 IDE 显示它们，好像它们就在那儿，以帮助您更好地理解代码上下文。推断注解也与常规注解一样在代码分析中使用。

IntelliJ IDEA 可以推断以下 JetBrains 注解： @Nullable、 @NotNull、 @Contract、 @Unmodifiable 和 @UnmodifiableView。有关此注释风格的完整文档，请参阅 package source code。

在编辑器中，推断注解会在边栏中以图标标记。

向代码添加推断注解

如果您想在代码中实际插入推断的注解，请点击附近的所需注解，然后选择插入。

内联显示推断注释

您可以配置 IDE 以在代码中直接显示推断的注释。

按 Ctrl+Alt+S 打开设置，然后选择编辑器｜内嵌提示｜注解｜Java。
请选择推断注解复选框。

外部注解

如果您希望显式地使用注解，但又不希望它们杂乱地充斥您的代码库，也可以将它们存储在外部。您可以选择将带有注释的文件提交到公共仓库中，也可以将它们仅保留在本地环境中。

外部注解是存储在名为 annotations.xml 的 XML 文件中的常规注解。

通常情况下，您可能希望使用它们：

团队成员使用不同的 IDE 和静态分析工具
标注您无法更改其来源的代码，例如，库类
保持代码没有那些特定用途的注解（例如， @Async.Schedule/Execute 或 @DebugRenderer）。

在代码中，外部注释用栏边图标标记，并用灰色高亮显示。默认情况下，IntelliJ IDEA 会在编辑器中显示外部注释。

启用外部注释

要使用外部注解，您需要在设置中启用它们。如果您跳过此步骤，您将能够在外部注释库代码，但无法在源代码中使用外部注释。

按 Ctrl+Alt+S 打开设置，然后选择编辑器 | 代码样式 | Java | 代码生成。
请选择使用外部注解复选框。

添加外部注释

请通过以下一种方式指定外部注解：
- 在处理项目代码时，您可以输入注释，然后使用外部注释意图操作。要访问意图操作菜单，请将文本光标放在注解处并按 Alt+Enter （或点击意图操作图标）。
- 另一种方法，您可以对项目代码和库同时使用，就是对元素本身使用注解意图操作。
  根据当前上下文中的注释，IntelliJ IDEA 将允许您从菜单中选择所需的注释，或者如果只有一个注释可用，则会立即建议插入该注释。
如果您的项目或模块尚未配置annotations目录，IntelliJ IDEA将提示您进行设置。
此模块中添加的每个外部注解都将存储在该文件夹中。如果您有多个注解根，IntelliJ IDEA 将询问您使用哪一个。
您可以稍后更改此位置。

移除外部注解

点击注释元素附近的边距图标，然后选择取消标注。

配置注释根目录

注解根目录是存储外部注解的文件夹。它们根据适用的项目部分配置在不同的位置。

整个项目：项目结构 Ctrl+Alt+Shift+S | SDKs | 注解
对于单个模块：项目结构 Ctrl+Alt+Shift+S ｜模块｜路径｜外部注解
对于外部 Maven/Gradle 依赖：项目结构 Ctrl+Alt+Shift+S | 模块 | 依赖 | 注解

隐藏外部注释

默认情况下，外部注解会显示在编辑器中。您可以从代码中隐藏它们：

右键点击外部注释，并禁用显示外部注解选项。当内嵌提示被隐藏时，只有位于装订区域的图标标记它们在代码中的存在。

如果您想稍后启用 inlay hints，您可以在设置 Ctrl+Alt+S | 编辑器 | 内嵌提示 | Java 进行操作

为语言注入添加注解

您可以使用来自 JetBrains Annotations 库的 @Language 注解，将代码元素（如成员和参数）标记为语言注入。这将为您在 IDE 中提供正确的高亮、导航和搜索功能。

例如，您可以将一个注解参数标记为引用某个 Java 方法：

            import org.intellij.lang.annotations.Language;

            // you can use @Language as a meta-annotation
            @Language("jvm-method-name")
            @interface MethodName {}

            @interface ComponentProperties {
                @MethodName String waitForMethod() default "";
            }

            class MainComponent {
                @ComponentProperties(waitForMethod = "waitForExampleComponent")
                public ExampleComponent exampleComponent;

                private void waitForExampleComponent() { }
            }
        
  

IntelliJ IDEA 会将带注解的字符串识别为方法名，并允许您对该元素使用 Rename重构以及其他功能。

最后修改日期： 2025年 9月 22日