Skip to content
Permalink
Browse files

release v2.1

  • Loading branch information...
wendux committed Mar 12, 2019
1 parent 303ea44 commit 7e468a935056c98aef000e7c10576cba78c69f29
Showing with 124 additions and 8 deletions.
  1. +4 −2 README-ZH.md
  2. +1 −1 README.md
  3. +11 −1 example/test.dart
  4. +99 −0 migration_to_2.0.md
  5. +4 −2 package_src/README-ZH.md
  6. +1 −1 package_src/README.md
  7. +3 −0 package_src/lib/src/adapter.dart
  8. +1 −1 package_src/pubspec.yaml
@@ -15,10 +15,10 @@ dio是一个强大的Dart Http请求库,支持Restful API、FormData、拦截

```yaml
dependencies:
dio: ^2.0.x // 请使用pub上2.0分支的最新版本
dio: ^2.1.x // 请使用pub上2.1分支的最新版本
```

如果您是1.0的用户,可以参照此文档升级到2.0,详情请查看 [Change log](https://github.com/flutterchina/dio/blob/master/CHANGELOG.md) 。
如果您是1.0的用户,可以参照此文档升级到2.x,详情请查看 [1.x迁移至2.x指南](https://github.com/flutterchina/dio/blob/master/migration_to_2.0.md) 。

## 一个极简的示例

@@ -491,6 +491,8 @@ dio.interceptors.add(InterceptorsWrapper(
```dart
dio.interceptors.add(LogInterceptor(responseBody: false)); //开启请求日志
```
> 由于拦截器队列的执行顺序是FIFO,如果把log拦截器添加到了最前面,则后面拦截器对`options`的更改就不会被打印(但依然会生效), 所以建议把log拦截添加到队尾。

### Cookie管理

@@ -12,7 +12,7 @@ A powerful Http client for Dart, which supports Interceptors, Global configurati

```yaml
dependencies:
dio: 2.0.x #latest version
dio: 2.1.x #latest version
```
If you are using 1.0.x , this doc can help you upgrade to 2.0.x. [Change log](https://github.com/flutterchina/dio/blob/master/CHANGELOG.md)
## Super simple to use
@@ -5,7 +5,17 @@ main() async {
dio.interceptors.add(LogInterceptor(requestBody: true, requestHeader: true));
dio.options.connectTimeout=5000;
dio.options.receiveTimeout=5000;
dio.get("https://flutterchina.club");
dio.get("https://flutterchina.club",queryParameters: {
"selectedId": ["1", "2"],
},);

dio.options.baseUrl="http://domain.com/";
Response response = await dio.getUri(
Uri(path: "api",queryParameters: {
"selectedId": ["1", "2"],
})
);
//print(response);

// Response<List<int>> rs = await Dio().get<List<int>>(
// 'https://admin-test.shiguangkey.com/captcha.jpg',
@@ -0,0 +1,99 @@
# 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>`类型,比如:

```dart
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一致,如:

```dart
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的方式来提交二进制数据了,详细的示例可以参考[这里](https://github.com/flutterchina/dio/blob/master/example/post_stream_and_bytes.dart)。

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拦截器,开发者可以按需使用,如:

```dart
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解码时引起的界面卡顿,详情请见[这里](https://github.com/flutterchina/dio#in-flutter) 。

### 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` 来发起网络请求。

[这里](https://github.com/flutterchina/dio/blob/master/example/adapter.dart) 有一个简单的自定义Adapter的示例,读者可以参考。另外本项目的自动化测试用例全都是通过一个自定义的[MockAdapter](https://github.com/flutterchina/dio/blob/master/package_src/test/mock_adapter.dart)来模拟服务器返回数据的。

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

@@ -11,7 +11,7 @@ dio是一个强大的Dart Http请求库,支持Restful API、FormData、拦截

```yaml
dependencies:
dio: ^2.0.x // 请使用pub上2.0分支的最新版本
dio: ^2.1.x // 请使用pub上2.1分支的最新版本
```

如果您是1.0的用户,可以参照此文档升级到2.0,详情请查看 [Change log](https://github.com/flutterchina/dio/blob/master/CHANGELOG.md) 。
@@ -307,7 +307,7 @@ Dio实例的核心API是 :

## 拦截器

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

```dart
@@ -435,6 +435,8 @@ dio.interceptors.add(InterceptorsWrapper(
dio.interceptors.add(LogInterceptor(responseBody: false)); //开启请求日志
```

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

我们可以通过添加`CookieManager`拦截器来自动管理请求/响应 cookie。`CookieManager` 依赖 `cookieJar` package:
@@ -13,7 +13,7 @@ A powerful Http client for Dart, which supports Interceptors, Global configurati

```yaml
dependencies:
dio: 2.0.x #latest version
dio: 2.1.x #latest version
```
If you are using 1.0.x , this doc can help you upgrade to 2.0.x. [Change log](https://github.com/flutterchina/dio/blob/master/CHANGELOG.md)
## Super simple to use
@@ -61,6 +61,9 @@ class ResponseBody {
/// Http status code
int statusCode;

/// Returns the series of redirects this connection has been through. The
/// list will be empty if no redirects were followed. [redirects] will be
/// updated both in the case of an automatic and a manual redirect.
List<RedirectInfo> redirects = [];

Map<String, dynamic> extra={};
@@ -1,6 +1,6 @@
name: dio
description: A powerful Http client for Dart, which supports Interceptors, FormData, Request Cancellation, File Downloading, Timeout etc.
version: 2.0.23
version: 2.1.0
homepage: https://github.com/flutterchina/dio
author: wendux <824783146@qq.com>

0 comments on commit 7e468a9

Please sign in to comment.
You can’t perform that action at this time.