URL参数，也称为Query (查询参数)，是跟随在URL地址中 ? 后的字符串，常以 key=value 的键值对形式出现，用于向服务端传递数据。

ForestRequest 对象提供了添加和修改 Query 参数的方法

添加参数

addQuery(String name, Object value) 添加Query参数

• 参数 name: Query参数名
• 参数 value: Query参数值

Forest.get("/")
        .addQuery("a", 1)  // 添加 Query 参数 a=1
        .addQuery("b", 2); // 添加 Query 参数 b=2
// 最后产生 Query 参数 ?a=1&b=2

适用 ForestRequest.addQuery 方法可以重复添加重名 Query 参数。 此功能可用于传递数组

request.addQuery("a", 1)  // 添加 Query 参数 a=1
       .addQuery("a", 2)  // 添加 Query 参数 a=2
       .addQuery("a", 3); // 添加 Query 参数 a=3
// 最后产生 Query 参数 ?a=1&a=2&a=3

添加Map参数

addQuery(Map queryMap) 添加Map类型Query参数

• 参数 queryMap: Map对象

Map<String, Object> map = new HashMap();
map.put("a", 1);
map.put("b", 2);
request.addQuery(map)  // 添加 Map 对象到 Query 参数中
// 最后产生 Query 参数 ?a=1&b=2

添加对象参数

addQuery(Object queryParameters) 添加Java对象类型Query参数

• 参数 queryParameters: 任意类型Java对象

// 自定义一个普通的Java数据类
public class MyQuery {
    private int a;
    private int b;
    // getter 和 setter 代码（省略）
}

// 创建自定义的Java对象实例
MyQuery myQuery = new MyQuery();
myQuery.setA(1);
myQuery.setB(2);
request.addQuery(myQuery)  // 添加 Java 对象到 Query 参数中
// 最后产生 Query 参数 ?a=1&b=2

添加延迟参数

延迟参数 （也称作 Lambda 参数），在您需要不马上求值的情况使用。

有很多情况，Query的参数值不能马上得出，而是在请求发送前的那一刻（所有请求参数都到位时）才能得出，典型的例子就是加签验证的场景（在请求体参数中添加一个参数token，而token的值是对整个URL Query(除token之外所有参数)做加密的结果）

addQuery(String name, Lazy lazyValue) 添加Lazy类型的Query参数

• 参数 lazyValue: 延迟求值的Query参数值（即 Lambda）

request.addQuery("name", req -> {
    // req 为请求对象
    // 返回值将作为参数值添加到 URL Query 中
    return "";
});

在 Lambda 代码块中可以调用req.queryString() 来生成整个请求的URL Query字符串

但会自动排除 Lambda 所对应的 Query 参数（即 token 参数），而不用担心会造成死循环

request.addQuery("a", 1)         // 添加 Query 参数 a=1
        .addQuery("b", 2)        // 添加 Query 参数 b=2
        .addQuery("c", 3)        // 添加 Query 参数 c=3
        .addQuery("token", req -> Base64.encode(req.getQueryString())); // 添加延迟参数
// 最后产生 Query 参数 ?a=1&b=2&c=3&token=YT0xJmI9MiZjPTM=

强制编码

注意

使用 addQuery(String name, String value) 方法时, 绝大部分Query参数值都会被自动UrlEncode编码，但有某些特殊的参数值不会被编码，如: http://www.baidu.com 这样的url地址会被原封不动保留。

这时候需要使用 addQuery(String name, String value, boolean isUrlEncode, String charset) 方法来强制UrlEncode。

addQuery(String name, String value, boolean isUrlEncode, String charset) 添加Query参数

• 参数 name: Query参数名
• 参数 value: Query参数值
• 参数 isUrlEncode: 是否强制UrlEncode
• 参数 charset: 编码字符集

Forest.get("http://127.0.0.1:8080/")
         // 不强制UrlEncode
        .addQuery("url1", "http://localhost/test");
         // 强制UrlEncode
        .addQuery("url2", "http://localhost/test", true, "UTF-8");
// 最终url为
// http://127.0.0.1:8080/?url1=http://localhost/test&url2=http%3A%2F%2Flocalhost%2Ftest

修改参数

修改已存在的 Query 参数

replaceQuery(String name, Object value) 替换Query参数值

• 参数 name: Query参数名
• 参数 value: Query参数值

request.addQuery("a", 1)      // 添加 Query 参数 a=1
       .replaceQuery("a", 2); // 修改 Query 参数 a=2
// 最后产生 Query 参数 ?a=2

ForestRequest.replaceQuery 可以方法修改 Query 参数，但对于还不存在的 Query 参数就无法处理了

// 创建一个新请求对象
// url: http://localhost/
Forest.get("/")
       // 这时候还不存在 Query 参数 a
       // 所以此时调用 replaceQuery 是无效的
      .replaceQuery("a", "1");
// 最后地址还是为 http://localhost/

这时候可以用 ForestRequest.replaceOrAddQuery 方法，它在 Query 参数不存在的情况下添加参数，在已存在的情况下修改参数

replaceOrAddQuery(String name, String value) 替换或添加Query参数

• 参数 name: Query参数名
• 参数 value: Query参数值

// 创建一个新请求对象
// url: http://localhost/
Forest.get("/");
      .replaceOrAddQuery("a", "1")  // 添加或修改 Query 参数 a=1
      .addQuery("b", "2")           // 修改 Query 参数 a=2
      .replaceOrAddQuery("b", "3"); // 添加或修改 Query 参数 b=3
// 最后地址还是为 http://localhost/?a=1&b=3

数组参数

有些时候，需要通过URL参数传递一个数组或者一个列表

// 添加列表到Query参数
List<Integer> list = Arrays.asList(1, 2, 3);
Forest.get("/")
     .addQuery("a", list)
     .execute();
// query参数为 a=1&a=2&a=3

// 添加数组到Query参数
Object[] array = new Object[] {1, 2, 3};
Forest.get("/")
     .addQuery("a", array)
     .execute();
// Query参数为 a=1&a=2&a=3

// 添加数组到Query参数 (可变参数)
Forest.get("/")
     .addQuery("a", 1, 2, 3)
     .execute();
// Query参数为 a=1&a=2&a=3

带方括号[]参数名的样式

// 添加列表到Query参数
List<Integer> list = Arrays.asList(1, 2, 3);
Forest.get("/")
     .addArrayQuery("a", list)
     .execute();
// query参数为 a[]=1&a[]=2&a[]=3

// 添加数组到Query参数
Object[] array = new Object[] {1, 2, 3};
Forest.get("/")
     .addArrayQuery("a", array)
     .execute();
// Query参数为 a[]=1&a[]=2&a[]=3

// 添加数组到Query参数 (可变参数)
Forest.get("/")
     .addArrayQuery("a", 1, 2, 3)
     .execute();
// Query参数为 a[]=1&a[]=2&a[]=3

JSON参数

如果不想以URL参数的标准格式传递列表，JSON字符串也是一种选择

addJSONQuery(String name, Object value) 添加 JSON Query 参数

• 参数name: Query参数名
• 参数value: Query参数值，将被序列化为JSON字符串

// 添加列表到Query数组参数
Forest.get("/")
     .addJSONQuery("a", Arrays.asList(1, 2, 3))
     .execute();
// query参数为 a=[1,2,3]
// 注意：这里的JSON数据最终会被 URLEncode
// 所以最终请求的参数为 a=%5B1%2C2%2C3%5D

获取参数

获取请求的整个 Query 参数表

getQuery() 获取请求的Query参数表

• 返回值: Query参数表，ForestQueryMap 类实例

// 构建请求
// Query 参数为 a=1&b=2&b=3
ForestRequest<?> request = Forest.get("/")
        .addQuery("a", 1)
        .addQuery("b", 2)
        .addQuery("b", 3);
// 获取 Query 参数表
ForestQueryMap queries = request.getQuery();
// 返回参数为 a=1 的 ForestQueryParameter 对象
ForestQueryParameter param1 = queries.getQuery("a");
// 返回包含 b=2和b=3 的 ForestQueryParameter 对象列表
List<ForestQueryParameter> params = queries.getQueries("b"); 

获取单个 Query 参数

getQuery(String name) 根据名称获取请求的Query参数值

• 参数name: Query参数名称
• 返回值: Query参数值

// 构建请求
// Query 参数为 a=1&b=2&b=3
ForestRequest<?> request = Forest.get("/")
        .addQuery("a", 1)
        .addQuery("b", 2);

request.getQuery("a"); // 获取 1
request.getQuery("b"); // 获取 2

获取整个请求的 Query 参数字符串

getQueryString() 获取请求的URL Query参数字符串

• 返回值: Query参数字符串

// 构建请求
// Query 参数为 a=1&b=2&b=3
ForestRequest<?> request = Forest.get("/")
        .addQuery("a", 1)
        .addQuery("b", 2)
        .addQuery("c", 3);

request.getQueryString(); // 获取 a=1&b=2&c=3