★ FEATURED ARTICLE 项目标题里嵌着三个关键词Flutter、OpenHarmony、Web开发助手App最后落到API测试上。乍一看是又一套HTTP调试工具但把技术栈换成Flutter适配OpenHarmony之后这件事的性质就变了——它不是普通的上层应用开发而是要在跨平台框架和开源系统之间搭一座桥。我实际做完这个项目之后最大的感受是API测试功能本身并不难写真正的坑全埋在Flutter接入OpenHarmony这条链路里。这篇文章把我从环境搭建到功能落地的完整过程拆开来讲包括技术选型的判断依据、每个关键模块的代码实现、以及那些网上文档基本不会写清楚的踩坑记录。无论是想给OpenHarmony做应用的Flutter工程师还是正打算开发本地调试工具的同学这篇都值得参考。1. 项目定位与技术选型为什么非要用Flutter做OpenHarmony应用1.1 这个App到底解决什么问题先明确一下这个Web开发助手的定位。它不是浏览器也不是IDE而是面向Web前端、后端接口联调、以及移动端调试场景的API测试工具箱。核心功能就是发HTTP请求、看响应、管理历史记录、快速构造参数——类似Postman或Apifox的精简版但它的运行平台是OpenHarmony设备。我做这个项目的起因其实很实际团队里负责OpenHarmony应用开发的同事一直抱怨在鸿蒙设备上调试接口很麻烦要么连PC端工具要么用系统浏览器凑合都没有专门针对这套系统的调试工具。所以这个App的目标用户非常明确OpenHarmony应用开发者、以及在这套系统上做前后端联调的工程师。它的核心价值在于在设备上直接完成接口调试省去来回切换电脑的折腾。1.2 Flutter能不能正经适配OpenHarmony提到OpenHarmony应用开发很多人第一反应是ArkTS和ArkUI。但问题是团队里有大量Flutter基础扎实的工程师ArkTS生态对个人开发者来说也有学习成本。我选择Flutter走OpenHarmony适配路线主要考量有三点代码复用率Flutter本身是跨平台方案一套Dart代码可以跑在Android、iOS、Web上而OpenHarmony这边已经有社区维护的flutter_flutter分支可以把同一套逻辑带到OH设备上。UI表达力API测试工具这类开发调试类App界面以表单、按钮、列表、代码区为主Flutter的Widget体系在构建这类工具型界面时效率非常高尤其是Table、TextField、ListView这些组件的组合能力。生态沉淀Flutter的插件机制成熟网络请求、JSON解析、持久化存储都有现成方案哪怕底层需要对接OpenHarmony的API也可以封装成Platform Channel。当然这里必须说清楚一个现实情况如果你要开发的App重度依赖OpenHarmony的系统能力比如分布式软总线、流转、超级终端协同那原生ArkTS依然是更稳妥的路线。而我做的Web开发助手本质上是一个UI密集、系统能力依赖弱的工具类应用Flutter的适配优势恰好能得到发挥。1.3 技术栈全景图整个项目涉及到的技术组件如下模块技术选型说明UI框架Flutterflutter_flutter分支主分支为官方Flutter一套代码目标OpenHarmony Android等网络请求原生HttpURLConnection Platform Channel封装OpenHarmony侧网络权限管控与Android不同状态管理Provider轻量、易调试适合工具类App数据持久化shared_preferences JSON文件存储历史记录和集数据解析dart:convert简单场景不需要引入json_serializable这里最核心的决策是网络请求不走Dio或http包而是走Platform Channel调用系统原生能力。原因我在后面第三个章节重点展开。2. 开发环境与工程搭建绕过那些文档没写全的坑2.1 环境准备清单先说环境。截至我做的这个版本Flutter适配OpenHarmony的主流方式是使用OpenHarmony SIG组织维护的flutter_flutter仓库对应的是OpenHarmony SDK。你需要准备四样东西DevEco StudioOpenHarmony应用开发IDE我用的是4.0 ReleaseOpenHarmony SDK建议用API 9以上版本我用的是API 10flutter_flutter分支源码clone后切换到对应release分支Node.jsOpenHarmony侧构建工具链会用到安装过程有个容易踩的坑flutter_flutter分支不能直接用官方flutter命令管理需要单独配置环境变量指向这个分支的bin目录。然后注意不能用flutter create直接创建OH工程我一开始想偷懒结果生成的工程结构完全对不上。正确顺序是先用DevEco Studio创建一个Native C工程也就是OpenHarmony的标准工程再把Flutter模块嵌入进去。2.2 创建工程的具体步骤我实际走通的流程大概是这样的在DevEco Studio里新建一个标准OpenHarmony工程包名我用的是com.windea.apitool注意包名要符合应用市场规范不能用下划线。在工程根目录下创建一个flutter模块目录比如叫oh_host把flutter_flutter分支的framework代码和你的Dart业务代码放进来。配置build-profile.json5和module.json5加入Flutter引擎依赖以及网络权限{ module: { requestPermissions: [ { name: ohos.permission.INTERNET, reason: API测试工具需要访问网络, usedScene: { ability: MainAbility, when: inuse } } ] } }这一步很关键——OpenHarmony的INTERNET权限不申请网络请求会直接报权限拒绝而且是在运行时才会暴露不是编译期报错。在MainAbility的onCreate里加载Flutter容器。我用的是FlutterAbility这种方式它可以理解为一个能在OH应用里承载Flutter页面的系统组件。加载代码大概是// MainAbility.ets import FlutterAbility from ohos/flutter_ability; export default class MainAbility extends FlutterAbility { onWindowStageCreate(windowStage: window.WindowStage): void { windowStage.loadContent(pages/index).then(() { this.loadFlutter(); }); } }注意loadContent的页面路径要提前建好否则Stage组件加载不到页面会白屏。2.3 本地调试的一个实用技巧OpenHarmony设备连接调试和Android不太一样它默认不开USB调试。我用的方法是在DevEco Studio里直接配自动签名然后通过HDCHarmonyOS Device Connector类似adb的工具连接设备测试。如果第一次连接不上先检查设备上有没有开启开发者模式然后在hdc shell里执行hdc shell param get const.product.software.version能返回系统版本说明hdc通道OK。这个命令我每次换设备都会先跑一遍避免后面半天排查才发现是连接问题。3. API测试核心功能设计把发请求这件事拆到最简3.1 数据模型先是名词解释写API测试工具第一步不是写UI而是把一个HTTP请求这个概念用代码表示出来。我建了一个ApiRequest模型class ApiRequest { String id; // 唯一标识用毫秒时间戳随机数生成 String name; // 请求名称例如获取用户列表 String method; // GET/POST/PUT/DELETE/PATCH String url; // 请求地址 MapString, String headers; // 请求头 MapString, dynamic params; // 查询参数或body参数 String bodyType; // none/form/json/raw String bodyContent; // 原始body内容 int timeout; // 超时时间默认10秒 int createdAt; // 创建时间 ApiRequest({ required this.id, required this.name, this.method GET, this.url , this.headers const {}, this.params const {}, this.bodyType none, this.bodyContent , this.timeout 10, required this.createdAt, }); factory ApiRequest.fromCache(MapString, dynamic map) { return ApiRequest( id: map[id] as String, name: map[name] as String, method: map[method] as String, url: map[url] as String, headers: MapString, String.from(map[headers] ?? {}), params: MapString, dynamic.from(map[params] ?? {}), bodyType: map[bodyType] as String? ?? none, bodyContent: map[bodyContent] as String? ?? , timeout: map[timeout] as int? ?? 10, createdAt: map[createdAt] as int, ); } }这个模型覆盖了一个HTTP请求的所有关键维度。很多人会忽略id和createdAt这两个字段但做历史记录和请求去重时它们非常有用。Model层的设计原则是后市无论接入什么存储方式模型保持稳定。3.2 原生网络能力接入为什么非走Channel不可这里说一下我在技术选型时最纠结的一点。正常做Flutter网络请求大家第一反应就是用Dio它封装了拦截器、Cookie、重试机制非常好用。但这个项目有个特殊性Flutter层跑在OpenHarmony上但Dio底层依赖的是Dart的dart:io库的HTTP实现而Flutter在OH上的引擎层对dart:io的网络支持并不完整实测下来有概率出现请求发送成功但回调丢失、或者SSL握手异常的问题这也是OpenHarmony Flutter适配已知的坑之一。所以我最后选择了不走Dart的HTTP栈而是通过Platform Channel把请求交给OpenHarmony原生侧处理// 网络请求的Flutter侧封装 import package:flutter/services.dart; class NetworkService { static const MethodChannel _channel MethodChannel(com.windea.apitool/network); static FutureMapString, dynamic request({ required String method, required String url, MapString, String headers const {}, String body , int timeout 10, }) async { try { final result await _channel.invokeMethod(httpRequest, { method: method, url: url, headers: headers, body: body, timeout: timeout, }); return MapString, dynamic.from(result as Map); } on PlatformException catch (e) { return {error: e.message ?? 网络请求异常}; } } }OpenHarmony原生侧有一个封装类核心逻辑是使用http模块的createHttpClient()。这么做的好处是网络请求全部跑在系统原生栈上HTTP/1.1、HTTPS、重定向、Cookie这些基础能力系统已经帮你处理好了Flutter只负责UI渲染和业务逻辑风险可控。3.3 UI状态管理Provider还是别的方案UI状态管理我选了Provider没有上bloc或者riverpod。理由是这个App的页面状态复杂度其实有限——主要就是当前编辑的请求正在发送中的状态历史记录列表这三个维度Provider的ChangeNotifier模式足够清晰而且调试起来特别直观出了问题点开Widget Inspector就能看到状态变化链路。我设计了一个ApiRequestProviderclass ApiRequestProvider extends ChangeNotifier { ApiRequest currentRequest; bool isSending false; ApiResponseData? responseData; ListApiRequest history []; void updateRequest(ApiRequest req) { currentRequest req; notifyListeners(); } void updateSendingState(bool sending) { isSending sending; notifyListeners(); } void updateResponseData(ApiResponseData data) { responseData data; notifyListeners(); } void addToHistory(ApiRequest req) { history.insert(0, req); notifyListeners(); } }这里有个设计上的小心思每次发送请求时不需要重建整个页面只要updateSendingState(true)UI里Loading组件就会响应更新响应数据回来后再updateResponseData整条链路非常顺滑。这种拆分方式也方便后面加批量发送之类的扩展功能。4. 核心环节实现从发一个请求到管理历史记录4.1 发送请求的完整流程我来说说主流程的具体实现。发送请求这步是整个App的心脏我把它分成5个阶段参数组装把UI上填的method、url、headers、body拼接成Map传给NetworkService。Loading状态发送前把按钮禁用显示转圈防止重复点击。请求执行调用_channel.invokeMethod发起Channel请求等待原生返回。响应解析原生返回的是一条JSON字符串statusCode、headers、bodyFlutter侧交给jsonDecode解析成ApiResponseData。历史记录保存发送成功无论状态码是否2xx都把请求写入历史记录。其中第4步有一个容易忽略的点响应体可能是大文件或者二进制。我的做法是原生侧先检查Content-Type如果是JSON或文本类型就直接转字符串否则做base64编码再由Flutter转存。这个细节决定了API测试工具能不能调试文件上传接口。核心发送代码我贴一下简化过的Futurevoid executeRequest() async { _provider.updateSendingState(true); try { final response await NetworkService.request( method: _provider.currentRequest.method, url: _provider.currentRequest.url, headers: _provider.currentRequest.headers, body: _buildBodyString(), timeout: _provider.currentRequest.timeout, ); if (response.containsKey(error)) { _provider.updateResponseData( ApiResponseData( statusCode: 0, headers: const {}, body: response[error] as String, duration: 0, ), ); } else { _provider.updateResponseData( ApiResponseData( statusCode: response[statusCode] as int, headers: MapString, String.from(response[headers]), body: response[body] as String, duration: response[duration] as int, ), ); } } finally { _provider.updateSendingState(false); _provider.addToHistory(_provider.currentRequest); } }你仔细看会发现我把请求体拼接和解析这部分独立出来_buildBodyString因为form、json、raw三种body格式的拼接逻辑完全不同挤在一个方法里会让代码膨胀得很快拆开之后每个分支都清楚。4.2 常用请求集的保存与导入作为一个面向开发辅助的工具光有单次请求不够我还加了请求集Collection管理。逻辑很简单就是一个文件夹式结构Collection文件夹 ├── 用户模块 │ ├── 获取用户列表GET /api/users │ └── 创建用户POST /api/users └── 订单模块 └── 查询订单GET /api/orders/:id保存方式用JSON文件存到应用沙箱里每个Collection一个文件文件名用Collection的id。这样天然支持导出/导入——直接把JSON文件复制走就行。这个功能做起来不难但性价比极高团队内部可以互通API集合省去每人重新配置的功夫。4.3 响应展示与格式化体验响应这块我做了两个让开发体验很好的设计。第一个是代码高亮用了一个轻量的Dart正则高亮方案把JSON的key、字符串、数字、布尔值分别染色。不引入重型的语法高亮库是因为在OpenHarmony上包体积能省则省。第二个是响应耗时展示原生请求返回时会带上耗时毫秒数我会在UI上用一个彩色标签显示200 OK · 235ms联调时一眼看懂接口快慢。这两个功能看起来小但对开发助手类App的体验提升极大。几乎所有用了这个App的同事都会感叹响应体高亮以后看着舒服太多了。5. 常见问题与排查技巧实录这些坑我踩了一遍5.1 组件通信Flutter和原生之间消息发丢了项目开发到一半我遇到一个诡异的问题Flutter层调用Channel请求网络偶尔会有回调收不到的情况。排查了一整天才发现是OpenHarmony的FlutterAbility生命周期和消息通道时序不一致导致的。在页面还没完全挂载的时候如果Flutter侧发起invokeMethod消息会排在队列里但原生侧如果错过了注册时机这条消息就永远没有回执。解决办法是在Flutter侧加一个ensureEngineReady的等待逻辑通过原生侧回调确认引擎就绪后才允许发送网络请求。这也解释了为什么我前面的NetworkService里没有加缓存——它就是给业务层兜底用的。5.2 Impeller渲染引擎带来的奇怪白屏这是我调试时碰到的最离奇的问题。Flutter官方在推进Impeller作为渲染引擎flutter_flutter分支里默认也启用了Impeller。但在我的一台OpenHarmony设备GPU驱动较老上切换到带有TextField的页面就直接白屏root cause是Impeller的着色器编译在旧GPU上有兼容性bug。解决方案是在FlutterAbility的配置里关掉Impellerthis.flutterEngine?.setRunArguments([ --enable-impellerfalse ]);或者更直接一点在flutter层配置FlutterEngine.configure({ enableImpeller: false });这个坑让我对默认设置不能乱信有了更深的体会。好在flutter_flutter分支保留了切回Skia渲染的开关否则这个App在某些设备上基本没法用。5.3 PlatformView嵌入代码区时的键盘问题因为API测试工具里免不了要展示请求体/响应体的大段文本我需要把代码编辑区做出来。在OpenHarmony上常用的方式是Flutter的UiExtensionView类似Android的PlatformView把系统原生TextView嵌进Flutter页面。但这里有个体验问题平台视图在滚动列表里会漂移上下滑动时输入框和键盘位置对不上。排查后确认是PlatformView的缓冲区和Flutter滚动事件的同步延迟导致。最后我调整了策略不直接把PlatformView放进列表而是改成全屏模态展示——点击代码区后跳转到一个专门的编辑页面这个页面只包含一个PlatformView没有复杂滚动问题就消失了。5.4 常见问题速查表症状可能原因解决办法网络请求报权限错误module.json5缺少INTERNET权限按文中步骤补权限声明页面白屏Impeller引擎兼容问题关闭Impeller回退SkiaChannel消息无回执Flutter容器未ready加引擎就绪等待逻辑PlatformView滑动漂移滚动容器与平台视图同步延迟改用全屏模态编辑页HTTP响应中文乱码编码格式未按UTF-8解析原生侧统一按UTF-8转字符串6. 项目后续还能怎么扩展我从使用反馈里得到的启发做完核心功能之后我在团队内部小范围试用了一个月。大家的反馈集中在几个方向上我也顺便规划好了迭代思路保存请求模板把常用的鉴权请求比如token换取做成全局模板每个新请求都能自动携带公共Header。这一步对做企业级Web开发的同事帮助很大他们的接口都有统一的签名参数。多环境切换开发环境、测试环境、预发环境的base URL一键切换。这个在现有模型里加一个Environments配置即可成本比较低。API文档导入导出支持从Swagger/OpenAPI规范里导入接口定义然后在App里直接编辑测试比手动填参数省太多时间。尤其是第一点实际开发中90%的接口调试都要先拿token能自动带公共头会让效率高出好几个量级。这也是工具类App的通用发展方向——从单次请求工具进化成接口工作台。我个人在实际操作中的体会是开发这种开源系统上的工具App不能只把思路局限在如何写出一套漂亮的Flutter UI而要多想一层——Flutter和系统之间的桥梁稳不稳、数据格式对齐了没有、生命周期接住了没有。这些问题往往决定了项目能不能从demo走到真正被人天天使用。如果你也在做Flutter for OpenHarmony的开发建议先把Platform Channel的调试打通再往上层堆功能会顺畅很多。接下来我准备把请求集同步功能加上如果你有想了解的具体实现细节欢迎一起交流。
阅读完成 · 觉得有帮助？
