参考官网文档齐全,各种高级特性等用法
https://gitee.com/dromara/forest/blob/master/README.md
http://forest.dtflyx.com/
一、简介
什么是 Forest?#
Forest 是一个开源的 Java HTTP 客户端框架,它能够将 HTTP 的所有请求信息(包括 URL、Header 以及 Body 等信息)绑定到您自定义的 Interface 方法上,能够通过调用本地接口方法的方式发送 HTTP 请求。
为什么使用 Forest?#
使用 Forest 就像使用类似 Dubbo 那样的 RPC 框架一样,只需要定义接口,调用接口即可,不必关心具体发送 HTTP 请求的细节。同时将 HTTP 请求信息与业务代码解耦,方便您统一管理大量 HTTP 的 URL、Header 等信息。而请求的调用方完全不必在意 HTTP 的具体内容,即使该 HTTP 请求信息发生变更,大多数情况也不需要修改调用发送请求的代码。
Forest 如何使用?#
Forest 不需要您编写具体的 HTTP 调用过程,只需要您定义一个接口,然后通过 Forest 注解将 HTTP 请求的信息添加到接口的方法上即可。请求发送方通过调用您定义的接口便能自动发送请求和接受请求的响应。
Forest 的工作原理#
Forest 会将您定义好的接口通过动态代理的方式生成一个具体的实现类,然后组织、验证 HTTP 请求信息,绑定动态数据,转换数据形式,SSL 验证签名,调用后端 HTTP API(httpclient 等 API)执行实际请求,等待响应,失败重试,转换响应数据到 Java 类型等脏活累活都由这动态代理的实现类给包了。 请求发送方调用这个接口时,实际上就是在调用这个干脏活累活的实现类。
Forest 的架构
我们讲 HTTP 发送请求的过程分为前端部分和后端部分,Forest 本身是处理前端过程的框架,是对后端 HTTP API 框架的进一步封装。
前端部分:
- Forest 配置: 负责管理 HTTP 发送请求所需的配置。
- Forest 注解: 用于定义 HTTP 发送请求的所有相关信息,一般定义在 interface 上和其方法上。
- 动态代理: 用户定义好的 HTTP 请求的
interface
将通过动态代理产生实际执行发送请求过程的代理类。 - 模板表达式: 模板表达式可以嵌入在几乎所有的 HTTP 请求参数定义中,它能够将用户通过参数或全局变量传入的数据动态绑定到 HTTP 请求信息中。
- 数据转换: 此模块将字符串数据和
JSON
或XML
形式数据进行互转。目前 JSON 转换器支持Jackson
、Fastjson
、Gson
三种,XML 支持JAXB
一种。 - 拦截器: 用户可以自定义拦截器,拦截指定的一个或一批请求的开始、成功返回数据、失败、完成等生命周期中的各个环节,以插入自定义的逻辑进行处理。
- 过滤器: 用于动态过滤和处理传入 HTTP 请求的相关数据。
- SSL: Forest 支持单向和双向验证的 HTTPS 请求,此模块用于处理 SSL 相关协议的内容。
后端部分:
后端为实际执行 HTTP 请求发送过程的第三方 HTTP API,目前支持okHttp3
和httpclient
两种后端 API。
Spring Boot Starter Forest:
提供对Spring Boot
的支持
所需环境#
Forest 1.0.x 和 Forest 1.1.x 基于 JDK 1.7, Forest 1.2.x及以上版本基于 JDK 1.8
二、springboot集成
第一步 添加Maven依赖
<dependency>
<groupId>com.dtflys.forest</groupId>
<artifactId>forest-spring-boot-starter</artifactId>
<version>1.5.0</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); } }
第四步:调用接口
OK,我们可以愉快地调用接口了
// 注入接口实例 @Autowired private AmapClient amapClient; ... // 调用接口 Map result = amapClient.getLocation("121.475078", "31.223577"); System.out.println(result);