Forest輕量級(jí) HTTP 客戶端

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

package com.yoursite.client;

import com.dtflys.forest.annotation.Request;
import com.dtflys.forest.annotation.DataParam;

public interface AmapClient {

    /**
     * 聰明的你一定看出來(lái)了@Get注解代表該方法專做GET請(qǐng)求
     * 在url中的${0}代表引用第一個(gè)參數(shù)，${1}引用第二個(gè)參數(shù)
     */
    @Get("http://ditu.amap.com/service/regeo?longitude=${0}&latitude=${1}")
    Map getLocation(String longitude, String latitude);
}

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

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

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

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

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

/**
 * 將一個(gè)通過(guò)JAXB注解修飾過(guò)的類型對(duì)象解析為XML字符串
 * 并放在請(qǐng)求的Body進(jìn)行傳輸
 */
@Post("/message")
String sendXmlMessage(@XMLBody MyMessage message);

/**
 * 直接傳入一個(gè)XML字符串，并放在請(qǐng)求的Body進(jìn)行傳輸
 */
@Post("/test/xml")
String postXmlBodyString(@XMLBody String xml);

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

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的循環(huán)計(jì)數(shù)（從零開(kāi)始計(jì)）
 */
@Post("/upload")
ForestRequest<Map> uploadByteArrayList(@DataFile(value = "file", fileName = "test-img-${_index}.jpg") List<byte[]> byteArrayList);

/**
 * 在方法上加上@DownloadFile注解
 * dir屬性表示文件下載到哪個(gè)目錄
 * OnProgress參數(shù)為監(jiān)聽(tīng)上傳進(jìn)度的回調(diào)函數(shù)
 * ${0}代表引用第一個(gè)參數(shù)
 */
@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!   --------");
    }
});

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

@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();

/**
 * 用Forest自定義注解實(shí)現(xiàn)一個(gè)自定義的簽名加密注解
 * 凡用此接口修飾的方法或接口，其對(duì)應(yīng)的所有請(qǐng)求都會(huì)執(zhí)行自定義的簽名加密過(guò)程
 * 而自定義的簽名加密過(guò)程，由這里的@MethodLifeCycle注解指定的生命周期類進(jìn)行處理
 * 可以將此注解用在接口類和方法上
 */
@Documented
/** 重點(diǎn)： @MethodLifeCycle注解指定該注解的生命周期類*/
@MethodLifeCycle(MyAuthLifeCycle.class)
@RequestAttributes
@Retention(RetentionPolicy.RUNTIME)
/** 指定該注解可用于類上或方法上 */
@Target({ElementType.TYPE, ElementType.METHOD})
public @interface MyAuth {

    /** 
     * 自定義注解的屬性：用戶名
     * 所有自定注解的屬性可以在生命周期類中被獲取到
     */
    String username();

    /** 
     * 自定義注解的屬性：密碼
     * 所有自定注解的屬性可以在生命周期類中被獲取到
     */
    String password();
}

/**
 *  MyAuthLifeCycle 為自定義的 @MyAuth 注解的生命周期類
 * 因?yàn)?@MyAuth 是針對(duì)每個(gè)請(qǐng)求方法的，所以它實(shí)現(xiàn)自 MethodAnnotationLifeCycle 接口
 * MethodAnnotationLifeCycle 接口帶有泛型參數(shù)
 * 第一個(gè)泛型參數(shù)是該生命周期類綁定的注解類型
 * 第二個(gè)泛型參數(shù)為請(qǐng)求方法返回的數(shù)據(jù)類型，為了盡可能適應(yīng)多的不同方法的返回類型，這里使用 Object
 */
public class MyAuthLifeCycle implements MethodAnnotationLifeCycle<MyAuth, Object> {

 
    /**
     * 當(dāng)方法調(diào)用時(shí)調(diào)用此方法，此時(shí)還沒(méi)有執(zhí)行請(qǐng)求發(fā)送
     * 次方法可以獲得請(qǐng)求對(duì)應(yīng)的方法調(diào)用信息，以及動(dòng)態(tài)傳入的方法調(diào)用參數(shù)列表
     */
    @Override
    public void onInvokeMethod(ForestRequest request, ForestMethod method, Object[] args) {
        System.out.println("Invoke Method '" + method.getMethodName() + "' Arguments: " + args);
    }

    /**
     * 發(fā)送請(qǐng)求前執(zhí)行此方法，同攔截器中的一樣
     */
    @Override
    public boolean beforeExecute(ForestRequest request) {
        // 通過(guò)getAttribute方法獲取自定義注解中的屬性值
        // getAttribute第一個(gè)參數(shù)為request對(duì)象，第二個(gè)參數(shù)為自定義注解中的屬性名
        String username = (String) getAttribute(request, "username");
        String password = (String) getAttribute(request, "password");
        // 使用Base64進(jìn)行加密
        String basic = "MyAuth " + Base64Utils.encode("{" + username + ":" + password + "}");
        // 調(diào)用addHeader方法將加密結(jié)構(gòu)加到請(qǐng)求頭MyAuthorization中
        request.addHeader("MyAuthorization", basic);
        return true;
    }

    /**
     * 此方法在請(qǐng)求方法初始化的時(shí)候被調(diào)用
     */
    @Override
    public void onMethodInitialized(ForestMethod method, BasicAuth annotation) {
        System.out.println("Method '" + method.getMethodName() + "' Initialized, Arguments: " + args);
    }
}

/**
 * 在請(qǐng)求接口上加上自定義的 @MyAuth 注解
 * 注解的參數(shù)可以是字符串模板，通過(guò)方法調(diào)用的時(shí)候動(dòng)態(tài)傳入
 * 也可以是寫(xiě)死的字符串
 */
@Get("/hello/user?username=${username}")
@MyAuth(username = "${username}", password = "bar")
String send(@DataVariable("username") String username);