Flutter网络请求插件http_rest的使用

HTTP REST

HTTP REST 提供了所有必要的工具来简化和优化您的 HTTP 交互。它是一个基于流行的 Flutter 的 http 库的轻量级且灵活的网络库，并作为增强功能提供了一些额外的功能和功能，例如：

• 中间件（拦截器）
• 请求/响应体转换器
• 请求/响应日志记录
• 读/写进度跟踪
• 带有进度的多部分请求

开始使用

创建一个 HttpRestClient 实例，然后运行 HttpRestRequest。

import 'package:http/http.dart' as http;
import 'package:http_rest/http_rest.dart';

/// ...
final httpClient = HttpRestClient.builder(DefaultRequestExecutor(http.Client()))
    .addResponseConverter(JsonToMapResponseConverter()) // 添加响应转换器
    .addRequestConverter(MapToJsonRequestConverter()) // 添加请求转换器
    .addRequestMiddleware(RequestLogger()) // 添加请求中间件
    .addResponseMiddleware(ResponseLogger()) // 添加响应中间件
    .build();

// 这个请求将向图书馆添加一本书
final result = await httpClient.execute(HttpRestRequest(
    method: Methods.post,
    // 指定请求转换器类型
    requestConverterType: MapToJsonRequestConverter,
    // 指定响应转换器类型
    responseConverterType: JsonToMapResponseConverter,
    url: 'https://example.com/books',
    headers: {'Language': 'en'},
    body: {
      "id": 2,
      "bookName": "1984",
      "author": "George Orwell"
    }));

if (result.rowResponse.code == 201) {
  print(result.response); // 实例为 Map
}

同样的 httpClient 实例也可以用来执行其他 HTTP 请求。

// 这个请求会获取图书馆的书籍列表。
final result = await httpClient.execute(HttpRestRequest(
    method: Methods.get,
    responseConverterType: JsonToMapResponseConverter,
    url: 'https://example.com/books?count=10'));

中间件

HttpRestClient 使用中间件链来修改请求和响应。

以下是创建一个请求中间件以在每个 HttpRestRequest 中添加授权头的方法：

class AuthorizationMiddleware extends Middleware<RowRequest> {
  @override
  Future<RowRequest> onNext(
      RowRequest row, Middleware<RowRequest> nextMiddleware) async {
    row.request.headers['Authorization'] = 'YOUR AUTHORIZATION TOKEN';
    return await super.onNext(row, nextMiddleware);
  }
}

在构建 HttpRestClient 实例时添加它：

final httpClient = HttpRestClient.builder(
        DefaultRequestExecutor(http.Client()))
    .addResponseConverter(JsonToMapResponseConverter())
    .addRequestConverter(MapToJsonRequestConverter()) 
    .addRequestMiddleware(AuthorizationMiddleware()) // 添加
    .addRequestMiddleware(RequestLogger()) 
    .addResponseMiddleware(ResponseLogger())
    .build();

因此，Authorization 头将会被添加到由 httpClient 执行的所有请求中。

请注意，RequestLogger 和 ResponseLogger 也是中间件。

可以在 HttpRestClient 中添加任意数量的请求和响应中间件，它们将以添加的顺序作为链调用。

转换器

转换器用于转换请求和响应体。库自带了一些默认的转换器：

• MapToJsonRequestConverter 用于将请求的映射体转换为 JSON 字符串。
• JsonToMapResponseConverter 用于将响应体字节转换为映射对象。
• StringResponseConverter 用于将响应体字节转换为字符串。

每个 HttpRestRequest 可以指定请求和响应转换器类型，HttpRestClient 将使用指定的转换器来转换请求和响应体。

// 这个请求会获取图书馆的书籍列表。
final result = await httpClient.execute(HttpRestRequest(
    method: Methods.get,
    // 将请求体转换为 JSON
    responseConverterType: JsonToMapResponseConverter,
    url: 'https://example.com/books?count=10'));

以下是如何创建一个将接收到的体字节转换为映射实例的转换器：

import 'dart:convert';

class JsonToMapResponseConverter extends ResponseConverter {
  @override
  HttpRestResponse fromRow(RowResponse rowResponse) {
    dynamic jsonMap;
    final rowBody = rowResponse.bodyBytes;
    if (rowBody != null && rowBody.isNotEmpty) {
      final rowBodyUtf8 = utf8.decode(rowBody);
      jsonMap = json.decode(rowBodyUtf8);
    }
    return HttpRestResponse(rowResponse.request, rowResponse, jsonMap);
  }
}

注意，fromRow 方法接收 RowResponse 的实例并返回 HttpRestResponse 的实例。

• RowResponse 是较低级别的响应模型，包含响应的 bodyBytes 以及其他内容，如响应码和响应头。
• HttpRestResponse 是 await client.execute(HttpRestRequest(...)) 返回的实例，它包含原始的 HttpRestRequest、RowResponse 和转换后的体 jsonMap。

请求日志记录

RequestLogger 和 ResponseLogger 用于在控制台中记录网络交互。

这里是如何在控制台中查看记录的请求的样子：

→ REQUEST →
POST: https://example.com/books
HEADERS:    Content-Type : application/json
            Authorization : eyJhbGciOi....
            Language : EN
            Version : 1.1.76
BODY:       {"id":2, "bookName":"1984", "author":"George Orwell"}

← RESPONSE ←
POST: https://example.com/books
CODE: 200
HEADERS:    connection : keep-alive
            date : Thu, 04 May 2023 19:02:10 GMT
            transfer-encoding : chunked
            vary : accept-encoding
            content-encoding : gzip
            strict-transport-security : max-age=15724800; includeSubDomains
            content-type : application/json

BODY:       {"message":"Success"}

使用 LogParts 枚举来控制可记录的部分：

enum LogParts {
  headers,
  body,
  url,
  code;

  static const all = {url, headers, code, body}; // 默认
}

默认情况下，请求和响应的所有部分都会被记录。这里是仅记录 URL 和头部的方法：

final httpClient = HttpRestClient.builder(
    DefaultRequestExecutor(http.Client()))
//...
    .addRequestMiddleware(RequestLogger(logParts: {LogParts.url, LogParts.headers})) // 中间件
    .addResponseMiddleware(ResponseLogger(logParts: {LogParts.url, LogParts.headers}))
    .build();

读/写进度跟踪

要跟踪任何请求的读取/写入进度，可以使用 HttpRestRequest 的 writeProgressListener 和 readProgressListener 成员。

以下是如何从 GitHub 下载图像并跟踪下载进度的例子：

void downloadImage() => 
    httpClient.execute(HttpRestRequest(
      method: Methods.get,
      url: 'https://raw.githubusercontent.com/RobertApikyan/http_rest/main/doc/assets/intro.png',
      readProgressListener: (bytes, totalBytes) => print('download progress= ${bytes/totalBytes}'),
    ));

多部分请求

对于多部分请求，只需提供 MultipartRequestBody 到 HttpRestRequest 的 body 中。

以下是如何创建一个多部分请求以上传书籍并监控进度：

void uploadBook(MultipartFile multipartFile) => 
    httpClient.execute(HttpRestRequest(
      method: Methods.post,
      url: 'https://example.com/book',
      body: MultipartRequestBody(
        fields: {},
        files: [multipartFile],
        progressListener: (bytes, totalBytes) {
          // 监控进度
          final progress = bytes / totalBytes;
        },
      ),
    ));

请求执行器

RequestExecutor 负责实际执行 HTTP 请求并返回结果。这是一个抽象类，有一个单抽象方法 execute。

abstract class RequestExecutor {
  /// 重写此方法并使用 [rowRequest] 参数中的参数实现 HTTP 调用。
  Future<RowResponse> execute(RowRequest rowRequest);
}