前言移动应用的本质是数据消费——从服务器获取数据、提交表单、上传文件这一切都依赖 HTTP 网络请求。HarmonyOS 提供了ohos.net.http模块封装了完整的 HTTP 客户端能力支持 GET/POST 等常见方法、自定义请求头、超时控制、响应解析等核心功能。相比 Web 端的fetch/XMLHttpRequestHarmonyOS 的 HTTP 模块采用了更接近原生网络栈的设计——createHttp()创建请求任务、request()发起请求、destroy()释放资源。这种显式的生命周期管理让开发者对网络连接有更精细的控制。本文通过一个可交互的API 请求调试器Demo深入讲解ohos.net.http的全部核心 API涵盖请求配置、响应处理、错误捕获和资源释放。导入与基础概念ohos.net.http从kit.NetworkKit导入模块核心是http命名空间下的三个关键元素import{http}fromkit.NetworkKit;元素类型说明http.createHttp()函数创建 HTTP 请求任务实例http.HttpRequest接口请求任务对象提供request、destroy等方法http.HttpResponse接口响应对象包含result、responseCode、headercreateHttp() —— 创建请求任务一切 HTTP 请求的起点是createHttp()它返回一个HttpRequest实例lethttpRequest:http.HttpRequesthttp.createHttp();每个HttpRequest实例代表一个独立的网络任务。多次调用createHttp()会创建多个互不干扰的任务实例可以并发发送多个请求。创建实例后必须在使用完毕后调用destroy()释放底层 socket 等系统资源否则会造成资源泄漏。HttpRequest.request() —— 发送请求基础用法GET 请求lethttpRequesthttp.createHttp();letresponse:http.HttpResponseawaithttpRequest.request(https://api.example.com/data);httpRequest.destroy();不带options参数时默认使用 GET 方法。返回的HttpResponse对象包含完整的响应数据。完整配置指定方法和请求头lethttpRequesthttp.createHttp();letoptions:http.HttpRequestOptions{method:http.RequestMethod.GET,connectTimeout:10000,readTimeout:10000,header:{Content-Type:application/json,User-Agent:HarmonyOS-App/1.0}};letresponse:http.HttpResponseawaithttpRequest.request(url,options);HttpRequestOptions 详细参数HttpRequestOptions接口提供了丰富的请求配置选项interfaceHttpRequestOptions{method?:RequestMethod;// 请求方法默认 GETheader?:Object;// 自定义请求头extraData?:string|Object|ArrayBuffer;// POST 请求体connectTimeout?:number;// 连接超时毫秒默认 60000readTimeout?:number;// 读取超时毫秒默认 60000expectDataType?:HttpDataType;// 期望的响应数据类型usingProtocol?:HttpProtocol;// 协议类型HTTP/1.1 或 HTTP/2.0usingCache?:boolean;// 是否使用缓存priority?:number;// 请求优先级 0-10multiFormDataList?:MultiFormData[];// 多表单数据certificatePinning?:CertificatePinning;// 证书锁定dnsPrefetch?:string[];// DNS 预解析clientCert?:ClientCert;// 客户端证书}RequestMethod 枚举enumRequestMethod{OPTIONSOPTIONS,GETGET,HEADHEAD,POSTPOST,PUTPUT,DELETEDELETE,TRACETRACE,CONNECTCONNECT}POST 请求发送 POST 请求需要设置method和extraDatalethttpRequesthttp.createHttp();letoptions:http.HttpRequestOptions{method:http.RequestMethod.POST,header:{Content-Type:application/json},extraData:JSON.stringify({title:foo,body:bar,userId:1})};letresponseawaithttpRequest.request(https://jsonplaceholder.typicode.com/posts,options);httpRequest.destroy();extraData支持三种数据类型string纯文本或 JSON 字符串ObjectJavaScript 对象框架会自动序列化ArrayBuffer二进制数据适合上传文件超时控制connectTimeout控制建立 TCP 连接的最大等待时间readTimeout控制等待服务器响应的最大时间。两者都应合理设置——太短会导致慢网络环境下请求频繁失败太长会让用户等待过久。letoptions:http.HttpRequestOptions{connectTimeout:5000,// 连接超时 5 秒readTimeout:15000// 读取超时 15 秒};对于需要快速响应的接口如搜索建议可以设置更短的超时对于上传大文件的接口应该设置更长的超时。HttpResponse —— 响应处理响应字段interfaceHttpResponse{result:string|Object|ArrayBuffer;// 响应体resultType:HttpDataType;// 响应体类型标识responseCode:number;// HTTP 状态码header:Object;// 响应头cookies:string;// Cookie 字符串}响应体的三种数据类型result的类型由expectDataType控制enumHttpDataType{STRING0,// 字符串默认OBJECT1,// JSON 对象ARRAY_BUFFER2// 二进制数据}字符串STRING最常见的情况API 返回 JSON 文本时使用。直接用JSON.parse()解析if(typeofresponse.resultstring){letdataJSON.parse(response.resultasstring);}对象OBJECT设置expectDataType: http.HttpDataType.OBJECT后框架自动将 JSON 响应解析为对象。通过下标访问字段letoptions:http.HttpRequestOptions{expectDataType:http.HttpDataType.OBJECT};letresponseawaithttpRequest.request(url,options);letresult:Objectresponse.result;letuserId(resultasRecordstring,Object)[userId];二进制ARRAY_BUFFER适合下载图片、文件等二进制数据。结合util.TextDecoder可以转回文本import{util}fromkit.ArkTS;if(response.resultinstanceofArrayBuffer){letdecoderutil.TextDecoder.create(utf-8);lettextdecoder.decodeWithStream(newUint8Array(response.resultasArrayBuffer),undefined);}状态码检查responseCode是 HTTP 标准状态码200 表示成功2xx 系列均表示成功4xx 表示客户端错误5xx 表示服务器错误。if(response.responseCode200){// 成功}elseif(response.responseCode400){// 错误处理}注意HTTP 层面的错误如 404、500不会抛出异常request()仍然正常返回HttpResponse只是responseCode不是 2xx。只有网络层面的错误如 DNS 解析失败、连接超时、TLS 握手失败才会通过异常抛出。响应头解析response.header是一个键值对对象通过下标访问letheader:Objectresponse.header;letcontentType(headerasRecordstring,string)[content-type];letserver(headerasRecordstring,string)[server];HttpRequest.destroy() —— 资源释放这是最重要的 API 之一但开发者经常忽略。每个HttpRequest实例持有底层 socket 连接不及时destroy()会导致内存泄漏——未释放的 socket 占用内存连接耗尽——系统文件描述符有限泄露过多会导致新请求失败性能退化——后台积累的僵尸连接影响网络栈性能最佳实践在try-finally中确保始终调用destroy()asyncfunctionfetchData(url:string):Promisehttp.HttpResponse|null{lethttpRequest:http.HttpRequest|nullnull;try{httpRequesthttp.createHttp();letresponseawaithttpRequest.request(url);returnresponse;}catch(err){console.error(请求失败);returnnull;}finally{if(httpRequest){httpRequest.destroy();}}}on(‘headersReceive’) —— 响应头事件在请求过程中可以在request()之前注册headersReceive事件监听器在服务器返回响应头但响应体尚未接收完毕时触发lethttpRequesthttp.createHttp();httpRequest.on(headersReceive,(header:Object){console.info(收到响应头);letcontentType(headerasRecordstring,string)[content-type];});letresponseawaithttpRequest.request(url);httpRequest.destroy();这个事件在以下场景非常有用根据content-type提前决定如何解析响应体根据content-length计算下载进度记录请求耗时在事件中计算与请求开始的时间差错误处理HTTP 模块的异常分为两类1. 网络层异常抛出错误以下情况会通过catch捕获try{letresponseawaithttpRequest.request(url);}catch(err){leterrObjerrasObject;letrecerrObjasRecordstring,Object;letmessagerec[message]asstring;// 常见错误信息// - Couldnt resolve host name → DNS 解析失败// - Timeout was reached → 超时// - SSL certificate problem → TLS 证书问题// - Failed to connect to → 服务器不可达}2. HTTP 层错误正常响应4xx 和 5xx 状态码不会抛出异常需要检查responseCodeletresponseawaithttpRequest.request(url);if(response.responseCode200response.responseCode300){// 成功处理}elseif(response.responseCode404){// 资源不存在}elseif(response.responseCode500){// 服务器错误}性能与安全建议1. 实例复用同一个域名下的多次请求可以复用HttpRequest实例底层会复用 TCP 连接HTTP Keep-Alive// 推荐复用同一个实例lethttpRequesthttp.createHttp();for(leturlofurls){letresponseawaithttpRequest.request(url);}httpRequest.destroy();// 不推荐每次都创建新实例浪费连接for(leturlofurls){letreqhttp.createHttp();letresponseawaitreq.request(url);req.destroy();}2. HTTPS 证书安全生产环境应当严格验证 HTTPS 证书。HarmonyOS 默认启用系统 CA 证书库验证这是最安全的配置。开发阶段如果遇到自签名证书可以在测试环境使用以下配置但绝对不能用于生产环境// 仅开发调试用切勿在生产代码中使用letoptions:http.HttpRequestOptions{remoteValidation:skip// 跳过证书验证危险};3. DNS 预解析对于已知的目标域名可以在应用启动时预解析 DNS减少首次请求的延迟letoptions:http.HttpRequestOptions{dnsPrefetch:[api.example.com,cdn.example.com]};4. 请求优先级当同时发起多个请求时可以设置优先级让重要请求优先获得网络资源letoptions:http.HttpRequestOptions{priority:5// 0最低到 10最高};DemoAPI 请求调试器我们构建了一个完整的 HTTP 请求调试工具可以在真机或模拟器上实际发送网络请求并查看响应。功能模块URL 输入与快捷 API输入任意 URL或点击预设的 3 个 JSONPlaceholder API 快速填充GET/POST 方法切换可视化按钮切换GET 蓝色、POST 粉色发送请求与加载状态按钮在请求中显示请求中…并禁用防止重复发送响应摘要卡片展示状态码绿色2xx红色错误橙色其他、请求方法、耗时响应头显示解析并显示前 10 个响应头响应体预览等宽字体、可滚动文本框超过 2000 字符自动截断并标注完整长度请求历史记录最近 15 条请求的序号、方法、URL、状态码和时间核心发送逻辑asyncsendRequest():Promisevoid{this.isLoadingtrue;letstartTime:numberDate.now();lethttpRequest:http.HttpRequest|nullnull;try{httpRequesthttp.createHttp();letoptions:http.HttpRequestOptions{method:this.methods[this.methodIndex]POST?http.RequestMethod.POST:http.RequestMethod.GET,connectTimeout:10000,readTimeout:10000,header:{Content-Type:application/json,User-Agent:HarmonyOS-HttpDemo/1.0}};letresponse:http.HttpResponseawaithttpRequest.request(this.urlInput.trim(),options);letelapsed:numberDate.now()-startTime;this.statusCoderesponse.responseCode.toString();this.responseTimeelapsedms;// 解析响应体if(typeofresponse.resultstring){this.responseBodyresponse.resultasstring;}elseif(response.resultinstanceofArrayBuffer){letdecoderutil.TextDecoder.create(utf-8);this.responseBodydecoder.decodeWithStream(newUint8Array(response.resultasArrayBuffer),undefined);}else{this.responseBodyJSON.stringify(response.result);}// 解析响应头if(response.header){lethdr:Objectresponse.header;letheaderStr:string;letkeys:string[]Object.keys(hdr);for(leti0;iMath.min(keys.length,10);i){headerStrkeys[i]: (hdrasRecordstring,string)[keys[i]]\n;}this.responseHeadersheaderStr;}this.addHistory(this.methods[this.methodIndex],this.urlInput.trim(),response.responseCode.toString());}catch(err){this.statusCodeERROR;letrec:Recordstring,ObjecterrasRecordstring,Object;this.responseBody错误: (rec[message]asstring);this.addHistory(this.methods[this.methodIndex],this.urlInput.trim(),FAIL);}finally{if(httpRequest){httpRequest.destroy();}this.isLoadingfalse;}}请求历史管理使用不可变状态更新模式维护最近 15 条记录addHistory(method:string,url:string,status:string):void{this.historyIndex;letrecordnewRequestRecord(this.historyIndex,method,url,status,newDate().toLocaleTimeString());letnewHistory:RequestRecord[][record].concat(this.history);if(newHistory.length15){newHistory.pop();}this.historynewHistory;}注意事项Demo 使用的jsonplaceholder.typicode.com是一个公开的测试 API返回模拟数据。在实际应用开发中你需要申请网络权限在module.json5中添加ohos.permission.INTERNET配置网络安全生产环境使用 HTTPS开发调试可在module.json5中配置networkSecurity处理大响应Demo 截断 2000 字符以上的响应实际应用中应流式处理大文件下载总结本文详细讲解了 HarmonyOSohos.net.http模块的核心 APIcreateHttp()— 创建请求任务返回 HttpRequest 实例HttpRequest.request()— 发送请求支持 GET/POST 等方法、自定义请求头、超时控制HttpResponse— 响应处理支持字符串/对象/二进制三种数据类型HttpRequest.destroy()— 资源释放务必在请求完成后调用on(‘headersReceive’)— 响应头事件提前获取元数据错误处理— 区分网络层异常catch和 HTTP 层错误responseCodeHarmonyOS 的 HTTP 模块提供了完整的网络请求能力其 API 设计强调显式资源管理通过createHttp/destroy配对确保不泄露系统资源。结合 Promise 异步模型可以写出清晰、可维护的网络层代码。API 请求调试器 Demo 是一个实用的开发工具不仅展示 HTTP 模块的使用方式本身也可以用于日常调试第三方 API 接口。