Http请求-Dio package

Dio

通过上一节介绍，我们可以发现直接使用HttpClient发起网络请求是比较麻烦的，很多事情得我们手动处理，如果再涉及到

• 文件上传/下载
• Cookie管理等

就会非常繁琐。幸运的是，Dart社区有一些第三方http请求库，用它们来发起http请求将会简单的多，本节我们介绍一下目前人气较高的dio库

• dio是一个强大的Dart Http请求库，支持Restful API、FormData、拦截器、请求取消、Cookie管理、文件上传/下载、超时、自定义适配器等…
• dio的使用方式随着其版本升级可能会发生变化，如果本节所述内容和dio官方有差异，请以dio官方文档为准
• 以下版本为English,点击查看中文简体

添加依赖

dependencies:
  dio: 3.0.9 #// 请使用pub上3.0.0分支的最新版本 latest version

dio 3.0.0为了支持Flutter Web，需要进行较大重构，因此无法直接兼容2.1.x， 如果你是2.1.x的用户，可以参照此文档升级到3.0，详情请查看 从2.1升级到3.0指南 。

一个极简的示例

import 'package:dio/dio.dart';
void getHttp() async {
  try {
    Response response = await Dio().get("http://www.google.com");
    print(response);
  } catch (e) {
    print(e);
  }
}

相关插件

🎉 A curated list of awesome things related to dio.

Plugins	Status	Description
dio_cookie_manager		A cookie manager for Dio
dio_http2_adapter		A Dio HttpClientAdapter which support Http/2.0
dio_flutter_transformer		A Dio transformer especially for flutter, by which the json decoding will be in background with compute function.
dio_http_cache		A cache library for Dio, like Rxcache in Android. dio-http-cache uses sqflite as disk cache, and LRU strategy as memory cache.
retrofit		retrofit.dart is an dio client generator using source_gen and inspired by Chopper and Retrofit.

Welcome to submit Dio’s third-party plugins and related libraries here

Examples

发起一个 GET 请求

Response response;
Dio dio = new Dio();
response = await dio.get("/test?id=12&name=wendu");
print(response.data.toString());
// Optionally the request above could also be done as
response = await dio.get("/test", queryParameters: {"id": 12, "name": "wendu"});
print(response.data.toString());

发起一个 POST 请求

response = await dio.post("/test", data: {"id": 12, "name": "wendu"});

发起多个并发请求

response = await Future.wait([dio.post("/info"), dio.get("/token")]);

下载文件

response = await dio.download("https://www.google.com/", "./xx.html");

以流的方式接收响应数据

Response<ResponseBody> rs = await Dio().get<ResponseBody>(url,
 options: Options(responseType: ResponseType.stream), //设置接收类型为stream
);
print(rs.data.stream); //response stream

以二进制数组的方式接收响应数据：

Response<List<int>> rs = await Dio().get<List<int>>(url,
 options: Options(responseType: ResponseType.bytes), // // set responseType to `bytes`
);
print(rs.data); // List<int>

发送 FormData

FormData formData = new FormData.fromMap({
    "name": "wendux",
    "age": 25,
  });
response = await dio.post("/info", data: formData);

通过FormData上传多个文件

FormData formData = FormData.fromMap({
    "name": "wendux",
    "age": 25,
    "file": await MultipartFile.fromFile("./text.txt",filename: "upload.txt"),
    "files": [
      await MultipartFile.fromFile("./text1.txt", filename: "text1.txt"),
      await MultipartFile.fromFile("./text2.txt", filename: "text2.txt"),
    ]
});
response = await dio.post("/info", data: formData);

监听发送(上传)数据进度

response = await dio.post(
  "http://www.dtworkroom.com/doris/1/2.0.0/test",
  data: {"aa": "bb" * 22},
  onSendProgress: (int sent, int total) {
    print("$sent $total");
  },
);

以流的形式提交二进制数据

// Binary data
List<int> postData = <int>[...];
await dio.post(
  url,
  data: Stream.fromIterable(postData.map((e) => [e])), //create a Stream<List<int>>
  options: Options(
    headers: {
      Headers.contentLengthHeader: postData.length, // set content-length
    },
  ),
);

Dio APIs

创建一个Dio实例，并配置它

建议在项目中使用Dio单例，这样便可对同一个dio实例发起的所有请求进行一些统一的配置，比如设置公共header、请求基地址、超时时间等；这里有一个在Flutter工程中使用Dio单例（定义为top level变量）的示例供开发者参考。

你可以使用默认配置或传递一个可选 BaseOptions参数来创建一个Dio实例 :

Dio dio = new Dio(); // with default Options
// Set default configs
dio.options.baseUrl = "https://www.xx.com/api";
dio.options.connectTimeout = 5000; //5s
dio.options.receiveTimeout = 3000;
// or new Dio with a BaseOptions instance.
BaseOptions options = new BaseOptions(
    baseUrl: "https://www.xx.com/api",
    connectTimeout: 5000,
    receiveTimeout: 3000,
);
Dio dio = new Dio(options);

Dio实例的核心API

Future request(String path,
{data,
Map queryParameters,
Options options,
CancelToken cancelToken,
ProgressCallback onSendProgress,
ProgressCallback onReceiveProgress})

response=await request(
    "/test",
    data: {"id":12,"name":"xx"},
    options: Options(method:"GET"),
);

请求方法别名

为了方便使用，Dio提供了一些其它的Restful API, 这些API都是request的别名

Future get(...)
Future post(...)
Future put(...)
Future delete(...)
Future head(...)
Future put(...)
Future path(...)
Future download(...)

请求配置

BaseOptions描述的是Dio实例发起网络请求的的公共配置，而Options类描述了每一个Http请求的配置信息，每一次请求都可以单独配置，单次请求的Options中的配置信息可以覆盖BaseOptions中的配置，下面是BaseOptions的配置项：

{
  /// Http method.
  String method;
  /// 请求基地址,可以包含子路径，如: "https://www.google.com/api/".
  String baseUrl;
  /// Http请求头.
  Map<String, dynamic> headers;
  /// 连接服务器超时时间，单位是毫秒.
  int connectTimeout;
  /// 2.x中为接收数据的最长时限.
  int receiveTimeout;
  /// 请求路径，如果 `path` 以 "http(s)"开始, 则 `baseURL` 会被忽略； 否则,
  /// 将会和baseUrl拼接出完整的的url.
  String path = "";
  /// 请求的Content-Type，默认值是"application/json; charset=utf-8".
  /// 如果您想以"application/x-www-form-urlencoded"格式编码请求数据,
  /// 可以设置此选项为 `Headers.formUrlEncodedContentType`,  这样[Dio]
  /// 就会自动编码请求体.
  String contentType;
  /// [responseType] 表示期望以那种格式(方式)接受响应数据。
  /// 目前 [ResponseType] 接受三种类型 `JSON`, `STREAM`, `PLAIN`.
  ///
  /// 默认值是 `JSON`, 当响应头中content-type为"application/json"时，dio 会自动将响应内容转化为json对象。
  /// 如果想以二进制方式接受响应数据，如下载一个二进制文件，那么可以使用 `STREAM`.
  ///
  /// 如果想以文本(字符串)格式接收响应数据，请使用 `PLAIN`.
  ResponseType responseType;
  /// `validateStatus` 决定http响应状态码是否被dio视为请求成功， 返回`validateStatus`
  ///  返回`true` , 请求结果就会按成功处理，否则会按失败处理.
  ValidateStatus validateStatus;
  /// 用户自定义字段，可以在 [Interceptor]、[Transformer] 和 [Response] 中取到.
  Map<String, dynamic> extra;
  /// Common query parameters
  Map<String, dynamic /*String|Iterable<String>*/ > queryParameters;
}

这里有一个完成的示例.

import 'dart:io';
import 'package:dio/dio.dart';
main() async {
  Response response;
  var dio = Dio(BaseOptions(
    baseUrl: "http://httpbin.org/",
    connectTimeout: 5000,
    receiveTimeout: 100000,
    // 5s
    headers: {
      HttpHeaders.userAgentHeader: "dio",
      "api": "1.0.0",
    },
    contentType: Headers.jsonContentType,
    // Transform the response data to a String encoded with UTF8.
    // The default value is [ResponseType.JSON].
    responseType: ResponseType.plain,
  ));
  response = await dio.get("/get");
  print(response.data);
  Response<Map> responseMap = await dio.get(
    "/get",
    // Transform response data to Json Map
    options: Options(responseType: ResponseType.json),
  );
  print(responseMap.data);
  response = await dio.post(
    "/post",
    data: {
      "id": 8,
      "info": {"name": "wendux", "age": 25}
    },
    // Send data with "application/x-www-form-urlencoded" format
    options: Options(
      contentType: Headers.formUrlEncodedContentType,
    ),
  );
  print(response.data);
  response = await dio.request(
    "/",
    options: RequestOptions(baseUrl: "https://baidu.com"),
  );
  print(response.data);
}

响应数据

当请求成功时会返回一个Response对象，它包含如下字段：

{
  /// 响应数据，可能已经被转换了类型, 详情请参考Options中的[ResponseType].
  T data;
  /// 响应头
  Headers headers;
  /// 本次请求信息
  Options request;
  /// Http status code.
  int statusCode;
  /// 是否重定向(Flutter Web不可用)
  bool isRedirect;
  /// 重定向信息(Flutter Web不可用)
  List<RedirectInfo> redirects ;
  /// 真正请求的url(重定向最终的uri)
  Uri realUri;
  /// 响应对象的自定义字段（可以在拦截器中设置它），调用方可以在`then`中获取.
  Map<String, dynamic> extra;
}

When request is succeed, you will receive the response as follows:

Response response = await dio.get("https://www.google.com");
print(response.data);
print(response.headers);
print(response.request);
print(response.statusCode);

拦截器

每个 Dio 实例都可以添加任意多个拦截器，他们组成一个队列，拦截器队列的执行顺序是FIFO。通过拦截器你可以在请求之前或响应之后(但还没有被 then 或 catchError处理)做一些统一的预处理操作。

dio.interceptors.add(InterceptorsWrapper(
    onRequest:(RequestOptions options) async {
     // 在请求被发送之前做一些事情
     return options; //continue
     // 如果你想完成请求并返回一些自定义数据，可以返回一个`Response`对象或返回`dio.resolve(data)`。
     // 这样请求将会被终止，上层then会被调用，then中返回的数据将是你的自定义数据data.
     //
     // 如果你想终止请求并触发一个错误,你可以返回一个`DioError`对象，或返回`dio.reject(errMsg)`，
     // 这样请求将被中止并触发异常，上层catchError会被调用。
    },
    onResponse:(Response response) async {
     // 在返回响应数据之前做一些预处理
     return response; // continue
    },
    onError: (DioError e) async {
      // 当请求失败时做一些预处理
     return e;//continue
    }
));

一个简单的自定义拦截器示例:

import 'package:dio/dio.dart';
class CustomInterceptors extends InterceptorsWrapper {
  @override
  Future onRequest(RequestOptions options) {
    print("REQUEST[${options?.method}] => PATH: ${options?.path}");
    return super.onRequest(options);
  }
  @override
  Future onResponse(Response response) {
    print("RESPONSE[${response?.statusCode}] => PATH: ${response?.request?.path}");
    return super.onResponse(response);
  }
  @override
  Future onError(DioError err) {
    print("ERROR[${err?.response?.statusCode}] => PATH: ${err?.request?.path}");
    return super.onError(err);
  }
}

完成和终止请求/响应

在所有拦截器中，你都可以改变请求执行流， 如果你想完成请求/响应并返回自定义数据，你可以返回一个 Response 对象或返回 dio.resolve(data)的结果。 如果你想终止(触发一个错误，上层catchError会被调用)一个请求/响应，那么可以返回一个DioError 对象或返回 dio.reject(errMsg)的结果.

import 'dart:io';
import 'package:dio/dio.dart';
main() async {
  Dio dio = new Dio();
  dio.interceptors.add(InterceptorsWrapper(
    onRequest: (RequestOptions options) {
      if (options.path == '/vip') {
        return dio.resolve("暂时不支持【/vip】的请求");
      }
    },
  ));
  Response response = await dio.get("/vip");
  print(response.data); //"fake data"
}

拦截器中支持异步任务

拦截器中不仅支持同步任务，而且也支持异步任务, 下面是在请求拦截器中发起异步任务的一个实例:

dio.interceptors.add(InterceptorsWrapper(
    onRequest:(Options options) async{
        //...If no token, request token firstly.
        Response response = await dio.get("/token");
        //Set the token to headers
        options.headers["token"] = response.data["data"]["token"];
        return options; //continue
    }
));

Lock/unlock 拦截器

你可以通过调用拦截器的 lock()/unlock方法来锁定/解锁拦截器。一旦请求/响应拦截器被锁定，接下来的请求/响应将会在进入请求/响应拦截器之前排队等待，直到解锁后，这些入队的请求才会继续执行(进入拦截器)。这在一些需要串行化请求/响应的场景中非常实用，后面我们将给出一个示例。

tokenDio = new Dio(); //Create a new instance to request the token.
tokenDio.options = dio;
dio.interceptors.add(InterceptorsWrapper(
    onRequest:(Options options) async {
        // If no token, request token firstly and lock this interceptor
        // to prevent other request enter this interceptor.
        dio.interceptors.requestLock.lock();
        // We use a new Dio(to avoid dead lock) instance to request token.
        Response response = await tokenDio.get("/token");
        //Set the token to headers
        options.headers["token"] = response.data["data"]["token"];
        dio.interceptors.requestLock.unlock();
        return options; //continue
    }
));

You can clean the waiting queue by calling ;

Clear()

你也可以调用拦截器的clear()方法来清空等待队列

别名

当请求拦截器被锁定时，接下来的请求将会暂停，这等价于锁住了dio实例，因此，Dio示例上提供了请求拦截器lock/unlock的别名方法：

dio.lock() == dio.interceptors.requestLock.lock()
dio.unlock() == dio.interceptors.requestLock.unlock()
dio.clear() == dio.interceptors.requestLock.clear()

Example

假设这么一个场景：出于安全原因，我们需要给所有的请求头中添加一个csrfToken，如果csrfToken不存在，我们先去请求csrfToken，获取到csrfToken后，再发起后续请求。 由于请求csrfToken的过程是异步的，我们需要在请求过程中锁定后续请求（因为它们需要csrfToken), 直到csrfToken请求成功后，再解锁，代码如下：

dio.interceptors.add(InterceptorsWrapper(
    onRequest: (Options options) async {
        print('send request：path:${options.path}，baseURL:${options.baseUrl}');
        if (csrfToken == null) {
            print("no token，request token firstly...");
            //lock the dio.
            dio.lock();
            return tokenDio.get("/token").then((d) {
                options.headers["csrfToken"] = csrfToken = d.data['data']['token'];
                print("request token succeed, value: " + d.data['data']['token']);
                print(
                    'continue to perform request：path:${options.path}，baseURL:${options.path}');
                return options;
            }).whenComplete(() => dio.unlock()); // unlock the dio
        } else {
            options.headers["csrfToken"] = csrfToken;
            return options;
        }
    }
));

完整的示例在下面，或者代码请点击 这里.

import 'dart:async';
import 'package:dio/dio.dart';
main() async {
  Dio dio = Dio();
  //  dio instance to request token
  Dio tokenDio = Dio();
  String csrfToken;
  dio.options.baseUrl = "http://www.dtworkroom.com/doris/1/2.0.0/";
  tokenDio.options = dio.options;
  dio.interceptors.add(InterceptorsWrapper(onRequest: (RequestOptions options) {
    print('send request：path:${options.path}，baseURL:${options.baseUrl}');
    if (csrfToken == null) {
      print("no token，request token firstly...");
      dio.lock();
      //print(dio.interceptors.requestLock.locked);
      return tokenDio.get("/token").then((d) {
        options.headers["csrfToken"] = csrfToken = d.data['data']['token'];
        print("request token succeed, value: " + d.data['data']['token']);
        print(
            'continue to perform request：path:${options.path}，baseURL:${options.path}');
        return options;
      }).whenComplete(() => dio.unlock()); // unlock the dio
    } else {
      options.headers["csrfToken"] = csrfToken;
      return options;
    }
  }, onError: (DioError error) {
    //print(error);
    // Assume 401 stands for token expired
    if (error.response?.statusCode == 401) {
      RequestOptions options = error.response.request;
      // If the token has been updated, repeat directly.
      if (csrfToken != options.headers["csrfToken"]) {
        options.headers["csrfToken"] = csrfToken;
        //repeat
        return dio.request(options.path, options: options);
      }
      // update token and repeat
      // Lock to block the incoming request until the token updated
      dio.lock();
      dio.interceptors.responseLock.lock();
      dio.interceptors.errorLock.lock();
      return tokenDio.get("/token").then((d) {
        //update csrfToken
        options.headers["csrfToken"] = csrfToken = d.data['data']['token'];
      }).whenComplete(() {
        dio.unlock();
        dio.interceptors.responseLock.unlock();
        dio.interceptors.errorLock.unlock();
      }).then((e) {
        //repeat
        return dio.request(options.path, options: options);
      });
    }
    return error;
  }));
  _onResult(d) {
    print("request ok!");
  }
  await Future.wait([
    dio.get("/test?tag=1").then(_onResult),
    dio.get("/test?tag=2").then(_onResult),
    dio.get("/test?tag=3").then(_onResult)
  ]);
}

日志

我们可以添加LogInterceptor拦截器来自动打印请求、响应日志, 如:

dio.interceptors.add(LogInterceptor(responseBody: false)); //开启请求日志

由于拦截器队列的执行顺序是FIFO，如果把log拦截器添加到了最前面，则后面拦截器对options的更改就不会被打印（但依然会生效）， 所以建议把log拦截添加到队尾。

Cookie管理

dio_cookie_manager 包是Dio的一个插件，它提供了一个Cookie管理器

import 'package:dio/dio.dart';
import 'package:dio_cookie_manager/dio_cookie_manager.dart';
import 'package:cookie_jar/cookie_jar.dart';
main() async {
  var dio =  Dio();
  var cookieJar=CookieJar();
  dio.interceptors.add(CookieManager(cookieJar));
  // Print cookies
  print(cookieJar.loadForRequest(Uri.parse("https://baidu.com/")));
  // second request with the cookie
  await dio.get("https://baidu.com/");
  ... 
}

自定义拦截器

开发者可以通过继承 类来实现自定义拦截器，这是一个简单的缓存示例拦截器。

错误处理

当请求过程中发生错误时, Dio 会包装 Error/Exception 为一个 DioError

try {
    //404
    await dio.get("https://wendux.github.io/xsddddd");
} on DioError catch(e) {
    // The request was made and the server responded with a status code
    // that falls out of the range of 2xx and is also not 304.
    if(e.response) {
        print(e.response.data)
        print(e.response.headers)
        print(e.response.request)
    } else{
        // Something happened in setting up or sending the request that triggered an Error
        print(e.request)
        print(e.message)
    }
}

DioError 字段

 {
  /// Request info.
  RequestOptions request;

  /// Response info, it may be `null` if the request can't reach to
  /// the http server, for example, occurring a dns error, network is not available.
  Response response;

  /// 错误类型，见下文
  DioErrorType type;

  ///原始的error或exception对象，通常type为DEFAULT时存在。
  dynamic error;
}

DioErrorType

enum DioErrorType {
  /// When opening  url timeout, it occurs.
  CONNECT_TIMEOUT,

  ///It occurs when receiving timeout.
  RECEIVE_TIMEOUT,

  /// When the server response, but with a incorrect status, such as 404, 503...
  RESPONSE,

  /// When the request is cancelled, dio will throw a error with this type.
  CANCEL,

  /// Default error type, Some other Error. In this case, you can
  /// read the DioError.error if it is not null.
  DEFAULT,
}

使用application/x-www-form-urlencoded编码

默认情况下, Dio 会将请求数据(除过String类型)序列化为 JSON. 如果想要以 application/x-www-form-urlencoded格式编码, 你可以显式设置contentType :

//Instance level
dio.options.contentType= Headers.formUrlEncodedContentType;
//or works once
dio.post("/info", data:{"id":5}, 
         options: Options(contentType:Headers.formUrlEncodedContentType ));

FormData

您也可以使用Dio发送form data，它将在multipart/form-data中发送数据，并且它支持上载文件

FormData formData = FormData.fromMap({
    "name": "wendux",
    "age": 25,
    "file": await MultipartFile.fromFile("./text.txt",filename: "upload.txt")
});
response = await dio.post("/info", data: formData);

There is a complete example here.

import 'dart:convert';
import 'dart:io';
import 'package:dio/dio.dart';
import 'package:dio/adapter.dart';

void showProgress(received, total) {
  if (total != -1) {
    print((received / total * 100).toStringAsFixed(0) + "%");
  }
}

Future<FormData> FormData1() async {
  return FormData.fromMap({
    "name": "wendux",
    "age": 25,
    "file":
        await MultipartFile.fromFile("./example/xx.png", filename: "xx.png"),
    "files": [
      await MultipartFile.fromFile("./example/upload.txt",
          filename: "upload.txt"),
      MultipartFile.fromFileSync("./example/upload.txt",
          filename: "upload.txt"),
    ]
  });
}

Future<FormData> FormData2() async {
  var formData = FormData();
  formData.fields..add(MapEntry("name", "wendux"))..add(MapEntry("age", "25"));

  formData.files.add(MapEntry(
    "file",
    await MultipartFile.fromFile("./example/xx.png", filename: "xx.png"),
  ));

  formData.files.addAll([
    MapEntry(
      "files[]",
      await MultipartFile.fromFile("./example/upload.txt",
          filename: "upload.txt"),
    ),
    MapEntry(
      "files[]",
      MultipartFile.fromFileSync("./example/upload.txt",
          filename: "upload.txt"),
    ),
  ]);
  return formData;
}

Future<FormData> FormData3() async {
  return FormData.fromMap({
    "file": await MultipartFile.fromFile("./example/upload.txt",
        filename: "uploadfile"),
  });
}

/// FormData will create readable "multipart/form-data" streams.
/// It can be used to submit forms and file uploads to http server.
main() async {
  var dio = Dio();
  dio.options.baseUrl = "http://localhost:3000/";
  dio.interceptors.add(LogInterceptor());
  //dio.interceptors.add(LogInterceptor(requestBody: true));
  (dio.httpClientAdapter as DefaultHttpClientAdapter).onHttpClientCreate =
      (HttpClient client) {
    client.findProxy = (uri) {
      //proxy all request to localhost:8888
      return "PROXY localhost:8888";
    };
    client.badCertificateCallback =
        (X509Certificate cert, String host, int port) => true;
  };
  Response response;

  var formData1 = await FormData1();
  var formData2 = await FormData2();
  var bytes1 = await formData1.readAsBytes();
  var bytes2 = await formData2.readAsBytes();
  assert(bytes1.length == bytes2.length);

  var t = await FormData3();
  print(utf8.decode(await t.readAsBytes()));

  response = await dio.post(
    //"/upload",
    "http://localhost:3000/upload",
    data: await FormData3(),
    onSendProgress: (received, total) {
      if (total != -1) {
        print((received / total * 100).toStringAsFixed(0) + "%");
      }
    },
  );
  print(response);
}

多文件上传

多文件上传时，通过给key加中括号“[]”方式作为文件数组的标记，大多数后台也会通过key[]这种方式来读取。不过RFC中并没有规定多文件上传就必须得加“[]”，所以有时不带“[]”也是可以的，关键在于后台和客户端得一致
v3.0.0 以后通过Formdata.fromMap()创建的Formdata,如果有文件数组，是默认会给key加上“[]”的，比如：

  FormData.fromMap({
    "files": [
      MultipartFile.fromFileSync("./example/upload.txt",
          filename: "upload.txt"),
      MultipartFile.fromFileSync("./example/upload.txt",
          filename: "upload.txt"),
    ]
  });

最终编码时会key会为 “files[]”，如果不想添加“[]”，可以通过Formdata的API来构建：

  var formData = FormData();
  formData.files.addAll([
    MapEntry(
      "files",
       MultipartFile.fromFileSync("./example/upload.txt",
          filename: "upload.txt"),
    ),
    MapEntry(
      "files",
      MultipartFile.fromFileSync("./example/upload.txt",
          filename: "upload.txt"),
    ),
  ]);

转换器

转换器Transformer 用于对请求数据和响应数据进行编解码处理。Dio实现了一个默认转换器DefaultTransformer作为默认的 Transformer.
如果你想对请求/响应数据进行自定义编解码处理，可以提供自定义转换器，通过dio.transformer设置。

请求转换器 Transformer.transformRequest(…) 只会被用于 ‘PUT’、 ‘POST’、 ‘PATCH’方法，因为只有这些方法才可以携带请求体(request body)。但是响应转换器 Transformer.transformResponse() 会被用于所有请求方法的返回数据。

Flutter中设置

如果你在开发Flutter应用，强烈建议json的解码通过compute方法在后台进行，这样可以避免在解析复杂json时导致的UI卡顿。

注意，根据笔者实际测试，发现通过compute在后台解码json耗时比直接解码慢很多，建议开发者仔细评估。

// 必须是顶层函数
_parseAndDecode(String response) {
  return jsonDecode(response);
}

parseJson(String text) {
  return compute(_parseAndDecode, text);
}

void main() {
  ...
  // 自定义 jsonDecodeCallback
  (dio.transformer as DefaultTransformer).jsonDecodeCallback = parseJson;
  runApp(MyApp());
}

其它示例

这里有一个 自定义Transformer的示例.

import 'dart:async';
import 'package:dio/dio.dart';

/// If the request data is a `List` type, the [DefaultTransformer] will send data
/// by calling its `toString()` method. However, normally the List object is
/// not expected for request data( mostly need Map ). So we provide a custom
/// [Transformer] that will throw error when request data is a `List` type.
class MyTransformer extends DefaultTransformer {
  @override
  Future<String> transformRequest(RequestOptions options) async {
    if (options.data is List<String>) {
      throw DioError(error: "Can't send List to sever directly");
    } else {
      return super.transformRequest(options);
    }
  }

  /// The [Options] doesn't contain the cookie info. we add the cookie
  /// info to [Options.extra], and you can retrieve it in [ResponseInterceptor]
  /// and [Response] with `response.request.extra["cookies"]`.
  @override
  Future transformResponse(
      RequestOptions options, ResponseBody response) async {
    options.extra["self"] = 'XX';
    return super.transformResponse(options, response);
  }
}

main() async {
  var dio = Dio();
  // Use custom Transformer
  dio.transformer = MyTransformer();

  Response response = await dio.get("https://www.baidu.com");
  print(response.request.extra["self"]);

  try {
    await dio.post("https://www.baidu.com", data: ["1", "2"]);
  } catch (e) {
    print(e);
  }
  print("xxx");
}

执行流

虽然在拦截器中也可以对数据进行预处理，但是转换器主要职责是对请求/响应数据进行编解码，之所以将转化器单独分离，

• 一是为了和拦截器解耦
• 二是为了不修改原始请求数据(如果你在拦截器中修改请求数据(options.data)，会覆盖原始请求数据，而在某些时候您可能需要原始请求数据)

Dio的请求流是：
请求拦截器 => 请求转换器 => 发起请求 => 响应转换器=>响应拦截器 => 最终结果。
这是一个自定义转换器的示例

HttpClientAdapter

HttpClientAdapter是 Dio 和 HttpClient之间的桥梁。2.0抽象出adapter主要是方便切换、定制底层网络库

• Dio实现了一套标准的、强大API，而HttpClient则是真正发起Http请求的对象。
• 我们通过HttpClientAdapter将Dio和HttpClient解耦，这样一来便可以自由定制Http请求的底层实现，比如，
  • 在Flutter中我们可以通过自定义HttpClientAdapter将Http请求转发到Native中，然后再由Native统一发起请求
  • 再比如，假如有一天OKHttp提供了dart版，你想使用OKHttp发起http请求，那么你便可以通过适配器来无缝切换到OKHttp，而不用改之前的代码。

    Dio 使用DefaultHttpClientAdapter作为其默认HttpClientAdapter，DefaultHttpClientAdapter使用dart:io:HttpClient 来发起网络请求

dio.httpClientAdapter = new DefaultHttpClientAdapter();

Here is a simple example to custom adapter.

import 'dart:async';
import 'package:dio/dio.dart';
import 'package:dio/adapter.dart';

class MyAdapter extends HttpClientAdapter {
  DefaultHttpClientAdapter _adapter = DefaultHttpClientAdapter();

  @override
  Future<ResponseBody> fetch(RequestOptions options,
      Stream<List<int>> requestStream, Future cancelFuture) async {
    Uri uri = options.uri;
    // hook requests to  google.com
    if (uri.host == "google.com") {
      return ResponseBody.fromString("Too young too simple!", 200);
    }
    return _adapter.fetch(options, requestStream, cancelFuture);
  }

  @override
  void close({bool force = false}) {
    _adapter.close(force: force);
  }
}

main() async {
  var dio = Dio();
  dio.httpClientAdapter = MyAdapter();
  Response response = await dio.get("https://google.com");
  print(response);
  response = await dio.get("https://baidu.com");
  print(response);
}

设置Http代理

DefaultHttpClientAdapter 提供了一个onHttpClientCreate 回调来设置底层 dart:io:HttpClient的代理，我们想使用代理，可以参考下面代码：

import 'package:dio/dio.dart';
import 'package:dio/adapter.dart';
...
(dio.httpClientAdapter as DefaultHttpClientAdapter).onHttpClientCreate = (client) {
    // config the http client
    client.findProxy = (uri) {
        //proxy all request to localhost:8888
        return "PROXY localhost:8888";
    };
    // you can also create a HttpClient to dio
    // return HttpClient();
};

完整的示例请查看这里.

Https证书校验

有两种方法可以校验https证书，假设我们的后台服务使用的是自签名证书，证书格式是PEM格式，我们将证书的内容保存在本地字符串中，那么我们的校验逻辑如下：

String PEM="XXXXX"; // certificate content
(dio.httpClientAdapter as DefaultHttpClientAdapter).onHttpClientCreate  = (client) {
    client.badCertificateCallback=(X509Certificate cert, String host, int port){
        if(cert.pem==PEM){ // Verify the certificate
            return true;
        }
        return false;
    };
};

X509Certificate是证书的标准格式，包含了证书除私钥外所有信息，读者可以自行查阅文档。另外，上面的示例没有校验host，是因为只要服务器返回的证书内容和本地的保存一致就已经能证明是我们的服务器了（而不是中间人），host验证通常是为了防止证书和域名不匹配。
对于自签名的证书，我们也可以将其添加到本地证书信任链中，这样证书验证时就会自动通过，而不会再走到badCertificateCallback回调中：

(dio.httpClientAdapter as DefaultHttpClientAdapter).onHttpClientCreate  = (client) {
    SecurityContext sc = SecurityContext();
    //file is the path of certificate
    sc.setTrustedCertificates(file);
    HttpClient httpClient = HttpClient(context: sc);
    return httpClient;
};

注意，通过setTrustedCertificates()设置的证书格式必须为PEM或PKCS12，如果证书格式为PKCS12，则需将证书密码传入，这样则会在代码中暴露证书密码，所以客户端证书校验不建议使用PKCS12格式的证书。

请求取消

你可以通过cancel token来取消发起的请求：

CancelToken token = CancelToken();
dio.get(url, cancelToken: token)
    .catchError((DioError err){
        if (CancelToken.isCancel(err)) {
            print('Request canceled! '+ err.message)
        }else{
            // handle error.
        }
    });
// cancel the requests with "cancelled" message.
token.cancel("cancelled");

注意: 同一个cancel token 可以用于多个请求，当一个cancel token取消时，所有使用该cancel token的请求都会被取消。

完整的示例请参考取消示例.

import 'dart:async';
import 'package:dio/dio.dart';

main() async {
  var dio = Dio();
  dio.interceptors.add(LogInterceptor());
  // Token can be shared with different requests.
  CancelToken token = CancelToken();
  // In one minute, we cancel!
  Timer(Duration(milliseconds: 500), () {
    token.cancel("cancelled");
  });

  // The follow three requests with the same token.
  var url1 = "https://www.google.com";
  var url2 = "https://www.facebook.com";
  var url3 = "https://www.baidu.com";

  await Future.wait([
    dio
        .get(url1, cancelToken: token)
        .then((response) => print('${response.request.path}: succeed!'))
        .catchError(
      (e) {
        if (CancelToken.isCancel(e)) {
          print('$url1: $e');
        }
      },
    ),
    dio
        .get(url2, cancelToken: token)
        .then((response) => print('${response.request.path}: succeed!'))
        .catchError((e) {
      if (CancelToken.isCancel(e)) {
        print('$url2: $e');
      }
    }),
    dio
        .get(url3, cancelToken: token)
        .then((response) => print('${response.request.path}: succeed!'))
        .catchError((e) {
      if (CancelToken.isCancel(e)) {
        print('$url3: $e');
      }
      print(e);
    })
  ]);
}

继承 Dio class

Dio 是一个拥有factory 构造函数的接口类，因此不能直接继承 Dio ，但是可以通过 DioForNative 或DioForBrowser 来间接实现:

import 'package:dio/dio.dart';
import 'package:dio/native_imp.dart'; //在浏览器中, import 'package:dio/browser_imp.dart'
class Http extends DioForNative {
  Http([BaseOptions options]):super(options){
    // 构造函数做一些事
  }
}

我们也可以直接实现 Dio接口类 :

class MyDio with DioMixin implements Dio{
  // ...
}

示例目录

你可以在这里查看dio的全部示例.

实例

我们通过Github开放的API来请求flutterchina组织下的所有公开的开源项目，实现：

1. 在请求阶段弹出loading
2. 请求结束后，如果请求失败，则展示错误信息；如果成功，则将项目名称列表展示出来。

代码如下：

import 'package:dio/dio.dart';
import 'package:flutter/material.dart';
void main() => runApp(new MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
        debugShowCheckedModeBanner: true,

        title: 'FutureBuilderRoute网络请求',

        theme: ThemeData(
          primarySwatch: Colors.blue,

        ),
        home: Scaffold(
          appBar: AppBar(title: Text("FutureBuilderRoute网络请求")),
          body: FutureBuilderRoute(),
        ));
  }
}

class FutureBuilderRoute extends StatefulWidget {
  FutureBuilderRoute({Key key}) : super(key: key);

  @override
  _FutureBuilderRouteState createState() => _FutureBuilderRouteState();
}


class _FutureBuilderRouteState extends State<FutureBuilderRoute> {
  Dio _dio = new Dio();
  @override
  Widget build(BuildContext context) {
    return new Container(
      alignment: Alignment.center,
      child: FutureBuilder(
          future: _dio.get("https://api.github.com/orgs/flutterchina/repos"),
          builder: (BuildContext context, AsyncSnapshot snapshot) {
            //请求完成
            if (snapshot.connectionState == ConnectionState.done) {
              Response response = snapshot.data;
              //发生错误
              if (snapshot.hasError) {
                return Text(snapshot.error.toString());
              }
              //请求成功，通过项目信息构建用于显示项目名称的ListView
              return ListView(
                children: response.data.map<Widget>((e) =>
                    ListTile(title: Text(e["full_name"]))
                ).toList(),
              );
            }
            //请求未完成时弹出loading
            return CircularProgressIndicator();
          }
      ),
    );
  }
}

Http2支持

dio_http2_adapter包提供了一个支持Http/2.0的Adapter，详情可以移步 dio_http2_adapter