Forest Forest
💒 首页
  • v1.5.30
  • v1.5.28
  • 🎄 ForestX
🌰 案例
💖 支持
🛫 更新记录
🧢 开发团队
⚒️ 参与贡献
  • MaxKey - 业界领先的身份管理和认证产品 (opens new window)
  • Snowy - 国内首个国密前后端分离快速开发平台 (opens new window)
  • Eoapi - 一个开源、可拓展的 API 工具平台 (opens new window)
  • Gitee (opens new window)
  • Github (opens new window)
💒 首页
  • v1.5.30
  • v1.5.28
  • 🎄 ForestX
🌰 案例
💖 支持
🛫 更新记录
🧢 开发团队
⚒️ 参与贡献
  • MaxKey - 业界领先的身份管理和认证产品 (opens new window)
  • Snowy - 国内首个国密前后端分离快速开发平台 (opens new window)
  • Eoapi - 一个开源、可拓展的 API 工具平台 (opens new window)
  • Gitee (opens new window)
  • Github (opens new window)
  • 序言

    • 🎁 新手介绍
    • 📖 文档
    • 🌰 使用案例
    • 🕵️‍ 关于作者
    • 👨‍🎓 贡献者列表
  • 入门

    • 🎬 安装配置说明
    • 🏹 Springboot环境安装
    • 📐 Springboot环境配置
    • 🎯 Springboot环境使用
    • 🏹 Spring环境安装
    • 📐 Spring环境配置
    • 🎯 Spring环境使用
    • 🏹 原生Java环境安装
    • 📐 原生Java环境配置
    • 🎯 原生Java环境使用
    • 🧬 编程式接口
  • 配置项

    • 👜 Springboot环境配置项
    • 👝 Spring环境配置项
    • 🎒 原生Java环境配置项
    • 📚 配置优先级/作用域
  • 声明式接口

    • 🧱 构建接口
    • 🍀 请求方法
    • 🚚 请求地址
    • 🎈 URL 参数
    • 🍭 请求头
    • 👔 请求体
    • 🍮 后端框架
    • 🧁 接口注解
    • 📬 接收数据
    • 🍛 数据转换
    • 🍓 成功/失败条件
    • 🍌 重试机制
    • 🥂 重定向
    • 🍔 Gzip解压
    • 🎂 日志管理
    • ⚽ 回调函数
    • 🍟 异步请求
    • 🛡️ HTTPS
    • 🍪 使用Cookie
    • 🛸 使用代理
    • 🍉 上传下载
    • 🚑 异常处理
  • 编程式接口

    • 请求API

      • 🚀 请求对象
      • 🚢 请求属性
      • ✨ 执行请求
      • 🎊 后端框架
      • 🎪 请求类型
      • 🔮 请求地址
      • 🧀 URL 参数
        • 添加参数
        • 添加Map参数
        • 添加对象参数
        • 强制编码
        • 修改参数
        • 数组参数
        • JSON参数
        • 获取参数
      • 🚅 请求头
      • 🚋 请求体
      • ⚓ 回调函数
      • 🚁 异步请求
      • 🥯 Cookie
      • 🍜 成功/失败条件
      • 🌶️ 重试机制
      • ⛵ 重定向
      • 🛰️ 请求代理
    • 响应API

      • 🌠 响应对象
      • ✒️ 读取数据
      • 🦋 响应状态码
      • 🏥 响应错误处理
      • 🎧 响应头
      • 🥞 Cookie
  • 模板表达式

    • 🍬 Hello World
    • 🍹 配置属性引用
    • 🍖 变量引用
    • 🥃 动态变量绑定
    • 🥗 参数序号引用
    • 🍍 引用对象属性
    • 🥝 调用对象方法
  • 高级特性

    • 🥪 拦截器
    • 🍏 自定义注解
    • 🍇 组合注解
    • 🥑 自定义转换器
  • v1.5.28文档
  • 编程式接口
  • 请求API
公子骏
2022-07-20
目录

🧀 URL 参数

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
1
2
3
4

适用 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
1
2
3
4
5

# 添加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
1
2
3
4
5

# 添加对象参数

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
1
2
3
4
5
6
7
8
9
10
11
12
13

# 强制编码

注意

使用 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
1
2
3
4
5
6
7

# 修改参数

修改已存在的 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
1
2
3

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

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

这时候可以用 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
1
2
3
4
5
6
7

# 数组参数

有些时候,需要通过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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

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

// 添加列表到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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 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
1
2
3
4
5
6
7

# 获取参数

获取请求的整个 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"); 
1
2
3
4
5
6
7
8
9
10
11
12

获取单个 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
1
2
3
4
5
6
7
8

获取整个请求的 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
1
2
3
4
5
6
7
8
帮助我们改善此文档 (opens new window)
上次更新: 2023/03/07, 12:59:48
🔮 请求地址
🚅 请求头

← 🔮 请求地址 🚅 请求头→

Theme by Vdoing | Copyright © 2016-2023 公子骏 | MIT License
  • 跟随系统
  • 浅色模式
  • 深色模式
  • 阅读模式