一個基于介面和注解的Java HTTP客戶端

easy-http

快速開始

easy-http是一個完全基于注解和介面的http客戶端，為簡化開發、提高效率而生，

1. 特性

• 注解簡單： 遵循大家的命名習慣，@Body、@Query、@Var等注解見名之意，
• 無侵入： 介面不需要繼承，
• 多客戶端實作: 底層支持多種客戶端，默認已實作Java原生URL和HttpClient，也可以自己實作，
• 支持自定義編解碼：默認已經內置了JSON編解碼(回傳引數支持泛型)，如需支持xml，可自定義，
• 支持自定義攔截器：請求前，和請求后的攔截，攔截器可滿足大部分業務需求，如：計算請求耗時，動態添加公共請求頭，回傳錯誤統一處理等等，
• 提供spring-boot版本，使用更簡單，
• 未實作：規劃實作異步請求、回應式模式、以及Java11的客戶端，

2. 安裝

<dependency>
  <groupId>com.github.firelcw</groupId>
  <artifactId>easy-http</artifactId>
  <version>1.6.0</version>
</dependency>

spring-boot版本移步: easy-http-boot-starter

3. 使用

首先定義一個介面:

public interface BookHttpService {
    @Get("/books/{id}")
    ApiResult<Book> getBookById(@Var("id") String id);
}    

這是一個最簡單的查詢介面，然后通過介面構建執行

BookHttpService bookHttpService = EasyHttp.builder()
    								.url("127.0.0.1:8888")
    								.build(BookHttpService.class);
ApiResult<Book> bookRet = bookHttpService.getBookById("166895");
System.out.println(bookRet.getData().getName());

像類似@GET的注解還有@Post、@Put、@Delete，@Post、@Put可指定content-type，默認是application/json，

4.方法引數注解

• @var

  路徑變數注解，用于替換路徑上的變數，路徑變數只能是簡單引數型別，八大基本型別加String，

  @Get("/books/{id}")
  ApiResult<Book> getBookById(@Var("id") String id);
  @Get("/books?author={author}")
  ApiResult<Book> getBookById(@Var("author") String author);
  

• @Query

  被注解的引數可以是任意型別，如果被注解的引數是簡單型別，那么必須指定value(查詢引數的key)，當一個引數沒有任何注解時默認為查詢引數，

  @Get("/books")
  ApiResult<List<Book>> listBooksByAuthor(@Query("author") String author);
  @Get("/books")
  ApiResult<List<Book>> listBooksByAuthor(@Query Map<String, String> params);
  @Get("/books")
  ApiResult<List<Book>> listBooksByAuthor(Map<String, String> params);
  

• @Body

  body引數，被注解的引數會根據編碼器處理放到請求body里面, 如果被注解的引數是簡單型別，則不會進行編碼，

  @Post("/books")
  void addBook(@Body Book book);
  

• @Headers

  請求頭注解，可用于介面、方法和方法引數上，當用于介面和方法需指定value, 格式key: value (冒號后面有和空格)

   @Headers({"clent: Easy-http"})
   @Post("/books")
   ApiResult<Void> addBook(@Body Book book,  @Headers Map<String, String> headers);
  

5. 自定義編碼器

編碼器： 將引數物件決議成http的相關請求引數

撰寫自定義編碼器類CustomEncoder實作Encoder介面

public class CustomEncoder implements Encoder {
     /**
     * 將物件轉化成成Map<String,String> 用于編碼@Query和@Headers
     * @param object 待編碼物件
     * @return map
     */
    @Override
    public Map<String, String> encodeMap(Object object) {
        return null;
    }
	 /**
     * 將物件轉化成string，用于編碼 @Body注解的物件（默認是決議成json字串）
     * @param object
     * @return string
     */
    @Override
    public String encodeString(Object object) {
        return null;
    }
}

在構建物件是加入CustomEncoder

BookHttpService bookHttpService = EasyHttp.builder()
                                            .url("127.0.0.1:8888")
                                            .encoder(new CustomEncoder())
                                            .build(BookHttpService.class);

6. 自定義解碼器

將回傳體決議成物件

撰寫自定義編碼器類CustomDecoder實作Decoder介面

public class CustomDecoder implements Decoder {
     /**
     * 回應解碼(默認使用fastjon解碼)
     * @param response 回應引數
     * @param type 回傳值型別
     * @return Object
     */
    @Override
    public Object decode(HttpResponse response, Type type) {
        return null;
    }
}

在構建物件是加入CustomDecoder

BookHttpService bookHttpService = EasyHttp.builder()
                                        .url("127.0.0.1:8888")
                                        .encoder(new CustomEncoder())
                                        .decoder(new CustomDecoder())
                                        .build(BookHttpService.class);

6. 自定義攔截器

   在請求發出前和請求回應后進行攔截

撰寫自定義編碼器類ResultInterceptor實作HttpInterceptor介面

public class ResultInterceptor implements HttpInterceptor {
    @Override
    public boolean preHandle(HttpRequest request, HttpRequestConfig config) {
        return true;
    }

    @Override
    public void postHandle(HttpRequest request, HttpResponse response) {
        if (!response.isSuccess()) {
            throw new EasyHttpException("請求錯誤~");
        }
        if (StringUtils.isBlank(response.getBody())) {
           return;
        }
        JSONObject retJson = JSON.parseObject(response.getBody());
        // 假設業務code：200 為操作成功
        if (retJson.getInteger("code") == 200) {
            // 覆寫包含公共資訊的json
            response.setBody(retJson.getString("data"));
        }
    }

    @Override
    public int order() {
        return 4;
    }
    @Override
    public List<ExcludePath> excludes() {
        return Arrays.asList(ExcludePath.instance("/books/**", HttpMethod.DELETE, HttpMethod.POST));
    }
}

preHandle 請求前攔截，回傳true則通過，反之則被攔截，postHandle 回應后攔截，order定義攔截器的順序，值越小，越靠前，excludes定義需要排除使用攔截器的路徑串列，這里ResultInterceptor對統一的回傳作了處理，不僅判斷了請求和業務是否成功，并且還統一包裝了回傳體，去掉了通過回傳部分，具體根據業務定制，

在構建物件是加入攔截器串列

        BookHttpService bookHttpService = EasyHttp.builder()
                                                    .url("127.0.0.1:8888")
                                                    .encoder(new CustomEncoder())
                                                    .decoder(new CustomDecoder())
                                                    .withInterceptor(new ResultInterceptor())
                                                    .withInterceptor(new TimeInterceptor())
                                                    .build(BookHttpService.class);

7. 切換客戶端

    EasyHttp.builder()
            .url("127.0.0.1:8888")
            .client(ApacheHttpClient.getInstance())
            .build(BookHttpService.class);
   

聯系作者

如您有好的建議，或者有任何疑問，可聯系我

• QQ: 274550900
• Email: [email protected]

標籤：Java

上一篇：IDEA 非常重要的一些設定項 → 一連串的問題差點讓我重新用回 Eclipse ！

下一篇：自己動手撰寫一個Mybatis插件：Mybatis脫敏插件