Forest 是一个以接口 + 注解形式定义请求为主的HTTP框架，发送请求前先需要定义一个 interface 接口类，再组合使用 Forest 的注解（如：@Get）定义绑定的HTTP请求参数，随后再实例化接口类对象，最终调用该接口绑定HTTP参数注解的方法实现请求的发送。

这样做有很多优点，比如在 Java 代码和 HTTP 协议之间实现解耦，同时方便众多请求接口的管理。但缺点也很明显：步骤较多，如果想要直接快速的请求一个简单的URL地址就显得过重了。

不过，Forest 自 1.5.3 版本起，就提供了编程式接口，不用定义接口类也能发送请求，使用也很方便。

发送请求

以字符串形式接受响应数据

// Get请求
// 并以 String 类型接受数据
String str = Forest.get("/").executeAsString();

以自定义类型形式接受响应数据

// Post请求
// 并以自定义的 MyResult 类型接受
MyResult myResult = Forest.post("/").execute(MyResult.class);

以带复杂泛型参数的类型形式接受响应数据

// 通过 TypeReference 引用类传递泛型参数
// 就可以将响应数据以带复杂泛型参数的类型接受了
Result<List<User>> userList = Forest.post("/")
        .execute(new TypeReference<Result<List<User>>>() {});

异步请求

// 异步 Post 请求
// 通过 onSuccess 回调函数处理请求成功后的结果
// 而 onError 回调函数则在请求失败后被触发
Forest.post("/")
        .async()
        .onSuccess(((data, req, res) -> {
            // data 为响应成功后返回的反序列化过的数据
            // req 为Forest请求对象，即 ForestRequest 类实例
            // res 为Forest响应对象，即 ForestResponse 类实例
        }))
        .onError(((ex, req, res) -> {
            // ex 为请求过程可能抛出的异常对象
            // req 为Forest请求对象，即 ForestRequest 类实例
            // res 为Forest响应对象，即 ForestResponse 类实例
        }))
        .execute();

定义请求的各种参数

// 定义各种参数
// 并以 Map 类型接受
Map<String, Object> map = Forest.post("/")
      .backend("okhttp3")        // 设置后端为 okhttp3
      .host("127.0.0.1")         // 设置地址的host为 127.0.0.1
      .port(8080)                // 设置地址的端口为 8080
      .contentTypeJson()         // 设置 Content-Type 头为 application/json
      .addBody("a", 1)           // 添加 Body 项(键值对)： a, 1
      .addBody("b", 2)           // 添加 Body 项(键值对)： b, 2
      .maxRetryCount(3)          // 设置请求最大重试次数为 3
      // 设置 onSuccess 回调函数
      .onSuccess((data, req, res) -> { log.info("success!"); })
      // 设置 onError 回调函数
      .onError((ex, req, res) -> { log.info("error!"); })
      // 设置请求成功判断条件回调函数
      .successWhen((req, res) -> res.noException() && res.statusOk())
      // 执行并返回Map数据类型对象
      .executeAsMap();

Forest 的快速接口（如：Forest.get(String url)、Forest.post(String url)等方法）本质上是返回了一个 Forest 请求对象（即 ForestRequest 类对象），Forest 的绝大部分操作都是围绕请求对象所作的工作。

文档导航

要详细了解 Forest 请求对象如何使用，请参见《请求对象》