Flutter Http库Dio 2.1正式发布

12,702 阅读6分钟

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

从1.0发布至今,Dio受到了大量国内外开发者的关注,用户遍布世界各地。在受到开发者肯定的同时也收到了很多建议,为了让Dio功能更强大、更易用,我们综合了1.0中的各种反馈,在2.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.x中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.responseTypeResponseType.stream 来接收响应流,然后再通过读取响应流来获取完整的二进制内容,而2.x中只需要设置为ResponseType.bytes,则可直接获得响应流的而精致数组。

  5. API统一添加了onSendProgressonReceiveProgress 两个回调,用于监听发送数据和接收数据的具体精度,在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中添加了一些关于重定向信息的字段,有isRedirectredirectsrealUri

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: 重定向最大次数。