Flutter Http库Dio 2.1正式发布

Flutter Http库Dio 2.1正式发布

Dio 是一个强大的Dart Http请求库，支持Restful API、FormData、拦截器、请求取消、Cookie管理、文件上传/下载、超时、自定义适配器等。目前Dio在pub上综合得分100分，排名已上榜pub首页(All Tab下) ！同时Dio也是Github上最受欢迎的Flutter第三方库，项目地址： Dio-Github。

在1.0发布至今，Dio受到了大量国内外开发者的关注，并收到了不少确定和建议。为了让Dio功能更强大、让开发者使用起来更容易，咱们综合了1.0中的各类反馈，对Dio进行了一次大的更新，为了让使用者在1.0和2.x之间有个过渡，咱们将2.0.x-2.1.0做为预发布版在全网进行了接近两个月的公测。如今，很高兴的告诉你们，2.x的功能已经收敛、质量已经稳定，所以，今天咱们正式发布Dio 2.x的第一个稳定版Dio v2.1.0。

相比1.x，2.x在Restful API、拦截器、FormData等不少地方都进行了扩展和调整，除了这些，Dio在2.x中还引入Adapter层，为Mock接口数据和自定义底层网络库提供了支持。总体功能相比1.x有了很大的提高，所以咱们强烈建议全部1.x用户都能升级到2.1。

Dio V2.1.x 变动列表

Restful API

2.1中对全部Restful API的变化有：

1. 支持Uri，在1.x中，Url只能是字符串，2.1中全部API都提供了对应支持Uri的版本，如get方法有dio.get(...)和dio.gerUri(...)。

2. 全部方法都支持queryParameters，2.1标准化了参数语义，并容许全部请求均可以传query，而data只针对能够提交请求体的方法如post做为请求体提交。另外相对于Uri.queryParameters，咱们对Restful API中的queryParameters的功能作了增强，主要有两个差别：

   • 参数值类型不一样；前者只能接受Map<String, String|Iterable<String>>类型的参数，然后者能够接受Map<String, dynamic>类型，好比:

     dio.getUri(Uri(url, queryParameters: {"age":15})) //会抛出异常，Uri.queryParameter的value不能是int类型
     dio.get(url, queryParameters: {"age":15}); //这是OK的！

   • 编码方式有所差别; Uri.queryParameters编码方式遵循Dart SDK中的规则，而Restful API中的queryParameters编码方式和jQuery一致，如：

     dio.options.baseUrl="http://domain.com/";
       
       //下面请求的最终uri为：http://domain.com/api?selectedId=1&selectedId=2
       Response response = await dio.getUri(
         Uri(path: "api",queryParameters:  {"selectedId": ["1", "2"],});
       );
       //下面请求的最终uri为：https://flutterchina.club?selectedId%5B%5D=1&selectedId%5B%5D=2
       dio.get("api",queryParameters: {"selectedId": ["1", "2"], });

3. 支持以Stream方式提交数据了；2.1中能够经过Stream的方式来提交二进制数据了，详细的示例能够参考这里。
4. 支持以二进制数组形式接收数据了；1.x中若是要以二进制形式接收响应数据则须要设置options.responseType为ResponseType.stream 来接收响应流，而后再经过读取响应流来获取完整的二进制内容，而2.x中只须要设置为ResponseType.bytes，则可直接得到响应流的而精致数组。
5. API统一添加了onSendProgress 和 onReceiveProgress 两个回调，用于监听发送数据和接收数据的具体精度，在1.x中只有在下载文件和上传formdata时才能监听进度，而2.x中全部接口均可以了。

拦截器

1. 支持设置多个拦截器；

   这样咱们就能够将一些功能单独抽离，好比打印请求/响应日志和cookie管理均可以单独封装在一个拦截器中，这样在解耦的同时能够提升代码的可复用度。

   2.1中拦截器是一个队列，拦截器将会按照FIFO顺序执行，若是队列中的某个拦截器返回了Response或Error，则请求结束，队列后面的拦截器将不会再被执行。

2. 预置了打印请求/响应日志的LogInterceptor和管理cookie的CookieManager拦截器，开发者能够按需使用，如：

   dio.interceptors
       ..add(LogInterceptor(responseBody: false))
       ..add(CookieManager(CookieJar()));

FormData

1.x中，在提交FormData时会先将FormData转成一个二进制数组，而后再提交，这在FormData中的数据量比较大时（如包含多个大文件）在上传的过程当中会比较占用内存。2.1中咱们队FormData进行了加强，给FormData添加一个stream属性，它能够将FormData转为一个stream，在提交时无需一次性加载到内存。

同时FormData也添加了asBytes() 、asBytesAsync()、length等方法、属性。

Response

Response中添加了一些关于重定向信息的字段，有isRedirect、redirects、realUri。

TransFormer

2.x中对于DefaultTransformer添加了一个jsonDecodeCallback，经过它能够定制json解码器，这在flutter中很是有用，咱们能够经过compute方法来在后台进行json解码，从而避免在UI线程对复杂json解码时引发的界面卡顿，详情请见这里 。

HttpClientAdapter

HttpClientAdapter是 Dio 和 HttpClient之间的桥梁。2.0抽象出了adapter层，能够带来两个主要收益：

1. 实现Dio于HttpClient的解耦，这样能够方便的切换、定制底层网络库。
2. 能够Mock数据；

Dio实现了一套标准的、强大API，而HttpClient则是真正发起Http请求的对象，二者并非固定的一对一关系，咱们彻底能够在使用Dio时经过其余网络库(而不只仅是dart HttpClient )来发起网络请求。咱们经过HttpClientAdapter将Dio和HttpClient解耦，这样一来即可以自由定制Http请求的底层实现，好比，在Flutter中咱们能够经过自定义HttpClientAdapter将Http请求转发到Native中，而后再由Native统一发起请求。再好比，假若有一天OKHttp提供了dart版，你想使用OKHttp发起http请求，那么你即可以经过适配器来无缝切换到OKHttp，而不用改以前的代码。

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

这里 有一个简单的自定义Adapter的示例，读者能够参考。另外本项目的自动化测试用例全都是经过一个自定义的MockAdapter来模拟服务器返回数据的。

Options

Options对象包含了对网络请求的配置，在1.x中不管是实例配置仍是单次请求的配置都使用的是Options 对象，这样会带来一些二义性，甚至有时会让开发者感到疑惑，好比Options.baseUrl属性表明请求基地址，理论上它只应该在实例配置中设置，而不该该出如今每次请求的配置中；再好比Options.path属性，它表明请求的相对路径，不该该在实例请求配置中。2.1中将请求配置分拆成三个类：

类名	做用
BaseOptions	Dio实例基配置，默认对该dio实例的全部请求生效
Options	单次请求配置，能够覆盖BaseOptions中的同名属性
RequestOptions	请求的最终配置，是对Option和BaseOptions合并后的

另外，添加了一些新的配置项：

1. cookies：能够添加一些公共cookie
2. receiveDataWhenStatusError：当响应状态码不是成功状态(如404)时，是否接收响应内容，若是是false,则response.data将会为null
3. maxRedirects: 重定向最大次数。