forest Releases

v1.4.0

2020-08-24 15:04

v1.4.0

v1.4.0正式版发布了！非常抱歉，由于新增功能比较多，正式版一直延期到现在。

相比1.3.x版本1.4.0版本多了以下这些特性：

* 文件上传
* 文件下载
* 文件上传、下载的进度监听
* 可扩展自定义注解，绑定拦截器，形成标签化拦截器
* `dataType`属性默认为`"auto"`，能自动识别返回数据的类型进行反序列化
* 重试机制，通过实现`Retryer`接口扩展重试策略，并也可通过`retyer`属性指定
* 基于退避算法的重试策略，并为默认重试策略
* 根据方法名前缀设置请求类型
* 添加`@Get`,`@GetRequest`,`@Post`,`@PostRequest`,`@Delete`,`@DeleteRequest`等注解方便简化请求接口的描述。
* 添加`@Query`,`@Body`, `@Header`注解，相比以前的`@DataParam`, `@DataObject`等注解意图更为清晰。

以下是相对于上个预览版本`1.4.0-RC4`更新内容

#### 新增的特性:

* feat: 在`ForestRequest`中添加`addBody`, `replaceBody`, `getArguments`方法
* feat: 上传文件无需指定`Content-Type`
* feat: `Header`注解修饰的参数
* feat: 发送`GET`请求可以带上`BODY`信息（仅在`Httpclient`后端下有效）
* feat: 添加`userAgent`属性

#### 修复的BUG:

* fix: Request注解的`url`为空字符串的情况
* fix: baseURL不含http://
* fix: baseUrl会自动删去 / 的问题
* fix: httpclient后端上传文件服务端500错误
* fix: contentType、contentEncoding、userAgent等属性为空的情况
* fix: Content-type和Content-Encoding的优先级问题
* fix: 不传递依赖spring boot starter
* fix: 从response头中获取Content-Encoding为空
* fix: FastJSON序列化Map的问题
* fix: 打印httpclient中get请求的body内容
* fix: 使FastJsonConverter支持顺序
* fix: Content-Type头失效
* fix: FastJson转换成Map时顺序无效

#### 代码变动:

* refactor: 转移MethodAnnotationLifeCycle和ParameterAnnotationLifeCycle的所在包
* refactor: 去掉ForestRequest中的setArguments方法
* refactor: MappingParameter.type字段改名成target字段
* refactor: 去掉MappingParameter.query字段，改成type字段
* refactor: httpclient的url builder统一用一套
* refactor: Query、Body、Header注解不强制填写value，可修饰对象参数
* refactor: 包装Httpclient的Get、Head、Options、Trace、Delete方法的Entity
* refactor: 包装Httpclient的Get、Head、Options、Trace、Delete方法的Entity
* refactor: Query不强制填写value，可修饰对象参数
* refactor: 去掉BodyObject和HeaderObject注解
* refactor: 所有内置注解通过可扩展方式实现

Last committed message: Merge branch 'dev' into gitee-master

Preview version

v1.4.0-RC4

0512409

2020-08-14 12:27

v1.4.0-RC4

Last committed message: refactor: rename AnnotationLifeCycle

Preview version

v1.4.0-RC2

6af0e9f

2020-08-11 14:35

v1.4.0-RC2

`v1.4.0-RC2`版本为预览版，下个版本就是正式版了。该版本新增了@DataQuery注解和@DataBody注解，根据方法名前缀设置请求类型，以及可以从`ForestReponse`对象中获取头信息。

#### @DataQuery注解和@DataBody注解

```java
@Request(
    url = "http://localhost:${port}/hello/user"
)
String send(@DataQuery("username") String username);
```
`@DataQuery`注解修饰的参数一定是出现在请求的`url`参数中。

```java
@Request(
    url = "http://localhost:${port}/complex",
    type = "post",
    headers = {"Accept:text/plan"}
)
String send(@DataQuery("param") String param,
                @DataBody("username") String username,
                @DataBody("password") String password);
```

`@DataBody`注解修饰的参数一定是出现在请求的`body`中。当然，像`GET`, `HEAD`这些不带请求体的方法除外。

#### 方法名前缀决定请求类型

```java

@Request(
    url = "http://localhost:${port}/hello",
    data = "username=foo&password=123456"
)
String getHello(); // GET请求

@Request(
    url = "http://localhost:${port}/hello",
    data = "username=foo&password=123456"
)
String postHello(); // POST请求

@Request(
    url = "http://localhost:${port}/hello",
    data = "username=foo&password=123456"
)
String putHello(); // PUT请求

@Request(
    url = "http://localhost:${port}/hello",
    data = "username=foo&password=123456"
)
String hello(); // 前缀什么都不匹配，type也没设置的情况下，还是GET请求
```

#### 新增特性:

feat: 根据方法名前缀设置请求类型
feat: 下载文件名默认先从URL中取
feat: 添加@DataQuery注解和@DataBody注解
feat: #I1QY77

#### 修复问题:

fix: 文件下载返回byte数组出错
fix: 变量[method]为null或之前判断过是否为null，但运行到此行时无法保证值为非空值，存在空指针异常隐患
fix: Move this call to "wait()" into a synchronized block to be sure the monitor on "this" is held.

#### 改动内容:

refactor: 去掉没被用到的SavingTrustManager内部类
refactor: 请求中的headers改成ForestHeaderMap类
add: ForestHeader和ForestHeaderMap类
add: NameUtils名称工具类
add: 文件下载进度条打印工具类

Last committed message: update: new version 1.4.0-RC2

Preview version

v1.4.0-RC1

b85f75e

2020-08-10 13:01

v1.4.0-RC1

`1.4.0-RC1`版本发布，该版本新增了针对文件下载进度监听，以及重试机制。

#### 下载进度监听

```java
@Request(url = "http://forspeed.onlinedown.net/down/QQliveSetup_20_731.exe")
@DownloadFile(dir = "${dir}", filename = "${filename}")
File downloadFile(@DataVariable("dir") String dir, @DataVariable("filename") String filename, OnProgress onProgress);
```

调用的时候用`Lambda`

```java
File file = downloadClient.downloadFile("D:\\TestDownload", "QQliveSetup_20_731.exe", progress -> {
    System.out.println("------------------------------------------");
    System.out.println("total bytes: " + progress.getTotalBytes());   // 文件大小
    System.out.println("current bytes: " + progress.getCurrentBytes());   // 已下载字节数
    System.out.println("progress: " + Math.round(progress.getRate() * 100) + "%");  // 已下载百分比
    if (progress.isDone()) {   // 是否下载完成
        System.out.println("--------   Download Completed!   --------");
    }
});

```

#### 重试机制:

在配置文件中加上:

```yaml
forest:
  retry-count: 3                          # 请求失败后重试次数
  max-retry-interval: 2000                # 请求重试之间最大间隔时间，单位为毫秒
```

如果针对的是某一个请求的重试配置，在@Request注解中配上:

```java
@Request(
        url = "http://localhost:${port}/hello/user?username=foo",
        retryCount = 3,
        maxRetryInterval = 2000)
String testRetry();
```

默认重试机制为`退避算法`。简单的说，它不是设置几次重试就直接重复调用请求，而是每次重试之间都会间隔一段时间，间隔的时间按`2`的`n`次方累进，`n`为重试的次数。不过最大间隔时间不能超过`maxRetryInterval`属性指定的最大间隔时间。

#### 新的特性:

* feat: 文件下载进度监听
* feat: 重试机制，通过实现Retryer接口扩展重试策略，并也可通过retyer属性指定
* feat: 基于退避算法的重试策略，并为默认重试策略
* feat: 自定义反序列化器，通过decoder属性指定

#### 修复的问题:

* fix: response contentType为空的情况
* fix: 拦截器中`OnMethodInvoke`没被调用的问题
* fix: Client的动态代理类对象调用equals报错的问题
* fix: `Interceptor`的`addAttribute`无效问题
* fix: Request的`addInterceptorAttribute`中的问题
* fix: @DownloadFile注解无法返回File对象的问题

#### 其他改动:

* add: ContentType类
* refactor: 抽出`ForestEncoder`接口，并将`convertToJson`、`converterToXml`统一命名为`encodeToString`
* rrefactor: 使用静态变量`DEFAULT_CHARSET`
* rrefactor: 把`@DownloadFile`注解拦截器移到extensions包
* rrefactor: 把`BasicAuthInterceptor`类移到extension包
* rrefactor: 把`@BasicAuth`注解类移到extension包

Last committed message: update: new version 1.4.0-RC1

v1.3.11

ca0bb2e

2020-08-07 02:03

v1.3.11

Last committed message: update: new version 1.3.11

Preview version

v1.4.0-BETA2

379f0a7

2020-08-05 11:36

v1.4.0-BETA2

`v1.4.0-BETA2`发布了，这次版本改动较大，但主要是新增了三个新特性：文件下载、自定义注解拦截器、自动识别返回数据的类型。

#### 文件下载：

```java

/**
 * 用@DownloadFile注解下载文件，dir属性指定下载目标目录，filename指定目标文件名
 */
@Request(url = "http://localhost:8080/images/test-img.jpg")
@DownloadFile(dir = "${targetDir}", filename = "new-img.jpg")
void downloadImage(@DataVariable("targetDir") String targetDir);

/**
 * 返回类型用byte[]，可将下载的文件转换成字节数组
 * @return
 */
@Request(url = "http://localhost:8080/images/test-img.jpg")
byte[] downloadImageToByteArray();

/**
 * 返回类型用InputStream将下载的文件转换成流，并可以和@DownloadFile注解共用
 * @return
 */
@Request(url = "http://localhost:8080/images/test-img.jpg")
@DownloadFile(dir = "D:\\TestDownload", filename = "temp.jpg")
InputStream downloadImageToInputStream();

```
#### 自定义注解：

新版本允许您通过拦截器来扩展您自己定义的注解，做起来也很简单：

1. 新建一个拦截器，比如叫`MyAuthInceptor`
2. 新建一个注解，并绑上`@InterceptorClass`，指定好您要绑定的拦截器

```java
@Documented
// 标签化拦截器的标示，并指定拦截器类为BasicAuthInterceptor
@InterceptorClass(BasicAuthInterceptor.class)
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface MyAuth {
    /**
     * auth username
     * @return
     */
    String username();

/**
     * auth password
     * @return
     */
    String password();
}
```

3. 使用您自定义的拦截器

绑定到接口类上
```java
@BaseRequest(baseURL = "http://localhost:${port}")
@MyAuth(username = "${username}", password = "bar")
public interface BaseAuthClient {...}
```

或者绑定到方法上
```java
@Request( url = "http://localhost:${port}/hello/user?username=${username}")
@MyAuth(username = "${username}", password = "bar")
String send(@DataVariable("username") String username);
```

Forest该版本内置了一个基本验证注解 `@BasicAuth`

#### 自动识别数据类型

新增了`auto`类型的`dataType`，它会根据请求返回的数据自动判断出数据是哪张格式的，并进行反序列化，不再需要明确指定是`JSON`、`XML`还是`TEXT`

```java
@Request(
    url = "http://ditu.amap.com/service/regeo",
    dataType = "auto"   // 自动判断出返回结果为JSON还是XML
)
Map getLocation(@DataParam("longitude") String longitude, @DataParam("latitude") String latitude);
```

而且`auto`为默认数据类型，也就是说您不必再担心`dataType`属性漏填或错填了，直接不填就行。

```java
// 不填dataType情况下，自动判断返回结果类型
@Request(url = "http://ditu.amap.com/service/regeo")
Map getLocation(@DataParam("longitude") String longitude, @DataParam("latitude") String latitude);
```

#### 具体的新特性：

* feat: 文件下载
* feat: 可扩展自定义注解，绑定拦截器，形成标签化拦截器
* feat: `ForestRequest`对象可添加附件
* feat: 二进制转换处理字节数组和流类型
* feat: `Basic`验证
* feat: `dataType`属性默认为"`auto`"，能自动识别返回数据的类型进行反序列化

#### 修复的BUG：

* fix: 模板字符串遇到`\\`时解析出错
* fix: 不同`OkHttp3`版本下的兼容问题
* fix: `OkHttp`后端下`Future`返回类型数据转换错误

#### 代码改动：

* add: Auto自动类型转换器
* add: `ForestResponse`中的`filename`, `contentType`, `contentEncoding`, `contentLength`属性
* add: Basic验证注解拦截器
* add: 文件下载注解拦截器
* add: 标签化拦截器注解定义注解标识 `InterceptorClass`
* add: 拦截器属性类 `InterceptorAttributes`
* add: 生命周期方法 `handleInvokeMethod`
* add: Interceptor接口的default方法：`beforeExecute`, `afterExecute`, `addAttribute`, `getAttributes`, `getAttributeAsString`, `getAttributeAsInteger`, `getAttributeAsFloat`, `getAttributeAsDouble`
* add: `Base64`工具类
* add: `@DownloadFile`注解拦截器
* add: 新数据类型 `auto`, `binary`
* refactor: 处理二进制下载请求的结果转换
* refactor: response content结果获取的代码移到`ForestResponse`子类中
* update: 更新okhttp版本
* refactor: `ReflectUtil`改名为`ReflectUtils`
* refactor: 文本数据类型通过专门的Converter去处理
* refactor: `ForestConverter`添加source的泛型参数
* update: 在`ForestConfiguration`中注册文本转换器、二进制转换器和自动类型转换器

Last committed message: test: @BasicAuth注解拦截器

Preview version

v1.4.0-BETA1

873a89d

2020-08-03 11:52

v1.4.0-BETA1

`v1.4.0-BETA1`为BETA版本，主要实现了文件上传特性，关于文件下载要等到后续的BETA版本。

#### 文件上传的用法：

```java
@Request(
    url = "/upload",
    type = "post",
    dataType = "json",
    contentType = "multipart/form-data"
)
Map upload(@DataFile("file") File file, OnProgress onProgress);
```

要点：

1. 用`@DataFile`注解修饰要上传的参数对象，对象类型包括`File`, `String`, `InputStream`, `byte[]`, `MultipartFile`, `Resource`这几种。

2. `@DataFile`注解的`value`为必填属性，代表其文件对象在请求中的参数名

3. `@DataFile`注解的`fileName`属性代表的是文件名，对于`File`， `String`,`MultipartFile`, `Resource`文件类为可选属性，对于`InputStream` 和 `byte[]` 为必填项。

4. `OnProgress`参数为监听上传进度的回调函数

#### 新的特性：

* feat: 文件上传
* feat: 文件上传进度监听
* feat: 新增@DataFile注解，用于修饰上传的文件参数，支持的参数类型有File, String, InputStream, byte[], MultipartFile, Resource
* feat: 新增OnProgress回调函数，用于上传进度监听
* feat: 新增用于OnProgress回调函数的参数ForestProgress类对象
* feat: @Request注解新增progressStep属性, 用于描述每处理多少比特监听一次进度
* feat: 拦截器新增OnProgress接口方法（在实现类中不强制实现）

#### 改动内容：

* refactor: ResponseHandler更名为LifeCycleHandler
* refactor: 升级Httpclient版本到4.5.2
* refactor: 新增ForestMultipart类，封装用于上传的文件数据类型

Last committed message: update: new version 1.4.0-BETA1