Forest是一個高層的、極簡的輕量級HTTP調用API框架。相比于直接使用Httpclient您不再用寫一大堆重復的代碼了，而是像調用本地方法一樣去發(fā)送HTTP請求。

Forest有哪些特性？

以Httpclient和OkHttp為后端框架

通過調用本地方法的方式去發(fā)送Http請求, 實現(xiàn)了業(yè)務邏輯與Http協(xié)議之間的解耦

因為針對第三方接口，所以不需要依賴Spring Cloud和任何注冊中心

支持所有請求方法：GET, HEAD, OPTIONS, TRACE, POST, DELETE, PUT, PATCH

支持文件上傳和下載

支持靈活的模板表達式

支持攔截器處理請求的各個生命周期

支持自定義注解

支持OAuth2驗證

支持過濾器來過濾傳入的數(shù)據(jù)

基于注解、配置化的方式定義Http請求

支持Spring和Springboot集成

JSON字符串到Java對象的自動化解析

XML文本到Java對象的自動化解析

JSON、XML或其他類型轉換器可以隨意擴展和替換

支持JSON轉換框架: Fastjson, Jackson, Gson

支持JAXB形式的XML轉換

可以通過OnSuccess和OnError接口參數(shù)實現(xiàn)請求結果的回調

配置簡單，一般只需要@Request一個注解就能完成絕大多數(shù)請求的定義

支持異步請求調用

極速開始

以下例子基于Spring Boot

第一步：添加Maven依賴

直接添加以下maven依賴即可

<dependency>

<groupId>com.dtflys.forest</groupId>

<artifactId>spring-boot-starter-forest</artifactId>

<version>1.5.0-BETA9</version>

</dependency>

第二步：創(chuàng)建一個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}代表引用第一個參數(shù)，${1}引用第二個參數(shù)

*/

@Get(url = "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);

}

}

第四步：調用接口

OK，我們可以愉快地調用接口了

// 注入接口實例

@Autowired

private AmapClient amapClient;

...

// 調用接口

Map result = amapClient.getLocation("121.475078", "31.223577");

System.out.println(result);

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

/**

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

*/

@Post(url = "/register")

String registerUser(@JSONBody MyUser user);

/**

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

*/

@Post(url = "/test/json")

String postJsonMap(@JSONBody Map mapObj);

/**

* 直接傳入一個JSON字符串，并放在請求的Body進行傳輸

*/

@Post(url = "/test/json")

String postJsonText(@JSONBody String jsonText);

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

/**

* 將一個通過JAXB注解修飾過的類型對象解析為XML字符串

* 并放在請求的Body進行傳輸

*/

@Post(url = "/message")

String sendXmlMessage(@XMLBody MyMessage message);

/**

* 直接傳入一個XML字符串，并放在請求的Body進行傳輸

*/

@Post(url = "/test/xml")

String postXmlBodyString(@XMLBody String xml);

文件上傳

/**

* 用@DataFile注解修飾要上傳的參數(shù)對象

* OnProgress參數(shù)為監(jiān)聽上傳進度的回調函數(shù)

*/

@Post(url = "/upload")

Map upload(@DataFile("file") String filePath, OnProgress onProgress);

可以用一個方法加Lambda同時解決文件上傳和上傳的進度監(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! --------");

}

});

 多文件批量上傳

/**

* 上傳Map包裝的文件列表，其中 ${_key} 代表Map中每一次迭代中的鍵值

*/

@Post(url = "/upload")

ForestRequest<Map> uploadByteArrayMap(@DataFile(value = "file", fileName = "${_key}") Map<String, byte[]> byteArrayMap);

/**

* 上傳List包裝的文件列表，其中 ${_index} 代表每次迭代List的循環(huán)計數(shù)（從零開始計）

*/

@Post(url = "/upload")

ForestRequest<Map> uploadByteArrayList(@DataFile(value = "file", fileName = "test-img-${_index}.jpg") List<byte[]> byteArrayList);

文件下載

下載文件也是同樣的簡單

/**

* 在方法上加上@DownloadFile注解

* dir屬性表示文件下載到哪個目錄

* OnProgress參數(shù)為監(jiān)聽上傳進度的回調函數(shù)

* ${0}代表引用第一個參數(shù)

*/

@Get(url = "http://localhost:8080/images/xxx.jpg")

@DownloadFile(dir = "${0}")

File downloadFile(String dir, OnProgress onProgress);

調用下載接口以及監(jiā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! --------");

}

});

 基本簽名驗證

@Post(url = "/hello/user?username=${username}")

@BasicAuth(username = "${username}", password = "bar")

String send(@DataVariable("username") String username);

OAuth 2.0

@OAuth2(

tokenUri = "/auth/oauth/token",

clientId = "password",

clientSecret = "xxxxx-yyyyy-zzzzz",

grantType = OAuth2.GrantType.PASSWORD,

scope = "any",

username = "root",

password = "xxxxxx"

)

@Get(url = "/test/data")

String getData();

自定義注解

Forest允許您根據(jù)需要自行定義注解，不但讓您可以簡單優(yōu)雅得解決各種需求，而且極大得擴展了Forest的能力。

定義一個注解

/**

* 用Forest自定義注解實現(xiàn)一個自定義的簽名加密注解

* 凡用此接口修飾的方法或接口，其對應的所有請求都會執(zhí)行自定義的簽名加密過程

* 而自定義的簽名加密過程，由這里的@MethodLifeCycle注解指定的生命周期類進行處理

* 可以將此注解用在接口類和方法上

*/

@Documented

/** 重點： @MethodLifeCycle注解指定該注解的生命周期類*/

@MethodLifeCycle(MyAuthLifeCycle.class)

@RequestAttributes

@Retention(RetentionPolicy.RUNTIME)

/** 指定該注解可用于類上或方法上 */

@Target({ElementType.TYPE, ElementType.METHOD})

public @interface MyAuth {

/**

* 自定義注解的屬性：用戶名

* 所有自定注解的屬性可以在生命周期類中被獲取到

*/

String username();

/**

* 自定義注解的屬性：密碼

* 所有自定注解的屬性可以在生命周期類中被獲取到

*/

String password();

}

定義注解生命周期類

/**

* MyAuthLifeCycle 為自定義的 @MyAuth 注解的生命周期類

* 因為 @MyAuth 是針對每個請求方法的，所以它實現(xiàn)自 MethodAnnotationLifeCycle 接口

* MethodAnnotationLifeCycle 接口帶有泛型參數(shù)

* 第一個泛型參數(shù)是該生命周期類綁定的注解類型

* 第二個泛型參數(shù)為請求方法返回的數(shù)據(jù)類型，為了盡可能適應多的不同方法的返回類型，這里使用 Object

*/

public class MyAuthLifeCycle implements MethodAnnotationLifeCycle<MyAuth, Object> {

/**

* 當方法調用時調用此方法，此時還沒有執(zhí)行請求發(fā)送

* 次方法可以獲得請求對應的方法調用信息，以及動態(tài)傳入的方法調用參數(shù)列表

*/

@Override

public void onInvokeMethod(ForestRequest request, ForestMethod method, Object[] args) {

System.out.println("Invoke Method '" + method.getMethodName() + "' Arguments: " + args);

}

/**

* 發(fā)送請求前執(zhí)行此方法，同攔截器中的一樣

*/

@Override

public boolean beforeExecute(ForestRequest request) {

// 通過getAttribute方法獲取自定義注解中的屬性值

// getAttribute第一個參數(shù)為request對象，第二個參數(shù)為自定義注解中的屬性名

String username = (String) getAttribute(request, "username");

String password = (String) getAttribute(request, "password");

// 使用Base64進行加密

String basic = "MyAuth " + Base64Utils.encode("{" + username + ":" + password + "}");

// 調用addHeader方法將加密結構加到請求頭MyAuthorization中

request.addHeader("MyAuthorization", basic);

return true;

}

/**

* 此方法在請求方法初始化的時候被調用

*/

@Override

public void onMethodInitialized(ForestMethod method, BasicAuth annotation) {

System.out.println("Method '" + method.getMethodName() + "' Initialized, Arguments: " + args);

}

}

使用自定義的注解

/**

* 在請求接口上加上自定義的 @MyAuth 注解

* 注解的參數(shù)可以是字符串模板，通過方法調用的時候動態(tài)傳入

* 也可以是寫死的字符串

*/

@Get(url = "/hello/user?username=${username}")

@MyAuth(username = "${username}", password = "bar")

String send(@DataVariable("username") String username);

Forest v1.6.4 版本發(fā)布了！

此次版本更新主要調整了 SSE 消息處理方面的接口

SSE 消息行模式

SSE 的消息通常為標準的多行一組的name:value格式，每組消息用空白行隔開，具體如下：

id:1
event:json
data:{"name":"a"}
text:xxx
id:2
event:json
data:{"name":"b"}
text:yyy

對于這種標準的格式，可使用多行(MULTI_LINES)，或自動(AUTO)模式

Forest.get("/sse")
        .sse()
        .setOnMessage(event -> {
            event.id(); // 消息名為 id 的值，這里應得到 1, 2
            event.event(); // json
            event.data(); // {"name": "a"}, ...
            event.value("text"); // 獲取非標準名稱的消息值，如: text，這里應得到 xxx, yyy
        })
        .listen(SSELinesMode.MULTI_LINES);

或者使用AUTO，listen方法不傳參數(shù)的情況下，默認為AUTO，AUTO模式會自動識別需要采用的行模式

// AUTO 模式會自動識別需要采用的行模式
sse.listen(); // 默認行模式為 AUTO

SSE 的消息除了有標準格式，還有很多非標準的格式，比如每行都是一條JSON字符串，每一行都是單獨的消息

{"name":"a"}
{"name":"b"}
{"name":"c"}

對于這種類型的消息，就要使用單行模式(SINGLE_LINE)

Forest.get("/sse")
        .sse()
        .setOnMessage(event -> {
            String str = event.value(); // 獲取字符串類型的消息值
            MyUser user = event.value(MyUser.class); // 獲取消息值并轉換為自定義類型
        })
        .listen(SSELinesMode.SINGLE_LINE);

新增特性

feat: 添加根據(jù)類型獲取body對象的接口，可通過request.body().get(Class)獲得body中對應類型的對象

feat: 支持指定 SSE 消息行模式，包括單行、多行、以及自動模式

修復問題

fix: 由Content-Type中; charest=utf8部分包含空格導致的body無故亂碼的問題

fix: 和老版本forest沖突時，新版本Forest類缺乏get(url)、post(url)等方法簽名，造成錯誤