[[394925]]

一、前言

最近在碼云上扒了一波，發(fā)現(xiàn)了一個非常優(yōu)秀的開源的輕量級HTTP客戶端API框架Forest，這款A(yù)PI框架讓Java發(fā)送HTTP/HTTPS請求不再難，他比原先了OkHttp和HttpClient更高層，以前在調(diào)用一個第三方外部API接口時，你可能需要使用HTTPClient或者OkHttp工具來實(shí)現(xiàn)，封裝一個HTTPClientUtil工具類，工具類中封裝一些Post/Get請求，那么現(xiàn)在你完全不需要這么做了，使用Forest框架只需要在你的接口上面加一個注解即可實(shí)現(xiàn)第三方API接口的調(diào)用。

二、Forest簡介

1.簡介

輕量級HTTP客戶端API框架，讓Java發(fā)送HTTP/HTTPS請求不再難。它比OkHttp和HttpClient更高層，是封裝調(diào)用第三方restful api client接口的好幫手，是retrofit和feign之外另一個選擇。

• 項(xiàng)目主頁： http://forest.dtflyx.com/
• 中文文檔： http://forest.dtflyx.com/docs/

2.什么是 Forest?

orest 是一個開源的 Java HTTP 客戶端框架，它能夠?qū)?HTTP 的所有請求信息(包括 URL、Header 以及 Body 等信息)綁定到您自定義的 Interface 方法上，能夠通過調(diào)用本地接口方法的方式發(fā)送 HTTP 請求。

3. 為什么使用 Forest?

使用 Forest 就像使用類似 Dubbo 那樣的 RPC 框架一樣，只需要定義接口，調(diào)用接口即可，不必關(guān)心具體發(fā)送 HTTP 請求的細(xì)節(jié)。同時將 HTTP 請求信息與業(yè)務(wù)代碼解耦，方便您統(tǒng)一管理大量 HTTP 的 URL、Header 等信息。而請求的調(diào)用方完全不必在意 HTTP 的具體內(nèi)容，即使該 HTTP 請求信息發(fā)生變更，大多數(shù)情況也不需要修改調(diào)用發(fā)送請求的代碼。

4.Forest 的工作原理

Forest 會將您定義好的接口通過動態(tài)代理的方式生成一個具體的實(shí)現(xiàn)類，然后組織、驗(yàn)證 HTTP 請求信息，綁定動態(tài)數(shù)據(jù)，轉(zhuǎn)換數(shù)據(jù)形式，SSL 驗(yàn)證簽名，調(diào)用后端 HTTP API(httpclient 等 API)執(zhí)行實(shí)際請求，等待響應(yīng)，失敗重試，轉(zhuǎn)換響應(yīng)數(shù)據(jù)到 Java 類型等臟活累活都由這動態(tài)代理的實(shí)現(xiàn)類給包了。請求發(fā)送方調(diào)用這個接口時，實(shí)際上就是在調(diào)用這個干臟活累活的實(shí)現(xiàn)類。

5.Forest 的架構(gòu)

architecture

我們講 HTTP 發(fā)送請求的過程分為前端部分和后端部分，F(xiàn)orest 本身是處理前端過程的框架，是對后端 HTTP API 框架的進(jìn)一步封裝。

前端部分：

1. Forest 配置：負(fù)責(zé)管理 HTTP 發(fā)送請求所需的配置。
2. Forest 注解：用于定義 HTTP 發(fā)送請求的所有相關(guān)信息，一般定義在 interface 上和其方法上。
3. 動態(tài)代理：用戶定義好的 HTTP 請求的interface將通過動態(tài)代理產(chǎn)生實(shí)際執(zhí)行發(fā)送請求過程的代理類。
4. 模板表達(dá)式：模板表達(dá)式可以嵌入在幾乎所有的 HTTP 請求參數(shù)定義中，它能夠?qū)⒂脩敉ㄟ^參數(shù)或全局變量傳入的數(shù)據(jù)動態(tài) 綁定到 HTTP 請求信息中。
5. 數(shù)據(jù)轉(zhuǎn)換：此模塊將字符串?dāng)?shù)據(jù)和JSON或XML形式數(shù)據(jù)進(jìn)行互轉(zhuǎn)。目前 JSON 轉(zhuǎn)換器支持Jackson、Fastjson、Gson三種，XML 支持JAXB一種。
6. 攔截器：用戶可以自定義攔截器，攔截指定的一個或一批請求的開始、成功返回?cái)?shù)據(jù)、失敗、完成等生命周期中的各個環(huán)節(jié)，以插入自定義的邏輯進(jìn)行處理。
7. 過濾器：用于動態(tài)過濾和處理傳入 HTTP 請求的相關(guān)數(shù)據(jù)。
8. SSL：Forest 支持單向和雙向驗(yàn)證的 HTTPS 請求，此模塊用于處理 SSL 相關(guān)協(xié)議的內(nèi)容。

后端部分：

后端為實(shí)際執(zhí)行 HTTP 請求發(fā)送過程的第三方 HTTP API，目前支持okHttp3和httpclient兩種后端 API。

Spring Boot Starter Forest:提供對Spring Boot的支持

環(huán)境要求

Forest 1.0.x 和 Forest 1.1.x 基于 JDK 1.7, Forest 1.2.x及以上版本基于 JDK 1.8

三、Forest有哪些特性?

• 以Httpclient和OkHttp為后端框架
• 通過調(diào)用本地方法的方式去發(fā)送Http請求, 實(shí)現(xiàn)了業(yè)務(wù)邏輯與Http協(xié)議之間的解耦
• 因?yàn)獒槍Φ谌浇涌?，所以不需要依賴Spring Cloud和任何注冊中心
• 支持所有請求方法：GET, HEAD, OPTIONS, TRACE, POST, DELETE, PUT, PATCH
• 支持文件上傳和下載
• 支持靈活的模板表達(dá)式
• 支持?jǐn)r截器處理請求的各個生命周期
• 支持自定義注解
• 支持OAuth2驗(yàn)證
• 支持過濾器來過濾傳入的數(shù)據(jù)
• 基于注解、配置化的方式定義Http請求
• 支持Spring和Springboot集成
• JSON字符串到Java對象的自動化解析
• XML文本到Java對象的自動化解析
• JSON、XML或其他類型轉(zhuǎn)換器可以隨意擴(kuò)展和替換
• 支持JSON轉(zhuǎn)換框架: Fastjson, Jackson, Gson
• 支持JAXB形式的XML轉(zhuǎn)換
• 可以通過OnSuccess和OnError接口參數(shù)實(shí)現(xiàn)請求結(jié)果的回調(diào)
• 配置簡單，一般只需要@Request一個注解就能完成絕大多數(shù)請求的定義
• 支持異步請求調(diào)用

四、SpringBoot如何快速接入

在官方的文檔上明確介紹了有關(guān)Spring傳統(tǒng)項(xiàng)目如何接入Forest，這里我直接以SpringBoot為例，都是一個道理，無非對于SpringBoot提供的是xxx-spring-boot-starter以開頭的依賴forest-spring-boot-starter。

1. 第一步：添加Maven依賴

直接添加以下maven依賴即可：

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

2. 第二步：創(chuàng)建一個interfacepackage

package com.yoursite.client; 
 
import com.dtflys.forest.annotation.Request; 
import com.dtflys.forest.annotation.DataParam; 
 
public interface AmapClient { 
 
    /** 
     * 聰明的你一定看出來了@Get注解代表該方法專做GET請求 
     * 在url中的${0}代表引用第一個參數(shù)，${1}引用第二個參數(shù) 
     */ 
    @Get("http://ditu.amap.com/service/regeo?longitude=${0}&latitude=${1}") 
    public Map getLocation(String longitude, String latitude); 
     
} 

3. 第三步：掃描接口

在Spring Boot的配置類或者啟動類上加上@ForestScan注解，并在basePackages屬性里填上遠(yuǎn)程接口的所在的包名：

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

4. 第四步：調(diào)用接口

// 注入接口實(shí)例 
@Autowired 
private AmapClient amapClient; 
... 
// 調(diào)用接口 
Map result = amapClient.getLocation("121.475078", "31.223577"); 
System.out.println(result); 

5. application.yml全局基本配置

forest: 
  bean-id: config0 # 在spring上下文中bean的id, 默認(rèn)值為forestConfiguration 
  backend: okhttp3 # 后端HTTP API：okhttp3 
  max-connections: 1000 # 連接池最大連接數(shù)，默認(rèn)值為500 
  max-route-connections: 500 # 每個路由的最大連接數(shù)，默認(rèn)值為500 
  timeout: 3000 # 請求超時時間，單位為毫秒, 默認(rèn)值為3000 
  connect-timeout: 3000 # 連接超時時間，單位為毫秒, 默認(rèn)值為2000 
  retry-count: 1 # 請求失敗后重試次數(shù)，默認(rèn)為0次不重試 
  ssl-protocol: SSLv3 # 單向驗(yàn)證的HTTPS的默認(rèn)SSL協(xié)議，默認(rèn)為SSLv3 
  logEnabled: true # 打開或關(guān)閉日志，默認(rèn)為true 
  log-request: true # 打開/關(guān)閉Forest請求日志（默認(rèn)為 true） 
  log-response-status: true # 打開/關(guān)閉Forest響應(yīng)狀態(tài)日志（默認(rèn)為 true） 
  log-response-content: true # 打開/關(guān)閉Forest響應(yīng)內(nèi)容日志（默認(rèn)為 false 

五、支持發(fā)送的請求類型

1. 請求類型：可支持(GET, POST, PUT, HEAD, OPTIONS, DELETE)使用POST方式

public interface MyClient { 
 
    /** 
     * 通過 @Request 注解的 type 參數(shù)指定 HTTP 請求的方式。 
     */ 
    @Request( 
            url = "http://localhost:8080/hello", 
            type = "POST" 
    ) 
    String simplePost(); 
 
    /** 
     * 使用 @Post 注解，可以去掉 type = "POST" 這行屬性 
     */ 
    @Post("http://localhost:8080/hello") 
    String simplePost(); 
 
    /** 
     * 使用 @PostRequest 注解，和上面效果等價(jià) 
     */ 
    @PostRequest("http://localhost:8080/hello") 
    String simplePost(); 
 
} 

除了GET和POST，也可以指定成其他幾種HTTP 請求方式(PUT, HEAD, OPTIONS, DELETE)。

其中type屬性的大小寫不敏感，寫成POST和post效果相同。

• GET和POST大小寫不敏感

// GET請求 
@Request( 
        url = "http://localhost:8080/hello", 
        type = "get" 
) 
String simpleGet(); 
 
// POST請求 
@Request( 
        url = "http://localhost:8080/hello", 
        type = "post" 
) 
String simplePost(); 
 
// PUT請求 
@Request( 
        url = "http://localhost:8080/hello", 
        type = "put" 
) 
String simplePut(); 
 
// HEAD請求 
@Request( 
        url = "http://localhost:8080/hello", 
        type = "head" 
) 
String simpleHead(); 
 
// Options請求 
@Request( 
        url = "http://localhost:8080/hello", 
        type = "options" 
) 
String simpleOptions(); 
 
// Delete請求 
@Request( 
        url = "http://localhost:8080/hello", 
        type = "delete" 
) 
String simpleDelete(); 

另外，可以用@GetRequest, @PostRequest等注解代替@Request注解，這樣就可以省去寫type屬性的麻煩了。

• 例如xxxRequest等價(jià)于xxx

// GET請求 
@Get("http://localhost:8080/hello") 
String simpleGet(); 
 
// GET請求 
@GetRequest("http://localhost:8080/hello") 
String simpleGetRequest(); 
   
// POST請求 
@Post("http://localhost:8080/hello") 
String simplePost(); 
 
// POST請求 
@PostRequest("http://localhost:8080/hello") 
String simplePostRequest(); 
 
// PUT請求 
@Put("http://localhost:8080/hello") 
String simplePut(); 
 
// PUT請求 
@PutRequest("http://localhost:8080/hello") 
String simplePutRequest(); 
 
// HEAD請求 
@HeadRequest("http://localhost:8080/hello") 
String simpleHead(); 
 
 
// Options請求 
@Options("http://localhost:8080/hello") 
String simpleOptions(); 
 
// Options請求 
@OptionsRequest("http://localhost:8080/hello") 
String simpleOptionsRequest(); 
 
// Delete請求 
@Delete("http://localhost:8080/hello") 
String simpleDelete(); 
 
// Delete請求 
@DeleteRequest("http://localhost:8080/hello") 
String simpleDeleteRequest(); 

如上所示，請求類型是不是更一目了然了，代碼也更短了。

@Get和@GetRequest兩個注解的效果是等價(jià)的，@Post和@PostRequest、@Put和@PutRequest等注解也是同理。

六、支持的數(shù)據(jù)發(fā)送格式

1. 發(fā)送JSON數(shù)據(jù)

• 將對象參數(shù)解析為JSON字符串，并放在請求的Body進(jìn)行傳輸 ：

/** 
 * 將對象參數(shù)解析為JSON字符串，并放在請求的Body進(jìn)行傳輸 
 */ 
@Post("/register") 
public String registerUser(@JSONBody MyUser user); 

• 將Map類型參數(shù)解析為JSON字符串，并放在請求的Body進(jìn)行傳輸 ：

/** 
 * 將Map類型參數(shù)解析為JSON字符串，并放在請求的Body進(jìn)行傳輸 
 */ 
@Post("/test/json") 
public String postJsonMap(@JSONBody Map mapObj); 

• 直接傳入一個JSON字符串，并放在請求的Body進(jìn)行傳輸 ：

/** 
 * 直接傳入一個JSON字符串，并放在請求的Body進(jìn)行傳輸 
 */ 
@Post("/test/json") 
public String postJsonText(@JSONBody String jsonText); 

2. 發(fā)送XML數(shù)據(jù)

/** 
 * 將一個通過JAXB注解修飾過的類型對象解析為XML字符串 
 * 并放在請求的Body進(jìn)行傳輸 
 */ 
@Post("/message") 
String sendXmlMessage(@XMLBody MyMessage message); 
 
/** 
 * 直接傳入一個XML字符串，并放在請求的Body進(jìn)行傳輸 
 */ 
@Post("/test/xml") 
String postXmlBodyString(@XMLBody String xml); 

3. 文件上傳

/** 
 * 用@DataFile注解修飾要上傳的參數(shù)對象 
 * OnProgress參數(shù)為監(jiān)聽上傳進(jìn)度的回調(diào)函數(shù) 
 */ 
@Post("/upload") 
Map upload(@DataFile("file") String filePath, OnProgress onProgress); 

可以用一個方法加Lambda同時解決文件上傳和上傳的進(jìn)度監(jiān)聽

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!   --------"); 
    } 
}); 

4. 多文件批量上傳

/** 
 * 上傳Map包裝的文件列表，其中 ${_key} 代表Map中每一次迭代中的鍵值 
 */ 
@Post("/upload") 
ForestRequest<Map> uploadByteArrayMap(@DataFile(value = "file", fileName = "${_key}") Map<String, byte[]> byteArrayMap); 
 
/** 
 * 上傳List包裝的文件列表，其中 ${_index} 代表每次迭代List的循環(huán)計(jì)數(shù)（從零開始計(jì)） 
 */ 
@Post("/upload") 
ForestRequest<Map> uploadByteArrayList(@DataFile(value = "file", fileName = "test-img-${_index}.jpg") List<byte[]> byteArrayList); 

5. 文件下載

下載文件也是同樣的簡單

/** 
 * 在方法上加上@DownloadFile注解 
 * dir屬性表示文件下載到哪個目錄 
 * OnProgress參數(shù)為監(jiān)聽上傳進(jìn)度的回調(diào)函數(shù) 
 * ${0}代表引用第一個參數(shù) 
 */ 
@Get("http://localhost:8080/images/xxx.jpg") 
@DownloadFile(dir = "${0}") 
File downloadFile(String dir, OnProgress onProgress); 

調(diào)用下載接口以及監(jiān)聽下載進(jìn)度的代碼如下：

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

6.基本簽名驗(yàn)證

@Post("/hello/user?username=${username}") 
@BasicAuth(username = "${username}", password = "bar") 
String send(@DataVariable("username") String username); 

7. OAuth2.0

@OAuth2( 
        tokenUri = "/auth/oauth/token", 
        clientId = "password", 
        clientSecret = "xxxxx-yyyyy-zzzzz", 
        grantType = OAuth2.GrantType.PASSWORD, 
        scope = "any", 
        username = "root", 
        password = "xxxxxx" 
) 
@Get("/test/data") 
String getData(); 

等等特性，詳細(xì)文檔請看：http://forest.dtflyx.com/

七、詳細(xì)文檔請看：http://forest.dtflyx.com/