# Java 注解 > For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/idea/llms.txt). 注解是关于代码元素（如类、方法或参数）的元数据。 ```JAVA @Override public String toString() { return String.valueOf(id); } ``` 在 Java 中，有一组内置注解。 此外，许多库和框架，如 Spring 和 Lombok，定义了它们自己的注解。 这些注解提供的元数据可用于编译时和运行时，例如生成样板代码或通过反射与用户类进行交互。 ## 代码合同注解 还有一类注解描述代码语义和契约。 开发者可以使用它们更好地了解使用特定 API 的影响，并帮助 static 分析器识别问题区域。 ```JAVA public @Nullable List getDiscounts() { return discounts; } ``` IntelliJ IDEA 能识别最受欢迎的的 Java 注释，并在分析代码时将其考虑在内。 此类注解框架的示例有 [Checker Framework](https://checkerframework.org) 和 [ErrorProne](https://errorprone.info) 有关 JetBrains 的 `@Contract` 注释信息，请参阅 [官方存储库](https://github.com/JetBrains/java-annotations/blob/master/src/jvmMain/java/org/jetbrains/annotations/Contract.java)。 ### 空指针注解 空值注解是代码契约注解的一个子集。 通过显式声明元素的可空性，代码将更易于维护且不易发生与可空性相关的错误。 另一方面，IntelliJ IDEA 的静态分析将使用这些注释在设计时捕捉潜在错误。 例如，IntelliJ IDEA 会分析项目中的数据流并报告潜在可能为 `null` 的变量的解引用尝试，或者反之，建议在安全的情况下删除多余的保护条件。 Procedure: 配置空值注解 虽然 IntelliJ IDEA 识别最受欢迎的的空值注解，但您可能仍然希望将自定义注解添加到列表中。 IntelliJ IDEA 会然后使用它们来确定符号的空值性。 1. 前往 `设置 | 编辑器 | 检查 | 可能的错误 | 可空性和数据流问题` 。 2. 在 选项 下，选择 配置注释 。 #### 默认的可空性注解 默认情况下，以下注解会被 IntelliJ IDEA 识别： 可为 null: * 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 Procedure: 禁用空值检查 使用 IntelliJ IDEA 构建工具编译项目时，IDE 会向所有使用 `@NotNull` 注解的代码元素添加断言。 如果这些元素在运行时 `null` ，这些断言将引发错误。 这种快速失败行为可能有助于您在早期阶段诊断问题。 如果这不是您想要的效果，您可以禁用这些断言。 * 前往 `设置 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) | 构建、执行、部署 | 编译器` 并取消选中 为 notnull 注解的方法和参数添加运行时断言 选项。 Procedure: 推断可空性 如果您的项目缺少空值注解，完全或部分缺少，您可以让 IntelliJ IDEA 推导并插入空值注解。 1. 确保已为您的项目配置包含注解的库。 IntelliJ IDEA 使用在 用于代码生成的注解 中指定的注解在 `设置 | 编辑器 | 检查 | 可能的错误 | 空值性和数据流问题 | 配置注解` 中。 > **Tip:** > 如果要使用 [JetBrains 注解](#jetbrains-annotations)，并且正在使用 IntelliJ IDEA 构建工具，IDE 将检测到缺少的依赖项，并建议自动添加它 2. 在主菜单中，前往 `编码 | 分析代码 | 推断空值` 。 3. 在 指定推断空值范围 对话框中，请选择分析范围。 如果您想包括测试 sources 或注释局部变量，请选择相应的复选框。 ### JetBrains 注解依赖 IntelliJ IDEA 有自己的注解集，可作为单独的依赖项。 其包含用于表示空值性、范围、约定、可变性、纯度等的注释。 该包包含数十个注解。 一些最常见的是： * `@Nullable` 和 `@NotNull` —— 指示一个变量、参数或返回值可以或不可以为 null。 * `@Nls` – 表示带注释的代码元素是需要本地化的字符串。 * `@NonNls` – 表示注释的代码元素是用户不可见的字符串，不需要本地化，且不包含需要本地化的字符串。 当您使用 `@NonNls` 标注一个元素时，本地化工具会跳过该元素及其中的字符串。 * `@PropertyKey` 表示方法参数接受的参数必须是特定资源包中的有效属性键。 当一个不是捆绑包中属性键的字符串文本作为参数传递时，IntelliJ IDEA 将其高亮显示为错误。 该注解还用于在作为参数传递的字符串文本中提供补全。 * `@TestOnly` —— 表示方法或构造函数必须仅从测试代码中调用。 * `@Contract` ——使您可以指定方法必须遵循的一组规则（契约）。 如果违反合同，IntelliJ IDEA 会报告问题。 * `@Language` – 在 Java 字符串中注入用另一种语言编写的代码。 > **Note:** > 要查看完整注释说明，请使用快速文档 `Ctrl+Q` (Windows), `F1` (macOS), `⌃ J` (IntelliJ IDEA Classic (macOS)), `⌘ I` (macOS System Shortcuts), `Ctrl+Q` (XWin), `Ctrl+Q` (GNOME), `Ctrl+Q` (KDE), `Ctrl+Q` (Emacs), `Ctrl+Q` (Sublime Text), `Ctrl+Q` (Sublime Text (macOS)), `Ctrl+K, I` (Visual Studio), `⌘ K, I` (Visual Studio (macOS)), `Ctrl+Q` (NetBeans), `Alt+Middle-Click` (Eclipse), `⌥ Middle-Click` (Eclipse (macOS))或参考 [package repository](https://github.com/JetBrains/java-annotations)。 Procedure: 将 JetBrains Annotations 依赖项添加到项目中 * 当您在代码中使用 JetBrains 注解时， 将"annotations"添加到 classpath 意图操作将帮助您快速添加所需的依赖项。 ![向项目添加 JetBrains 注解依赖项](https://resources.jetbrains.com/help/img/idea/2026.3/annotations-quick-fix.png) * 否则，您可以使用以下工件坐标手动添加它： [https://central.sonatype.com/artifact/org.jetbrains/annotations/24.0.1](https://central.sonatype.com/artifact/org.jetbrains/annotations/24.0.1) Maven: ```XML org.jetbrains annotations 26.0.2 provided ``` Gradle Groovy: ```GROOVY dependencies { compileOnly 'org.jetbrains:annotations:26.0.2' } ``` Gradle Kotlin: ```KOTLIN dependencies { compileOnly("org.jetbrains:annotations:26.0.2") } ``` IntelliJ IDEA 构建工具: 前往 `项目结构 `Ctrl+Alt+Shift+S` (Windows), `⌘ ;` (macOS), `⌘ ;` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ Comma` (macOS System Shortcuts), `Ctrl+Alt+Shift+S` (XWin), `Ctrl+Alt+Shift+S` (GNOME), `Ctrl+Alt+Shift+S` (KDE), `Ctrl+Alt+Shift+S` (Emacs), `Ctrl+Alt+Shift+S` (Sublime Text), `⌘ ;` (Sublime Text (macOS)), `Ctrl+Alt+Shift+S` (Visual Studio), `⌘ ;` (Visual Studio (macOS)), `Ctrl+Alt+Shift+S` (NetBeans), `Ctrl+Alt+Shift+S` (Eclipse), `⌘ ;` (Eclipse (macOS)) | 库` 。 点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)，然后选择 从 Maven 。 在搜索字段中，输入 `org.jetbrains:annotations:26.0.2` 。 点击 OK 。 > **Warning:** > 对于 JDK 1.5 到 1.7，请使用 [annotations-java5](https://mvnrepository.com/artifact/org.jetbrains/annotations-java5) 工件。 ## 推断注解 如果代码完全没有注释，IntelliJ IDEA 仍然可以从字节码和源代码推断出许多注释。 这些注解并不会实际插入代码中，但 IDE 显示它们，好像它们就在那儿，以帮助您更好地理解代码上下文。 推断注解也与常规注解一样在代码分析中使用。 IntelliJ IDEA 可以推断以下 [JetBrains 注解](#jetbrains-annotations)： `@Nullable` 、 `@NotNull` 、 `@Contract` 、 `@Unmodifiable` 和 `@UnmodifiableView` 。 有关此注释风格的完整文档，请参阅 [package source code](https://github.com/JetBrains/java-annotations)。 > **Note:** > 如果您 [为代码生成指定了自定义的空注解](#configure-nullability-annotations)，它们将被推断为代替 JetBrains 的注解。 在编辑器中，推断注解会在边栏中以 ![推断注释图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.gutter.extAnnotation.svg) 图标标记。 ![编辑器中的推断注释](https://resources.jetbrains.com/help/img/idea/2026.3/inferred-annotations-icon.png) Procedure: 向代码添加推断注解 * 如果您想在代码中实际插入推断的注解，请点击 ![推断注释图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.gutter.extAnnotation.svg)附近的所需注解，然后选择 插入 。 ![向代码添加推断注解](https://resources.jetbrains.com/help/img/idea/2026.3/add-inferred-annotation.png) Procedure: 内联显示推断注释 您可以配置 IDE 以在代码中直接显示推断的注释。 ![推断注解的内嵌提示](https://resources.jetbrains.com/help/img/idea/2026.3/inferred-annotation-icon-hint.png) 1. 按 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 打开设置，然后选择 `编辑器｜内嵌提示｜注解｜Java` 。 2. 请选择 推断注解 复选框。 > **Tip:** > 如果您以后需要隐藏注释，可以使用相同的设置或只需右键点击注释提示并选择 关闭推断注解 。 ## 外部注解 如果您希望显式地使用注解，但又不希望它们杂乱地充斥您的代码库，也可以将它们存储在外部。 您可以选择将带有注释的文件提交到公共仓库中，也可以将它们仅保留在本地环境中。 外部注解是存储在名为 `annotations.xml` 的 XML 文件中的常规注解。 通常情况下，您可能希望使用它们： * 团队成员使用不同的 IDE 和静态分析工具 * 标注您无法更改其来源的代码，例如，库类 * 保持代码没有那些特定用途的注解（例如， [@Async.Schedule/Execute](debug-asynchronous-code.html#async-annotation) 或 [@DebugRenderer](customizing-views.html#renderer-annotation)）。 在代码中，外部注释用 ![外部注释图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.gutter.extAnnotation.svg) 栏边图标标记，并用灰色高亮显示。 默认情况下，IntelliJ IDEA 会在编辑器中显示外部注释。 ![装订区域中的外部注解图标](https://resources.jetbrains.com/help/img/idea/2026.3/external-annotation-gutter-and-hint.png) Procedure: 启用外部注释 要使用外部注解，您需要在设置中启用它们。 如果您跳过此步骤，您将能够在外部注释库代码，但无法在源代码中使用外部注释。 1. 按 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 打开设置，然后选择 `编辑器 | 代码样式 | Java | 代码生成` 。 2. 请选择 使用外部注解 复选框。 Procedure: 添加外部注释 1. 请通过以下一种方式指定外部注解： * 在处理项目代码时，您可以输入注释，然后使用 外部注释 意图操作。 要访问意图操作菜单，请将文本光标放在注解处并按 `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Alt+Enter` (NetBeans), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS))（或点击意图操作 ![意图操作图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.codeInsight.intentionBulb.png)图标）。 ![将常规注解转换为外部注解](https://resources.jetbrains.com/help/img/idea/2026.3/annotate-externally-fix.png) * 另一种方法，您可以对项目代码和库同时使用，就是对元素本身使用 注解 意图操作。 ![添加新的外部注释](https://resources.jetbrains.com/help/img/idea/2026.3/annotate-element-quick-fix.png) 根据当前上下文中的注释，IntelliJ IDEA 将允许您从菜单中选择所需的注释，或者如果只有一个注释可用，则会立即建议插入该注释。 2. 如果您的项目或模块尚未配置annotations目录，IntelliJ IDEA将提示您进行设置。 此模块中添加的每个外部注解都将存储在该文件夹中。 如果您有多个注解根，IntelliJ IDEA 将询问您使用哪一个。 您可以稍后 [更改此位置](#configure-annotations-root)。 Procedure: 移除外部注解 * 点击注释元素附近的边距图标，然后选择 取消标注 。 ![删除外部注释](https://resources.jetbrains.com/help/img/idea/2026.3/external-deannotate.png) Procedure: 配置注释根目录 注解根目录是存储外部注解的文件夹。 它们根据适用的项目部分配置在不同的位置。 * 整个项目： `项目结构 `Ctrl+Alt+Shift+S` (Windows), `⌘ ;` (macOS), `⌘ ;` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ Comma` (macOS System Shortcuts), `Ctrl+Alt+Shift+S` (XWin), `Ctrl+Alt+Shift+S` (GNOME), `Ctrl+Alt+Shift+S` (KDE), `Ctrl+Alt+Shift+S` (Emacs), `Ctrl+Alt+Shift+S` (Sublime Text), `⌘ ;` (Sublime Text (macOS)), `Ctrl+Alt+Shift+S` (Visual Studio), `⌘ ;` (Visual Studio (macOS)), `Ctrl+Alt+Shift+S` (NetBeans), `Ctrl+Alt+Shift+S` (Eclipse), `⌘ ;` (Eclipse (macOS))| SDKs | 注解` * 对于单个模块： `项目结构 `Ctrl+Alt+Shift+S` (Windows), `⌘ ;` (macOS), `⌘ ;` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ Comma` (macOS System Shortcuts), `Ctrl+Alt+Shift+S` (XWin), `Ctrl+Alt+Shift+S` (GNOME), `Ctrl+Alt+Shift+S` (KDE), `Ctrl+Alt+Shift+S` (Emacs), `Ctrl+Alt+Shift+S` (Sublime Text), `⌘ ;` (Sublime Text (macOS)), `Ctrl+Alt+Shift+S` (Visual Studio), `⌘ ;` (Visual Studio (macOS)), `Ctrl+Alt+Shift+S` (NetBeans), `Ctrl+Alt+Shift+S` (Eclipse), `⌘ ;` (Eclipse (macOS))｜模块｜路径｜外部注解` * 对于外部 Maven/Gradle 依赖： `项目结构 `Ctrl+Alt+Shift+S` (Windows), `⌘ ;` (macOS), `⌘ ;` (IntelliJ IDEA Classic (macOS)), `⌘ ⇧ Comma` (macOS System Shortcuts), `Ctrl+Alt+Shift+S` (XWin), `Ctrl+Alt+Shift+S` (GNOME), `Ctrl+Alt+Shift+S` (KDE), `Ctrl+Alt+Shift+S` (Emacs), `Ctrl+Alt+Shift+S` (Sublime Text), `⌘ ;` (Sublime Text (macOS)), `Ctrl+Alt+Shift+S` (Visual Studio), `⌘ ;` (Visual Studio (macOS)), `Ctrl+Alt+Shift+S` (NetBeans), `Ctrl+Alt+Shift+S` (Eclipse), `⌘ ;` (Eclipse (macOS)) | 模块 | 依赖 | 注解` Procedure: 隐藏外部注释 默认情况下，外部注解会显示在编辑器中。 您可以从代码中隐藏它们： * 右键点击外部注释，并禁用 显示外部注解 选项。 当内嵌提示被隐藏时，只有位于装订区域的 ![外部注释图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.gutter.extAnnotation.svg) 图标标记它们在代码中的存在。 如果您想稍后启用 inlay hints，您可以在 `设置 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) | 编辑器 | 内嵌提示 | Java` 进行操作 ## 为语言注入添加注解 您可以使用来自 [JetBrains Annotations](#jetbrains-annotations) 库的 `@Language` 注解，将代码元素（如成员和参数）标记为语言注入。 这将为您在 IDE 中提供正确的高亮、导航和搜索功能。 例如，您可以将一个注解参数标记为引用某个 Java 方法： ```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() { } } ``` > **Note:** > 有关 `@Language` 和其他 JetBrains 注解的完整文档，请参阅 [JetBrains 注解仓库](https://github.com/JetBrains/java-annotations/blob/master/src/jvmMain/java/org/intellij/lang/annotations/Language.java)。 IntelliJ IDEA 会将带注解的字符串识别为方法名，并允许您对该元素使用 [Rename](rename-refactorings.html)重构以及其他功能。 ![“重命名”弹出窗口会同时重命名目标方法和带注解的字符串](https://resources.jetbrains.com/help/img/idea/2026.3/annotate-as-method-name.png) ## See also ### 概念 [代码检查](code-inspection.html)