在鸿蒙NEXT中发起HTTP网络请求：从入门到精通

随着鸿蒙NEXT（HarmonyOS NEXT）的正式发布，其全新的开发体系和强大的能力吸引了众多开发者的目光。应用开发中，网络请求几乎是不可或缺的一环。本文将带你全面了解如何在鸿蒙NEXT中使用其官方的@kit.NetworkKit网络库，安全、高效地发起HTTP请求。

一、环境准备与权限配置

在开始编写代码之前，我们需要完成两步准备工作。

1. 导入NetworkKit

在项目的entry模块下的oh-package.json5文件中，添加@kit.NetworkKit依赖。

json5

复制

下载

复制代码

// entry/oh-package.json5
"dependencies": {
  "@kit.NetworkKit": "^1.0.0"
}

完成后，在终端中执行 ohpm install 命令来安装依赖。

2. 配置网络访问权限

在module.json5配置文件中，申请必要的网络权限。

json5

复制

下载

复制代码

// entry/module.json5
"module": {
  "requestPermissions": [
    {
      "name": "ohos.permission.INTERNET"
    }
  ]
}

注意：如果你的应用需要访问非HTTPS的明文HTTP链接，在API 10及更高版本中，还需要在应用根目录的 AppScope 下的 app.json5 中声明 network 安全配置。

json5

复制

下载

复制代码

// AppScope/app.json5
"app": {
  "bundleName": "com.yourcompany.yourapp",
  "network": {
    "cleartextTraffic": true // 允许HTTP明文流量
  }
  // ... 其他配置
}

二、发起一个简单的GET请求

让我们从一个最基础的例子开始：获取一个公开的API数据。

typescript

复制

下载

复制代码

// 导入NetworkKit
import { http } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 定义一个数据模型（根据API返回结构定义）
interface Post {
  userId: number;
  id: number;
  title: string;
  body: string;
}

async function fetchPostData(): Promise<void> {
  // 1. 创建请求对象
  let httpRequest = http.createHttp();

  // 2. 定义请求的URL
  let url = 'https://jsonplaceholder.typicode.com/posts/1';

  try {
    // 3. 发起GET请求
    let response = await httpRequest.request(
      url,
      {
        method: http.RequestMethod.GET, // 指定请求方法
        header: { // 设置请求头（可选）
          'Content-Type': 'application/json'
        }
      }
    );

    // 4. 检查请求是否成功 (状态码 200-299)
    if (response.responseCode === http.ResponseCode.OK) {
      // 5. 解析返回的JSON数据
      let result = response.result.toString();
      let post: Post = JSON.parse(result) as Post;
      console.info(`Fetch Success! Title: ${post.title}`);
      // 在这里更新你的UI，例如：this.postTitle = post.title;
    } else {
      console.error(`HTTP Error! Code: ${response.responseCode}, Message: ${response.result.toString()}`);
    }

  } catch (error) {
    // 6. 捕获并处理异常（网络错误、解析错误等）
    let err: BusinessError = error as BusinessError;
    console.error(`Request Failed! Code: ${err.code}, Message: ${err.message}`);
  } finally {
    // 7. 释放请求对象，防止内存泄漏
    httpRequest.destroy();
  }
}

// 在某个按钮点击事件或页面生命周期中调用
// fetchPostData();

代码解析：

创建对象 ：使用 http.createHttp() 创建一个HTTP请求实例。
配置请求 ：在 request 方法的第二个参数中，指定方法为 GET，并可以设置请求头。
异步处理 ：使用 async/await 语法处理异步请求，让代码更清晰。
结果检查 ：通过 response.responseCode 判断请求是否成功。
数据解析 ：将返回的字符串结果解析成我们定义的 Post 接口对象。
异常处理 ：使用 try-catch 捕获网络请求过程中可能出现的所有错误。
资源释放 ：最后在 finally 块中销毁请求对象，这是一个好习惯。

三、发起一个POST请求

向服务器提交数据同样简单。

typescript

复制

下载

复制代码

async function submitUserData(user: { name: string; email: string }): Promise<void> {
  let httpRequest = http.createHttp();
  let url = 'https://api.example.com/users';

  try {
    // 将JavaScript对象序列化为JSON字符串
    let data = JSON.stringify(user);

    let response = await httpRequest.request(
      url,
      {
        method: http.RequestMethod.POST,
        header: {
          'Content-Type': 'application/json', // 告诉服务器我们发送的是JSON
        },
        extraData: data // 请求体数据
      }
    );

    if (response.responseCode === http.ResponseCode.OK || response.responseCode === http.ResponseCode.CREATED) {
      console.info('User created successfully!');
      let responseData = response.result.toString();
      console.info(`Server Response: ${responseData}`);
    } else {
      console.error(`Submission Failed! Code: ${response.responseCode}`);
    }

  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error(`Request Failed! Code: ${err.code}, Message: ${err.message}`);
  } finally {
    httpRequest.destroy();
  }
}

// 使用示例
// submitUserData({ name: '张三', email: 'zhangsan@example.com' });

关键点：

方法：将 method 改为 http.RequestMethod.POST。
请求体 ：需要提交的数据通过 extraData 属性传递。
请求头 ：设置 'Content-Type': 'application/json' 至关重要，它确保了服务器能正确解析你发送的数据。

四、高级配置与最佳实践

1. 设置超时

为了避免请求无限期挂起，总是设置一个合理的超时时间。

typescript

复制

下载

复制代码

let response = await httpRequest.request(
  url,
  {
    method: http.RequestMethod.GET,
    connectTimeout: 10000, // 连接超时 10秒
    readTimeout: 10000,    // 读取超时 10秒
  }
);

2. 使用HTTP代理

如果你的网络环境需要，可以配置代理。

typescript

复制

下载

复制代码

let httpRequest = http.createHttp();
// 先销毁默认配置
httpRequest.destroy();
// 使用代理配置重新创建
let proxyInfo: http.HttpProxy = {
  host: '192.168.1.100',
  port: 8080,
  exclusionList: [] // 排除列表，这些地址不走代理
};
httpRequest = http.createHttp({ proxy: proxyInfo });

3. 安全建议

生产环境禁用明文HTTP ：除非万不得已，否则不要设置 cleartextTraffic: true。始终使用HTTPS来保护用户数据。
证书校验：鸿蒙默认会进行证书校验，确保通信安全。请不要轻易禁用证书校验功能。
敏感信息：不要在URL或日志中暴露API Key、Token等敏感信息。

五、总结

鸿蒙NEXT的@kit.NetworkKit提供了一个现代化、易于使用的HTTP客户端。其核心步骤可以概括为：

创建：http.createHttp()
配置：在 options 中设置方法、头、超时等。
发送：使用 request() 方法。
处理：检查状态码，解析结果。
清理：在 finally 中调用 destroy()。