我去年团队接到一个挺特殊的需求:把已经跑在Android和iOS上的电子合同签署App,做到OpenHarmony上去。业务方明确要求复用现有Flutter代码,不能重新写一套原生实现。项目落地之后,踩了不少坑,也沉淀了一些方法,今天把API集成这块的完整思路和实操过程整理出来分享给需要的朋友。如果你正准备做OpenHarmony上的Flutter应用,或者在做合同、金融类App的API对接,这篇文章应该能帮你省几天的调研时间。
先说清楚这个项目是做什么的。简单说,就是面向企业客户的电子合同签署工具,核心链路包括合同模板管理、创建合同、发起签署、实名认证、手写签名、签署完成归档。客户端主要承担三件事:展示合同内容、接收用户签署操作、与后端API同步状态。技术选型上,UI层用Flutter,跨端逻辑全部复用,OpenHarmony侧通过社区的flutter适配分支跑Dart代码,底层能力(比如文件存储、网络、安全元件调用)用自定义的平台通道补齐。
这篇文章的重点放在API集成实现上,包括协议怎么设计、网络层怎么封装、签名加密怎么做、文件上传下载怎么处理,以及我在OpenHarmony适配过程中遇到的几个典型问题。往下看。
1. 项目背景与技术选型:OpenHarmony生态下的Flutter实战思路
1.1 OpenHarmony的运行环境和Flutter适配现状
先说实话,OpenHarmony目前的应用生态相比Android和iOS还差不少,但企业端的国产化需求是实打实的,尤其是政务、金融、大型国央企这些行业,对鸿蒙生态的覆盖要求越来越高。我们接到需求的时候,评估过两条路线:一条是用ArkTS配合ArkUI从零开发,另一条就是坚持Flutter跨端复用。
结论很明确,选Flutter。原因有三点:第一,我们现有代码库90%以上是Dart写的,业务逻辑和UI基本可以平移到OpenHarmony;第二,电子合同这类业务,核心逻辑全在服务端,客户端偏重展示和交互,Flutter做展示层绰绰有余;第三,团队没人写过ArkTS,从头学成本太高,项目排期不允许。
目前社区主流的适配方案是基于OpenHarmony SIG组的flutter_flutter分支,配合对应的dart sdk和flutter engine,编译产物是HAP包(HarmonyOS Ability Package)。这里提醒一下,不要直接用官方Flutter SDK来编OpenHarmony目标,文件格式和构建链路都不一样,直接用会卡在gradle或native编译阶段,非常浪费时间。
1.2 电子合同业务链路拆解
电子合同表面上是个"签名"动作,实际上背后是一整条业务链路。我从后端的接口清单反推客户端需要做哪些事,大致分成五个环节:
- 模板与合同管理:企业管理员上传合同模板(PDF或者HTML转PDF),签署请求方根据模板填充参数创建合同实例。
- 签署流程编排:创建合同之后,需要指定签署方和签署顺序,每个签署方有独立的任务列表。
- 身份认证:签署前必须做实名认证,通常是对接权威数据源,比如手机号三要素、人脸识别,走的是服务端API,但客户端需要配合拉起认证页并回传认证结果。
- 签署动作:用户在合同PDF上确认阅读、完成手写签名或者输入签署验证码,客户端把签署坐标、签名图片、时间戳等信息提交给服务端。
- 签署完成与存证:服务端完成验签后归档,生成存证报告,客户端查询状态并展示给用户。
API集成要覆盖的就是这五条线。做之前,我建议把业务状态图画清楚,因为后面的接口设计、回调通知、异常处理,全都依赖对状态的理解。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 整体架构设计:客户端分层与核心模块划分
2.1 Flutter工程结构设计
项目采用标准的feature-first目录结构,没有用传统的by-type分层(即把widgets、models、services各自堆一层),因为合同签署过程涉及的功能页面太多,按业务模块划分代码会更清晰,后面加新功能也不用在全局目录里翻来翻去。
code复制lib/
core/ // 核心基础能力
network/ // 网络层封装
security/ // 加解密、签名
platform/ // 平台通道封装
storage/ // 本地存储
features/
contract_list/ // 合同列表
contract_detail/ // 合同详情
sign/
hand_sign/ // 手写签名
verify_code/ // 验证码签署
template/ // 模板浏览
