How to Handle Errors the Right Way in Flutter: A Practical Guide to Sealed Classes, Records, and Result Types

Future<User> getUser(String userId) async {
  final response = await dio.get('/users/$userId');
  return User.fromJson(response.data);
}

// 不是这样 —— 可能会抛出异常
Future<User> getUser(String userId);

// 我们这样写 —— 始终返回一个结果
Future<Result<User>> getUser(String userId);

// result.dart

// sealed 表示所有可能的子类型都在这里定义。
// 编译器知道这里只有两种可能的结果 ——
// Success 和 Failure —— 没有其他可能性。
sealed class Result<T> {}

// Success 携带我们想要的值。
// T 是类型参数 —— Result<User> 表示
// Success 携带一个 User，Result<List<Post>> 携带一个列表。
class Success<T> extends Result<T> {
  final T data;
  const Success(this.data);
}

// Failure 携带一个 AppError，描述发生了什么错误。
// 我们使用一个类型化的错误类，而不是原始异常，
// 这样 UI 可以根据错误类型做出决策。
class Failure<T> extends Result<T> {
  final AppError error;
  const Failure(this.error);
}

// app_error.dart

// AppError 也是密封的 —— 所有我们应用程序可能产生的错误类型
// 都在这里定义。这使得无法出现未处理的错误类型。
sealed class AppError {}

// 没有网络连接
class NoInternetError extends AppError {}

// 服务器返回了错误响应
class ServerError extends AppError {
  final int statusCode;
  final String message;
  const ServerError({required this.statusCode, required this.message});
}

// 数据返回了意外的格式
class ParseError extends AppError {
  final String message;
  const ParseError(this.message);
}

// 发生了我们没有预料到的意外情况
class UnknownError extends AppError {
  final String message;
  const UnknownError(this.message);
}

// post_repository.dart

import 'dart:convert';
import 'package:http/http.dart' as http;
import 'package:dio/dio.dart';
import 'result.dart';
import 'app_error.dart';
import 'post.dart';

class PostRepository {
  final Dio _dio;
  PostRepository(this._dio);

  Future<Result<List<Post>>> getPosts() async {
    try {
      final response = await _dio.get(
        'https://jsonplaceholder.typicode.com/posts',
      );

      // 将响应解析为 Post 对象的列表。
      // 我们在这里使用自己的 try/catch，因为解析
      // 可以独立于网络调用失败 ——
      // API 可能返回有效的 JSON，但格式可能不符合预期。
      try {
        final List<dynamic> data = response.data as List<dynamic>;
        final posts = data
            .map((json) => Post.fromJson(json as Map<String, dynamic>))
            .toList();

注意发生了什么变化。函数签名 Future<Result<List<Post>>> 现在更加诚实。任何调用 getPosts() 的人都知道他们得到的是一个 Result —— 他们不能假装它总是成功。并且 try/catch 完全包含在仓库内部。没有任何内容泄露到调用者那里。

## Dart 3 元组及其带来的变化

在进入模式匹配之前，值得谈谈 Dart 3 的元组，因为它们与 Result 类型自然地搭配。

元组是一种轻量级、匿名对象，可以将多个值组合在一起，而无需定义完整的类。可以将其视为从函数中快速返回多个值的一种方式。

当需要返回一个值及其一些元数据时，元组在错误处理中变得非常有用：

使用方式如下：

元组对于 Result 类型并不是必需的，但它们消除了为仅用于携带两个或三个值的辅助类的需求。我经常在需要返回数据以及分页游标或缓存元数据的仓库方法中使用它们。

## 对错误进行模式匹配

这就是所有内容汇聚的地方。密封类加上模式匹配意味着编译器强制你处理每一种可能的结果。你不能意外地忽略失败的情况。

switch (result) {
  // 命名字段模式 —— 直接从 Success 中提取 'data'，
  // 而无需手动转换
  case Success(:final data):
    print('Got ${data.length} posts');

  case Failure(:final error):
    // 现在对错误类型进行模式匹配，
    // 以向用户显示正确的信息
    switch (error) {
      case NoInternetError():
        print('没有网络连接。请检查您的连接。');
      case ServerError(:final statusCode, :final message):
        print('服务器错误 $statusCode: $message');
      case ParseError(:final message):
        print('数据解析时出错: $message');
      case UnknownError(:final message):
        print('意外错误: $message');
    }
}

// 一个辅助扩展，使 Result 更易于使用
extension ResultExtension<T> on Result<T> {
  // 如果是 Success，运行 onSuccess；
  // 如果是 Failure，运行 onFailure
  R when<R>({
    required R Function(T data) onSuccess,
    required R Function(AppError error) onFailure,
  }) {
    return switch (this) {
      Success(:final data) => onSuccess(data),
      Failure(:final error) => onFailure(error),
    };
  }

  // 如果是 Success，返回数据；如果是 Failure，返回 null
  T? getOrNull() => switch (this) {
    Success(:final data) => data,
    Failure() => null,
  };

  // 如果是 Success，返回 true
  bool get isSuccess => this is Success<T>;

  // 如果是 Failure，返回 true
  bool get isFailure => this is Failure<T>;
}

final result = await repository.getPosts();

final posts = result.when(
  onSuccess: (data) => data,
  onFailure: (error) => <Post>[],
);

// post_state.dart

sealed class PostState {}

class PostInitial extends PostState {}

class PostLoading extends PostState {}

// Success 状态直接携带 posts
class PostLoaded extends PostState {
  final List<Post> posts;
  const PostLoaded(this.posts);
}

// Error 状态携带一个 AppError 类型的错误，而不仅仅是字符串。
// 这意味着 UI 可以根据错误类型做出决策 —— 显示“没有网络”的信息，
// 或“服务器错误”的信息，或“请重试”的信息。
class PostError extends PostState {
  final AppError error;
  const PostError(this.error);
}

// post_bloc.dart

class PostBloc extends Bloc<PostEvent, PostState> {
  final PostRepository _repository;

  PostBloc(this._repository) : super(PostInitial()) {
    on<LoadPosts>(_onLoadPosts);
  }

  Future<void> _onLoadPosts(
    LoadPosts event,
    Emitter<PostState> emit,
  ) async {
    emit(PostLoading());

    // getPosts() 现在返回 Result<List<Post>>
    // 我们直接对结果进行模式匹配 ——
    // 这里不需要 try/catch，因为仓库
    // 已经处理了所有错误情况，并将其包装在 Failure 中。
    // Bloc 只需读取结果。
    final result = await _repository.getPosts();

switch (result) {
  case Success(:final data):
    emit(PostLoaded(data));
  case Failure(:final error):
    emit(PostError(error));
}
}

// post_screen.dart

BlocBuilder<PostBloc, PostState>(
  builder: (context, state) {
    return switch (state) {
      PostInitial() => const Center(
          child: Text('Press the button to load posts'),
        ),

      PostLoading() => const Center(
          child: CircularProgressIndicator(),
        ),

      PostLoaded(:final posts) => ListView.builder(
          itemCount: posts.length,
          itemBuilder: (context, index) {
            final post = posts[index];
            return ListTile(
              leading: Text('${post.id}'),

              subtitle: Text(post.body),
            );
          },
        ),

      // 对错误类型进行模式匹配，以显示
      // 每种特定错误的正确信息。
      // 这是 try/catch 无法提供的 ——
      // 可以让 UI 做出响应的类型化、结构化的错误。
      PostError(:final error) => Center(
          child: Column(
            mainAxisSize: MainAxisSize.min,
            children: [
              Text(
                switch (error) {
                  NoInternetError() =>
                    '没有网络连接。请检查您的连接。',
                  ServerError(:final statusCode) =>
                    '服务器错误 ($statusCode)。请重试。',
                  ParseError() =>
                    '发生了一些错误。请重试。',
                  UnknownError() =>
                    '发生了意外错误。',
                },
              ),
              const SizedBox(height: 16),
              ElevatedButton(
                onPressed: () {
                  context.read<PostBloc>().add(LoadPosts());
                },
                child: const Text('重试'),
              ),
            ],
          ),
        ),
    };
  },
)

lib/
  core/
    result.dart
    app_error.dart
  models/
    post.dart
  data/
    post_repository.dart
  bloc/
    post_bloc.dart
    post_event.dart
    post_state.dart
  ui/
    post_screen.dart
  main.dart

sealed class Result<T> {}

class Success<T> extends Result<T> {
  final T data;
  const Success(this.data);
}

class Failure<T> extends Result<T> {
  final AppError error;
  const Failure(this.error);
}

extension ResultExtension<T> on Result<T> {
  R when<R>({
    required R Function(T data) onSuccess,
    required R Function(AppError error) onFailure,
  }) {
    return switch (this) {
      Success(:final data) => onSuccess(data),
      Failure(:final error) => onFailure(error),
    };
  }
}

sealed class AppError {}

class NoInternetError extends AppError {}

class ServerError extends AppError {
  final int statusCode;
  final String message;
  const ServerError({required this.statusCode, required this.message});
}

class ParseError extends AppError {
  final String message;
  const ParseError(this.message);
}

class UnknownError extends AppError {
  final String message;
  const UnknownError(this.message);
}

class Post {
  final int id;
  final String title;
  final String body;
  final int userId;

  const Post({
    required this.id,
    required this.title,
    required this.body,
    required this.userId,
  });

  factory Post.fromJson(Map<String, dynamic> json) {
    return Post(
      id: json['id'] as int,

      body: json['body'] as String,
      userId: json['userId'] as int,
    );
  }
}

import 'package:dio/dio.dart';
import '../core/result.dart';
import '../core/app_error.dart';
import '../models/post.dart';

class PostRepository {
  final Dio _dio;
  PostRepository(this._dio);

  Future<Result<List<Post>>> getPosts() async {
    try {
      final response = await _dio.get(
        'https://jsonplaceholder.typicode.com/posts',
      );

      try {
        final List<dynamic> data = response.data as List<dynamic>;
        final posts = data
            .map((json) => Post.fromJson(json as Map<String, dynamic>))
            .toList();
        return Success(posts);
      } catch (e) {
        return Failure(ParseError('Failed to parse posts: $e'));
      }
    } on DioException catch (e) {
      if (e.type == DioExceptionType.connectionError) {
        return Failure(NoInternetError());
      }
      return Failure(
        ServerError(
          statusCode: e.response?.statusCode ?? 0,
          message: e.message ?? 'Server error',
        ),
      );
    } catch (e) {
      return Failure(UnknownError(e.toString()));
    }
  }
}

sealed class PostEvent {}

class LoadPosts extends PostEvent {}

import '../core/app_error.dart';
import '../models/post.dart';

sealed class PostState {}

class PostInitial extends PostState {}
class PostLoading extends PostState {}

class PostLoaded extends PostState {
  final List<Post> posts;
  const PostLoaded(this.posts);
}

class PostError extends PostState {
  final AppError error;
  const PostError(this.error);
}

import 'package:flutter_bloc/flutter_bloc.dart';
import '../core/result.dart';
import '../data/post_repository.dart';
import 'post_event.dart';
import 'post_state.dart';

class PostBloc extends Bloc<PostEvent, PostState> {
  final PostRepository _repository;

  PostBloc(this._repository) : super(PostInitial()) {
    on<LoadPosts>(_onLoadPosts);
  }

  Future<void> _onLoadPosts(
    LoadPosts event,
    Emitter<PostState> emit,
  ) async {
    emit(PostLoading());

    final result = await _repository.getPosts();

    switch (result) {
      case Success(:final data):
        emit(PostLoaded(data));
      case Failure(:final error):
        emit(PostError(error));
    }
  }
}

import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import '../bloc/post_bloc.dart';
import '../bloc/post_event.dart';
import '../bloc/post_state.dart';
import '../core/app_error.dart';

class PostScreen extends StatelessWidget {
  const PostScreen({super.key});

  String _errorMessage(AppError error) {
    return switch (error) {
      NoInternetError() =>
        'No internet connection. Please check your connection.',
      ServerError(:final statusCode) =>
        'Server error ($statusCode). Please try again.',
      ParseError() => 'Something went wrong. Please try again.',
      UnknownError() => 'An unexpected error occurred.',
    };
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Posts')),
      body: BlocBuilder<PostBloc, PostState>(
        builder: (context, state) {
          return switch (state) {
            PostInitial() => const Center(
                child: Text('Press the button to load posts'),
              ),
            PostLoading() => const Center(
                child: CircularProgressIndicator(),
              ),
            PostLoaded(:final posts) => ListView.builder(
                itemCount: posts.length,
                itemBuilder: (context, index) {
                  final post = posts[index];
                  return ListTile(
                    leading: Text('${post.id}'),

                    subtitle: Text(post.body),
                  );
                },
              ),
            PostError(:final error) => Center(
                child: Column(
                  mainAxisSize: MainAxisSize.min,
                  children: [
                    Text(_errorMessage(error)),
                    const SizedBox(height: 16),
                    ElevatedButton(
                      onPressed: () {
                        context.read<PostBloc>().add(LoadPosts());
                      },
                      child: const Text('Try again'),
                    ),
                  ],
                ),
              ),
          };
        },
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: () => context.read<PostBloc>().add(LoadPosts()),
        child: const Icon(Icons.download),
      ),
    );
  }
}

import 'package:dio/dio.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'bloc/post_bloc.dart';
import 'data/post_repository.dart';
import 'ui/post_screen.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(

      home: BlocProvider(
        create: (_) => PostBloc(PostRepository(Dio())),
        child: const PostScreen(),
      ),
    );
  }
}