Kotlin Multiplatform 扩展到 Web:先划清边界,再谈代码复用

25 阅读10分钟

Kotlin Multiplatform 扩展到 Web:先划清边界,再谈代码复用

本文以 Falcon 为背景,讨论将既有多端实时媒体客户端扩展到 Web 时的一般工程判断。文中不涉及具体业务、接口、部署或内部实现细节。

背景:从原生多端到 Web

Falcon 是一个已覆盖 Android、iOS 和 Desktop 的多端实时媒体客户端,涉及视频播放、音视频采集、屏幕共享等能力。

当我们考虑增加 Web 端时,表面上是在为现有产品增加一个运行平台,实际面对的是一次能力边界的重新划分:哪些逻辑可以跨端复用,哪些能力必须遵循浏览器的安全模型、媒体模型与生命周期重新实现。

这并不是一个“把原生页面搬到浏览器”的问题。更准确地说,它是一个产品与工程共同的问题:

  • Web 端要承担哪些任务?
  • 哪些逻辑的业务语义在所有平台一致?
  • 哪些能力天然依赖平台运行环境?
  • 当涉及实时媒体时,前端、后端和媒体基础设施分别负责什么?

本文不试图给出一套可以直接复制的架构,而是提供一个适合做前期方案判断的框架。

先定义 Web 的角色,而不是先开始迁移

开始开发前,最值得确认的不是“哪些页面能复用”,而是 Web 在整个产品中的定位。

Web 可以是一个轻量入口,也可以是协作和观看入口,还可以是完整功能端。不同定位会直接影响技术方案、交付范围和跨团队依赖。

如果一开始没有定义边界,项目很容易掉进一个陷阱:将“与原生端功能完全一致”当作默认目标。这个目标听起来合理,但常常既昂贵又不必要。

浏览器有自己的一套规则:

  • 用户权限由浏览器和操作系统共同控制;
  • 媒体采集和播放受浏览器能力约束;
  • 后台标签页的执行与网络行为不等同于原生 App;
  • 文件、存储、网络和第三方 SDK 都有不同的运行模型。

因此,更好的问题是:

Web 是否能以符合浏览器特点的方式,稳定地完成它应承担的任务?

这意味着 Web 可以与原生端共享同一个业务目标,却不必拥有相同的技术实现。

按“稳定业务”和“平台能力”划分复用边界

跨端项目中,“能编译”不是共享的充分理由。

更实用的判断方法是:这段代码是否依赖某个平台才成立的假设?如果依赖,那么即使它恰好能被多个 Target 编译,也未必值得共享。

更适合共享更适合按平台适配
数据模型与接口契约会话与本地存储
表单校验与错误映射文件选择、下载与上传
领域状态转换媒体采集、播放与设备切换
主题、设计令牌与尺寸规范浏览器/系统生命周期
无平台依赖的 UI 结构第三方 SDK 与系统集成

这里的重点不是追求最大复用率,而是避免业务规则分叉。

例如,模型字段、校验规则、状态转换这些内容通常有稳定的业务含义;但媒体播放、文件访问、生命周期处理等能力,即使表面上服务于同一个功能,也会因平台能力而有完全不同的实现路径。

一个简单的原则是:

共享业务语义,不共享平台假设。

共享逻辑之前,先找出它依赖的假设

同一个功能名称,并不代表同一种实现可以适用于所有端。

“文件上传”在桌面端可能依赖本地路径;在浏览器中,文件通常以 File 或 Blob 的形式出现,并受到用户手势、权限和内存限制影响。

“保持会话”在原生端可以使用平台提供的安全存储;在浏览器中,则要重新判断刷新、关闭标签页、跨标签页、Token 过期和敏感信息持久化的边界。

“开始播放”在原生端可能只是创建播放器;在浏览器中,还要面对自动播放策略、音频权限、后台节流、编解码支持和跨域资源限制。

所以,在决定共享之前,可以先问三个问题:

  1. 这段逻辑依赖哪些系统能力?
  2. 这些能力在浏览器中是否存在等价物?
  3. 即使有等价物,它们的失败方式和生命周期是否相同?

如果答案不相同,就应该把差异收敛在平台适配层,而不是把分支散落到每一个业务页面中。

实时媒体:播放、采集和屏幕共享不是纯前端问题

实时媒体往往是 Web 扩展中最容易被低估的一部分。

浏览器可以申请摄像头、麦克风和屏幕共享,也可以播放浏览器支持的媒体流。但“拿到画面”“本地预览”和“形成稳定可用的线上实时媒体链路”是三件不同的事。

播放能力:先确认浏览器能消费什么

浏览器并不天然支持所有输入协议和编码组合。拿到一个播放地址,不代表它可以被浏览器连接、解复用、解码和稳定播放。

常见的选择通常是:

  • 实时互动、低延迟场景:WebRTC;
  • 面向更多观看用户、可接受一定延迟:HLS;
  • 需要兼容已有输入流:通过媒体网关完成协议接入、转码或转封装,再输出浏览器可消费的流。

这不是说浏览器“做不了播放”,而是说媒体能力不能只由前端决定。前端负责播放器、交互、状态展示与错误恢复;媒体服务负责接入、转换、分发、鉴权、录制和质量监控。

同时,编解码兼容性、硬件解码能力和网络条件在不同浏览器、设备和操作系统上都可能不同。生产环境应有明确的降级策略:例如切换低码率流、提示更换浏览器、展示错误状态,或回退到静态内容。

摄像头和麦克风:权限只是第一步

浏览器通过 getUserMedia() 提供摄像头和麦克风采集能力,但权限成功并不代表采集链路已经稳定。

实际还要处理:

  • 用户拒绝权限或之后撤回权限;
  • 没有可用设备,或设备被其他应用占用;
  • 多摄像头、多麦克风的设备枚举与切换;
  • 外接设备拔出、系统切换输入设备;
  • 浏览器切换到后台后的采集、编码或网络变化;
  • 用户主动停止采集。

因此,采集能力不应只用一个 isStreaming 布尔值表达,而应建模为有明确终态和错误状态的状态机。下面是与具体框架无关的伪代码:

sealed interface MediaState {
    data object Idle : MediaState
    data object RequestingPermission : MediaState
    data object Previewing : MediaState
    data object Connecting : MediaState
    data object Publishing : MediaState
    data object Stopped : MediaState

    data class Failed(
        val category: FailureCategory,
        val retryable: Boolean
    ) : MediaState
}

enum class FailureCategory {
    PermissionDenied,
    DeviceUnavailable,
    NetworkInterrupted,
    ServerRejected,
    BrowserUnsupported
}

这个状态机的价值不在于代码形式,而在于明确区分:用户拒绝、设备不可用、网络异常、服务端拒绝和浏览器不支持,不应被统一处理成“推流失败”。

屏幕共享:浏览器提供采集,但控制权属于用户

屏幕共享通常通过 getDisplayMedia() 实现。它可以完成采集,但浏览器会保留很强的控制权:

  • 必须由用户操作触发,不能静默开启;
  • 用户自己选择共享屏幕、窗口或标签页;
  • 是否能共享系统音频或标签页音频,取决于浏览器和操作系统;
  • 用户可以通过浏览器原生控件随时停止共享;
  • 共享目标关闭、最小化或切换后,画面可能冻结、降帧或结束。

因此,屏幕共享应被视为“随时可能中断的用户输入”,而不是一个可以被应用长期控制的资源。前端需要监听轨道结束事件,明确展示共享范围、音频状态和停止入口;而媒体服务则需要承接后续的传输、分发、录制和权限控制。

前端、后端与媒体服务如何分工

“Web 端不能直接做某件事”常被误解为“这件事不能实现”。更准确的说法是:它通常无法由前端单独可靠完成。

能力浏览器前端主要负责后端与媒体服务主要负责
摄像头/麦克风权限、设备选择、本地预览、交互状态鉴权、信令、媒体转发、录制、质量统计
屏幕共享用户触发采集、轨道状态、停止处理分发、录制、房间权限、转码
实时互动WebRTC 客户端连接、重连交互、设备切换信令、TURN、SFU、房间管理、带宽策略
大规模观看播放器、清晰度选择、错误提示流接入、转码、切片、CDN、播放鉴权
非浏览器原生流展示浏览器可用的输出流协议转换、媒体网关、解码与转封装

其中最重要的协作动作是尽早确认:服务端最终能向浏览器提供什么形式的输出?是否存在信令、鉴权、媒体转发或协议转换能力?能否增加媒体网关?

如果这些前置条件尚不存在,前端仍然可以完成设备采集与本地预览,但不能把它等同于“实时媒体功能已上线”。

其他容易被低估的浏览器约束

媒体之外,还有几类问题值得在方案阶段提前确认。

首先是生命周期。页面刷新、标签页隐藏、浏览器后台节流、网络切换都可能改变任务执行状态。恢复到前台时,应重新检查连接和媒体状态,而不是假定一切仍正常。

其次是文件能力。浏览器没有稳定的本地文件路径,应围绕 File、Blob、受控下载和用户选择行为设计。大文件上传还应考虑进度、取消、重试和刷新页面后的恢复策略。

最后是网络与安全环境。HTTPS、CORS、Cookie 或 Token 策略、预检请求、过期后的恢复流程,都应在开发早期联调。只在本地环境请求成功,并不代表浏览器端方案已经成立。

一个务实的推进顺序

如果要将既有客户端扩展到 Web,我会建议按以下顺序推进:

  1. 定义 Web 的用户任务,以及明确不承担的能力;
  2. 打通基础会话、路由、错误处理和网络环境;
  3. 优先迁移模型、校验、状态转换等稳定业务逻辑;
  4. 将文件、生命周期和第三方 SDK 放在平台适配层;
  5. 与后端、媒体服务共同跑通最小端到端媒体链路;
  6. 最后补齐弱网、设备切换、后台恢复、监控和降级策略。

验证也应分层:编译通过、自动化测试、服务联调、真实浏览器与设备验证,分别代表不同程度的完成,不能互相替代。

结语

将既有客户端扩展到 Web,不是多编译一个 Target,而是在浏览器的安全模型、媒体模型和生命周期约束下,重新设计一部分能力。

Kotlin Multiplatform 的价值不在于让所有平台共享同一份实现,而在于帮助团队更清楚地区分:哪些是稳定的业务本质,哪些只是特定平台上的实现方式。

好的跨端架构,不是让每个平台看起来完全相同;而是让每个平台都能以适合自己的方式,稳定地承载同一个业务目标。