Kotlin-講解 實驗性API

前言

在編碼過程中，編輯未開發完成的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'