添加注解处理器

本页面详细介绍了如何将注解处理器添加为项目依赖项并进行配置。要了解有关注解处理器的更多信息，请参阅配置依赖项中的条目。

如果将注解处理器添加到编译类路径，您会看到类似以下内容的错误消息：

Error: Annotation processors must be explicitly declared now.

要解决此错误，请使用 annotationProcessor 配置您的依赖项，如以下示例所示，将注解处理器添加到您的项目中：

Kotlin

dependencies {
    // Adds libraries defining annotations to only the compile classpath.
    compileOnly("com.google.dagger:dagger:version-number")
    // Adds the annotation processor dependency to the annotation processor classpath.
    annotationProcessor("com.google.dagger:dagger-compiler:version-number")
}

Groovy

dependencies {
    // Adds libraries defining annotations to only the compile classpath.
    compileOnly 'com.google.dagger:dagger:version-number'
    // Adds the annotation processor dependency to the annotation processor classpath.
    annotationProcessor 'com.google.dagger:dagger-compiler:version-number'
}

注意：Android Gradle 插件 3.0.0+ 不再支持 android-apt 插件。

向注解处理器传递参数

如果需要向注解处理器传递参数，可以使用模块构建配置中的 AnnotationProcessorOptions 块进行操作。例如，如果要将基本数据类型作为键值对传递，可以使用 argument 属性，如以下示例所示：

Kotlin

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                arguments += mapOf("key1" to "value1",
                                   "key2" to "value2")
            }
        }
    }
}

Groovy

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                argument 'key1', 'value1'
                argument 'key2', 'value2'
            }
        }
    }
}

但是，在使用 Android Gradle 插件 3.2.0 及更高版本时，需要使用 Gradle 的 CommandLineArgumentProvider 接口传递表示文件或目录的处理器参数。

使用 CommandLineArgumentProvider 可以让您或注解处理器作者通过对每个参数应用增量构建属性类型注解来提高增量构建和缓存清理构建的正确性和性能。

例如，以下类实现了 CommandLineArgumentProvider 并为处理器注解了每个参数。

Kotlin

class MyArgsProvider(
    // Annotates each directory as either an input or output for the
    // annotation processor.
    @get:InputFiles
    // Using this annotation helps Gradle determine which part of the file path
    // should be considered during up-to-date checks.
    @get:PathSensitive(PathSensitivity.RELATIVE)
    val inputDir: FileCollection,

    @get:OutputDirectory
    val outputDir: File
) : CommandLineArgumentProvider {
    // Specifies each directory as a command line argument for the processor.
    // The Android plugin uses this method to pass the arguments to the
    // annotation processor.

    override fun asArguments(): Iterable<String> {
        // Use the form '-Akey[=value]' to pass your options to the Java compiler.
        return listOf("-AinputDir=${inputDir.singleFile.absolutePath}",
                      "-AoutputDir=${outputDir.absolutePath}")
    }
}

android {...}

Groovy

class MyArgsProvider implements CommandLineArgumentProvider {

    // Annotates each directory as either an input or output for the
    // annotation processor.
    @InputFiles
    // Using this annotation helps Gradle determine which part of the file path
    // should be considered during up-to-date checks.
    @PathSensitive(PathSensitivity.RELATIVE)
    FileCollection inputDir

    @OutputDirectory
    File outputDir

    // The class constructor sets the paths for the input and output directories.
    MyArgsProvider(FileCollection input, File output) {
        inputDir = input
        outputDir = output
    }

    // Specifies each directory as a command line argument for the processor.
    // The Android plugin uses this method to pass the arguments to the
    // annotation processor.
    @Override
    Iterable<String> asArguments() {
        // Use the form '-Akey[=value]' to pass your options to the Java compiler.
        ["-AinputDir=${inputDir.singleFile.absolutePath}",
         "-AoutputDir=${outputDir.absolutePath}"]
    }
}

android {...}

定义实现 CommandLineArgumentProvider 的类后，您需要创建一个实例并使用 annotationProcessorOptions.compilerArgumentProvider 方法将其传递给 Android 插件，如以下示例所示。

Kotlin

// This is in your module's build.gradle file.
android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                // Creates a new MyArgsProvider object, specifies the input and
                // output paths for the constructor, and passes the object
                // to the Android plugin.
                compilerArgumentProvider(MyArgsProvider(files("input/path"),
                                                          file("output/path")))
            }
        }
    }
}

Groovy

// This is in your module's build.gradle file.
android {
    defaultConfig {
        javaCompileOptions {
            annotationProcessorOptions {
                // Creates a new MyArgsProvider object, specifies the input and
                // output paths for the constructor, and passes the object
                // to the Android plugin.
                compilerArgumentProvider new MyArgsProvider(files("input/path"),
                                         new File("output/path"))
            }
        }
    }
}

要详细了解实现 CommandLineArgumentProvider 如何帮助提高构建性能，请阅读缓存 Java 项目。

停用注解处理器错误检查

如果编译类路径中包含您不需要的注解处理器依赖项，可以通过将以下内容添加到 build.gradle.kts 文件中来停用错误检查。请记住，您添加到编译类路径的注解处理器仍然不会添加到处理器类路径中。

Kotlin

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                argument("includeCompileClasspath", "false")
            }
        }
    }
}

Groovy

android {
    ...
    defaultConfig {
        ...
        javaCompileOptions {
            annotationProcessorOptions {
                includeCompileClasspath false
            }
        }
    }
}

如果您使用 Kotlin 和 kapt

Kotlin

android {
    ...
    defaultConfig {
        ...
        kapt {
            includeCompileClasspath = false
        }
    }
}

Groovy

android {
    ...
    defaultConfig {
        ...
        kapt {
            includeCompileClasspath false
        }
    }
}

如果您在将项目的注解处理器迁移到处理器类路径后遇到问题，可以通过将 includeCompileClasspath 设置为 true 来允许编译类路径上的注解处理器。但是，不建议将此属性设置为 true，并且在未来的 Android 插件更新中将移除此选项。