_RequestConfig

_RequestConfig类描述http请求信息和配置。

class _RequestConfig {
  _RequestConfig({
    Duration? receiveTimeout,
    Duration? sendTimeout,
    String? method,
    Map<String, dynamic>? extra,
    Map<String, dynamic>? headers,
    String? contentType,
    ListFormat? listFormat,
    bool? followRedirects,
    int? maxRedirects,
    bool? persistentConnection,
    bool? receiveDataWhenStatusError,
    ValidateStatus? validateStatus,
    ResponseType? responseType,
    this.requestEncoder,
    this.responseDecoder,
  })  : assert(receiveTimeout == null || !receiveTimeout.isNegative),
        _receiveTimeout = receiveTimeout,
        assert(sendTimeout == null || !sendTimeout.isNegative),
        _sendTimeout = sendTimeout {
    this.headers = headers;

    final contentTypeInHeader =
        this.headers.containsKey(Headers.contentTypeHeader);
    assert(
      !(contentType != null && contentTypeInHeader) ||
          this.headers[Headers.contentTypeHeader] == contentType,
      'You cannot set different values for contentType param and a content-type header',
    );

    this.method = method ?? 'GET';
    this.listFormat = listFormat ?? ListFormat.multi;
    this.extra = extra ?? {};
    this.followRedirects = followRedirects ?? true;
    this.maxRedirects = maxRedirects ?? 5;
    this.persistentConnection = persistentConnection ?? true;
    this.receiveDataWhenStatusError = receiveDataWhenStatusError ?? true;
    this.validateStatus = validateStatus ??
        (int? status) {
          return status != null && status >= 200 && status < 300;
        };
    this.responseType = responseType ?? ResponseType.json;
    if (!contentTypeInHeader) {
      this.contentType = contentType;
    }
  }
}

上述代码是 Dio 库中的 _RequestConfig 类的构造函数实现。该类用于设置请求的配置选项。

构造函数接受多个可选参数，包括：

receiveTimeout 和 sendTimeout：用于设置请求的接收超时和发送超时时间。
method：请求方法，默认为 'GET'。
extra：用于设置额外的请求参数。
headers：请求头。
contentType：请求的内容类型。
listFormat：用于指定请求的列表格式，默认为 ListFormat.multi。
followRedirects：是否跟随重定向，默认为 true。
maxRedirects：最大重定向次数，默认为 5。
persistentConnection：是否使用持久连接，默认为 true。
receiveDataWhenStatusError：是否在状态错误时接收响应数据，默认为 true。
validateStatus：用于验证响应状态码的函数。
responseType：响应数据的类型，默认为 ResponseType.json。
requestEncoder 和 responseDecoder：请求和响应数据的编码器。

构造函数内部会对参数进行合法性检查，并设置相应的配置选项。例如，如果 contentType 参数与请求头中的内容类型不一致，则会抛出异常。

最后，构造函数还会根据需要设置请求的内容类型。

这是 _RequestConfig 类的构造函数实现的简要解析。通过这些配置选项，可以灵活地定制 Dio 请求的行为和参数。

headers

Map<String, dynamic> get headers => _headers;
late Map<String, dynamic> _headers;

set headers(Map<String, dynamic>? headers) {
  _headers = caseInsensitiveKeyMap(headers);
  if (!_headers.containsKey(Headers.contentTypeHeader) &&
      _defaultContentType != null) {
    _headers[Headers.contentTypeHeader] = _defaultContentType;
  }
}

headers 属性的实现。该属性用于设置请求的头部信息。

headers 是一个 Map 类型，用于存储请求头的键值对。在构造函数中，会将传入的 headers 参数通过 caseInsensitiveKeyMap 方法转换为大小写不敏感的键值对 Map，并赋值给 _headers 属性。

在设置 _headers 属性的同时，还会判断是否包含 Content-Type 头部，并且如果没有设置默认的内容类型 _defaultContentType，则会将其添加到 _headers 中。

需要注意的是，headers 的键是大小写不敏感的，也就是说，例如 'Content-Type' 和 'content-type' 被视为相同的键。这样设计的目的是为了方便使用者在设置和获取头部信息时不必担心大小写的问题。

通过设置 headers 属性，可以为请求添加自定义的头部信息，例如设置认证信息、内容类型、User-Agent 等。这样可以灵活地定制请求的头部，以满足特定的业务需求。

sendTimeout

Duration? get sendTimeout => _sendTimeout;




set sendTimeout(Duration? value) {
  if (value != null && value.isNegative) {

    throw StateError('sendTimeout should be positive');
  }

  _sendTimeout = value;
}



Duration? _sendTimeout;

sendTimeout 属性的实现。该属性表示发送数据的超时时间。

sendTimeout 是一个 Duration 类型的属性，用于设置发送数据的超时时间。如果超过该时间，Dio 会抛出一个 DioError，错误类型为 DioErrorType.sendTimeout。

如果将 sendTimeout 设置为 null，表示没有超时限制。

在设置 sendTimeout 属性时，会先进行判断，如果传入的值为负数，则会抛出 StateError 异常，提示 sendTimeout 应为正数。

通过设置 sendTimeout 属性，可以控制请求发送数据的超时时间，以防止请求长时间无响应导致的阻塞。可以根据实际需求设置适当的超时时间，以保证请求的及时性和稳定性。

receiveTimeout

Duration? get receiveTimeout => _receiveTimeout;




set receiveTimeout(Duration? value) {
  if (value != null && value.isNegative) {

    throw StateError('receiveTimeout should be positive');
  }

  _receiveTimeout = value;
}



Duration? _receiveTimeout;

receiveTimeout 属性的实现。该属性表示接收数据的超时时间。

receiveTimeout 是一个 Duration 类型的属性，用于设置接收数据的超时时间。如果超过该时间，Dio 会抛出一个 DioError，错误类型为 DioErrorType.receiveTimeout。

如果将 receiveTimeout 设置为 null，表示没有超时限制。

在设置 receiveTimeout 属性时，会先进行判断，如果传入的值为负数，则会抛出 StateError 异常，提示 receiveTimeout 应为正数。

通过设置 receiveTimeout 属性，可以控制请求接收数据的超时时间，以防止请求长时间无响应导致的阻塞。可以根据实际需求设置适当的超时时间，以保证请求的及时性和稳定性。

contentType

String? get contentType => _headers[Headers.contentTypeHeader] as String?;




set contentType(String? contentType) {
  final newContentType = contentType?.trim();
  _defaultContentType = newContentType;
  if (newContentType != null) {
    _headers[Headers.contentTypeHeader] = newContentType;
  } else {
    _headers.remove(Headers.contentTypeHeader);
  }
}


String? _defaultContentType;

contentType 属性的实现。该属性用于设置请求的 Content-Type。

contentType 是一个可空的字符串属性，表示请求的 Content-Type。在 HTTP 请求中，Content-Type 表示请求体的数据类型。

通过设置 contentType 属性，可以指定请求的数据类型，例如 “application/json”、”application/x-www-form-urlencoded” 等。Dio 会将该值设置到请求头中的 “Content-Type” 字段。

在设置 contentType 属性时，首先会将传入的值进行修剪（去除首尾空格），然后将修剪后的值赋给 _defaultContentType 属性。然后，如果修剪后的值不为 null，则将其设置到 _headers 中的 “Content-Type” 键对应的值中；如果修剪后的值为 null，则从 _headers 中移除 “Content-Type” 键。

通过设置 contentType 属性，可以灵活地指定请求的数据类型，以满足不同的请求需求。

辅助类

late ResponseType responseType;




/// `validateStatus` defines whether the request is successful for a given
/// HTTP response status code. If `validateStatus` returns `true` ,
/// the request will be perceived as successful; otherwise, considered as failed.
late ValidateStatus validateStatus;

/// Whether receiving response data when http status code is not successful.
/// The default value is true
late bool receiveDataWhenStatusError;

/// Custom field that you can retrieve it later in [Interceptor]、[Transformer] and the [Response] object.
late Map<String, dynamic> extra;


/// see [HttpClientRequest.followRedirects],
/// The default value is true
late bool followRedirects;

/// Set this property to the maximum number of redirects to follow
/// when [followRedirects] is `true`. If this number is exceeded
/// an error event will be added with a [RedirectException].
///
/// The default value is 5.
late int maxRedirects;

/// see [HttpClientRequest.persistentConnection],
/// The default value is true
late bool persistentConnection;

/// The default request encoder is utf8encoder, you can set custom
/// encoder by this option.
RequestEncoder? requestEncoder;

/// The default response decoder is utf8decoder, you can set custom
/// decoder by this option, it will be used in [Transformer].
ResponseDecoder? responseDecoder;

/// The [listFormat] indicates the format of collection data in request
/// query parameters and `x-www-url-encoded` body data.
/// Possible values defined in [ListFormat] are `csv`, `ssv`, `tsv`, `pipes`, `multi`, `multiCompatible`.
/// The default value is `multi`.
///
/// The value can be overridden per parameter by adding a [ListParam]
/// object to the query or body data map.
late ListFormat listFormat;

OptionsMixin

mixin OptionsMixin {
  /// Request base url, it can contain sub paths like: https://pub.dev/api/.
  late String baseUrl;

  /// Common query parameters.
  ///
  /// List values use the default [ListFormat.multiCompatible].
  ///
  /// The value can be overridden per parameter by adding a [ListParam]
  /// object wrapping the actual List value and the desired format.
  late Map<String, dynamic> queryParameters;


  /// Timeout in milliseconds for opening url.
  /// [Dio] will throw the [DioError] with [DioErrorType.connectionTimeout] type
  ///  when time out.
  Duration? get connectTimeout => _connectTimeout;

  set connectTimeout(Duration? value) {
    if (value != null && value.isNegative) {
      throw StateError('connectTimeout should be positive');
    }
    _connectTimeout = value;
  }

  Duration? _connectTimeout;
}

上述代码是 Dio 库中的 OptionsMixin mixin 的一部分。

OptionsMixin 定义了一些常用的请求选项属性和方法，供 Dio 请求使用。

以下是其中的一些属性和方法的解释：

baseUrl: 请求的基础 URL，可以包含子路径。
queryParameters: 请求的通用查询参数，以键值对形式存储。
connectTimeout: 打开 URL 的超时时间，单位为毫秒。如果超过指定时间仍未能建立连接，Dio 会抛出 DioError 异常，并使用 DioErrorType.connectionTimeout 类型标识。

通过使用 OptionsMixin，可以方便地设置请求的基础 URL、查询参数和连接超时时间，从而满足不同的请求需求。这些选项可以与 Dio 的其他功能和方法结合使用，以完成网络请求操作。

RequestOptions

class RequestOptions extends _RequestConfig with OptionsMixin {
  RequestOptions({
    this.path = '',
    this.data,
    this.onReceiveProgress,
    this.onSendProgress,
    this.cancelToken,
    String? method,
    Duration? sendTimeout,
    Duration? receiveTimeout,
    Duration? connectTimeout,
    Map<String, dynamic>? queryParameters,
    String? baseUrl,
    Map<String, dynamic>? extra,
    Map<String, dynamic>? headers,
    ResponseType? responseType,
    String? contentType,
    ValidateStatus? validateStatus,
    bool? receiveDataWhenStatusError,
    bool? followRedirects,
    int? maxRedirects,
    bool? persistentConnection,
    RequestEncoder? requestEncoder,
    ResponseDecoder? responseDecoder,
    ListFormat? listFormat,
    bool? setRequestContentTypeWhenNoPayload,
    StackTrace? sourceStackTrace,
  })  : assert(connectTimeout == null || !connectTimeout.isNegative),
        super(
          method: method,
          sendTimeout: sendTimeout,
          receiveTimeout: receiveTimeout,
          extra: extra,
          headers: headers,
          responseType: responseType,
          contentType: contentType,
          validateStatus: validateStatus,
          receiveDataWhenStatusError: receiveDataWhenStatusError,
          followRedirects: followRedirects,
          maxRedirects: maxRedirects,
          persistentConnection: persistentConnection,
          requestEncoder: requestEncoder,
          responseDecoder: responseDecoder,
          listFormat: listFormat,
        ) {
    this.sourceStackTrace = sourceStackTrace ?? StackTrace.current;
    this.queryParameters = queryParameters ?? {};
    this.baseUrl = baseUrl ?? '';
    this.connectTimeout = connectTimeout;
  }

  /// Create a Option from current instance with merging attributes.
  RequestOptions copyWith({
    String? method,
    Duration? sendTimeout,
    Duration? receiveTimeout,
    Duration? connectTimeout,
    dynamic data,
    String? path,
    Map<String, dynamic>? queryParameters,
    String? baseUrl,
    ProgressCallback? onReceiveProgress,
    ProgressCallback? onSendProgress,
    CancelToken? cancelToken,
    Map<String, dynamic>? extra,
    Map<String, dynamic>? headers,
    ResponseType? responseType,
    String? contentType,
    ValidateStatus? validateStatus,
    bool? receiveDataWhenStatusError,
    bool? followRedirects,
    int? maxRedirects,
    bool? persistentConnection,
    RequestEncoder? requestEncoder,
    ResponseDecoder? responseDecoder,
    ListFormat? listFormat,
    bool? setRequestContentTypeWhenNoPayload,
  }) {
    final contentTypeInHeader = headers != null &&
        headers.keys
            .map((e) => e.toLowerCase())
            .contains(Headers.contentTypeHeader);

    assert(
      !(contentType != null && contentTypeInHeader),
      'You cannot set both contentType param and a content-type header',
    );

    final ro = RequestOptions(
      method: method ?? this.method,
      sendTimeout: sendTimeout ?? this.sendTimeout,
      receiveTimeout: receiveTimeout ?? this.receiveTimeout,
      connectTimeout: connectTimeout ?? this.connectTimeout,
      data: data ?? this.data,
      path: path ?? this.path,
      baseUrl: baseUrl ?? this.baseUrl,
      queryParameters: queryParameters ?? Map.from(this.queryParameters),
      onReceiveProgress: onReceiveProgress ?? this.onReceiveProgress,
      onSendProgress: onSendProgress ?? this.onSendProgress,
      cancelToken: cancelToken ?? this.cancelToken,
      extra: extra ?? Map.from(this.extra),
      headers: headers ?? Map.from(this.headers),
      responseType: responseType ?? this.responseType,
      validateStatus: validateStatus ?? this.validateStatus,
      receiveDataWhenStatusError:
          receiveDataWhenStatusError ?? this.receiveDataWhenStatusError,
      followRedirects: followRedirects ?? this.followRedirects,
      maxRedirects: maxRedirects ?? this.maxRedirects,
      persistentConnection: persistentConnection ?? this.persistentConnection,
      requestEncoder: requestEncoder ?? this.requestEncoder,
      responseDecoder: responseDecoder ?? this.responseDecoder,
      listFormat: listFormat ?? this.listFormat,
      sourceStackTrace: sourceStackTrace,
    );

    if (contentType != null) {
      ro.headers.remove(Headers.contentTypeHeader);
      ro.contentType = contentType;
    } else if (!contentTypeInHeader) {
      ro.contentType = this.contentType;
    }

    return ro;
  }

  /// The source [StackTrace] which should always point to
  /// the invocation of [DioMixin.request] or if not provided,
  /// to the construction of the [RequestOptions] instance.
  /// In both instances the source context should still be
  /// available before it is lost due to asynchronous operations.
  @internal
  StackTrace? sourceStackTrace;

  /// generate uri
  Uri get uri {
    String url = path;
    if (!url.startsWith(RegExp(r'https?:'))) {
      url = baseUrl + url;
      final s = url.split(':/');
      if (s.length == 2) {
        url = '${s[0]}:/${s[1].replaceAll('//', '/')}';
      }
    }
    final query = Transformer.urlEncodeQueryMap(queryParameters, listFormat);
    if (query.isNotEmpty) {
      url += (url.contains('?') ? '&' : '?') + query;
    }
    // Normalize the url.
    return Uri.parse(url).normalizePath();
  }

  /// Request data, can be any type.
  ///
  /// When using `x-www-url-encoded` body data,
  /// List values use the default [ListFormat.multi].
  ///
  /// The value can be overridden per value by adding a [ListParam]
  /// object wrapping the actual List value and the desired format.
  dynamic data;

  /// If the `path` starts with 'http(s)', the `baseURL` will be ignored,
  /// otherwise, it will be combined and then resolved with the baseUrl.
  String path;

  CancelToken? cancelToken;

  ProgressCallback? onReceiveProgress;

  ProgressCallback? onSendProgress;
}

RequestOptions 是 Dio 库中用于配置 HTTP 请求的类。以下是对其属性和方法的分析：

baseUrl：请求的基础 URL，可以包含子路径。
queryParameters：通用的查询参数。
connectTimeout：连接超时时间。
sendTimeout：发送数据的超时时间。
receiveTimeout：接收数据的超时时间。
data：请求的数据。
path：请求的路径。
cancelToken：用于取消请求的令牌。
onReceiveProgress：接收进度的回调函数。
onSendProgress：发送进度的回调函数。
extra：额外的配置参数。
headers：请求头部信息。
responseType：响应的数据类型。
contentType：请求的内容类型。
validateStatus：验证响应状态的回调函数。
receiveDataWhenStatusError：当响应状态错误时是否接收数据。
followRedirects：是否跟随重定向。
maxRedirects：最大重定向次数。
persistentConnection：是否使用持久连接。
requestEncoder：请求数据的编码器。
responseDecoder：响应数据的解码器。
listFormat：列表数据的格式。

RequestOptions 还包含了一些方法，如 copyWith，用于创建一个新的 RequestOptions 对象，并在复制属性时进行一些修改。

这个类提供了许多配置选项，用于定制 HTTP 请求的各个方面，包括请求头部、超时时间、数据类型等。通过实例化 RequestOptions 对象，并设置相应的属性，可以构建出符合需求的 HTTP 请求配置。

以上是对 RequestOptions 类的简要分析，希望能对你理解 Dio 库的使用有所帮助。

ProgressCallback

typedef ProgressCallback = void Function(int count, int total);

ProgressCallback 是 Dio 库中定义的一个回调函数类型。用于监听发送或接收数据的进度。

该回调函数具有两个参数：

count：已发送或已接收的字节数。
total：请求体或响应体的总长度。

当用于发送数据时：

total 表示请求体的长度。

当用于接收数据时：

如果响应体的大小事先不可知，比如响应数据经过 gzip 压缩或没有 content-length 头部，那么 total 的值将为 -1。

文章版权归作者所有，未经允许请勿转载，侵权请联系 admin@trc20.tw 删除。

THE END

前端
# 前端

Dio网络请求框架之_RequestConfig、OptionsMixin、RequestOptions源码分析(一)