跨平台开发 / 系统课时
统一转换网络错误信息
统一转换网络错误信息
网络请求失败时,底层库通常只会返回各种异常对象或响应错误信息,业务页面难以直接使用。本篇将实现统一错误转换层,把不同来源的网络异常整理为稳定的业务错误类型,方便提示、重试和日志处理。
学习目标
- 理解为什么需要网络错误统一转换层
- 掌握在 Flutter 中设计业务错误类型的方法
- 实现异常到业务错误对象的转换流程
为什么需要统一网络错误
Flutter 应用中的网络失败来源很多,例如没有网络连接、请求超时、服务器返回错误、接口数据格式异常等。如果页面直接依赖 HTTP 客户端抛出的异常类型,业务代码会被底层实现绑定。
统一错误转换的目标不是隐藏错误,而是在数据层和业务层之间建立稳定边界。数据层负责识别技术原因,业务层只处理用户真正关心的结果。
例如页面不需要知道请求失败来自 SocketException 还是 TimeoutException,它只需要知道当前属于“网络不可用”还是“请求超时”。
设计业务错误类型
一个常见做法是定义应用自己的错误类型,并保存必要信息:
- 面向用户展示的信息
- 是否允许自动重试
- 原始错误原因,便于日志定位
- 可选的状态码或错误编号
下面使用 Dart 定义一个简单的网络错误模型。
dart
class NetworkFailure implements Exception {
final String message;
final bool canRetry;
final int? statusCode;
final Object? cause;
const NetworkFailure({
required this.message,
required this.canRetry,
this.statusCode,
this.cause,
});
}预期结果
text
NetworkFailure 可以作为应用内部统一处理的错误对象。业务层收到这个对象后,不需要关心底层网络库使用的是 Dio、http 还是其他实现。
将底层异常转换为业务错误
转换函数通常放在数据源或 Repository 层,让错误在离开数据层前完成归一化。
dart
NetworkFailure mapNetworkError(Object error) {
if (error is TimeoutException) {
return NetworkFailure(
message: '请求超时,请稍后重试',
canRetry: true,
cause: error,
);
}
if (error is SocketException) {
return NetworkFailure(
message: '当前网络不可用',
canRetry: true,
cause: error,
);
}
return NetworkFailure(
message: '请求失败,请稍后再试',
canRetry: false,
cause: error,
);
}预期结果
text
TimeoutException 被转换为可重试错误。
SocketException 被转换为网络不可用错误。
未知异常被转换为通用失败错误。实际项目中,如果使用 HTTP 客户端返回的响应对象,还可以在转换函数中补充状态码和服务端错误编号。
统一错误转换的使用边界
错误转换层应该保留足够的信息用于排查问题,但不要把底层异常结构直接暴露给 UI。
推荐的数据流是:
网络库异常 → 数据层转换 → 业务错误类型 → 页面状态展示
这样更容易替换网络库,也能让多个页面共享一致的错误处理逻辑。
需要注意的是,业务错误不应该吞掉所有异常。未知错误仍应保留原始原因,方便通过日志系统定位真实问题。
按自己的节奏,确认真正理解。