feature-next-arch/docs/ERROR_HANDLING_BEST_PRACTICE.md

Flutter 项目统一错误处理规范

核心原则

所有接口异常都不应该影响页面展示，只显示友好提示弹窗（2秒后自动消失）

实现方案

1. Cubit/Bloc 层处理

✅ 正确做法

class MyCubit extends Cubit<MyState> {
  Future<void> fetchData() async {
    try {
      emit(state.copyWith(isLoading: true));
      
      final result = await useCase.call(params);
      
      result.fold(
        (failure) {
          // 🔥 设置错误信息 + 标记需要显示弹窗
          emit(state.copyWith(
            isLoading: false,
            errorMessage: ErrorHandler.getErrorMessage(failure.message),
            shouldShowError: true, // 关键！
          ));
        },
        (data) {
          emit(state.copyWith(
            isLoading: false,
            data: data,
          ));
        },
      );
    } catch (e) {
      // 🔥 捕获所有异常
      emit(state.copyWith(
        isLoading: false,
        errorMessage: ErrorHandler.getErrorMessage(e),
        shouldShowError: true, // 关键！
      ));
    }
  }
}

❌ 错误做法

// ❌ 不要抛出异常到页面层
throw Exception('网络错误');

// ❌ 不要显示原始错误信息
emit(state.copyWith(errorMessage: e.toString()));

// ❌ 不要让页面崩溃
if (error) throw error;

2. State 设计

class MyState extends Equatable {
  final bool isLoading;
  final String? errorMessage;
  final bool shouldShowError; // 🔥 关键字段
  
  const MyState({
    this.isLoading = false,
    this.errorMessage,
    this.shouldShowError = false, // 默认 false
  });
  
  MyState copyWith({
    bool? isLoading,
    String? errorMessage,
    bool? shouldShowError,
  }) {
    return MyState(
      isLoading: isLoading ?? this.isLoading,
      errorMessage: errorMessage,
      shouldShowError: shouldShowError ?? false, // 🔥 默认重置为 false
    );
  }
}

关键点：

• shouldShowError 默认为 false
• 每次 emit 时如果不传，会自动重置为 false
• 这样可以确保错误弹窗只显示一次

3. 页面层监听

BlocConsumer<MyCubit, MyState>(
  listener: (context, state) {
    // 🔥 自动显示错误弹窗
    if (state.shouldShowError && state.errorMessage != null) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(
          content: Text(state.errorMessage!),
          backgroundColor: Colors.orange,
          duration: const Duration(seconds: 2),
          behavior: SnackBarBehavior.floating,
        ),
      );
    }
  },
  builder: (context, state) {
    // 页面正常渲染，不受错误影响
    if (state.isLoading) {
      return const CircularProgressIndicator();
    }
    
    return YourContent();
  },
)

4. ErrorHandler 工具类

import 'package:dio/dio.dart';
import 'package:flutter/material.dart';

class ErrorHandler {
  /// 获取友好的错误消息
  static String getErrorMessage(Object error) {
    if (error is DioException) {
      switch (error.type) {
        case DioExceptionType.connectionTimeout:
        case DioExceptionType.sendTimeout:
        case DioExceptionType.receiveTimeout:
          return '网络连接超时，请检查网络设置';
        
        case DioExceptionType.connectionError:
          return '网络连接失败，请检查网络';
        
        case DioExceptionType.badResponse:
          final statusCode = error.response?.statusCode;
          if (statusCode == 401) {
            return '登录已过期，请重新登录';
          } else if (statusCode == 403) {
            return '没有权限执行此操作';
          } else if (statusCode == 404) {
            return '请求的资源不存在';
          } else if (statusCode == 500) {
            return '服务器异常，请稍后重试';
          } else {
            return '服务器响应异常';
          }
        
        default:
          return '请求失败，请稍后重试';
      }
    } else {
      return '操作失败，请稍后重试';
    }
  }
}

完整示例

DeviceTaskCubit 示例

class DeviceTaskCubit extends Cubit<DeviceTaskState> {
  Future<void> cancelTask(String deviceId) async {
    final taskId = state.currentTaskId;
    if (taskId == null) {
      emit(state.copyWith(errorMessage: '无可用任务'));
      return;
    }

    emit(state.copyWith(
      isLoading: true,
      operationType: DeviceTaskOperationType.cancel,
    ));

    try {
      final result = await _cancelTaskUseCase.call(params);
      
      result.fold(
        (failure) {
          _logger.logWithLevel('❌ 取消任务失败: ${failure.message}');
          emit(state.copyWith(
            isLoading: false,
            errorMessage: ErrorHandler.getErrorMessage(failure.message),
            operationType: DeviceTaskOperationType.none,
            shouldShowError: true, // 🔥 标记需要显示弹窗
          ));
        },
        (success) {
          _logger.logWithLevel('✅ 取消任务成功');
          emit(state.copyWith(
            isLoading: false,
            operationType: DeviceTaskOperationType.none,
          ));
        },
      );
    } catch (e) {
      _logger.logWithLevel('❌ 取消任务异常: $e');
      emit(state.copyWith(
        isLoading: false,
        errorMessage: ErrorHandler.getErrorMessage(e),
        operationType: DeviceTaskOperationType.none,
        shouldShowError: true, // 🔥 标记需要显示弹窗
      ));
    }
  }
}

页面使用示例

class TaskPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocProvider(
      create: (_) => GetIt.I<DeviceTaskCubit>(),
      child: Scaffold(
        appBar: AppBar(title: const Text('任务管理')),
        body: BlocConsumer<DeviceTaskCubit, DeviceTaskState>(
          listener: (context, state) {
            // 🔥 自动显示错误弹窗
            if (state.shouldShowError && state.errorMessage != null) {
              ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(
                  content: Text(state.errorMessage!),
                  backgroundColor: Colors.orange,
                  duration: const Duration(seconds: 2),
                ),
              );
            }
          },
          builder: (context, state) {
            return Column(
              children: [
                // 页面内容不受错误影响
                Text('当前任务ID: ${state.currentTaskId ?? "无"}'),
                
                ElevatedButton(
                  onPressed: () {
                    context.read<DeviceTaskCubit>().cancelTask(deviceId);
                  },
                  child: const Text('取消任务'),
                ),
                
                if (state.isLoading)
                  const CircularProgressIndicator(),
              ],
            );
          },
        ),
      ),
    );
  }
}

错误提示文案规范

错误类型	提示文案
网络超时	"网络连接超时，请检查网络设置"
连接失败	"网络连接失败，请检查网络"
401 未授权	"登录已过期，请重新登录"
403 禁止访问	"没有权限执行此操作"
404 资源不存在	"请求的资源不存在"
500 服务器错误	"服务器异常，请稍后重试"
其他业务错误	"操作失败，请稍后重试"
未知错误	"未知错误，请稍后重试"

注意：

• ✅ 使用友好的中文提示
• ❌ 不要显示 HTTP 状态码
• ❌ 不要显示技术术语（如 "DioException"、"timeout"）
• ❌ 不要显示完整的错误堆栈

优势

1. 页面不崩溃 - 所有异常都被捕获
2. 用户体验好 - 友好的中文提示
3. 自动消失 - 2秒后弹窗自动关闭
4. 不影响操作 - 用户可以继续使用页面
5. 统一规范 - 全项目统一的错误处理方式

检查清单

在开发新功能时，确保：

• Cubit 中所有 try-catch 都使用了 ErrorHandler.getErrorMessage()
• State 中有 shouldShowError 字段
• 错误时设置 shouldShowError: true
• copyWith 中 shouldShowError 默认为 false
• 页面 BlocConsumer listener 中监听 shouldShowError
• 使用 SnackBar 显示错误（2秒自动消失）
• 不显示原始错误信息