@bingtang-rn/react-native-dns-lookup for HarmonyOS

本项目基于 react-native-dns-lookup 开发，为 React Native 鸿蒙（OpenHarmony）适配版本。如果在使用过程中有任何问题，可以在GitCode提Issue，会及时跟进。issue地址：issues。

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 见发布记录 | 1.0.6 | 0.72+ | 是/否 | API17+ |

安装

npm install @bingtang-rn/react-native-dns-lookup

使用

import { getIpAddressesForHostname } from 'react-native-dns-lookup';

// 解析主机名到全部 IP 地址字符串数组
const ips = await getIpAddressesForHostname('github.com');
console.log(ips); // ['20.205.243.166', ...]

// 空串/非法主机名会 reject（BusinessError 含 code+message）
try {
  await getIpAddressesForHostname('');
} catch (e) {
  // code: 2100001, message: 'Invalid parameter value.'
}

import 时使用原库名 'react-native-dns-lookup'，鸿蒙侧由 RNOH alias 自动映射到 @bingtang-rn/react-native-dns-lookup，无需在业务代码中改包名。

平台差异：

• HarmonyOS 底层使用 Network Kit 的 connection.getAddressesByName（系统 DNS），返回的 NetAddress.address 已是数值化 IP 字符串，与原 Android InetAddress.getAllByName / iOS CFHost + getnameinfo(NI_NUMERICHOST) 行为对等。
• 错误以 BusinessError（含 code+message）reject 透传：空串 → 2100001（Invalid parameter value）；null/undefined → 401（Parameter error）；未声明 INTERNET → 201（Permission denied）；网络服务连接失败 → 2100002；系统内部错误 → 2100003。原两端是 generic Error/NSError，鸿蒙端错误信息更结构化。

权限要求：

• 需在 module.json5 的 requestPermissions 声明 ohos.permission.INTERNET（normal 级，安装时授予，无需运行时动态申请）。
• HAR 与宿主 App 均需声明（HAR 已内置声明，宿主 App 在自身 module.json5 声明即可）。

Link

| 版本 | 是否支持 Autolink | |------|------------------| | 当前版本 | 是/否 |

如使用版本支持 Autolink 且工程已接入，可跳过手动配置。

说明：本模块需要同时在 C++ 侧和 ETS 侧注册 Package。

1. Overrides RN SDK

在工程根目录 oh-package.json5 添加：

{
  "overrides": {
    "@rnoh/react-native-openharmony": "./react_native_openharmony"
  }
}

2. 引入原生端依赖

打开 entry/oh-package.json5，添加：

"dependencies": {
  "@bingtang-rn/react-native-dns-lookup": "file:../../node_modules/@bingtang-rn/react-native-dns-lookup/harmony/dns_lookup.har"
}

执行 ohpm install。

3. 配置 CMakeLists

打开 entry/src/main/cpp/CMakeLists.txt，添加：

set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

add_subdirectory("${OH_MODULES}/@bingtang-rn/react-native-dns-lookup/src/main/cpp" ./dns_lookup)

target_link_libraries(rnoh_app PUBLIC dns_lookup)

4. 注册 Package（C++ 侧）

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "DnsLookupPackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<DnsLookupPackage>(ctx),
    };
}

5. 注册 Package（ETS 侧）

打开 entry/src/main/ets/RNPackagesFactory.ets，添加：

import { DnsLookupPackage } from '@bingtang-rn/react-native-dns-lookup/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new DnsLookupPackage(ctx),
  ];
}

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | getIpAddressesForHostname(hostname) | 解析主机名到全部 IP 地址字符串数组 | hostname: string | Promise<ReadonlyArray<string>> | ✅ 完全支持 |

平台差异

• 错误码与原两端不同：HarmonyOS 以标准 BusinessError（code+message）reject，错误码为 201/401/2100001/2100002/2100003；原两端为通用 Error/NSError。功能行为对等（成功返回 IP 字符串数组，失败 reject）。
• 非空校验由系统 API 完成：空串 → 2100001，null/undefined → 401；原两端在 native 层显式 hostname == null 校验后 reject。效果对等，错误信息更结构化。

未实现功能

无。本库为单方法纯数据型 NativeModule，鸿蒙端 connection.getAddressesByName 在能力、返回结构、错误码、设备形态覆盖上与原两端完全等价或更优，所有公开能力均已实现。

使用限制

• 需声明 ohos.permission.INTERNET（normal 级，安装时授予）。
• 解析依赖系统默认网络与系统 DNS，设备需有可用网络连接；网络不可达或 DNS 服务异常时返回 2100002/2100003。

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18 | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 17+ |

运行步骤

1. 克隆仓库

git clone <仓库地址>
cd <仓库目录>

2. 安装依赖并构建

npm install --legacy-peer-deps
npm pack           # 生成 tgz 包（会自动触发 prepare 构建 JS 产物）

3. 进入 example 目录，安装依赖

cd example
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。

约束与限制

兼容性

• RNOH: 0.72+
• HarmonyOS SDK: API 17+
• DevEco Studio: 5.0+

遗留问题

无（或列出已知问题）

开源协议

本项目基于 MIT License，详见 LICENSE 文件。