快速开始

GitHub 仓库: https://github.com/worldsanshu/DynamicDomainSDK

前置要求

• Flutter SDK
• Go 1.21+ (用于编译核心库)
• Android Studio / Xcode

安装

在您的 pubspec.yaml 中通过 GitHub 仓库添加 dynamic_domain 依赖：

dependencies:
  dynamic_domain:
    git:
      url: https://github.com/worldsanshu/DynamicDomainSDK
      path: dynamic_domain

或者使用本地路径（如果您已下载源码）：

dependencies:
  dynamic_domain:
    path: ../dynamic_domain

基础用法

在 main.dart 中初始化 SDK：

import 'package:dynamic_domain/dynamic_domain.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // 1. 创建 SDK 实例
  final dynamicDomain = DynamicDomain();
  
  // 2. 初始化 (需要 App ID)
  // 注意：请联系客服 (@zhuanmitools) 获取您的专属 App ID
  final String appId = "your_app_id";
  await dynamicDomain.init(appId);
  
  // 3. 获取远程配置
  String config = await dynamicDomain.fetchRemoteConfig(appId);
  
  // 4. 启动隧道
  // 返回本地代理地址 (例如 "127.0.0.1:10809")
  String proxyUrl = await dynamicDomain.startTunnel(config);
  
  print("隧道已启动，代理地址: $proxyUrl");
  
  runApp(MyApp());
}

初始化成功并启动隧道后，您可以使用返回的 proxyUrl 来配置您的网络请求或 WebView。

最佳实践与注意事项

为了确保 SDK 的稳定运行和最佳性能，请遵循以下开发建议：

1. 避免并发冲突

SDK 的 init、startTunnel 和 stopTunnel 是状态敏感的操作。

• 不要并发调用：请确保同一时间只有一个初始化或启动操作在进行。SDK 内部已增加保护锁，如果检测到冲突会抛出 busy 异常。
• 顺序执行：始终遵循 init -> fetchRemoteConfig -> startTunnel 的顺序。

2. 异常处理与状态反馈

SDK 对账户状态进行了精细化分类。建议对启动流程进行完整的错误捕获，并根据错误码给用户提供明确的反馈：

try {
  await dynamicDomain.startTunnel(config);
} catch (e) {
  final errorMsg = e.toString();
  if (errorMsg.contains('40301')) {
    // 账户已被后台禁用
    print("应用已停用: 请联系管理员。");
  } else if (errorMsg.contains('40302')) {
    // 账户已过期
    print("应用已过期: 请及时续费。");
  } else if (errorMsg.contains('40303')) {
    // 流量超限
    print("流量已超限: 请升级套餐。");
  } else {
    print("隧道启动失败: $e");
  }
}

3. 流量监控 (Stats)

SDK 提供了实时的流量统计功能。您可以通过订阅 stats 流来展示当前的上传和下载流量：

// 订阅统计流
_statsSubscription = dynamicDomain.stats.listen((stats) {
  print("总上行: ${stats.totalUplink} 字节");
  print("总下行: ${stats.totalDownlink} 字节");
  
  // 也可以获取特定节点的统计 (如果配置了多个节点)
  // stats.nodeStats["node_tag"]...
});

// 记得在 dispose 时取消订阅
_statsSubscription?.cancel();

3. 资源管理

• 及时停止：如果 App 退出或不再需要代理，请调用 stopTunnel() 释放本地端口和原生资源。
• 保活建议：在 Android 上，SDK 已内置前台服务。如果您需要极高稳定性的长连接（如 IM），请确保在 Android Manifest 中正确配置了权限。

进阶集成

如果您正在使用第三方 SDK（如 OpenIM、Firebase 或其他原生 C++/Go 核心的库），建议阅读：

• OpenIM 集成指南 - 了解如何为长连接 IM 框架配置 SOCKS5 代理。
• WebView 代理集成 - 让您的 H5 页面也具备抗封锁能力。