Создание и публикация многоплатформенной библиотеки — учебник

JVM

1. В директории jvmMain/kotlin создайте пакет org.jetbrains.base64.

2. Создайте файл Base64.kt в новом пакете.

3. Предоставьте простую реализацию объекта Base64Factory, которая делегирует классу java.util.Base64:

   package org.jetbrains.base64
   import java.util.*
   
   actual object Base64Factory {
       actual fun createEncoder(): Base64Encoder = JvmBase64Encoder
   }
   
   object JvmBase64Encoder : Base64Encoder {
       override fun encode(src: ByteArray): ByteArray = Base64.getEncoder().encode(src)
   }
   

Достаточно просто, не так ли? Вы предоставили платформоспецифическую реализацию, используя прямое делегирование сторонней реализации.

JS

Реализация JS будет очень похожа на JVM.

1. В директории jsMain/kotlin создайте пакет org.jetbrains.base64.

2. Создайте файл Base64.kt в новом пакете.

3. Предоставьте простую реализацию объекта Base64Factory, которая делегирует функции btoa().

   package org.jetbrains.base64
   
   import kotlinx.browser.window
   
   actual object Base64Factory {
       actual fun createEncoder(): Base64Encoder = JsBase64Encoder
   }
   
   object JsBase64Encoder : Base64Encoder {
       override fun encode(src: ByteArray): ByteArray {
           val string = src.decodeToString()
           val encodedString = window.btoa(string)
           return encodedString.encodeToByteArray()
       }
   }
   

Native

К сожалению, для всех целей Kotlin/Native нет сторонней реализации, поэтому вам нужно написать её самостоятельно.

1. В директории nativeMain/kotlin создайте пакет org.jetbrains.base64.

2. Создайте файл Base64.kt в новом пакете.

3. Предоставьте свою собственную реализацию для объекта Base64Factory:

   package org.jetbrains.base64
   
   private val BASE64_ALPHABET: String = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
   private val BASE64_MASK: Byte = 0x3f
   private val BASE64_PAD: Char = '='
   private val BASE64_INVERSE_ALPHABET = IntArray(256) {
       BASE64_ALPHABET.indexOf(it.toChar())
   }
   
   private fun Int.toBase64(): Char = BASE64_ALPHABET[this]
   
   actual object Base64Factory {
       actual fun createEncoder(): Base64Encoder = NativeBase64Encoder
   }
   
   object NativeBase64Encoder : Base64Encoder {
       override fun encode(src: ByteArray): ByteArray {
           fun ByteArray.getOrZero(index: Int): Int = if (index >= size) 0 else get(index).toInt()
           // 4n / 3 is expected Base64 payload
           val result = ArrayList<Byte>(4 * src.size / 3)
           var index = 0
           while (index < src.size) {
               val symbolsLeft = src.size - index
               val padSize = if (symbolsLeft >= 3) 0 else (3 - symbolsLeft) * 8 / 6
               val chunk = (src.getOrZero(index) shl 16) or (src.getOrZero(index + 1) shl 8) or src.getOrZero(index + 2)
               index += 3
   
               for (i in 3 downTo padSize) {
                   val char = (chunk shr (6 * i)) and BASE64_MASK.toInt()
                   result.add(char.toBase64().code.toByte())
               }
               // Fill the pad with '='
               repeat(padSize) { result.add(BASE64_PAD.code.toByte()) }
           }
   
           return result.toByteArray()
       }
   }
   

Предварительные условия

Перед написанием тестов добавьте метод encodeToString с реализацией по умолчанию в интерфейс Base64Encoder, который определён в commonMain/kotlin/org/jetbrains/base64/Base64.kt. Эта реализация преобразует массивы байтов в строки, что гораздо проще тестировать.

interface Base64Encoder {
    fun encode(src: ByteArray): ByteArray

    fun encodeToString(src: ByteArray): String {
        val encoded = encode(src)
        return buildString(encoded.size) {
            encoded.forEach { append(it.toInt().toChar()) }
        }
    }
}

Вы также можете предоставить более эффективную реализацию этого метода для определённой платформы, например, для JVM в jvmMain/kotlin/org/jetbrains/base64/Base64.kt:

object JvmBase64Encoder : Base64Encoder {
    override fun encode(src: ByteArray): ByteArray = Base64.getEncoder().encode(src)
    override fun encodeToString(src: ByteArray): String = Base64.getEncoder().encodeToString(src)
}

Одним из преимуществ кроссплатформенной библиотеки является наличие реализации по умолчанию с опциональными платформенно-специфичными переопределениями.

Написание общих тестов

Теперь у вас есть API, основанный на строках, который можно покрыть базовыми тестами.

1. В каталоге commonTest/kotlin создайте пакет org.jetbrains.base64.

2. Создайте файл Base64Test.kt в новом пакете.

3. Добавьте тесты в этот файл:

   package org.jetbrains.base64
   
   import kotlin.test.Test
   import kotlin.test.assertEquals
   
   class Base64Test {
       @Test
       fun testEncodeToString() {
           checkEncodeToString("Kotlin is awesome", "S290bGluIGlzIGF3ZXNvbWU=")
       }
   
       @Test
       fun testPaddedStrings() {
           checkEncodeToString("", "")
           checkEncodeToString("1", "MQ==")
           checkEncodeToString("22", "MjI=")
           checkEncodeToString("333", "MzMz")
           checkEncodeToString("4444", "NDQ0NA==")
       }
   
       private fun checkEncodeToString(input: String, expectedOutput: String) {
           assertEquals(expectedOutput, Base64Factory.createEncoder().encodeToString(input.asciiToByteArray()))
       }
   
       private fun String.asciiToByteArray() = ByteArray(length) {
           get(it).code.toByte()
       }
   }
   

4. В терминале выполните задачу Gradle check:

   ./gradlew check 
   

Тесты будут выполняться на всех платформах (JVM, JS и Native).

Добавление платформенно-специфичных тестов

Вы также можете добавить тесты, которые будут выполняться только для определённой платформы. Например, вы можете добавить тесты UTF-16 на JVM:

1. В каталоге jvmTest/kotlin создайте пакет org.jetbrains.base64.

2. Создайте файл Base64Test.kt в новом пакете.

3. Добавьте тесты в этот файл:

   package org.jetbrains.base64
   
   import kotlin.test.Test
   import kotlin.test.assertEquals
   
   class Base64JvmTest {
       @Test
       fun testNonAsciiString() {
           val utf8String = "Gödel"
           val actual = Base64Factory.createEncoder().encodeToString(utf8String.toByteArray())
           assertEquals("R8O2ZGVs", actual)
       }
   }
   

Этот тест будет автоматически выполняться на платформе JVM помимо общих тестов.