Flutter 三方库 http_mock_adapter — 赋能鸿蒙应用开发的高效率网络接口 Mock 与自动化测试注入引擎（适配鸿蒙 HarmonyOS Next ohos）

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.ZEEKLOG.net。

Flutter for OpenHarmony：Flutter 三方库 http_mock_adapter — 赋能鸿蒙应用开发的高效率网络接口 Mock 与自动化测试注入引擎（适配鸿蒙 HarmonyOS Next ohos）

前言

在华为鸿蒙（OpenHarmony）生态的应用开发中，前后端并行开发（Parallel Development）是常态。当后端 API 还在设计或局域网联调环境不稳定时，如果客户端开发者只能干等着真实数据，开发进度将会大打折扣。此外，在进行健壮性测试（如模拟服务器 500 错误、超时、返回脏数据）时，真实服务器往往难以配合。

http_mock_adapter 是一款专为 Dio 打造的高性能 Mock 拦截器。它能拦截应用发出的任何网络请求，并根据预设规则（Endpoint/Post Data/Headers）即时返回自定义的模拟响应。在鸿蒙跨平台应用的开发与自动化测试中，它让开发者能够摆脱对物理网络的依赖，构建出 100% 确定性的测试闭环。在构建鸿蒙平台的交付级测试套件、离线演示 Demo 或快速原型开发时，它是不可或缺的效率利器。

一、原理展示 / 概念介绍

1.1 基础概念

本库实现了在应用内部对网络协议栈的“中间人注入”。

鸿蒙自动化测试沙箱

匹配命中

未匹配

鸿蒙 App 业务代码

Dio 网络框架

http_mock_adapter 拦截器

返回虚拟 JSON/状态码

可选转发给真实网络

隔离物理网络 IO

1.2 核心要点解析

• 无感注入：只需为 Dio 实例添加一个 DioAdapter，业务层代码无需做任何修改（如切换 URL）。
• 丰富的匹配算子：支持根据路径通配符、请求体（Request Body）内容、特定 Header 甚至 Query 参数进行精准拦截。
• 状态全覆盖：支持模拟 200 (Success), 401 (Unauthorized), 404 (Not Found), 500 (Internal Server Error) 等各种网络状态及其响应时延。

二、核心 API / 组件详解

2.1 依赖引入

在鸿蒙工程的 pubspec.yaml 中添加以下开发辅助依赖：

dependencies:dio: ^5.0.0 dev_dependencies:http_mock_adapter: ^0.5.0 # 建议参考最新主流版本

2.2 初始化 Mock 适配器

在鸿蒙端初始化一个用于测试的模块：

import'package:dio/dio.dart';import'package:http_mock_adapter/http_mock_adapter.dart';voidsetupHarmonyMock(){final dio =Dio();// ✅ 推荐做法：创建 DioAdapter 并关联 Dio 实例final dioAdapter =DioAdapter(dio: dio);// 1. 定义拦截逻辑 dioAdapter.onGet('/api/harmony/profile',(server)=> server.reply(200,{'name':'鸿蒙开发者','level':99}), data:null, queryParameters:{}, headers:{},);}

2.3 模拟复杂的异步错误

💡 技巧：在鸿蒙端验证应用的容错率。

dioAdapter.onPost('/api/login',(server)=> server.throws(403,DioException(requestOptions:RequestOptions(path:'/api/login'), type:DioExceptionType.badResponse),),);

三、场景示例

3.1 场景一：鸿蒙端 UI 的“冒烟测试”

通过 Mock 不同长度的 JSON 列表，验证鸿蒙端列表视图在“数据过多”时的流畅度，以及在“数据为空”时的空状态占位图展示。

3.2 场景二：复杂支付流程的本地闭环

模拟支付成功、余额不足、系统扣费中等多种后端状态，让鸿蒙客户端能根据 Mock 返回跳转不同的业务结果页，提高测试覆盖率。

四、OpenHarmony 平台适配挑战

4.1 Mock 代码的打包隔离

Mock 逻辑不应该被打入正式发布的鸿蒙 HAP 包中。

✅ 适配策略建议：

1. 统一工厂注入：建议在项目中建立一个 HttpFactory。根据当前的编译宏（如 kDebugMode）或自定义的鸿蒙编译参数，决定是否装载 http_mock_adapter。
2. 本地测试目录隔离：将 Mock JSON 数据文件存放在鸿蒙测试资源的独立目录下，避免污染生产环境的包体大小。

五、综合实战示例代码

以下是一个演示如何在鸿蒙端实现的“接口联调模拟实验室”组件：

import'package:flutter/material.dart';import'package:dio/dio.dart';import'package:http_mock_adapter/http_mock_adapter.dart';classHttpMockLabPageextendsStatefulWidget{constHttpMockLabPage({super.key});@overrideState<HttpMockLabPage>createState()=>_HttpMockLabPageState();}class _HttpMockLabPageState extendsState<HttpMockLabPage>{final _dio =Dio();String _response ="点击按钮发起请求";@overridevoidinitState(){super.initState();_initMock();}void_initMock(){// 💡 实战技巧：拦截器注入final adapter =DioAdapter(dio: _dio); adapter.onGet('/harmony_data',(s)=> s.reply(200,{'msg':'来自模拟器的鸿蒙专属数据'}));}void_fetchData()async{try{final res =await _dio.get('/harmony_data');setState(()=> _response ="🎉 收到 Mock 数据:\n${res.data}");}catch(e){setState(()=> _response ="❌ 请求失败");}}@overrideWidgetbuild(BuildContext context){returnScaffold( appBar:AppBar(title:constText('网络 Mock 模拟实验室')), body:Center( child:Column( mainAxisAlignment:MainAxisAlignment.center, children:[constIcon(Icons.webhook_outlined, size:80, color:Colors.teal),constSizedBox(height:30),Container( padding:constEdgeInsets.all(16), margin:constEdgeInsets.symmetric(horizontal:20), decoration:BoxDecoration(color:Colors.teal[50], borderRadius:BorderRadius.circular(12)), child:Text(_response, textAlign:TextAlign.center),),constSizedBox(height:50),ElevatedButton(onPressed: _fetchData, child:constText('发起模拟接口调用')),],),),);}}

六、总结

http_mock_adapter 是保证 OpenHarmony 高质量交付的“消音器”。它消除了网络的不确定性噪点，让开发者能专注于业务逻辑与 UI 交互的打磨。

✅ 核心建议：

1. JSON 本地化：对于超大的响应体，建议配合 rootBundle.loadString 读取本地 JSON 文件再传入 reply，保持 Mock 逻辑的代码整洁。
2. 模拟延迟：通过 delay 参数模拟真实环境下的 200ms~2s 延迟，验证鸿蒙端 Loading 动画的视觉衔接。
3. 保持同步：前端 Mock 的结构定义应与后端 Swagger/OpenAPI 文档保持强一致，防止“Mock 是好的，一上线全是报错”。