HarmonyOS @kit.NetworkKit 的 http 用法详解

HarmonyOS @kit.NetworkKit 的 http 用法详解

@kit.NetworkKit的http是鸿蒙官方网络模块,零依赖、直接 import 就能用。本章整理http.createHttp()的完整用法、各种请求场景(GET / POST JSON / POST 表单 / GET 带 query)、Promise 链式调用、错误处理、资源释放。

最小可运行示例

import{http}from'@kit.NetworkKit'// 1. 创建请求实例lethttpRequest=http.createHttp()// 2. 发请求httpRequest.request('http://192.168.0.126:8080/goods/select',{method:http.RequestMethod.GET}).then(resp=>{// 3. 成功回调if(resp.responseCode===200){console.log('返回数据:',resp.result.toString())}}).catch((err:Error)=>{// 4. 失败回调console.error('网络错误:',err.message)}).finally(()=>{// 5. 释放资源 (必须做)httpRequest.destroy()})

request 方法的参数

httpRequest.request(url:string,options:{method?:http.RequestMethod// GET / POST / PUT / DELETE / ...header?:Object// 请求头(自定义 Content-Type / Authorization 等)extraData?:string|ArrayBuffer// 请求体(POST / PUT 才需要)expectDataType?:http.HttpDataType// 期望响应类型,影响 resp.result 的类型connectTimeout?:number// 连接超时毫秒,默认 60000readTimeout?:number// 读取超时毫秒,默认 60000usingCache?:boolean// 是否使用缓存,默认 true})

最常用的就是method+header+extraData三个。

http.RequestMethod 枚举

响应对象 resp 的结构

{responseCode:number// HTTP 状态码: 200 / 404 / 500 等result:string|ArrayBuffer|Object// 响应体resultType:http.HttpDataType// 响应体的实际类型header:Object// 响应头cookies:string// 响应 Cookie}

场景 1: GET 请求(无参数)

最简单的场景,直接拼 URL 即可。

functiongetList(){lethttpRequest=http.createHttp()httpRequest.request('http://192.168.0.126:8080/goods/select',{method:http.RequestMethod.GET}).then(resp=>{if(resp.responseCode===200){// 后端返回 JSON 数组 → 反序列化 + 类型断言constlist=JSON.parse(resp.result.toString())asGoods[]console.log('数据条数:',list.length)}}).finally(()=>httpRequest.destroy())}

场景 2: GET 请求带 query 参数

ArkTS 的 http 模块不会自动拼接 query 参数,需要自己拼到 URL 后面。

functiondeleteById(id:number){lethttpRequest=http.createHttp()httpRequest.request(`${BASE_URL}/goods/delete?id=${id}`,{method:http.RequestMethod.GET}).then(resp=>{/* ... */}).finally(()=>httpRequest.destroy())}

多个参数时:

constparams=`?name=${encodeURIComponent(name)}&page=${page}&size=${size}`httpRequest.request(`${BASE_URL}/goods/search${params}`,{...})

必须encodeURIComponent包含中文、空格、特殊字符的参数,否则 URL 会出问题。简单的纯数字 / 英文 id 可以省略。

场景 3: POST 请求 + JSON body

RESTful 接口最主流的写法。三个关键参数:method/header/extraData。

functioninsertGoods(name:string,price:number,desc:string,image:string){lethttpRequest=http.createHttp()httpRequest.request(`${BASE_URL}/goods/insert`,{method:http.RequestMethod.POST,header:{'Content-Type':'application/json'},extraData:JSON.stringify({name,price,desc,image})}).then(resp=>{if(resp.responseCode===200){console.log('插入成功')}}).catch((err:Error)=>{console.error('网络错误:',err.message)}).finally(()=>httpRequest.destroy())}

关键点:

Spring Boot 的@RequestBody Goods goods注解默认只解析 JSON,所以前端 Content-Type 必须是application/json才能正确反序列化。

场景 4: POST 请求 + 表单数据

如果后端用@RequestParam而不是@RequestBody,前端要发表单格式:

httpRequest.request(`${BASE_URL}/user/login`,{method:http.RequestMethod.POST,header:{'Content-Type':'application/x-www-form-urlencoded'},extraData:`username=${encodeURIComponent(username)}&password=${encodeURIComponent(password)}`})

数据格式是key1=value1&key2=value2,和 query 字符串一样。

场景 5: 加请求头(Authorization / Token 等)

httpRequest.request(url,{method:http.RequestMethod.GET,header:{'Content-Type':'application/json','Authorization':`Bearer${token}`,// JWT 鉴权'X-Custom-Header':'some-value'// 任意自定义头}})

场景 6: 设置超时

默认连接和读取都是 60 秒,实际开发中通常调短一点:

httpRequest.request(url,{method:http.RequestMethod.GET,connectTimeout:5000,// 5 秒连不上就失败readTimeout:10000// 10 秒没读完就失败})

链式调用结构

整个请求的标准结构:

httpRequest.request(url,options).then(resp=>{// 处理响应if(resp.responseCode===200){// 成功路径}else{// HTTP 状态码非 200(如 404 / 500)}}).catch((err:Error)=>{// 网络层失败(连接失败 / 超时 / DNS 解析失败 等)// 注意:HTTP 状态码 404 / 500 不会进 catch,而是进 then 的 else 分支}).finally(()=>{httpRequest.destroy()})

关键差异:HTTP 状态码不等于成功。只要服务器返回了响应,哪怕是 500,都会进 then。所以必须在 then 里手动判断responseCode === 200。

为什么必须 destroy()

http.createHttp()创建的实例底层持有 socket / 内存 / 文件描述符等资源。如果不destroy():

• 单次请求看不出问题
• 但频繁创建不释放(比如列表刷新调几十次) → 资源泄漏 → 应用变卡 → 最终可能崩溃

最佳实践:用.finally()保证无论成功失败都调用destroy()。

.finally(()=>{httpRequest.destroy()})

完整封装(整合后端 CRUD 的常用模式)

constBASE_URL='http://192.168.0.126:8080'// 通用 GETfunctionhttpGet(path:string):Promise<string>{returnnewPromise((resolve,reject)=>{letreq=http.createHttp()req.request(`${BASE_URL}${path}`,{method:http.RequestMethod.GET}).then(resp=>{if(resp.responseCode===200){resolve(resp.result.toString())}else{reject(newError(`HTTP${resp.responseCode}`))}}).catch(reject).finally(()=>req.destroy())})}// 通用 POST JSONfunctionhttpPostJson(path:string,body:object):Promise<string>{returnnewPromise((resolve,reject)=>{letreq=http.createHttp()req.request(`${BASE_URL}${path}`,{method:http.RequestMethod.POST,header:{'Content-Type':'application/json'},extraData:JSON.stringify(body)}).then(resp=>{if(resp.responseCode===200){resolve(resp.result.toString())}else{reject(newError(`HTTP${resp.responseCode}`))}}).catch(reject).finally(()=>req.destroy())})}// 调用asyncfunctionloadAndInsert(){try{constlistText=awaithttpGet('/goods/select')constlist=JSON.parse(listText)asGoods[]awaithttpPostJson('/goods/insert',{name:'新商品',price:999,desc:'测试',image:'xm17'})}catch(e){console.error(e)}}

学习项目可以不封装,直接用裸 API;但如果接口数量大于 5 个就建议封装,避免每个调用点都重复写 createHttp + destroy。

常见错误对照表

不止 http: rcp 模块更新更现代

鸿蒙还有一个@hms.collaboration.rcp模块(Remote Communication Kit),API 更现代(支持拦截器、自动 JSON、流式传输)。但是:

• 需要 API 12+
• 学习曲线比 http 高
• 当前学习项目用 http 已经够了

如果以后要做正式项目、需要拦截器统一加 token / 统一错误处理,再考虑迁移到 rcp。