鸿蒙新特性：@ohos.net.connection 网络连接诊断实验室实战 —— 网络检测、带宽查询与 DNS 解析

引言网络是移动应用的命脉。在开发中我们需要知道设备当前是否联网、连接的是 WiFi 还是蜂窝网络、带宽多少、DNS 解析是否正常。HarmonyOS NEXT 通过ohos.net.connection模块将这些网络诊断能力统一暴露为简洁的同步与异步 API大部分操作无需权限即可使用。ohos.net.connection属于kit.NetworkKit与 Android 的ConnectivityManager和 iOS 的NWPathMonitor定位类似但 API 设计更加直接——核心检测全部同步返回DNS 解析通过 Promise 异步完成没有复杂的事件订阅机制。本文将深入讲解ohos.net.connection的网络状态检测、带宽查询、承载类型识别和 DNS 域名解析四大核心能力并构建一个网络连接诊断实验室Demo在一个页面中完成网络诊断的全部操作。一、API 架构同步检测 异步解析1.1 核心设计理念ohos.net.connection的 API 分为两层同步层负责网络状态检测和能力查询——所有方法都带Sync后缀直接返回结果零延迟异步层负责 DNS 域名解析——通过 Promise 返回解析结果适合耗时网络操作。importconnectionfromohos.net.connection;// 同步瞬间返回无需 awaitconsthasNetconnection.hasDefaultNetSync();// booleanconstnetHandleconnection.getDefaultNetSync();// NetHandleconstcapsconnection.getNetCapabilitiesSync(netHandle);// NetCapabilities// 异步Promise 返回connection.getAddressesByName(www.example.com).then((addrs){/* ArrayNetAddress */}).catch((e){/* Error */});这种同步检测 异步解析的双层设计非常务实连接检测是高频操作每次网络请求前都需要判断同步 API 避免不必要的异步开销DNS 解析本身涉及网络 I/O异步 Promise 模型正合适。1.2 hasDefaultNetSync —— 网络连接检测hasDefaultNetSync()是网络诊断中最基础的 API。它同步返回一个boolean表示当前是否存在默认数据网络。这个方法无参数、无权限要求适合在任何地方调用。privaterefreshNetState():void{try{consthasNetconnection.hasDefaultNetSync();this.isConnectedhasNet;if(hasNet){// 有默认网络进一步获取详细信息constnetHandleconnection.getDefaultNetSync();constcapsconnection.getNetCapabilitiesSync(netHandle);// ... 读取带宽、承载类型等}else{// 无网络连接this.bearerType无连接;}}catch(e){this.isConnectedfalse;// 异常降级假设无网络}}关键点返回true仅表示系统存在默认数据网络路由不代表目标服务器可达配合ohos.net.http使用时hasDefaultNetSync()可以作为请求前的快速检查必须在 try/catch 中调用SDK 内部可能因系统服务异常而抛出错误1.3 getDefaultNetSync —— 获取默认网络句柄当hasDefaultNetSync()返回true时可以通过getDefaultNetSync()获取当前默认网络的NetHandle对象。NetHandle是一个不透明的网络句柄本身没有可读属性它的作用是为getNetCapabilitiesSync()提供参数。constnetHandleconnection.getDefaultNetSync();// netHandle 是一个 NetHandle 对象用于后续查询constcapsconnection.getNetCapabilitiesSync(netHandle);NetHandle的设计类似于文件描述符——它本身不暴露细节但可以作为钥匙打开对应的能力信息。1.4 getNetCapabilitiesSync —— 网络能力信息getNetCapabilitiesSync(netHandle)是网络诊断的核心 API。它接收一个NetHandle返回一个NetCapabilities对象包含当前网络的完整能力描述属性类型说明linkDownBandwidthKbpsnumber下行带宽kbps可能为 0 或 undefinedlinkUpBandwidthKbpsnumber上行带宽kbps可能为 0 或 undefinedbearerTypesArraynumber承载类型数组每个元素为 BearerType 枚举值注意linkDownBandwidthKbps和linkUpBandwidthKbps的值取决于底层网络驱动是否提供了带宽信息。在模拟器或某些网络环境下这两个值可能为 0 或 undefined需要做防御性处理。constcapsconnection.getNetCapabilitiesSync(netHandle);constdownBwcaps.linkDownBandwidthKbps;constupBwcaps.linkUpBandwidthKbps;// 防御性处理带宽值为空或 0 时显示占位符this.downBand(downBw!undefineddownBw0)?(downBw/1000).toFixed(1) Mbps:--;this.upBand(upBw!undefinedupBw0)?(upBw/1000).toFixed(1) Mbps:--;1.5 bearerTypes —— 承载类型识别bearerTypes是NetCapabilities中最实用的字段。它返回一个数字数组每个数字代表一种网络承载类型BearerType枚举值承载类型说明0WiFiIEEE 802.11 无线局域网1蜂窝网络4G/5G 移动网络2VPN虚拟专用网络3以太网有线网络连接一个网络连接可能同时具有多种承载类型例如 VPN over WiFi。在实际使用中bearerTypes[0]通常是主承载类型。privatebearerLabel(type:number):string{if(type0)returnWiFi;if(type1)return蜂窝网络;if(type2)returnVPN;if(type3)return以太网;return其他;}// 使用constbtcaps.bearerTypes;if(btbt.length0){this.bearerTypethis.bearerLabel(bt[0]asnumber);}else{this.bearerType未知;}二、DNS 域名解析2.1 getAddressesByName —— 异步 DNS 查询getAddressesByName(host: string)是ohos.net.connection提供的 DNS 解析 API。它接收一个域名字符串返回PromiseArrayNetAddress。每个NetAddress对象包含三个字段属性类型说明addressstringIP 地址字符串IPv4 或 IPv6 格式familynumber协议族1 IPv42 IPv6portnumber端口号DNS 查询中通常为 0privateresolveDNS():void{consthostthis.dnsHost.trim();if(host){this.addLog(请输入域名,error);return;}this.dnsLoadingtrue;this.dnsResult解析中...;connection.getAddressesByName(host).then((addrs:Arrayconnection.NetAddress){this.dnsLoadingfalse;if(addrs.length0){constipList:string[][];for(leti0;iaddrs.length;i){ipList.push(addrs[i].address);}this.dnsResultipList.join(\n);this.addLog(DNS: host → addrs.length.toString() 个地址,success);}else{this.dnsResult未解析到地址;this.addLog(DNS: host 无记录,system);}}).catch((e:Error){this.dnsLoadingfalse;this.dnsResult解析失败: e.message;this.addLog(DNS 失败: e.message,error);});}DNS 解析的完整流程用户输入域名如www.example.com调用getAddressesByName(host)发起系统级 DNS 查询系统返回所有解析到的 IP 地址可能有多个包括 IPv4 和 IPv6 地址遍历NetAddress数组提取address字段展示2.2 DNS 解析的实际意义在网络诊断场景中DNS 解析是判断网络是否真正可用的重要依据。hasDefaultNetSync()返回true只说明设备有网络连接而 DNS 解析成功才说明 DNS 服务器可达、域名可以正常解析。这两个检查配合使用可以准确定位网络问题hasDefaultNetSync() false → 设备无网络连接检查 WiFi/蜂窝开关hasDefaultNetSync() true 但 DNS 解析失败 → 网络已连接但 DNS 不通检查路由器/DNS 配置两者都正常 → 网络连通性良好三、实战 Demo网络连接诊断实验室3.1 页面设计网络连接诊断实验室页面分为五个功能区域连接状态卡片最上方展示当前网络连接状态绿色圆点 已连接或红色圆点 “未连接”右侧显示承载类型标签WiFi / 蜂窝网络 / VPN / 以太网。下方三栏卡片分别展示下行带宽、上行带宽和承载类型。网络操作区两个按钮——刷新网络状态重新读取当前网络信息检测连接调用hasDefaultNetSync()并在日志中输出结果。DNS 域名解析区文本输入框 解析按钮下方三个预设域名快捷按钮example.com、baidu.com、github.com点击后自动填入域名并执行解析。解析结果显示在底部灰色代码框中支持多行展示。API 能力说明区以灰色文字展示核心 API 的方法签名和功能说明帮助开发者快速了解模块能力。操作日志区按时间倒序记录所有操作不同类别success / error / system使用不同颜色标记。3.2 核心实现数据模型interfaceConnLog{time:string;msg:string;category:string;}StateisConnected:booleanfalse;StatebearerType:string--;StatedownBand:string--;StateupBand:string--;StatednsHost:stringwww.example.com;StatednsResult:string--;StatednsLoading:booleanfalse;Statelogs:ConnLog[][];状态设计要点isConnected控制连接状态的 UI 颜色和文字bearerType在三种场景下取值不同正常连接时显示承载标签无连接时显示无连接异常时显示–dnsLoading同时控制按钮文字和禁用状态防止重复点击logs使用ConnLog接口统一日志格式包含时间戳、消息内容和分类日志系统privateaddLog(msg:string,category:string):void{constnownewDate();consttsnow.getHours().toString().padStart(2,0):now.getMinutes().toString().padStart(2,0):now.getSeconds().toString().padStart(2,0);constentry:ConnLog{time:ts,msg:msg,category:category};constnewLogs:ConnLog[][entry];this.logsnewLogs.concat(this.logs).slice(0,30);}日志采用新在前、旧在后的顺序newLogs.concat(this.logs)最多保留 30 条记录。时间格式化为 HH:MM:SS 并补零对齐。日志颜色函数privatelogColor(cat:string):string{if(catsuccess)return#10B981;if(caterror)return#EF4444;return#64748B;}统计卡片 BuilderBuilderstatCard(label:string,value:string,color:string){Column(){Text(label).fontSize(10).fontColor(#94A3B8).margin({bottom:4})Text(value).fontSize(13).fontColor(color).fontWeight(FontWeight.Bold).fontFamily(monospace)}.alignItems(HorizontalAlign.Center).layoutWeight(1).padding({top:8,bottom:8}).backgroundColor(#F8FAFC).borderRadius(8).border({width:1,color:#E2E8F0}).margin({right:8})}3.3 交互方式Demo 提供三个核心交互点刷新网络状态单击按钮后重新执行refreshNetState()读取最新的网络连接状态、带宽数据和承载类型。适合在切换 WiFi / 移动网络后验证。检测连接直接调用hasDefaultNetSync()并输出结果到日志。这是一个最轻量的网络检查操作。DNS 域名解析输入域名后点击解析按钮或点击预设域名快捷按钮example.com / baidu.com / github.com直接触发解析。解析过程中按钮变为灰色解析中…并禁用防止重复提交。解析结果按行展示所有 IP 地址。四、实际应用场景4.1 网络请求前的连通性检查在发起 HTTP 请求前先用hasDefaultNetSync()判断网络状态避免无网络时发起注定失败的请求functionsafeHttpRequest(url:string):void{if(!connection.hasDefaultNetSync()){console.error(无网络连接取消请求);return;}// 发起 HTTP 请求consthttpRequesthttp.createHttp();httpRequest.request(url);}4.2 根据网络类型调整策略通过bearerTypes判断当前网络类型在 WiFi 下预加载高清资源在蜂窝网络下使用低质量资源functionshouldPreloadHD():boolean{try{constnetHandleconnection.getDefaultNetSync();constcapsconnection.getNetCapabilitiesSync(netHandle);constbtcaps.bearerTypes;// 仅 WiFi 或以太网下预加载高清资源returnbtbt.length0(bt[0]0||bt[0]3);}catch(e){returnfalse;// 异常时保守策略不预加载}}4.3 网络诊断工具构建一个完整的网络诊断函数依次检查连接状态、网络类型、DNS 解析interfaceNetDiagnosis{connected:boolean;bearerType:string;dnsResolved:boolean;dnsAddresses:string[];}asyncfunctionrunNetDiagnosis(host:string):PromiseNetDiagnosis{constresult:NetDiagnosis{connected:false,bearerType:未知,dnsResolved:false,dnsAddresses:[]};try{result.connectedconnection.hasDefaultNetSync();if(result.connected){consthandleconnection.getDefaultNetSync();constcapsconnection.getNetCapabilitiesSync(handle);if(caps.bearerTypescaps.bearerTypes.length0){result.bearerType[WiFi,蜂窝网络,VPN,以太网][caps.bearerTypes[0]]||其他;}constaddrsawaitconnection.getAddressesByName(host);result.dnsResolvedaddrs.length0;for(leti0;iaddrs.length;i){result.dnsAddresses.push(addrs[i].address);}}}catch(e){// 诊断失败返回默认值}returnresult;}五、与 ohos.net.http 的协作关系ohos.net.connection和ohos.net.http同属kit.NetworkKit两者职责分明、配合紧密模块职责典型 APIohos.net.connection网络状态检测、能力查询、DNS 解析hasDefaultNetSync, getNetCapabilitiesSync, getAddressesByNameohos.net.httpHTTP 请求发送、响应处理createHttp, request, HttpResponse协作模式// 1. 先检测网络状态if(!connection.hasDefaultNetSync()){showToast(网络未连接);return;}// 2. 可选根据网络类型调整请求策略constcapsconnection.getNetCapabilitiesSync(connection.getDefaultNetSync());// 3. 发起 HTTP 请求constreqhttp.createHttp();req.request(https://api.example.com/data,{method:http.RequestMethod.GET,connectTimeout:caps.bearerTypes?.[0]1?15000:5000// 蜂窝网络给更长超时});六、ArkTS 使用注意事项6.1 API 版本差异ohos.net.connection在 API 24 中提供的是精简版 API。实际可用的 API 包括hasDefaultNetSync()— 同步检测getDefaultNetSync()— 获取默认网络句柄getNetCapabilitiesSync(netHandle)— 获取网络能力getAddressesByName(host)— DNS 解析异步 Promise文档中可能提到的connection.on(netCapabilitiesChange)和connection.off(netCapabilitiesChange)事件订阅机制在当前 SDK 版本中不可用。如果需要持续监听网络状态变化应通过定时轮询hasDefaultNetSync()来实现。6.2 带宽值的防御性处理linkDownBandwidthKbps和linkUpBandwidthKbps在以下情况下可能为 0 或 undefined模拟器环境部分 VPN 连接驱动未提供带宽信息代码必须做空值判断constbwcaps.linkDownBandwidthKbps;constdisplay(bw!undefinedbw0)?(bw/1000).toFixed(1) Mbps:--;6.3 权限说明hasDefaultNetSync()和getDefaultNetSync()无权限要求getNetCapabilitiesSync()的带宽属性需要ohos.permission.GET_NETWORK_INFO权限缺省声明不影响编译getAddressesByName()需要ohos.permission.INTERNET权限七、总结ohos.net.connection是 HarmonyOS NEXT 中检测网络连接状态和执行 DNS 解析的核心模块。通过本文的学习你应该已经掌握同步检测模型hasDefaultNetSync()无参数无权限直接返回 boolean完成最基础的网络连通性判断网络能力查询getDefaultNetSync()getNetCapabilitiesSync()组合获取完整网络能力信息包括带宽linkDownBandwidthKbps/linkUpBandwidthKbps和承载类型bearerTypesWiFi/蜂窝/VPN/以太网DNS 域名解析getAddressesByName(host)异步 Promise 返回ArrayNetAddress支持 IPv4/IPv6 多地址解析防御性编程带宽值可能为空或 0承载类型数组可能为空——所有网络数据都需要做空值判断与 http 模块协作connection 负责检测网络状态和类型http 负责发起请求——两者同属kit.NetworkKit形成完整的网络通信栈ohos.net.connection的最佳使用模式可以总结为请求前用 hasDefaultNetSync 快速判断需要详情时用 getNetCapabilitiesSync 查询能力怀疑 DNS 问题时用 getAddressesByName 验证解析。所有 API 同步为主、异步为辅——简洁高效。网络连接状态是应用通信的基础。虽然ohos.net.connection的 API 数量不多但它与ohos.net.http的组合覆盖了从网络检测到数据通信的完整链路。在应用架构中为网络诊断保留一个标准化的检查流程是所有网络相关应用的必修课。ohos.net.connection属于kit.NetworkKit是 HarmonyOS NEXT 网络通信能力的基础模块。它的同步 API 零开销、异步 DNS 解析简洁高效相比 Android 的ConnectivityManager回调模式和 iOS 的NWPathMonitor异步监听ohos.net.connection的同步优先设计更符合先检测、再请求的直觉编程模型。