Kotlin-讲解 实验性API

版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

本文链接： https://blog.csdn.net/wangxueming/article/details/102485015

前言

在编码过程中，编辑未开发完成的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'