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