Flutter响应数据解析插件response_parser的使用

简介

Response Parser 是一个用于简化从服务器解析数据和错误响应的Flutter插件。它可以帮助你编写更简洁、更易于维护的网络请求处理代码。

特性

• 简化错误处理：自动处理不同类型的错误，并返回统一的错误对象。
• 类型安全：使用 Either 类型来表示成功或失败的结果。
• 灵活配置：可以通过自定义解析器来适应不同的API响应格式。

许可证与版本

• MIT License
• Pub Package
• Codecov

入门

假设你希望编写如下的简洁函数：

Future<Either<ApiFailure, User>> fetchUser() async {
  return parseApiResponse(
    requestAction: () => dio.get('/user'),
    mapper: User.fromJson,
  );
}

而不是以下冗长的代码：

Future<Either<ApiFailure, User>> fetchUser() async {
  final dio = Dio(BaseOptions(baseUrl: 'https://example.com'));
  try {
    final request = await dio.get('/user');
    final data = request.data?['data'];
    if (data == null) {
      final error = request.data?['error'];
      if (error != null) {
        return left(ApiFailure.serverFailure(error['message']));
      } else {
        return left(ApiFailure.unknown());
      }
    } else {
      return right(User.fromJson(data));
    }
  } catch (error, st) {
    ApiFailure? apiFailure;
    if (error is DioError) {
      final responseFailure = error.response?.data;
      if (responseFailure is Map<String, dynamic>) {
        apiFailure = ApiFailure.serverFailure(responseFailure['message']);
      } else {
        apiFailure = ApiFailure.httpError(error.response?.statusCode);
      }
    }
    return left(apiFailure ?? ApiFailure.unknown());
  }
}

如果你也想编写这样的简洁代码，请继续阅读！

不知道什么是 Either？

Either 是来自 fpdart 包 的一个类型。它用于返回要么是错误（左），要么是数据（右）。

使用方法

为了使用 response_parser，你需要进行一些准备工作。假设你的服务器返回如下的响应：

{
  "data": {
    // 请求的数据
  },
  "error": {
    // 服务器错误，需要解析并显示给用户
    "message": "Something went wrong"
  }
}

并且你的错误模型如下所示：

class ApiFailure {
  factory ApiFailure.unknown() = _UnknownApiFailure;
  factory ApiFailure.serverFailure(String errorMessage) = _ServerFailure;
  factory ApiFailure.httpError(int? statusCode) = _HttpError;
}

你需要实现 dataExtractor、failureParser 和 errorCatcher，如下所示：

final _exampleResponseParser = ResponseParser<Response, ApiFailure>(
  dataExtractor: (response) => response.data['data']!,
  failureParser: (response) {
    final error = response.data['error'];
    if (error is Map<String, dynamic>) {
      return ApiFailure.serverFailure(error['message']);
    } else {
      return null;
    }
  },
  errorCatcher: (error, stackTrace) {
    ApiFailure? apiFailure;
    if (error is DioError) {
      apiFailure = ApiFailure.httpError(error.response?.statusCode);
    }
    return apiFailure ?? ApiFailure.unknown();
  },
);

然后创建顶级的 parseApiResponse、parseListApiResponse 和 parseEmptyApiResponse 函数：

final parseApiResponse = _exampleResponseParser.parseApiResponse;
final parseListApiResponse = _exampleResponseParser.parseListApiResponse;
final parseEmptyApiResponse = _exampleResponseParser.parseEmptyApiResponse;

工作原理

下图展示了 parseApiResponse 方法的工作原理：

实际上，parseApiResponse 方法中的所有操作都包裹在一个 try-catch 块中，因此该方法是安全的，不会抛出任何异常。

另一种使用方式

除了创建顶级函数，你还可以创建一个继承自 ResponseParserBase 的类，并重写其方法：

class DefaultResponseParser extends ResponseParserBase<Response, ApiFailure> {
  @override
  Object extractData(Response response) => response.data['data']!;

  @override
  Failure? parseFailure(Response response) {
    final error = response.data['error'];
    if (error is Map<String, dynamic>) {
      return ApiFailure.serverFailure(error['message']);
    } else {
      return null;
    }
  }

  @override
  Failure catchError(Object error, StackTrace stackTrace) {
    ApiFailure? apiFailure;
    if (error is DioError) {
      apiFailure = ApiFailure.httpError(error.response?.statusCode);
    }

    return apiFailure ?? ApiFailure.unknown();
  }
}

示例代码

以下是一个完整的示例代码，展示了如何使用 response_parser 插件：

import 'package:dio/dio.dart';
import 'package:freezed_annotation/freezed_annotation.dart';
import 'package:response_parser/response_parser.dart';

part 'example.freezed.dart';
part 'example.g.dart';

final _exampleResponseParser = ResponseParser<Response, ApiFailure>(
  dataExtractor: (response) => response.data['data']!,
  failureParser: (response) => _parseApiFailure(response.data),
  errorCatcher: (error, stackTrace) {
    ApiFailure? apiFailure;
    if (error is DioError) {
      final responseFailure = error.response?.data;
      if (responseFailure is Map<String, dynamic>) {
        apiFailure = _parseApiFailure(responseFailure);
      } else {
        apiFailure = ApiFailure.httpError(error.response?.statusCode);
      }
    }

    return apiFailure ?? ApiFailure.unknown();
  },
);

ApiFailure? _parseApiFailure(Map<String, dynamic> json) {
  final error = json['error'];
  if (error is Map<String, dynamic>) {
    return ApiFailure.serverFailure(error['message']);
  } else {
    return null;
  }
}

final parseApiResponse = _exampleResponseParser.parseApiResponse;
final parseListApiResponse = _exampleResponseParser.parseListApiResponse;
final parseEmptyApiResponse = _exampleResponseParser.parseEmptyApiResponse;

Future<void> main() async {
  final dio = Dio(BaseOptions(baseUrl: 'https://example.com'));

  final userResult = await parseApiResponse(
    requestAction: () => dio.get('/user'),
    mapper: User.fromJson,
  );
  userResult.fold(
    (failure) => print('Error: ${failure.displayError}'),
    (user) => print('User is loaded: $user'),
  );

  final usersResult = await parseListApiResponse(
    requestAction: () => dio.get('/users'),
    mapper: User.fromJson,
  );
  usersResult.fold(
    (failure) => print('Error: ${failure.displayError}'),
    (users) => print('Users are loaded: $users'),
  );

  final deleteUserResult = await parseEmptyApiResponse(
    requestAction: () => dio.delete('/user'),
  );
  deleteUserResult.match<void>(
    () => print('User is successfully deleted!'),
    (failure) => print('Error: ${failure.displayError}'),
  );
}

@JsonSerializable()
class User {
  User(this.name);

  factory User.fromJson(Map<String, dynamic> json) => _$UserFromJson(json);

  final String name;
}

@freezed
class ApiFailure with _$ApiFailure {
  ApiFailure._();
  factory ApiFailure.unknown() = _UnknownApiFailure;
  factory ApiFailure.serverFailure(String errorMessage) = _ServerFailure;
  factory ApiFailure.httpError(int? statusCode) = _HttpError;

  String get displayError => when(
        unknown: () => 'Unknown',
        serverFailure: (errorMessage) => errorMessage,
        httpError: (statusCode) => 'Http error with status code $statusCode',
      );
}

以上就是 response_parser 插件的使用方法。希望对你有所帮助！如果有更多问题，可以查看示例代码或查阅官方文档。