基于 Kotlin KMP 实现 HarmonyOS 与 Android 双平台 SDK 开发实践 ...

背景

随着鸿蒙平台的进一步发展，大家的态度也渐渐从观望转向现实投入，越来越多的公司开始思量将自家应用迁移到鸿蒙平台。但是这一过程并非想象中的那么简单，尤其对于已经存在许多年的大型项目来说，直接投入大量人力物力重新开发一个鸿蒙版本的应用资本过高，短时间内难以实现。对于小公司而言，这种资本压力更是难以承受。
因此，许多公司倾向于使用跨平台技术，比方 React Native（RN）和 Flutter。但抛开性能这些先不说，使用这两种技术将 App 迁移到鸿蒙平台存在两个严重问题：

• 兼容性问题：鸿蒙 OS 的底层架构与 Android 存在肯定差别，RN 和 Flutter 在鸿蒙上的生态尚未成熟，遇到 API 兼容性问题，非常影相应用的稳固性。
  
• 技术栈转换资本：如果现有业务已经使用 RN 或 Flutter，迁移到鸿蒙仍然需要大量适配工作。如果未使用这些技术，直接将整个项目改造成 RN 或 Flutter 的技术栈再举行迁移，资本更是难以接受。
  

面对这样的情况，Kotlin 的 Kotlin Multiplatform（KMP）技术进入了大家的视野。1）Kotlin 本身就是 Android 端的 native 语言，可以将 Android 端的代码以较低的资本改造为 KMP 跨平台项目。2）Android 平台和鸿蒙平台相似度也较高，适配时会相对容易不少。比方两个平台的 webview 容器接口、对外的 callback 接口，险些可以视为一模一样只是名字不同。3）使用 KMP 的构建产物是各个平台的 native 代码，接入时各个端只是接入一个各自平台的 library，不需要接入额外的库。接入资本也低。
因此，使用 KMP 技术来迁移 Android 端至鸿蒙平台成为了一种极具吸引力的方案。

在跨平台开发中，尤其是针对 Android 和 HarmonyOS 双端 SDK 的开发，我们需要解决一些关键问题，以确保逻辑的统一性宁静台兼容性。以下是在开发过程中应重点思量的几个问题：
问题

• 两端的 context 怎样抹平？ Android 和 HarmonyOS 的 Context 机制存在差别，怎样在 KMP 项目中抹平这种差别，使得上层逻辑无需关心平台的具体实现？
  
• 在这种跨端项目中怎样实现异步操纵？两端的异步操纵怎样平衡？ 异步操纵是 SDK 开发中的常见需求，但 Android 和 HarmonyOS 的异步机制（如 Android 的 Coroutine 和 HarmonyOS 的 TaskDispatcher）不同，怎样在 KMP 中实现统一的异步调用？
  
• KMP 项目怎样调用底层的，特殊是体系的 API？ KMP 的 common 模块无法直接调用平台特定的 API，怎样通过 expect 和 actual 机制实现对体系 API 的调用？
  
• 如那边理平台特定的功能实现？ 比方，计算文件的 MD5 值，Android 和 HarmonyOS 的实现方式不同。在这种情况下，怎样在各自平台实现特定逻辑，并通过 KMP 项目标 commonMain 部分统一调用？
  

编写示例 Demo

为了更好地说明上述问题的解决方案，这里计划了一个简单的示例 Demo。 Demo 实现了一个名为 FileManager 的 SDK（它不包含 UI），仅提供纯逻辑功能。FileManager 的主要功能包罗：

• 判定文件是否存在：根据传入的文件路径，判定文件是否存在。
  
• 写入内容：向指定文件写入内容。
  
• 文件压缩：对指定文件举行压缩。
  
• 文件解压缩：对指定压缩文件举行解压。
  

尝试通过这个 Demo讲清楚在具体的项目实验中解决以上几个问题。接下来，渐渐实现这个 Demo，并详细说明每个步骤的关键点。
准备工作

创建KMP 项目

这个项目包罗的是 Android 端的 demo 工程和 Kotlin Multiplatform 的核心代码。使用 Android Studio 来创建
起首检查插件，如果没有安装。Android studio 先安装插件 Kotlin Multiplatform。
接着 File->New->New Project 创建 KMP 项目工程。此时新创建的项目缺失了鸿蒙（即jsMain）部分。1）模拟 androidMain 、iosMain 部分的结构创建 jsMain target 部分目次和初始platform 文件。如下图所示：

2）在 shared 的 build.gradle.kts文件中增加 js 对应的设置：

1. js(IR) {
2.        moduleName = "kmp-core-kit"
3.        compilations.all {
4.            compileTaskProvider.configure {
5.                compilerOptions.freeCompilerArgs.add("-Xerror-tolerance-policy=SYNTAX")
6.            }
7.            if(this.compilationName == "main") {
8.                packageJson {
9.                    name = "kmp-core-kit"
10.                    version = "0.0.1"
11.                }
12.            }
13.        }
14. ​
15.        generateTypeScriptDefinitions()
16.        useEsModules()
17.        nodejs()
18.        binaries.executable()
19.    }

复制代码

创建鸿蒙Demo工程

这里的工程包罗鸿蒙的 demo 工程，还有从 KMP 项目中将 kotlin 编译成的 js 代码。为了使用方便这一部分代码会作为主工程的 library 接入。
DevEco-Studio New 出工程，命名为 HarmonyExample。接着 New Project Module，类型选择 Shared Library。子模块名称随意，本次直接接纳默认名称 library。
然后在 entry 的 oh-package.json5 文件中设置 dependencies 节点，内容如下图所示。

创建karakum工程

该工程用于在编码过程中将鸿蒙的*.d.ts 文件转换为 kt 文件，在 KMP 工程中使用。Github 地点：GitHub - karakum-team/karakum: Converter of TypeScript declaration files to Kotlin declarations
本地演示接纳下令行模式来使用该工具。创建一个目次，然后执行指令

1. npm install karakum typescript -D

复制代码

接着创建 input、output 目次。创建一个名为karakum.config.json 的文件，内容设置为：

1. {
2.    "input": "input/*", //输入目录放置*.d.ts 文件
3.    "output": "output", //输出目录，用于存放转换生成的*.kt 文件
4.    "libraryName": "ohos" //生成的kt文件的包名
5. }

复制代码

设置完成后，工程结构如下图所示：

使用时只需要将需要转换的.d.ts 文件放置在 input 目次下，执行 如下下令即可。

1. npx karakum --config karakum.config.json

复制代码

开始编码

整个项目比较简单，模拟 app 下载 zip 到本地后，解压缩、校验解压缩后文件的 md5 值，这个场景。只是文件不是从远端下载而是本地生成一个 zip 文件供模拟使用。

• 文件根路径的处置惩罚，大概说平台 context 如那边理？
  对于 Android 平台获取一个文件操纵路径可以这样操纵：
  
  1. val rootPath = applicationContext.getExternalFilesDir("kmp_core")?.absolutePath ?: ""

  复制代码
  鸿蒙平台也有类似的写法：
  
  1. const rootDir = getContext(this).filesDir +"/kmp-core"

  复制代码
  问题在于两个平台的 context 不同，想抹平差别还是有点困难。针对这种场景我们想了两个方案，1）如果 context 是在步伐中持续要使用的，那么就编写一个 set 方法将各自平台的 context 注入到对应的 target。比方 Android 平台的就注入到 androidMain，鸿蒙的就注入到 jsMain；2）规避 context 的注入。比方我们现在Demo 的场景，我们只是需要一个文件根路径，那么完全可以在函数中增到场参，将 root 路径以一个 String 的形式注入到 commonMain 部分。
  因此我们在 commonMain target 部分，创建一个类 FileManager。计划一个函数 prepare，入参为 string 类型。
  
  1. class FileManager {
  2.    fun prepare(path: String) {
  3.    }

  复制代码
  那么在 Android 端的业务部分调用 FileManager 的时间就可以写为：
  
  1. val rootPath = applicationContext.getExternalFilesDir("kmp_core")?.absolutePath ?: ""
  2. val fileManager = FileManager()
  3. fileManager.prepare(rootPath)

  复制代码
  鸿蒙平台调用时代码写为：
  
  1. const rootDir = getContext(this).filesDir +"/kmp-core"
  2. const fileManager = new FileManager()
  3. fileManager.prepare(rootDir)

  复制代码
• 怎样调用体系本事，体系 API
  许多时间我们都需要调用体系本事，在这个 demo 里用一个日志打印功能来举例。
  起首在 commonMain 里定义：
  
  1. expect fun platformLog(tag: String, message: String)

  复制代码
  为了方便使用接着可以封装一个 log 模块：
  
  1. object ELog {
  3.     fun v(message: String) {
  4.         v("KMPCore", message)
  5.     }
  7.     fun v(tag: String, message: String) {
  8.         platformLog(tag, message)
  9.     }
  10. }

  复制代码
  第二步就是怎样调用底层体系的 API 来实现各个端上的真实的打印日志本事。
  Android 端非常容易，在 androidMain 的 Platform.android.kt 文件中，按照 KMP 的 expect/actual 协议来实现 platformLog 函数,而且在函数内直接调用android.util.Log 体系 API 即可。代码如下：
  
  1. actual fun platformLog(tag: String, message: String) {
  2.     Log.v(tag, message)
  3. }

  复制代码
  鸿蒙端就稍微有点复杂。同样按照 expect/actual 协议来操纵，在 jsMain target 部分的 Platform.js.kt 文件中我们可以做如下实现：
  
  1. actual fun platformLog(tag: String, message: String) {
  2.    
  3. }

  复制代码
  此时有个问题就是我们没有鸿蒙端对应的 kt 文件，无法实现这里的逻辑。我们借助于karakum 工具来实现鸿蒙平台调用底层日志打印的 kt 文件。
  
  
  
  • 鸿蒙平台打印日志的模块为 @ohos.hilog. 在HarmonyExample 工程中随便找个*.ets 文件顶部写import hilog from '@ohos.hilog'; 点进去就能找到@ohos.hilog.d.ts 文件。
    
  • 将@ohos.hilog.d.ts 文件 拷贝到karakum工程的 input 目次下。执行下令：npx karakum --config karakum.config.json。 在karakum工程的 output 目次下就会生成我们需要的@ohos.hilog.kt 文件
    
  • 接着将@ohos.hilog.kt 文件拷贝到 KMP 工程的 jsMain target。（为了方便管理，特意在karakum 的工程设置中增加了包路径ohos，以是这里拷贝来的文件需要放置在 ohos 目次下）
    
    
    
    
    
  • 这时的 kt文件还需要做进一步的修改：1）注释调顶部的@file:JsModule("ohos/@ohos.hilog") 2）增加JsModule 设置。
    
    1. @JsModule("@ohos.hilog")
    2. @JsNonModule
    3. external object hilog {

    复制代码
  • 最终回到 Platform.js.kt 文件，就可以调用 hilog来实现 KMP 调用鸿蒙平台的日志打印 API 功能
    
    1. import ohos.hilog
    2. actual fun platformLog(tag: String, message: String) {
    3.     hilog.debug(0.0, tag, message)
    4. }

    复制代码
  
  
• 怎样将基于体系 API 封装的功能模块，提供给 KMP 的 commonMain 调用
  在现实的开发过程中，调用各个端的本事不可能像 log 打印一样简单。各个端的差别比较大，还是很难抹平的。比方给文件计算 md5 值，每个端的实现差别还是比较大的。
  面对这种情况，我们接纳各个端来实现具体的逻辑，common 中只是一个空函数。
  在 commonMain target 的 Platform.kt 文件中定义：
  
  1. expect fun platformGetFileMd5(filePath: String): String

  复制代码
  在 androidMain target 的 Platform.android.kt 文件中实现 android 端的逻辑
  
  1. actual fun platformGetFileMd5(filePath: String): String {
  2.     val digest = MessageDigest.getInstance("MD5")
  3.     val file = File(filePath)
  4.     val inputStream = FileInputStream(file)
  5.     val buffer = ByteArray(8192)
  6.     var bytesRead: Int
  7.     while (inputStream.read(buffer).also { bytesRead = it } != -1) {
  8.         digest.update(buffer, 0, bytesRead)
  9.     }
  10.     inputStream.close()
  11.     val md5Bytes = digest.digest()
  12.     return md5Bytes.joinToString("") { "%02x".format(it) }
  13. }

  复制代码
  这种场景下鸿蒙端可以重复类似 log 模块的流程，将计算 md5 需要的各个kt 类都凑齐，然后在 jsMain target 的 Platform.js.kt 文件中实现和 Android 端同样的逻辑。只是这种比较贫苦，而且后期不容易调试。
  这里接纳另外一种方式。
  如图所示：
  
  
  
  
  
  
  
  • 起首我们在鸿蒙端FileUtil 类，对应两个文件，FileUtil.ts 和 FileUtil.d.ts
    
  • 在FileUtil.ts 中实现具体的鸿蒙端计算 md5 的内容逻辑：
    
    1. import fs from '@ohos.file.fs'
    2. import util from '@ohos.util'
    3. import zlib from '@ohos.zlib'
    4. import hilog from '@ohos.hilog';
    6. import { cryptoFramework } from '@kit.CryptoArchitectureKit'
    7. import { buffer } from '@kit.ArkTS'
    9. class FileUtil {
    10.   public static getFileMd5(filePath: string): string {
    11.       let md5 = cryptoFramework.createMd("MD5")
    12.     let file = fs.openSync(filePath, fs.OpenMode.READ_ONLY)
    13.     let arrayBuffer = new ArrayBuffer(2048)
    14.     let len : number = 0
    15.     let position: number = 0
    16.     do {
    17.       len = fs.readSync(file.fd, arrayBuffer, {offset: position})
    18.       if( len > 0) {
    19.         let uint8Array = new Uint8Array(arrayBuffer.slice(0, len))
    20.         md5.updateSync({data: uint8Array})
    21.         position += len
    22.       }
    23.     } while (len > 0)
    24.     let mdResult = md5.digestSync()
    26.     return Array.from(mdResult.data).map(byte => byte.toString(16).padStart(2, '0')).join('')
    27.   }
    28. }
    29. export default FileUtil;

    复制代码
    在 FiltUtil.d.ts 文件中做声明：
    
    1. declare class  FileUtil {
    2.   public static getFileMd5(filePath: string): string;
    3. }
    4. export default FileUtil;

    复制代码
  • 重复之前的步骤，将FiltUtil.d.ts 文件拷贝到karakum 生成对应的 kt 文件
    
  • 将 FiltUtil.kt 文件拷贝到 KMP 工程中，如图：
    
    
    
    
    再做修改：
    
    1. // Generated by Karakum - do not modify it manually!
    3. //@file:JsModule("ohos/FileUtil")
    4. @file:Suppress(
    5.     "NON_EXTERNAL_DECLARATION_IN_INAPPROPRIATE_FILE",
    6. )
    8. package ohos
    10. @JsModule("./ohos/FileUtil")
    11. @JsNonModule
    12. external class FileUtil {
    14. companion object {
    15. fun getFileMd5(filePath: String): String
    16. }
    17. }
    18. /* export default FileUtil; */

    复制代码
    （这里有个小发现，JsModule 部分如果写为：@JsModule("./ohos/FileUtil") 不直接用@JsModule("ohos/FileUtil"）。要不然构建导出的js 文件会报错，找不到我们在鸿蒙端定义的 FiltUtil类。加上./后，构建生成的 js 文件中就会长这样import FileUtil from './ohos/FileUtil';,免于后期修正)
    
  • FileUtil.kt 生成了剩下的就很简单，在 Platform.js.kt 中直接调用即可：
    
    1. import ohos.FileUtil
    2. actual fun platformGetFileMd5(filePath: String): String {
    3.     return FileUtil.getFileMd5(filePath)
    4. }

    复制代码
  
  
• 耗时操纵的异步
  
  
  
  • 在 commonMain 中异步，大概说开线程
    在项目开发中，耗时操纵异步处置惩罚险些是必不可少的。在 KMP 项目中相比于文章前面的几个模块功能，由于有官方封装的 kotlin 协程库异步反倒更简单一点。
    
    
    
    • 先引入协程库：
      
      1. commonMain.dependencies {
      2.    //put your multiplatform dependencies here
      3.    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")
      4. }

      复制代码
    • 然后使用即可：
      
      1. private val coroutineScope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
      3. fun prepare(path: String) {
      4.   coroutineScope.launch {
      5.           //todo
      6.   }
      7. }

      复制代码
    
    
  • 平台本身就要求异步调用，怎样抹平差别？
    各个平台的具体逻辑实现为同步式，在 commonMain 部分做异步操纵，是比较公道且通用的一种开发方式。比方在鸿蒙平台我们实现文件的 md5 计算，均调用fs.openSync这样的同步 API来实现。
    但凡事都怕例外，在开发过程中发现，一些操纵在体系层面就是个异步操纵还没有同步式的接口暴露。比方在鸿蒙平台做文件压缩操纵。
    
    1. function compressFile(inFile: string, outFile: string, options: Options): Promise<void>;

    复制代码
    开始面对这种情况感觉有点棘手。习惯性的接纳 Callback 回调方式来处置惩罚，Android 和鸿蒙端接纳回调方式将效果送到 commonMain，回到 commonMain 后，使用协程的suspendCoroutine 方式将异步转同步来实现逻辑。
    厥后发现了一个更优雅的方式。官方的协程库已经和 promise 做了很好的处置惩罚。
    
    
    
    • 第一步定义expect/actual 接口。只不过这次定义时增加suspend 关键字。
      
      1. expect suspend fun platformCompressToZip(sourceFile: String, outputZipPath: String): Boolean
      3. expect suspend fun platformUnZipFile(zipFilePath: String, targetDir: String): Boolean

      复制代码
      android 端非常简单，实现对应的函数，逻辑和之前一样直接添补进去就行。
      
      1. actual suspend fun platformCompressToZip(
      2.     sourceFile: String,
      3.     outputZipPath: String
      4. ): Boolean

      复制代码
    • 第二步，鸿蒙端在 FileUtil.d.ts 文件中做如下定义：
      
      1. public static compressToZip(sourceFile: string, outputZipPath: string): Promise<boolean>;

      复制代码
      在 FileUtil.ts 文件中实现具体逻辑。
      
      1. public static compressToZip(sourceFile: string, outputZipPath: string): Promise<boolean> {
      2.   return new Promise<boolean>((resolve, reject) => {
      3.     var options = {
      4.       level: zlib.CompressLevel.COMPRESS_LEVEL_DEFAULT_COMPRESSION,
      5.       memLevel: zlib.MemLevel.MEM_LEVEL_DEFAULT,
      6.       strategy: zlib.CompressStrategy.COMPRESS_STRATEGY_DEFAULT_STRATEGY
      7.     }
      8.     zlib.compressFile(sourceFile, outputZipPath, options).then(success => {
      9.       resolve(true)
      10.     }).catch(error => {
      11.       console.log(error)
      12.       reject(false)
      13.     })
      14.   })
      15. }

      复制代码
      注：这里为了对齐 boolean 做返回值这个逻辑，又用本身的 Promise 将体系的封装了一层。
      
    • 第三步，再次生成FileUtil.kt 文件，其中对应的函数为：
      
      1. fun compressToZip(sourceFile: String, outputZipPath: String): Promise<Boolean>

      复制代码
      接着在 Platform.js.kt 中使用
      
      1. actual suspend fun platformCompressToZip(
      2.     sourceFile: String,
      3.     outputZipPath: String
      4. ): Boolean {    return FileUtil.compressToZip(sourceFile, outputZipPath).await()}

      复制代码
      借助于协程库对 Promise 的封装，这里调用 Promise 的 await 方法，简化逻辑，比较优雅的实现了两端同步、异步不同实现的抹平。
      
    
    
  
  

总结

最厥后尝试答复文章开头的几个问题：

• 两端的 context 怎样抹平？
  context 的处置惩罚，方式 1；就是回避这个问题，比方上面的 demo 中，获取 context 是为了获取文件处置惩罚的路径。那么选择将 root 根路径直接从函数接口注入即可。方式 2；将各个平台的 context 注入到对应的平台 target 部分。比方 android 的注入到 androidMain 部分，commonMain 再通过定义expect /actual来调用 android 端的本事。
  
• 在这种跨端项目中怎样实现异步操纵？两端的异步操纵怎样平衡？ 异步操纵直接调用官方封装的协程库，各个端的实现逻辑只管接纳同步式写法。如果不能，比方鸿蒙端的文件压缩逻辑，那么就封装为 Promise，然后在 Platform.js.kt 中调用协程库的 await 等函数来做抹平操纵。
  
• KMP 项目怎样调用底层的，特殊是体系的 API？ 和 demo 中的 log 模块一样的处置惩罚逻辑。android 端直接调用，鸿蒙端则根据其接口定义生成对应的*.kt 文件，在 jsMain中调用。
  
• 如那边理平台特定的功能实现？ 稍显复杂的逻辑，比方 demo 中计算文件 md5，压缩文件等功能，接纳在commonMain 中定义expect /actual接口，各个端实现具体逻辑的方式来开发。
  

其他

• 跨端框架有许多，比方 flutter、RN 也可以做到跨端，也能覆盖到鸿蒙平台。Kotlin KMP 的不同点在哪？
  现在接触下来最大的感觉是 KMP 更靠近底层 native 层，Flutter、RN 方向于 UI 和业务。逻辑层的代码可以用 KMP 做统一。
  而且它的另外一个优势就是接入资本低，性能仅次于各个端 native 代码。KMP 的目标产物是各个平台的 native 代码，各端接入只是相当于多了个 library。Android 端，代码可以直接编译为 aar；鸿蒙端编译为*.js 代码；直接引入即可不需要额外集成其他的假造机、大概 skia 这样的库；侵入性也低。
  
• 整个 KMP 项目标开发调试还是有许多不敷，android 端可以做断点调试，其他的比方 js（鸿蒙）、ios 比较难处置惩罚，只能接纳打印 log 的方式举行。因此除了 android 端，其他端的 Platform.xxx.kt 文件中只管减少逻辑代码，真正的逻辑实现都在各自端实现方便调试，只是将生成的协议 kt 文件放置在项目中，供 KMP 项目调用。
  
• 对数据类型的处置惩罚：在跨平台通信时，String（字符串）和 Boolean（布尔值）是最稳固的类型，不容易由于平台差别而出现兼容性问题。因此，在定义跨端接口（如 common 层的 API）时，接口使用 String 和 Boolean 作为入参和返回值。如果需要传递列表数据，可以使用 类似List<String>的定义，这样在 Android、iOS、鸿蒙各个端都能保持一致，制止剖析错误。
  性能需衡量：这样的计划肯定会有性能问题，JSON的序列化/反序列化可能成为性能瓶颈，复杂场景可思量二进制协议；
  过分使用String可能导致类型擦除问题，建议配合kotlinx.serialization使用。
  重要数据建议做Base64编码制止剖析问题。
  
• 现在平台功能还不够完善，许多复杂功能需要本身构建 native 的实现供 common 调用。这种情况下通过“协议”方式穿透各端。在调用各平台的复杂功能（如网络请求）时，可以接纳协议封装的方式，让 common 层使用 JSON 结构传递信息，各端再剖析后调用各自的原生实现。比方，可以定义如下 JSON 格式的请求体：
  { "url": "https://api.example.com/data", "method": "OST", "header": "{Authorization: Bearer token}", "body": "{'key': 'value'}" }
  在 common 层，这个 JSON 字符串会作为统一的协议传递到 Android、iOS 或鸿蒙其他端，各端剖析后利用原生的网络库来执行现实的请求。
  
• 示例 demo 完备代码：GitHub - eleven-max/kmp-harmony-android-sdk-sample: 这是一个基于 Kotlin Multiplatform (KMP) 技术的样例工程，用于展示怎样实现同时支持 鸿蒙 (HarmonyOS) 和 Android 平台的 SDK 开发流程
  
• 参考资料：
  

• Kotlin/JS IR compiler | Kotlin Documentation
  
• https://juejin.cn/post/7404858270513152000
  
• https://juejin.cn/post/7379059228105621556
  

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。