Flutter网络请求插件network_y的使用

网络_y 🌐

network_y 是一个在 Dart 和 Flutter 应用程序中处理网络相关操作的简单且灵活的抽象层。它提供了一个清晰的接口来发起 HTTP 请求、管理响应并处理错误，使得与不同 HTTP 客户端的集成变得容易。🚀

快速开始

以下是一个简单的示例，帮助你快速上手 network_y：

// 定义你的请求
class GetUserRequest extends GetRequest {
  GetUserRequest(int userId) : super(
    baseUrl: 'https://api.example.com',
    endpoint: '/users/$userId',
  );
}

// 设置客户端
final apiClient = ApiClient(apiExecutor: DioApiExecutor());

// 发起请求
final result = await apiClient<Map<String, Object?>>(GetUserRequest(1));

// 处理结果
result.fold(
  onSuccess: (data) => print('User data: $data'),
  onFailure: (error) => print('Error: ${error.userFriendlyMessage}'),
);

这个简单的示例展示了如何定义请求、设置客户端、发起调用以及处理结果。

关键组件

classDiagram
    class ApiClient {
        +ApiExecutor executor
        +call(Request) AsyncResult
    }
    class ApiExecutor {
        <<interface>>
        +get(Request) AsyncResult
        +post(Request) AsyncResult
        +patch(Request) AsyncResult
        +setUp(SetupRequest)
    }
    class Request {
        <<abstract>>
        +String baseUrl
        +String endpoint
        +Headers headers
        +QueryParameters queryParameters
        +Duration timeout
    }
    class GetRequest {
        <<interface>>
    }
    class PostRequest {
        <<interface>>
        +Payload body
    }
    class PatchRequest {
        <<interface>>
        +Payload body
    }
    class DioApiExecutor {
        +get(Request) AsyncResult
        +post(Request) AsyncResult
        +patch(Request) AsyncResult
        +setUp(SetupRequest)
    }
    class Result {
        <<abstract>>
    }
    class Success {
        +value
    }
    class Failure {
        +ApiException error
    }

    ApiClient -->> ApiExecutor
    ApiExecutor <|.. DioApiExecutor
    ApiClient -->> Request
    Request <|-- GetRequest
    Request <|-- PostRequest
    Request <|-- PatchRequest
    ApiClient -->> Result
    Result <|-- Success
    Result <|-- Failure

ApiExecutor 🔧

ApiExecutor 负责实际的网络请求。内部它可以使用各种 HTTP 客户端包，如 dio、http 等。这种设计的优点在于你可以轻松地在不同的执行器之间切换而无需更改应用程序代码。

ApiClient 🖥️

ApiClient 是你用来发起网络请求的主要类。它接受一个 ApiExecutor 作为参数，允许你轻松地在不同的网络实现之间切换。

final apiClient = ApiClient(apiExecutor: DioApiExecutor());

这种设计使得更改底层 HTTP 客户端或为测试模拟网络请求变得简单。

如何使用

请求类型

• GetRequest：用于 GET 请求 📥
• PostRequest：用于带有主体的 POST 请求 📤
• PatchRequest：用于带有主体的 PATCH 请求 🔄

ApiException

一个全面的异常类，提供了有关网络错误的详细信息。🚨

示例

发起GET请求

class UserGetRequest extends GetRequest {
  UserGetRequest({required int userId})
      : super(
          baseUrl: 'https://api.example.com',
          endpoint: '/users/$userId',
        );
}

final request = UserGetRequest(userId: 1);
final result = await apiClient.call<Map<String, Object?>>(request);

result.fold(
  onSuccess: (data) => print('User data: $data'),
  onFailure: (error) => print('Error: ${error.userFriendlyMessage}'),
);

发起POST请求

class CreateUserRequest extends PostRequest {
  CreateUserRequest({required String name, required String email})
      : super(
          baseUrl: 'https://api.example.com',
          endpoint: '/users',
          body: {'name': name, 'email': email},
        );
}

final request = CreateUserRequest(name: 'John Doe', email: 'john@example.com');
final result = await apiClient.call<Map<String, Object?>>(request);

result.fold(
  onSuccess: (data) => print('User created: $data'),
  onFailure: (error) => print('Error: ${error.userFriendlyMessage}'),
);

使用基础请求

在许多应用中，你可能会有一些通用参数（如基础 URL、头等）在多个请求中共享。与其将这些参数传递给每个请求，你可以创建一个基础请求，并让其他所有请求扩展它。以下是示例：

class BaseApiRequest extends Request {
  BaseApiRequest({
    required super.endpoint,
    super.baseUrl = 'https://api.example.com/',
    super.headers = const {
      'Content-Type': 'application/json',
      'Api-Version': 'v1',
    },
  });
}

class GetUserRequest extends BaseApiRequest implements GetRequest {
  GetUserRequest({
    required this.userId,
  }) : super(
          endpoint: 'users/$userId',
        );

  final String userId;
}

class CreatePostRequest extends BaseApiRequest implements PostRequest {
  CreatePostRequest({
    required this.title,
    required this.content,
    required this.authorId,
  }) : super(
          endpoint: 'posts',
        );

  final String title;
  final String content;
  final String authorId;

  @override
  Payload get body => {
        'title': title,
        'content': content,
        'author_id': authorId,
      };
}

这种方法允许你集中配置公共参数，并轻松地为不同的端点创建特定请求。BaseApiRequest 设置了通用参数，如基础 URL 和默认头，而具体的请求类（如 GetUserRequest、CreatePostRequest）扩展此基础类并添加自己的独特属性和行为。

动态头部

在某些情况下，你在定义基础请求时可能无法访问某些头值（如身份验证令牌）。network_y 包允许你通过 ApiExecutor 的 setUp 方法动态添加这些头。以下是具体做法：

final apiExecutor = DioApiExecutor();

// 在设置期间添加动态头
apiExecutor.setUp(
  request: (
    headers: {
      'Authorization': 'Bearer ${getAuthToken()}',
      'Custom-Header': 'Some-Value',
    },
  ),
);

final apiClient = ApiClient(apiExecutor: apiExecutor);

这种方法允许你添加或更新那些可能不可用或频繁变化的头值，例如身份验证令牌或会话特定信息。这些头将应用于通过 apiClient 发起的所有请求，除了你在基础请求类或特定请求类中定义的头之外。

入门 🏁

1. 将包添加到你的 pubspec.yaml 文件中：

dependencies:
  network_y: ^0.0.4+3

1. 在你的 Dart 代码中导入该包：

import 'package:network_y/network_y.dart';