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 参数
      • 字符串模板传参
      • @Query 注解
      • 数组参数
      • 带 [] 的数组参数
      • 带下标的数组参数
      • JSON参数
    • 🍭 请求头
    • 👔 请求体
    • 🍮 后端框架
    • 🧁 接口注解
    • 📬 接收数据
    • 🍛 数据转换
    • 🍓 成功/失败条件
    • 🍌 重试机制
    • 🥂 重定向
    • 🍔 Gzip解压
    • 🎂 日志管理
    • ⚽ 回调函数
    • 🍟 异步请求
    • 🛡️ HTTPS
    • 🍪 使用Cookie
    • 🛸 使用代理
    • 🍉 上传下载
    • 🚑 异常处理
  • 编程式接口

    • 请求API

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

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

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

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

🎈 URL 参数

URL参数,也称为 URL 查询字符串,即跟在 URL 地址中?后面的那串字符串,可以用=表示一对键值对,多个键值对用&隔开,其可以作为 HTTP 请求的参数

通过这些参数可以告诉服务端要做哪些事情,以及这些事相关的数据(简单数据,数据大小受到 URL 长度标准的限制)

# 字符串模板传参

HTTP的URL不光有协议名、域名、端口号等等基本信息,更为重要的是它能携带各种参数,称为Query参数,它通常包含参数名和参数值两部分。

Forest给URL的Query部分传参也有多种方式,其中最简洁直白的就数字符串拼接了。

/**
 * 直接在url字符串的问号后面部分直接写上 参数名=参数值 的形式
 * 等号后面的参数值部分可以用 {参数序号} 这种字符串模板的形式替代
 * 在发送请求时会动态拼接成一个完整的URL
 * 使用这种形式不需要为参数定义额外的注解
 * 
 * 注:参数序号是从 0 开始记的方法参数的序号
 * 0 代表第一个参数,1 代表第二个参数,以此类推
 */
@Get("http://localhost:8080/abc?a={0}&b={1}&id=0")
String send1(String a, String b);

/**
 * 直接在url字符串的问号后面部分直接写上 参数名=参数值 的形式
 * 等号后面的参数值部分可以用 {变量名} 这种字符串模板的形式替代
 * 在发送请求时会动态拼接成一个完整的URL
 * 使用这种方式需要通过 @Var 注解或全局配置声明变量
 */
@Get("http://localhost:8080/abc?a={a}&b={b}&id=0")
String send2(@Var("a") String a, @Var("b") String b);


/**
 * 如果一个一个变量包含多个Query参数,比如: "a=1&b=2&c=3"
 * 为变量 parameters 的字符串值
 * 就用 ${变量名} 这种字符串模板格式
 * 使用这种方式需要通过 @Var 注解或全局配置声明变量
 */
@Get("http://localhost:8080/abc?${parameters}")
String send3(@Var("parameters") String parameters);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

调用{参数序号}字符串模板的方法

// 会对第二个参数 B&c=C 进行URL Encode
myClient.send1("A", "B&c=C");

// 产生的URL为
// http://localhost:8080/abc?a=A&b=B%26c%3DC&id=0
1
2
3
4
5

调用{变量名}字符串模板的方法

// 会对第二个参数 B&c=C 进行URL Encode
myClient.send2("A", "B&c=C");

// 产生的URL为
// http://localhost:8080/abc?a=A&b=B%26c%3DC&id=0
1
2
3
4
5

调用${变量名}字符串模板的方法

// 会用参数输入的字符串替换URL中的 ${parameters} 部分
myClient.send3("a=A&b=B&c=C");

// 产生的URL为
// http://localhost:8080/abc?a=A&b=B&c=C
1
2
3
4
5

文档导航

关于字符串模板的详细用法,请参见《模板表达式》

# @Query 注解

但把所有Query参数直接写在url属性的字符串里面是不是也太简单粗暴了,有没有优雅点的方式?有的。


/**
 * 使用 @Query 注解,可以直接将该注解修饰的参数动态绑定到请求url中
 * 注解的 value 值即代表它在url的Query部分的参数名
 */
@Get("http://localhost:8080/abc?id=0")
String send(@Query("a") String a, @Query("b") String b);

1
2
3
4
5
6
7
8

友情提示

@Query 注解修饰的参数一定会出现在 URL 中。

若是要传的URL参数太多了呢?难道要我在方法上定义十几二十个@Query修饰的参数?那也太难看了吧。别急,Forest还是有办法让您变的代码变得优雅的。


/**
 * 使用 @Query 注解,可以修饰 Map 类型的参数
 * 很自然的,Map 的 Key 将作为 URL 的参数名, Value 将作为 URL 的参数值
 * 这时候 @Query 注解不定义名称
 */
@Get("http://localhost:8080/abc?id=0")
String send1(@Query Map<String, Object> map);


/**
 * @Query 注解也可以修饰自定义类型的对象参数
 * 依据对象类的 Getter 和 Setter 的规则取出属性
 * 其属性名为 URL 参数名,属性值为 URL 参数值
 * 这时候 @Query 注解不定义名称
 */
@Get("http://localhost:8080/abc?id=0")
String send2(@Query UserInfo user);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

是不是瞬间简洁不少,但用@Query注解绑定参数的时候也有需要注意的地方:

注意

  • (1) 需要单个单个定义 参数名=参数值 的时候,@Query注解的value值一定要有,比如 @Query("name") String name

  • (2) 需要绑定对象的时候,@Query注解的value值一定要空着,比如 @Query User user 或 @Query Map map

# 数组参数

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

列表类型参数

/*
 * 接受列表参数为URL查询参数
 */
@Get("http://localhost:8080/abc")
String send1(@Query("id") List idList);
1
2
3
4
5

若调用 send1(Arrays.asList(1, 2, 3, 4))

则产生的最终URL为

http://localhost:8080/abc?id=1&id=2&id=3&id=4
1

数组类型参数

/*
 * 接受数组参数为URL查询参数
 */
@Get("http://localhost:8080/abc")
String send2(@Query("id") int[] idList);
1
2
3
4
5

若调用 send2(new int[] {1, 2, 3, 4})

则产生的最终URL为

http://localhost:8080/abc?id=1&id=2&id=3&id=4
1

# 带 [] 的数组参数

有些场景用带方括号([])的参数名来表示数组类型的 Query 参数

/*
 * 在 @Query 注解的参数名后跟上 [] 即可
 */
@Get("http://localhost:8080/abc")
String send(@Query("id[]") int[] idList);

1
2
3
4
5
6

若调用 send2(new int[] {1, 2, 3, 4})

则产生的最终URL为

http://localhost:8080/abc?id[]=1&id[]=2&id[]=3&id[]=4
1

# 带下标的数组参数

在字符串模板中引用内置变量_index

/*
 * 内置变量 _index 代表数组的下标
 */
@Get("http://localhost:8080/abc")
String send(@Query("id[${_index}]") int[] idList);
1
2
3
4
5

若调用 send2(new int[] {1, 2, 3, 4})

则产生的最终URL为

http://localhost:8080/abc?id[0]=1&id[1]=2&id[2]=3&id[3]=4
1

# JSON参数

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

这时,可以使用@JSONQuery注解

@Get("http://localhost:8080/abc")
String send(@JSONQuery("id") List idList);
1
2

若调用 send(Arrays.asList(1, 2, 3, 4))

则产生的最终URL为

http://localhost:8080/abc?id=[1, 2, 3, 4]
1
帮助我们改善此文档 (opens new window)
上次更新: 2023/03/07, 12:59:48
🚚 请求地址
🍭 请求头

← 🚚 请求地址 🍭 请求头→

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