一款Forest 是声明式 HTTP 客户端

Forest 是一个的 Java HTTP 客户端框架，它能够将 HTTP 所有请求信息（包括 URL、Header 以及 Body 等信息）绑定到自定义的 Interface 方法上，能够通过调用本地接口方法的方式发送 HTTP 请求。

使用 Forest 就像使用类似 Dubbo 那样的 RPC 框架一样，只需要定义接口，调用接口即可，不必关心具体发送 HTTP 请求的细节。同时将 HTTP 请求信息与业务代码解耦，方便统一管理大量 HTTP 的 URL、Header 等信息。而请求的调用方完全不必在意 HTTP 的具体内容，即使该 HTTP 请求信息发生变更，大多数情况也不需要修改调用发送请求的代码。

功能特性

• 声明式接口： 通过定义地接口+注解的方式封装Http请求, 实现了业务逻辑与Http协议之间的解耦
• 多种底层HTTP框架： 以Httpclient和OkHttp为后端框架（可根据需要二选一）
• 不依赖中间件： 因为针对第三方接口，所以不需要依赖Spring Cloud和任何注册中心
• 支持所有请求方法： GET, HEAD, OPTIONS, TRACE, POST, DELETE, PUT, PATCH
• 约定大于配置： 只要添加好依赖，基本上可以什么都不配置，就能马上运行
• 自动 JSON 转换： 内置 Jackson、Fastjson、Gson 三种JSON转换器
• 自动 XML 转换： 内置 JAXB 形式的 XML 转换器
• 自动 Protobuf 转换： 内置 Protobuf 格式数据转换器
• 多种验签方式： Basic Auth、 OAuth2、以及通过自定义拦截器或注解来验签
• Spring/Spring boot： 支持Spring和Springboot集成
• 上传下载： 支持多种上传和下载的方式，并能监听数据传输进度
• 模板表达式： 支持灵活的模板表达式，来配合声明式注解使用
• 拦截器： 支持拦截器处理请求的各个生命周期
• 自定义注解： 支持自定义注解，来极大增强扩展能力
• 回调函数： 支持通过OnSuccess和OnError接口参数实现请求结果的回调
• 异步请求： 支持方便的异步请求调用方式
• 编程式接口： 除声明式接口外，也支持直观的编程式接口

工作原理

Forest 会将定义好的接口通过动态代理的方式生成一个具体的实现类，然后组织、验证 HTTP 请求信息，绑定动态数据，转换数据形式，SSL 验证签名，调用后端 HTTP API(httpclient 等 API)执行实际请求，等待响应，失败重试，转换响应数据到 Java 类型等脏活累活都由这动态代理的实现类给包了。请求发送方调用这个接口时，实际上就是在调用这个干脏活累活的实现类。

快速开始

添加Maven依赖

Springboot环境：

<dependency>  
  <groupId>com.dtflys.forest</groupId>  
  <artifactId>forest-spring-boot-starter</artifactId>  
  <version>1.5.25</version>  
</dependency>

Spring环境：

<dependency>  
    <groupId>com.dtflys.forest</groupId>  
    <artifactId>forest-core</artifactId>  
    <version>1.5.25</version>  
</dependency>  
  
<dependency>  
  <groupId>com.dtflys.forest</groupId>  
  <artifactId>forest-spring</artifactId>  
  <version>1.5.25</version>  
</dependency>

原生Java环境：

<dependency>  
  <groupId>com.dtflys.forest</groupId>  
  <artifactId>forest-core</artifactId>  
  <version>1.5.25</version>  
</dependency>

创建一个interface

以高德地图API为例：

package com.yoursite.client;  
  
import com.dtflys.forest.annotation.Request;  
import com.dtflys.forest.annotation.DataParam;  
  
public interface AmapClient {  
  
    /**  
     * 聪明的你一定看出来了@Get注解代表该方法专做GET请求  
     * 在url中的{0}代表引用第一个参数，{1}引用第二个参数  
     */  
    @Get("http://ditu.amap.com/service/regeo?longitude={0}&latitude={1}")  
    Map getLocation(String longitude, String latitude);  
}

扫描接口

在Spring Boot的配置类或者启动类上加上 @ForestScan 注解，并在basePackages属性里填上远程接口的所在的包名

@SpringBootApplication  
@Configuration  
@ForestScan(basePackages = "com.yoursite.client")  
public class MyApplication {  
  public static void main(String[] args) {  
      SpringApplication.run(MyApplication.class, args);  
   }  
}

调用接口

// 注入接口实例  
@Autowired  
private AmapClient amapClient;  
...  
  
// 调用接口  
Map result = amapClient.getLocation("121.475078", "31.223577");  
System.out.println(result);

发送JSON数据

/**  
 * 将对象参数解析为JSON字符串，并放在请求的Body进行传输  
 */  
@Post("/register")  
String registerUser(@JSONBody MyUser user);  
  
/**  
 * 将Map类型参数解析为JSON字符串，并放在请求的Body进行传输  
 */  
@Post("/test/json")  
String postJsonMap(@JSONBody Map mapObj);  
  
/**  
 * 直接传入一个JSON字符串，并放在请求的Body进行传输  
 */  
@Post("/test/json")  
String postJsonText(@JSONBody String jsonText);

发送XML数据

/**  
 * 将一个通过JAXB注解修饰过的类型对象解析为XML字符串  
 * 并放在请求的Body进行传输  
 */  
@Post("/message")  
String sendXmlMessage(@XMLBody MyMessage message);  
  
/**  
 * 直接传入一个XML字符串，并放在请求的Body进行传输  
 */  
@Post("/test/xml")  
String postXmlBodyString(@XMLBody String xml);

发送Protobuf数据

/**  
 * ProtobufProto.MyMessage 为 Protobuf 生成的数据类  
 * 将 Protobuf 生成的数据对象转换为 Protobuf 格式的字节流  
 * 并放在请求的Body进行传输  
 *   
 * 注: 需要引入 google protobuf 依赖  
 */  
@Post(url = "/message", contentType = "application/octet-stream")  
String sendProtobufMessage(@ProtobufBody ProtobufProto.MyMessage message);

文件上传

/**  
 * 用@DataFile注解修饰要上传的参数对象  
 * OnProgress参数为监听上传进度的回调函数  
 */  
@Post("/upload")  
Map upload(@DataFile("file") String filePath, OnProgress onProgress);

可以用一个方法加Lambda同时解决文件上传和上传的进度监听

Map result = myClient.upload("D:\\TestUpload\\xxx.jpg", progress -> {  
    System.out.println("progress: " + Math.round(progress.getRate() * 100) + "%");  // 已上传百分比  
    if (progress.isDone()) {   // 是否上传完成  
        System.out.println("--------   Upload Completed!   --------");  
    }  
});

多文件批量上传

/**  
 * 上传Map包装的文件列表，其中 {_key} 代表Map中每一次迭代中的键值  
 */  
@Post("/upload")  
ForestRequest<Map> uploadByteArrayMap(@DataFile(value = "file", fileName = "{_key}") Map<String, byte[]> byteArrayMap);  
  
/**  
 * 上传List包装的文件列表，其中 {_index} 代表每次迭代List的循环计数（从零开始计）  
 */  
@Post("/upload")  
ForestRequest<Map> uploadByteArrayList(@DataFile(value = "file", fileName = "test-img-{_index}.jpg") List<byte[]> byteArrayList);

文件下载

下载文件也是同样的简单

/**  
* 在方法上加上@DownloadFile注解 
* dir属性表示文件下载到哪个目录 
* OnProgress参数为监听上传进度的回调函数  
* {0}代表引用第一个参数  
*/  
  
@Get("http://localhost:8080/images/xxx.jpg")  
  
@DownloadFile(dir = "{0}")  
  
File downloadFile(String dir, OnProgress onProgress);

调用下载接口以及监听下载进度的代码如下：

File file = myClient.downloadFile("D:\\TestDownload", progress -> {  
  
   System.out.println("progress: " + Math.round(progress.getRate() * 100) + "%"); // 已下载百分比   
   if (progress.isDone()) { // 是否下载完成  
   System.out.println("-------- Download Completed! --------");  
  
   }  
});