1
// _sendAndAwaitResponse：前置条件检查
2
if (_status != WsStatus.connected) {
3
  throw Exception('WebSocket 未连接');
4
}
5

6
// uploadFile：文件存在性检查
7
final file = File(filePath);
8
if (!await file.exists()) {
9
  throw Exception('文件不存在: $filePath');
10
}
11

12
// uploadFile：服务端返回异常
13
if (uploadId == null || uploadId.isEmpty) {
14
  throw Exception('服务器未返回 upload_id（请确认 Host 已更新并重启）');
15
}
16

17
// _normalizeServerUrl：格式校验
18
if (uri == null || uri.host.isEmpty) {
19
  throw const FormatException('无效地址');
20
}
21
if (uri.scheme != 'ws' && uri.scheme != 'wss') {
22
  throw const FormatException('仅支持 ws:// 或 wss://');
23
}

1
Map<String, dynamic> initResp;
2
try {
3
  initResp = await sendInit();
4
} catch (e) {
5
  final err = e.toString();
6
  if (err.contains('FILE_UPLOAD_INIT 请求超时')) {
7
    // 情况 1：是超时 → 重试一次
8
    debugPrint('[WS] FILE_UPLOAD_INIT 超时，正在重试一次...');
9
    try {
10
      initResp = await sendInit();
11
    } catch (_) {
12
      // 重试也失败 → 抛出更友好的错误信息
13
      throw Exception(
14
        '上传初始化超时：Host 未响应 FILE_UPLOAD_INIT。'
15
        '请检查 Host 是否已重启到最新代码。',
16
      );
17
    }
18
  } else {
19
    rethrow;  // 情况 2：不是超时 → 原样向上抛
20
    //         保留了原始异常的完整信息
21
  }
22
}

1
try {
2
  riskyCode();
3
} on FormatException catch (e) {
4
  // 捕获 FormatException，并获取异常对象 e
5
  print('格式错误: ${e.message}');
6
} on FormatException {
7
  // 捕获 FormatException，但不需要异常对象
8
  print('格式错误');
9
} on Exception catch (e, stackTrace) {
10
  // 捕获所有 Exception，获取异常和堆栈
11
  print('异常: $e\n$stackTrace');
12
} catch (e) {
13
  // 兜底捕获所有（包括 Error）
14
  print('未知: $e');
15
}

1
class AppException implements Exception {
2
  final String message;
3
  const AppException(this.message);
4

5
  @override
6
  String toString() => message;
7
}
8

9
class AuthException extends AppException {
10
  const AuthException(super.message);
11
}
12

13
class UploadException extends AppException {
14
  final String fileName;
15
  const UploadException(super.message, {required this.fileName});
16
}
17

18
// 分层捕获
19
try {
20
  await uploadFile(path);
21
} on UploadException catch (e) {
22
  print('上传 ${e.fileName} 失败: ${e.message}');
23
} on AuthException catch (e) {
24
  print('认证失败: ${e.message}');
25
} on AppException catch (e) {
26
  print('应用错误: ${e.message}');
27
}

1
// 1. 异常信息要有意义
2
throw Exception('文件不存在: $filePath');       // ✅ 包含上下文
3
// throw Exception('error');                    // ❌ 含义不清
4

5
// 2. 捕获具体类型
6
try { ... } on FormatException catch (e) { }   // ✅ 精确
7
// try { ... } catch (e) { }                   // ❌ 太宽泛
8

9
// 3. 用 rethrow 保留堆栈
10
catch (e) { cleanup(); rethrow; }              // ✅
11
// catch (e) { cleanup(); throw e; }           // ❌ 丢失堆栈
12

13
// 4. finally 做清理
14
try { ... } finally { resource.close(); }      // ✅
15

16
// 5. 前置条件检查（越早失败越好）
17
if (value == null) throw ArgumentError('value 不能为 null');

1
// 1. 不要吞掉异常（除非确实不需要处理）
2
try { ... } catch (e) { }                      // ❌ 异常被完全忽略
3

4
// 2. 不要用 catch 捕获 Error（应该修 bug）
5
try { ... } on RangeError catch (e) { }        // ❌ 越界是 bug，应该改代码
6

7
// 3. 不要用异常做流程控制
8
try {
9
  var value = list[index];
10
} on RangeError {
11
  value = defaultValue;                        // ❌ 应该先检查 index
12
}
13
// 正确做法：
14
var value = index < list.length ? list[index] : defaultValue;  // ✅
15

16
// 4. 不要在参数中 throw（虽然语法合法）
17
var name = getName() ?? (throw Exception('名字不能为空'));  // ❌ 可读性差

1
// bootstrap_service.dart 的启动流程
2
Future<void> start() async {
3
  // 每一步都做了错误处理
4
  final pythonOk = await _checkPythonAvailable();  // 内部 try-catch → 返回 bool
5
  if (!pythonOk) {
6
    _fail('未检测到 Python');           // ← 不崩溃，进入 failed 状态
7
    return;
8
  }
9

10
  final started = await _startAstrBot();           // 内部 try-catch → 返回 bool
11
  if (!started) {
12
    _fail('AstrBot 启动失败');
13
    return;
14
  }
15

16
  // ... 每一步都有对应的失败处理 ...
17
}