最近在把一套 Flutter 应用往鸿蒙平台迁移最直观的感受是UI 跑起来只是开始真正决定你能不能顺利交付的是网络层。Flutter 的跨端优势在 UI 上体现得最明显但网络请求、存储、权限这些基础能力换一个平台就会冒出一堆完全不一样的问题。这次为了在一套代码里同时照顾 Android、iOS 和鸿蒙网络层我选了 Dio。倒不是因为它花哨而是它对简单够用 后续可扩展这两点的平衡做得最好。今天就把这套基于 Dio 的网络请求架构完整拆开讲一遍包括鸿蒙适配的权限配置、拦截器设计、统一返回结构以及我实际踩过的坑。目标读者是正在做 Flutter 鸿蒙跨端适配的开发者或者想在项目早期就把网络层设计得不那么脆弱的人。1. 为什么是 Dio网络层选型背后的实际考量1.1 跨端场景下Dio 的下限比想象中高Flutter 生态里的网络库选择其实不多主流就是http、dio加上基于它们做的各种封装。http够轻官方文档也推荐它做基础请求但它的定位是简单客户端没有拦截器、没有全局配置、没有取消机制、没有上传下载进度回调。这些东西在单个页面上用不到但一旦项目里出现用户登录态、日志统一管理、大文件上传你就得开始自己造轮子。Dio 的优势不是某个单点功能而是这些功能组合起来刚好覆盖了跨端项目最常遇到的场景拦截器机制可以在请求发出前统一注入 token、统一做日志打印CancelToken页面销毁时随时取消在途请求避免用户明明已经返回了网络回调还在更新状态FormData和进度回调上传文件、下载文件都有配套方案底层用的是dart:io的HttpClient而鸿蒙的 Flutter 适配层实现了dart:io接口。这句话很重要意味着 Dio 在鸿蒙上不需要走平台通道不需要为鸿蒙单独写一套原生网络代码。第二个点需要展开说。很多人一听鸿蒙适配网络请求第一反应是要不要用 DevEco Studio 写原生网络代码再通过 MethodChannel 调。但 Flutter 引擎跑在鸿蒙上时Dart 层的dart:io是直接可用的底层会映射到鸿蒙的 socket 实现。也就是说你写的这段代码不做任何改动就能在 Android、iOS、鸿蒙三端发起请求。真正要改的是应用外围的权限声明、网络安全策略、证书校验规则这些系统层面的东西。1.2 再稳的库也扛不住裸用封装才是跨端的关键见过不少项目直接在业务页面里Dio().get()一把梭小项目短期没问题但涉及跨端适配就开始痛苦了日志代码散落在各个页面release 包想统一关掉只能一个个找token 更新了要跑到每个调用点去改 header服务端返回的错误信息格式不统一三端报错的表现还不一样排查起来全靠猜。我推荐的思路是页面不直接依赖 Dio而是依赖一个自己封装的ApiClient把平台差异和网络细节全部收拢到一个文件里。分层大概是这样的页面 / ViewModel ↓ Repository领域层 ↓ ApiClient网络层唯一的 Dio 入口 ↓ Dio第三方库页面只负责拿数据模型Repository 负责把业务数据转为模型ApiClient负责决定超时时间、请求头、拦截器、错误处理。这样以后不管鸿蒙又出了什么新权限规定还是 Dio 要换版本都只改ApiClient一个地方业务层不受影响。在我看来跨端开发的底层要求不是 API 调用处的三端一致而是差异的收敛点足够集中。2. 鸿蒙适配第一步搞懂权限和网络安全策略2.1 Flutter 跑在鸿蒙上的底层网络逻辑先理清一个背景Flutter 官方目前对鸿蒙的支持还在社区化推进阶段大多数团队的落地方式是使用基于 OpenHarmony 适配的 Flutter SDK。这个版本的 Flutter 引擎把 Dart 的dart:io层映射到了鸿蒙系统能力上所以网络请求才有零改动跨端的前提。但底层通不代表应用层通鸿蒙作为一个独立系统有自己的应用权限模型和网络安全策略。哪怕 Dio 把请求发出去了系统层面的校验没过请求照样失败。这一点是我在项目里花时间最多的不是写网络代码而是跟系统策略较劲。2.2 鸿蒙工程里先把这三样配齐如果你用 Flutter 创建了鸿蒙工程目录结构里会有一个entry/src/main/module.json5这是鸿蒙应用模块的配置文件。第一步是声明网络权限{ module: { name: entry, requestPermissions: [ { name: ohos.permission.INTERNET } ] } }不加这一项运行时会直接报SocketException: Permission denied而且报错位置随机有时候是 DNS 解析失败有时候是连接超时很难第一时间想到是权限问题。第二件事是明文 HTTP 请求的放行。如果你的后端接口在测试环境用的是http://不是https://鸿蒙默认会拒绝明文流量。跟 Android 9 之后的行为类似需要在网络安全配置里显式允许。在entry/src/main/resources/base/profile/目录下新建network_config.json{ network-security-config: { base-config: { cleartext-traffic-permitted: true } } }然后在module.json5的module节点里声明这个配置文件{ module: { name: entry, networkSecurityConfig: resources/base/profile/network_config.json } }cleartext-traffic-permitted这个开关是全域放行只建议在测试环境开启。如果你的应用里只有个别域名走 HTTP这里可以配置domain-config只对这些域名放行其他域名仍然强制 HTTPS。生产环境建议false配合全站 HTTPS 比较稳妥。第三件事是证书校验的预期管理。鸿蒙的 TLS 校验比较严格如果你的测试环境用自签名证书Dio 这边需要额外处理后面第 4 章会专门说。这里先记住一个结论三端里证书策略差异最大的就是鸿蒙别拿 Android 的经验直接套。2.3 三端网络配置对照速查表我把三端常用配置整理成了对照表方便你后面查配置项AndroidiOS鸿蒙OpenHarmony网络权限声明AndroidManifest.xml中uses-permission android:nameandroid.permission.INTERNET/一般不需要单独声明module.json5的requestPermissions添加ohos.permission.INTERNET明文 HTTP 开关AndroidManifest.xml中android:usesCleartextTraffictrue或 network security configInfo.plist中NSAppTransportSecurity的NSAllowsArbitraryLoadsnetwork_config.json的cleartext-traffic-permitted自签名证书默认拒绝需自定义 TrustManager默认拒绝需自定义 ATS 例外默认拒绝需在代码里处理配置文件位置打包进 APK打包进 IPA打包进 HAP这张表看起来简单但实际项目里最容易翻车的就是第三行自签名证书。因为跨端项目联调时经常是后端同学本地起一个服务iOS 上允许了Android 上允许了到了鸿蒙上直接连不上第一反应都以为是 Dio 写错了其实人家库根本没执行到。3. 一套简单但能抗事的请求架构长什么样3.1 BaseOptions 参数到底怎么填封装ApiClient第一步是配置 Dio 的BaseOptions。我踩过很多次超时时间设置不合理的坑所以这里给出一个比较通用的起点class ApiClient { static final ApiClient _instance ApiClient._internal(); factory ApiClient() _instance; late final Dio dio; ApiClient._internal() { dio Dio( BaseOptions( baseUrl: https://api.example.com, connectTimeout: const Duration(seconds: 10), receiveTimeout: const Duration(seconds: 15), sendTimeout: const Duration(seconds: 15), validateStatus: (status) status ! null status 500, headers: { Content-Type: application/json, }, ), ); dio.interceptors.addAll([ LoggingInterceptor(), AuthInterceptor(), ErrorInterceptor(), ]); } }几个参数我解释一下为什么这么填connectTimeout是建立连接的最大等待时间10 秒足够覆盖大部分网络环境。如果用户在高铁或电梯里这个时间已经偏长但作为通用配置 10 秒是合理区间。receiveTimeout和sendTimeout是数据读写超时15 秒。这两个值取决于业务接口的耗时如果你们有报表导出这类慢接口单独给那个请求设置receiveTimeout会更合适。validateStatus是很多人会忽略的配置。Dio 默认只有 HTTP 状态码在 200-299 之间才走成功回调但很多项目的后端业务层约定是HTTP 200 代表请求被处理了业务是否成功要看返回体里的 code。如果状态码 500 直接走失败分支业务层拿到的错误信息就不完整。我这里设置的是 500 以下都走成功分支业务成功与否在拦截器里根据code再判断。这里还有一个点用单例而不是每次Dio()新建一是为了复用底层连接二是让拦截器只挂载一次避免页面之间反复初始化造成内存浪费。3.2 用一个 ApiResponse 模型统一三端返回后端接口的返回格式如果很混乱跨端那简直是灾难。我一般会在网络层建一个统一的返回模型不管你后端是{code: 0, data: {}, message: ok}还是{status: 200, result: {}}都先把它映射成同一个结构class ApiResponseT { final int code; final String message; final T? data; bool get isSuccess code 0; ApiResponse({ required this.code, required this.message, this.data, }); factory ApiResponse.fromJson( MapString, dynamic json, { required T Function(MapString, dynamic)? fromData, }) { return ApiResponse( code: json[code] as int? ?? -1, message: json[message] as String? ?? , data: fromData ! null ? fromData(json[data] as MapString, dynamic) : null, ); } }这个模型不是为了炫技而是解决跨端项目里最烦人的一个问题三端对业务错误的处理逻辑不一致。iOS 可能拿到message直接弹 toastAndroid 可能要根据code做跳转如果没有统一模型同样一段业务逻辑要在三端写三次。统一模型的价值在于把判断收敛到一处。页面层只根据isSuccess判断成败失败时拿message展示即可。后续如果要接错误上报也只需要在拦截器里统一接一遍不需要改页面。3.3 四个拦截器的分工与实现拦截器是 Dio 的灵魂但真正用得好的项目不多。我按实际需求封装了四个各有各的职责第一个是日志拦截器。只在 debug 模式打印请求方法、完整 URL、请求头、请求体、响应状态和耗时release 模式直接跳过。这既方便开发期定位问题也防止线上日志泄露用户敏感参数。class LoggingInterceptor extends Interceptor { override void onRequest(RequestOptions options, RequestInterceptorHandler handler) { if (kDebugMode) { print(-- ${options.method} ${options.uri}); print(headers: ${options.headers}); print(queryParameters: ${options.queryParameters}); } handler.next(options); } override void onResponse(Response response, ResponseInterceptorHandler handler) { if (kDebugMode) { final data response.data; final details data is String ? data : jsonEncode(data); print(-- ${response.statusCode} ${response.requestOptions.uri}); print(body: $details); } handler.next(response); } override void onError(DioException err, ErrorInterceptorHandler handler) { if (kDebugMode) { print(X-- ${err.type} ${err.requestOptions.uri}); print(error: ${err.message}); } handler.next(err); } }第二个是鉴权拦截器。统一从配置中心读取 token注入Authorization头。这样业务代码不用关心 token 从哪来刷新 token 的时候也只改拦截器内部逻辑class AuthInterceptor extends Interceptor { override void onRequest(RequestOptions options, RequestInterceptorHandler handler) { final token UserStore.instance.token; if (token.isNotEmpty) { options.headers[Authorization] Bearer $token; } handler.next(options); } }第三个是错误拦截器。Dio 抛出的DioException类型很多连接超时、DNS 解析失败、连接拒绝、超时响应、未知错误如果让页面各自判断页面代码会膨胀。我在拦截器里把错误统一翻译成用户能理解的文案比如网络连接超时请检查网络、服务器开了小差请稍后重试class ErrorInterceptor extends Interceptor { override void onError(DioException err, ErrorInterceptorHandler handler) { final message switch (err.type) { DioExceptionType.connectionTimeout 连接超时请检查网络, DioExceptionType.receiveTimeout 服务器响应超时, DioExceptionType.sendTimeout 发送请求超时, DioExceptionType.connectionError 无法连接到服务器, DioExceptionType.badResponse 服务异常${err.response?.statusCode ?? }, _ 网络请求失败, }; err err.copyWith(message: message); handler.next(err); } }第四个是重试拦截器。注意重试不是一个无脑操作。只有 GET 请求和幂等的 POST 请求才能安全重试否则可能出现重复下单这样的严重问题。实现思路是如果请求失败且操作幂等、且重试次数小于阈值等待一段时间后重新发起。等待时间用指数退避第一次等 1 秒第二次等 2 秒第三次等 4 秒。3.4 Token 过期与刷新先给一个够用的版本商用项目里 token 过期是必然事件。很多初学方案是在错误拦截器里判断 401然后重新登录跳到登录页。这对用户体验来说很粗暴。更好的方案是401 时先刷新 token刷新成功则自动重放之前的请求刷新失败再踢到登录页。简化版的思路是这样的AuthInterceptor里判断响应状态码是 401则触发刷新流程刷新流程用一把锁保证并发请求只触发一次刷新刷新期间的请求先挂起等待刷新完成再重放刷新 token 的请求本身也用 Dio但必须使用不带AuthInterceptor的独立实例防止递归。damn 这个方案听起来不复杂但实现细节挺多。考虑到标题是简单的网络请求架构我建议第一版先做401 自动重放一次就够用了不用把所有并发场景都处理到位。等业务量起来了再上锁和请求队列。3.5 上传下载场景的 Dio 参数上传文件用FormData下载文件用download方法这两个场景在鸿蒙上也经常用到。因为鸿蒙设备的文件系统路径跟 Android 有差异推荐下载路径统一通过path_provider获取应用沙盒目录而不是硬编码/storage/emulated/0/这类路径。final formData FormData.fromMap({ file: await MultipartFile.fromFile(filePath), remark: cover, }); final response await dio.post(/upload, data: formData, onSendProgress: (sent, total) { final progress sent / total; // 更新进度条 }, ); await dio.download( /download/file.zip, savePath, onReceiveProgress: (received, total) { final progress received / total; }, );大文件用MultipartFile.fromFile而不是fromBytes前者直接流式读取后者会把文件全量读进内存大文件直接 OOM。这个坑在鸿蒙和 Android 上是一样的但很多同学在 PC 端开发时不在意真机一跑大文件就崩。4. 鸿蒙特有问题排查实录4.1 权限声明到位了请求还是失败我遇到过最诡异的一次问题INTERNET权限加了network_config.json也配了结果请求照样失败。当时排查过程记录一下第一步先检查是不是证书问题。我临时把请求地址从https换成http再试如果能通说明就是 TLS 证书校验的问题。第二步检查设备当前网络类型。鸿蒙设备在 Wi-Fi 下和移动数据下的表现有时候不一致特别是公司网络做了出口限制的Wi-Fi 下所有请求都会失败切到手机热点就正常。第三步检查应用权限状态。鸿蒙的运行时权限管理系统在部分版本上对网络权限有额外的状态管理去系统设置的应用权限里确认应用的网络权限是允许状态。大多数情况到第三步就解决了。如果还不行就重启设备吧这属于鸿蒙系统层的偶发问题跟 Flutter 和 Dio 都没有关系。4.2 明文 HTTP 被拒Android 能跑、鸿蒙报错这个现象很典型。你在 Android 上开发时后端用的是http://192.168.1.10:8080一切正常。切到鸿蒙上直接报错而且错误信息是类似Unhandled Exception: DioException [connection error]后面跟着SocketException: Connection refused。第一步排查方向应该是后端 IP 是否可达。从鸿蒙设备上用浏览器访问同一个http://地址如果浏览器能打开说明网络通浏览器打不开就要回去看network_config.json的cleartext-traffic-permitted是不是没设置对。这里也体现了一个好的习惯跨端联调时接口尽早切到 HTTPSHTTPS 能过滤掉一大半平台差异问题。4.3 抓包调试与自签名证书的攻防鸿蒙上调试网络请求最痛苦的地方在于你想用抓包工具看请求内容系统却不信任抓包工具的证书请求直接失败。这其实是安全机制在正常工作。开发阶段我的做法是在 Dio 里临时允许未校验的证书dio.httpClientAdapter IOHttpClientAdapter( createHttpClient: () { final client HttpClient() ..badCertificateCallback (cert, host, port) true; return client; }, );badCertificateCallback直接返回true等于信任所有证书只用来在开发环境方便抓包排查。发布版本必须把这段代码移除。我见过有人把它留着上线了结果应用的所有请求都能被中间人截获用户数据等于裸奔。有两点经验上线前全局搜索一下badCertificateCallback确保没有漏网的放行逻辑测试用的自签名证书更好的做法是把根证书预置到鸿蒙信任列表里不走代码放行。这样既能抓包调试又不引入代码逻辑漏洞。4.4 弱网断线重连与请求取消最后说一下跟用户感知最相关的场景弱网和页面销毁。弱网环境下一个请求可能十几秒不返回用户等得不耐烦。除了设置合理的超时时间我还建议在RetryInterceptor里加上重试逻辑。但重试不是盲目重试要给接口定义一个幂等标记。我一般是约定 GET 请求天然幂等POST 请求默认不重试只有后端明确说明可以重试的才加白名单。页面销毁场景最典型的是用户点击了某个按钮进入加载页等了一会儿返回上个页面结果网络回调在页面销毁后才执行setState 直接抛异常。Dio 的CancelToken就是干这个的final cancelToken CancelToken(); // 页面销毁时调用 override void dispose() { cancelToken.cancel(页面已销毁); super.dispose(); } final response await dio.get(/user/info, cancelToken: cancelToken);CancelToken本质上是一个可以被外部触发的开关。调用cancel方法后被这个 token 绑定的所有请求都会被取消Dio 会抛一个DioException你在ErrorInterceptor里识别到DioExceptionType.cancel就直接吞掉不弹任何提示。这样既能防止状态更新泄漏又能提升用户体验。另外在鸿蒙上做网络切换监听目前connectivity_plus的鸿蒙适配已经能用可以监听网络切换事件网络恢复时自动重拉数据。最后再分享一个调试技巧如果你是用社区维护的 Flutter 鸿蒙 SDK 在跑项目建议所有网络排查都遵循一个顺序先用 HTTPS 的公开接口比如https://www.baidu.com验证 Dio 本身能用再切到自己的后端接口。这个顺序能帮你二选一快速定位问题是鸿蒙系统策略拦截了请求还是你后端接口的证书、地址有兼容性问题。我自己的体会是Flutter 鸿蒙适配里代码层面的工作量其实不大真正花时间的都是这些系统参数的排列组合。网络层从一开始就做好统一封装把权限、证书、超时、错误处理的标准定下来等鸿蒙系统版本迭代的时候你大概率只需要改一个配置文件。另外一个实用小经验鸿蒙设备上真机调试时localhost不会指向你电脑。需要用adb reverse或者直接请求电脑的局域网 IP。这个点和 Android 早期很像但文档里写得少很多新手会卡在这一步。如果你的请求目标是http://localhost:8080恭喜八成就是这个问题。