HarmonyOS 6.0 利用 PAC 脚本实现网络代理管理

一个典型的 PAC 脚本示例

假设我们有一个内部网络 10.0.0.0/8 和公司内网域名 *.internal.company.com 需要直连，其他所有流量都通过代理 proxy.company.com:8080。PAC 脚本可以这样写：

function FindProxyForURL(url, host) {
    // 1. 如果是内部域名，直接连接
    if (dnsDomainIs(host, ".internal.company.com")) {
        return "DIRECT";
    }
    // 2. 如果是内部 IP 地址段 (10.0.0.0/8)，直接连接
    if (isInNet(host, "10.0.0.0", "255.0.0.0")) {
        return "DIRECT";
    }
    // 3. 其他所有请求，通过公司代理服务器
    // 可以配置多个备选代理以提高可用性
    return "PROXY proxy.company.com:8080; PROXY backup-proxy.company.com:8080; DIRECT";
}

代码解读:

• dnsDomainIs 和 isInNet 是 PAC 规范中内置的实用函数。
• host 参数可以是 IP 地址或域名，这些函数会智能地进行判断。
• 最后的返回值提供了两个代理地址作为备选，并在所有代理都不可用时回退到直连，保证了网络的健壮性。

实战演练：在鸿蒙应用中设置 PAC

接下来，我们通过一个完整的代码示例，演示如何在鸿蒙应用中使用 setPacFileUrl 接口。

场景设定

您的公司网络管理员提供了一个 PAC 文件，地址为 http://pac.company.com/config/proxy.pac。您的鸿蒙应用需要为整个应用设置这个 PAC 规则。

代码实现步骤

1. 导入必要的模块。
2. 调用 setPacFileUrl 接口。
3. 处理回调结果。

import { connection } from '@kit.NetworkKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct SetPacExample {
    // 定义 PAC 文件的 URL
    private pacUrl: string = 'http://pac.company.com/config/proxy.pac';

    build() {
        Column() {
            Button('设置公司 PAC 代理').onClick(() => {
                console.info(`开始设置 PAC URL: ${this.pacUrl}`);
                // 调用 API 设置 PAC 脚本 URL
                connection.setPacFileUrl(this.pacUrl, (error: BusinessError) => {
                    if (error) {
                        // 设置失败，打印错误信息
                        console.error(`设置 PAC 失败，错误码：${error.code}, 错误信息：${error.message}`);
                        // 可以根据错误码给用户友好的提示，例如：
                        // error.code === 201 表示权限校验失败
                        // error.code === 401 表示参数错误
                        // error.code === 2100001 可能是 URL 无效或无法访问
                    } else {
                        // 设置成功
                        console.info('PAC 脚本 URL 设置成功。代理规则已生效。');
                        // 可以在此处更新 UI，告知用户设置成功
                    }
                });
            }).margin(20).padding(10).fontSize(16).backgroundColor('#007DFF').fontColor(Color.White)
        }.width('100%').height('100%').justifyContent(FlexAlign.Center)
    }
}

代码详解

• 导入模块: 除了核心的 connection 模块，还导入了 BusinessError 以便更精确地处理错误类型。
• 接口调用: setPacFileUrl 的第一个参数是 PAC 文件的 URL 字符串，第二个参数是异步回调函数。
• 回调处理:
  • error 参数为 null 表示操作成功，PAC 设置已应用。此后，应用发起的网络请求将遵循该 PAC 脚本的规则。
  • 如果 error 对象存在，则需要根据 error.code 判断具体原因，并进行相应的处理或提示用户。例如，可能是网络不可达导致无法下载 PAC 文件，也可能是 URL 格式不正确。

总结与最佳实践

鸿蒙 connection.setPacFileUrl 接口为开发者提供了一个强大而灵活的工具，用于实现自动化的代理配置。其主要优势在于：

1. 动态性: 代理规则集中存储在服务器端，修改 PAC 文件即可实时更新所有客户端的代理策略，无需更新应用。
2. 灵活性: 通过 JavaScript 脚本，可以实现基于目标 URL、主机名、IP 段、甚至日期时间的复杂路由逻辑。
3. 易用性: 系统封装了 PAC 文件的下载、解析和函数调用过程，开发者只需提供一个 URL 即可。

开发建议

• PAC 文件的可靠性: 确保 PAC 文件的 URL 稳定、高速可达。如果 PAC 文件无法下载，系统可能无法正确代理网络请求。
• 脚本性能: PAC 脚本会在每次网络请求前执行，因此脚本逻辑应尽量简洁高效，避免复杂的循环或耗时的操作，以免影响网络性能。
• 错误处理: 务必在应用中妥善处理 setPacFileUrl 的回调，特别是网络错误场景，并给予用户适当的反馈。
• 权限声明: 使用此功能需要在 module.json5 文件中声明 ohos.permission.INTERNET 权限。

通过合理运用 PAC 脚本，鸿蒙应用能够智能地适应各种复杂的网络环境，为用户提供无缝且高效的上网体验。