版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。
前言
在编码过程中,编辑未开发完成的API,倘若需要使用它,Kotlin提供了实验性API进行提示,在使用后,会提示warnings或编译报错。
声明自定义的API
怎么进行定义声明呢?
看个范例
// library code
@Experimental
@Retention(AnnotationRetention.BINARY)
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
annotation class ExperimentalDateTime // Experimental API marker
@ExperimentalDateTime
class DateProvider // Experimental class
Experimental级别有两个
@Experimental(level = Experimental.Level.ERROR)
@Experimental(level = Experimental.Level.WARNING)
使用
使用了实验性API后,必须加注解,否则会报错
类级标注了Experimental
// client code
fun getYear(): Int {
val dateProvider: DateProvider // error: DateProvider is experimental
// ...
}
上面的例子会提示DataProvider is experimental
@ExperimentalDateTime
fun getDate(): Date {
val dateProvider: DateProvider // OK: the function is marked as experimental
// ...
}
需要如此添加注解,才不会编译出错
函数级标注了Experimental
fun displayDate() {
println(getDate()) // error: getDate() is experimental, acceptance is required
}
因为getDate()标注了Experimental,
所以,调用处也需要标注Experimental
@ExperimentalDateTime
fun displayDate() {
println(getDate()) // error: getDate() is experimental, acceptance is required
}
非传播使用
若希望使用Experimental的函数,可将getDate()的标记改成@UseExperimental(ExperimentalDateTime::class)
//client code
@UseExperimental(ExperimentalDateTime::class)
fun getDate(): Date { // uses DateProvider; doesn't expose the experimental status
val dateProvider: DateProvider
// ...
}
如果希望在整个文件中使用,而不需要每一处引用
可在文件顶部,在package之上,使用注解
@file:UseExperimental(ExperimentalDateTime::class)
若不想一个个文件引用,可以弄成模块级的
可以在gradle中进行配置
有几种方式可供参考。
- 单平台模块
tasks.withType<KotlinCompile>().all { kotlinOptions.freeCompilerArgs += "-Xuse- experimental=org.mylibrary.ExperimentalMarker" }
- 多平台模块
sourceSets { all { languageSettings.useExperimentalAnnotation("kotlin.Experimental") } }
- maven的方式
<build> <plugins> <plugin> <groupId>org.jetbrains.kotlin</groupId> <artifactId>kotlin-maven-plugin</artifactId> <version>${kotlin.version}</version> <executions>...</executions> <configuration> <args> <arg>-Xuse-experimental=org.mylibrary.ExperimentalMarker</arg> </args> </configuration> </plugin> </plugins> </build>
实验性API转正
API开发完成后,废弃这个注解
@Deprecated("This experimental API marker is not used anymore. Remove its usages from your code.")
@Experimental
annotation class ExperimentalDateTime
实验性 API 标记的实验性状态
实验性API本身以后也是可能变的,用户需要知道project中的实验性API情况
可以通过添加编译参数来提示
'-Xuse-experimental=kotlin.Experimental'