请求对象

请求对象是Forest中最核心的组件，其类名为ForestRequest

主要承担的作用是，将用户发送的请求中的所有属性和数据都封装在这个对象中，并提供直观的API接口方法对其进行修改和操作。

构建请求对象

在Forest中有两种创建 ForestRequest 对象的方法：接口方法返回请求对象和编程式接口创建请求对象。

我们先来说第一种方法，即通过自定义的Forest请求接口获取请求对象。

先在请求接口定义的方法中，使用 ForestRequest 作为方法返回类型。再调用该方法后会直接返回 ForestRequest 对象，而不会执行发送请求的过程。

public interface MyForestClient {

    /**
     * Get类型请求，url路径为 /test
     * <p>ForestRequest是带泛型参数的类型
     * <p>泛型参数代表返回的响应数据所期望转化成的类型
     * 
     * @return Forest请求对象
     */
    @Get("/test")
    ForestRequest<?> getForestRequest();
}

调用 getForestRequest() 方法后即可获取该方法所对应的 Forest 请求对象。

@Resource
MyForestClient myForestClient;

... ...
        
// 如果请求方法以 ForestRequest 作为返回值类型
// 不会直接发送请求
// 而是直接返回 Forest 请求对象        
ForestRequest<?> request = myForestClient.getForestRequest();
String path = request.path(); // 得到字符串 /test
// 手动执行发送请求，并以字符串形式接受响应数据
String ret = request.execute(String.class);

友情提示

若请求接口的方法以 ForestRequest 类作为返回值类型，调用该方法时不会直接执行发送请求的过程，而是返回 ForestRequest 类型的对象实例，以便做进一步的操作。 得到 Forest 请求对象后需要手动调用执行方法进行请求发送的过程。 关于如何手动发送请求，请求参见《执行请求》

第二种办法更为简单，即直接通过Forest编程式接口创建请求对象

// 通过ID为 ForestConfiguration Id 的Forest配置来创建一个新的 Forest 请求对象
ForestRequest<?> request1 = Forest.config("ForestConfiguration Id").request();
// 通过默认全局配置来创建一个新的 Forest 请求对象
ForestRequest<?> request2 = Forest.config().request();
// 同上，即通过默认全局配置来创建一个新的 Forest 请求对象 (推荐使用)
ForestRequest<?> request3 = Forest.request();

Forest.request() 会创建一个包含默认请求属性的ForestRequest对象

Forest的编程式接口还提供了其它快速创建请求对象的方法，可以在创建时就指定请求类型和url地址路径

// 创建 GET 请求对象
Forest.get("/");
// 创建 POST 请求对象
Forest.post("/");
// 创建 PUT 请求对象
Forest.put("/");
// 创建 DELETE 请求对象
Forest.delete("/");
// 创建 HEAD 请求对象
Forest.head("/");
// 创建 PATCH 请求对象
Forest.patch("/");
// 创建 OPTIONS 请求对象
Forest.options("/");
// 创建 TRACE 请求对象
Forest.trace("/");

以上示例代码中的方法名即为请求类型，参数为url地址，如: get("/") 就会返回 GET 类型请求，同时url地址为 http://localhost/。

此类方法的参数可以接受一个简短的不包含域名/端口号部分的路径字符串作为参数，也可以接受完整的url地址

// 参数只传 path 部分
// 请求地址为 http://localhost/test
Forest.get("/test")

// 参数传如完整的 URL 地址
// 请求地址同上，也为 http://localhost/test
Forest.get("http://localhost/test")

获取请求对象

在拦截器或 OnError、OnSuccess 等回调函数的参数中可以直接获取 Forest 请求对象，相关内容请参见《拦截器》

下面将接受 ForestRequest 对象各个属性的获取和修改的方法，以及如何执行发送请求的过程。

文档提示

在后面的示例代码中，ForestRequest 对象都将以 request 这一变量名表示。