Skip to main content

Conch API 详细文档

1. 核心 API​

1.1 runAppWrapper - 应用启动包装器​

1.1.1 功能概述​

runAppWrapper 是 Conch SDK 的核心启动方法，用于包装 Flutter 应用的启动流程，自动处理补丁加载、应用初始化和全局异常捕获。

1.1.2 工作流程​

  1. 异常处理器安装：在 runZonedGuarded 内安装全局异常处理器，捕获三类异常：

    • Flutter 框架同步异常（FlutterError.onError）
    • 引擎异步异常（PlatformDispatcher.instance.onError）
    • Zone 兜底异常（runZonedGuarded 的 onError）

  2. 初始化阶段：自动完成 SDK 初始化，设置配置参数和回调

  3. 补丁处理：依据配置相应加载补丁

  4. 应用启动：调用 appBuilder() 构建根 Widget，并通过 runApp() 启动应用

1.1.3 函数签名​

static void runAppWrapper(
  ConchParams params, {
  required FutureOr<Widget> Function() appBuilder,
  PatchInstallCallback? patchInstallCallback,
  PatchLoadCallback? patchLoadCallback,
  AppErrorHandlingConfig errorConfig = const AppErrorHandlingConfig(),
})

1.1.4 参数说明​

ConchParams 参数详解​
参数名类型必填说明
appIdString是应用唯一标识，从 Shiply 平台获取
appKeyString是在 Shiply 发布平台获取，需与平台配置一致，用于安全校验
moduleNameString是模块名称，与 Shiply 平台一致
appVersionString是应用版本号，用于补丁下发时版本匹配
envString否环境标识，默认为 "online" 正式环境
deviceIdString否设备标识，用于灰度发布、体验名单

注意： appId、appKey、moduleName 必须与 Shiply 平台配置完全一致，否则无法拉取到对应补丁。

runAppWrapper 参数详解​
参数名类型必填默认值说明
paramsConchParams是-Conch 运行时配置参数，包含 appId、appKey、moduleName 等关键信息
appBuilderFutureOr<Widget> Function()是-App 根 Widget 构建器，支持同步返回 Widget 或异步返回 Future<Widget>。补丁加载完成后会调用此函数构建根 Widget
patchInstallCallbackPatchInstallCallback?否null补丁安装完成回调，返回 PatchInstallResult 对象，包含安装结果码、版本号等信息
patchLoadCallbackPatchLoadCallback?否null补丁加载完成回调，返回 PatchLoadResult 对象，包含加载结果码、模块名、版本号等信息
errorConfigAppErrorHandlingConfig否const AppErrorHandlingConfig()应用级异常捕获与处理配置，用于自定义三类异常的处理逻辑
errorConfig 参数详解​

errorConfig 是 AppErrorHandlingConfig 类型对象，用于配置应用级的异常处理策略：

class AppErrorHandlingConfig {
  /// Flutter 框架同步异常处理器
  /// 返回值：true 表示已处理，阻止异常继续传播；false 表示未处理，交由系统默认处理器
  final bool Function(FlutterErrorDetails details)? onFlutterError;
  
  /// 引擎异步异常处理器
  /// 返回值：true 表示已处理，阻止异常继续传播；false 表示未处理，交由系统默认处理器
  final bool Function(Object error, StackTrace stackTrace)? onPlatformError;
  
  /// Zone 兜底异常处理器
  /// 返回值：true 表示已处理，阻止异常继续传播；false 表示未处理，转发到父 Zone
  final bool Function(Object error, StackTrace stackTrace)? onZonedError;
}

异常处理流程：

  1. Conch 先记录异常（用于补丁安全模式管理）
  2. 调用业务方配置的回调函数
  3. 根据回调返回值决定是否继续传播异常

返回值：

  • 类型：void
  • 说明：无返回值。该方法内部会调用 runApp() 启动应用，因此不需要在外部再次调用 runApp()

1.1.5 使用示例​

基础用法（无异常处理）​
void main() {
  ConchLoaderAPI.runAppWrapper(
    params,
    appBuilder: () => const MyApp(),
    patchInstallCallback: (result) {
      print('补丁安装结果: ${result.resultCode}');
    },
    patchLoadCallback: (result) {
      print('补丁加载结果: ${result.resultCode}');
    },
  );
}
完整用法（含异常处理）​
void main() {
  ConchLoaderAPI.runAppWrapper(
    params,
    appBuilder: () => const MyApp(),
    patchInstallCallback: (result) {
      print('补丁安装结果: ${result.resultCode}');
    },
    patchLoadCallback: (result) {
      print('补丁加载结果: ${result.resultCode}');
    },
    errorConfig: AppErrorHandlingConfig(
      // 处理 Flutter 框架同步异常
      onFlutterError: (FlutterErrorDetails details) {
        // 记录异常到监控系统
        Crashlytics.recordFlutterError(details);
        
        // 显示用户友好的错误提示
        if (isCriticalError(details.exception)) {
          showErrorDialog(details.exception.toString());
          return true; // 阻止默认红屏显示
        }
        
        return false; // 让系统继续处理
      },
      
      // 处理引擎异步异常
      onPlatformError: (Object error, StackTrace stack) {
        // 上报异常
        Crashlytics.recordError(error, stack);
        
        // 特殊异常处理
        if (error is NetworkException) {
          showNetworkErrorToast();
          return true;
        }
        
        return false;
      },
      
      // 处理 Zone 兜底异常
      onZonedError: (Object error, StackTrace stackTrace) {
        debugPrint('应用发生未处理异常: $error');
        
        // 紧急恢复策略
        if (shouldRestartApp(error)) {
          restartApp();
          return true;
        }
        
        return false;
      },
    ),
  );
}

1.1.6 注意事项​

  • 无需调用 runApp()：runAppWrapper 内部会自动调用 runApp()，因此不要在外部再次调用
  • 异常处理返回值：errorConfig 中的回调函数返回值非常重要：
    • true：表示业务已处理，Conch 将终止异常传播
    • false：表示业务未处理，Conch 将继续交由原有处理器
  • Debug 模式限制：Conch 补丁功能仅在 Release 模式下生效，但异常处理在 Debug 模式下也会生效
  • 防御性编程：在 errorConfig 回调内部也要做好异常捕获，避免处理器本身抛出异常

1.2 requestPatch - 补丁请求接口​

1.2.1 功能概述​

仅从服务器拉取补丁并安装到本地，不加载到运行时环境。

1.2.2 函数签名​

static Future<PatchInstallResult> requestPatch()

1.2.3 核心特性​

  • 纯网络操作：只下载和解密补丁到本地，不加载到运行时
  • 异步执行：不阻塞主线程，适合后台执行
  • 独立调用：可在任意时机调用，不依赖应用启动流程
  • 预下载：提前下载补丁，冷启动后加载

返回值： 类型：Future<PatchInstallResult>

PatchInstallResult 对象包含：

  • resultCode：安装状态码（SUCCESS、FETCH_NO_PATCH、NOT_INIT、INSTALL_FAIL 等）
  • moduleName：模块名称
  • version：补丁版本号
  • taskId：任务 ID

1.2.4 使用示例​

// 后台预下载补丁（不阻塞主流程）
ConchLoaderAPI.requestPatch().then((result) {
  if (result.resultCode == PatchInstallResultCode.SUCCESS) {
    print('补丁下载成功，已安装到本地: ${result.version}');
  } else {
    print('补丁安装失败或无可用补丁: ${result.resultCode}');
  }
});

1.2.5 注意事项​

  • 该方法只负责下载和安装补丁，不会加载补丁到运行时
  • 下载的补丁会在下次应用启动时自动加载

1.3 queryPatchLoadResult - 补丁加载状态查询​

1.3.1 功能概述​

同步查询当前补丁的加载结果，不触发任何加载流程。

1.3.2 函数签名​

static PatchLoadResult? queryPatchLoadResult()

1.3.3 核心特性​

  • 纯查询操作：不会触发网络请求或补丁加载

返回值 类型：PatchLoadResult?

返回值说明：

  • 非 null：包含当前补丁加载状态
    • resultCode：加载状态码（SUCCESS、NO_PATCH、PATCH_LOAD_FAIL 等）
    • moduleName：模块名称
    • version：补丁版本号
    • taskId：任务 ID
  • null：以下情况会返回 null
    • 补丁尚未开始加载或补丁加载流程未完成

1.3.4 使用示例​

// 基础用法
final result = ConchLoaderAPI.queryPatchLoadResult();
if (result != null) {
  if (result.resultCode == PatchLoadResultCode.SUCCESS) {
    print('当前已加载补丁版本: ${result.version}');
  } else {
    print('补丁未加载或加载失败: ${result.resultCode}');
  }
} else {
  print('SDK 未初始化、补丁尚未开始加载或加载流程未完成');
}

// 在业务逻辑中使用
Widget build(BuildContext context) {
  final patchResult = ConchLoaderAPI.queryPatchLoadResult();
  final version = patchResult?.version ?? '未知';
  
  return Text('当前补丁版本: $version');
}

1.3.5 注意事项​

  • 该方法为同步方法,不会阻塞线程
  • 仅查询状态,不会改变任何运行时状态
  • 建议在应用启动完成后调用

2. 安全模式设置接口​

Conch SDK 提供了一套安全模式机制,用于自动检测和拦截异常补丁,保障应用稳定性。通过以下接口可以配置安全模式的行为参数。

版本要求

此功能在 SDK 1.7.2 及以上版本可用。

2.1 核心概念​

安全模式工作原理:

  • 异常检测窗口:从应用启动开始计算的时间范围,只有在此窗口内发生的异常才会被计入
  • 异常计数:记录补丁在检测窗口内的连续异常次数(一次成功会重置计数)
  • 成功计数:记录补丁连续成功运行的次数(一次异常会重置计数)
  • 标记为不安全:当连续异常次数达到阈值时,该补丁将被标记为不安全并禁止加载
  • 标记为安全:当连续成功次数达到阈值时,该补丁将被标记为安全,不会进入安全模式

2.2 接口列表​

setMarkPatchUnsafeThreshold - 设置补丁异常次数阈值​

功能说明：

  • 设置触发安全模式的补丁连续异常次数阈值
  • 当连续异常次数达到阈值时，该补丁将被标记为不安全并禁止加载

函数签名：

static bool setMarkPatchUnsafeThreshold(int threshold)

参数说明： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | threshold | int | 是 | 补丁连续异常次数阈值，必须 >= 1 |

返回值：

  • true：设置成功
  • false：设置失败（threshold < 1）

使用示例：

// 设置连续异常次数阈值为 5 次
bool success = ConchLoaderAPI.setMarkPatchUnsafeThreshold(5);
if (success) {
  print('异常阈值设置成功');
}

setMarkPatchSafeThreshold - 设置补丁连续成功次数阈值​

功能说明：

  • 设置补丁连续成功次数阈值
  • 当补丁连续成功次数达到阈值时，该补丁将被标记为安全，安全模式将默认通过加载该补丁，不拦截

函数签名：

static bool setMarkPatchSafeThreshold(int threshold)

参数说明： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | threshold | int | 是 | 补丁连续成功次数阈值，必须 >= 1 |

返回值：

  • true：设置成功
  • false：设置失败（threshold < 1）

使用示例：

// 设置连续成功次数阈值为 10 次
bool success = ConchLoaderAPI.setMarkPatchSafeThreshold(10);
if (success) {
  print('安全阈值设置成功');
}

setSafeModeWindowSeconds - 设置安全模式检测窗口时间​

功能说明：

  • 设置安全模式 APP 检测窗口时间（秒）
  • 该方法用于配置安全模式下的异常检测时间窗口，即从 APP 启动开始计算的时间范围
  • 只有在此时间窗口内发生的异常才会被计入安全模式的异常计数

函数签名：

static bool setSafeModeWindowSeconds(int windowSeconds)

参数说明： | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | windowSeconds | int | 是 | 时间窗口（秒），取值范围 [1, 60] |

返回值：

  • true：设置成功
  • false：设置失败（windowSeconds 不在 [1, 60] 范围内）

使用示例：

// 设置检测窗口为 5 秒
bool success = ConchLoaderAPI.setSafeModeWindowSeconds(5);
if (success) {
  print('检测窗口设置成功');
}

getSafeModeWindowSeconds - 获取安全模式检测窗口时间​

功能说明：

  • 获取当前设置的安全模式 APP 检测窗口时间（秒）

函数签名：

static int getSafeModeWindowSeconds()

返回值：

  • 安全模式 APP 检测窗口时间（秒）

使用示例：

int windowSeconds = ConchLoaderAPI.getSafeModeWindowSeconds();
print('当前检测窗口: $windowSeconds 秒');

getMarkPatchSafeThreshold - 获取补丁连续成功次数阈值​

功能说明：

  • 获取当前设置的补丁连续成功次数阈值

函数签名：

static int getMarkPatchSafeThreshold()

返回值：

  • 补丁连续成功次数阈值

使用示例：

int threshold = ConchLoaderAPI.getMarkPatchSafeThreshold();
print('当前安全阈值: $threshold 次');

getMarkPatchUnsafeThreshold - 获取补丁异常次数阈值​

功能说明：

  • 获取当前设置的补丁异常次数阈值

函数签名：

static int getMarkPatchUnsafeThreshold()

返回值：

  • 补丁连续异常次数阈值

使用示例：

int threshold = ConchLoaderAPI.getMarkPatchUnsafeThreshold();
print('当前连续异常阈值: $threshold 次');

2.3 完整配置示例​

void main() {
  // 配置安全模式参数(建议在 runAppWrapper 之前调用)
  ConchLoaderAPI.setMarkPatchUnsafeThreshold(5);  // 连续异常 5 次后标记为不安全
  ConchLoaderAPI.setMarkPatchSafeThreshold(10);   // 连续成功 10 次后标记为安全
  ConchLoaderAPI.setSafeModeWindowSeconds(5);     // 检测窗口 5 秒  
  // 启动应用
  ConchLoaderAPI.runAppWrapper(
    params,
    appBuilder: () => const MyApp(),
    errorConfig: AppErrorHandlingConfig(
      onFlutterError: (details) {
        // 业务异常处理逻辑
        return false;
      },
    ),
  );
}

2.4 注意事项​

  • 调用时机：建议在 runAppWrapper 之前调用安全模式配置接口
  • 默认值：如果不调用配置接口，系统会使用默认值：
    • 连续异常次数阈值：3 次
    • 连续成功次数阈值：5 次
    • 检测窗口时间：3 秒
  • Release 模式生效：安全模式仅在 Release 模式下生效，Debug 模式下不会进行补丁拦截
  • 持久化存储：安全模式的计数器会持久化存储，应用重启后仍然有效
  • 补丁更新：当补丁版本更新（MD5 变化）时，计数器会自动重置
这篇文档对您有帮助吗？
监控定位
智能低代码
跨平台框架
全场景发布
应用合规
Copyright © 1998 - 2024 Tencent. All Rights Reserved.
服务协议
隐私保护声明
腾讯公司版权所有主体备案号粤B2-20090059