1. 问题背景：复杂GET请求参数的挑战
在api自动化测试中，我们经常需要构建包含复杂查询参数的get请求。例如，某些api可能要求参数名包含方括号，以表示数组或嵌套对象结构，例如 filters[start_date] 和 filters[end_date]，并且参数值可能是包含空格和特殊字符的日期时间字符串。
当尝试在Karate Framework中使用常见的 def query = {...} 语法来定义这类参数时，可能会遇到问题。Karate会将整个对象进行URL编码，导致方括号被错误地处理，最终生成的URL与预期不符。
例如，如果尝试使用以下定义：
* def query = {id: 60, 'filters[start_date]': 'Fri Nov 18 2022 10:14:59 GMT-0300', 'filters[end_date]': 'Sat Nov 19 2022 23:59:59 GMT-0300'}Karate生成的URL可能会是类似 https://urlbase/index?id=60&filters=%7Bstart_date%3D%2C+end_date%3D%7D 的形式，其中 filters 成为了一个单一的、被URL编码的对象字符串，而不是带有方括号的独立参数。这显然不是我们期望的 https://urlbase/index?id=60&filters[start_date]=...&filters[end_date]=... 结构。
2. 解决方案：使用 param 关键字
Karate Framework为处理这类复杂查询参数提供了更精确的控制方式：param 关键字。param 允许我们逐个指定参数名和参数值，Karate会正确地将它们拼接并进行URL编码，从而生成符合预期的请求URL。
param 关键字的语法非常直观：
* param parameterName = parameterValue
其中 parameterName 可以直接包含方括号等特殊字符，Karate会将其视为参数名的一部分进行处理。
3. 示例：构建带方括号和日期范围的GET请求
下面是一个完整的Karate特性文件示例，演示了如何使用 param 关键字来构建包含 filters[start_date] 和 filters[end_date] 这类复杂参数的GET请求：
Feature: GET请求与复杂参数（带方括号和日期范围）
Scenario: 发送包含filters[start_date]和filters[end_date]的GET请求
# 定义目标URL
* url 'https://httpbin.org/anything'
# 使用param关键字定义各个查询参数
# 对于简单的参数，可以直接赋值
* param id = 60
# 对于包含方括号的复杂参数名，直接写出参数名
* param filters[start_date] = 'Fri Nov 18 2022 10:14:59 GMT-0300'
* param filters[end_date] = 'Sat Nov 19 2022 23:59:59 GMT-0300'
# 发送GET请求
* method get
# 验证响应状态码
* status 200
# 打印响应，以便观察请求的URL和服务器接收到的参数
* print response在上述示例中，我们使用了 httpbin.org/anything 这个公共服务来模拟API端点，它可以将接收到的请求信息原样返回，便于我们检查Karate生成的请求是否正确。
4. 验证请求结果
运行上述Karate特性文件后，Karate会向 https://httpbin.org/anything 发送GET请求。在控制台输出的响应中，我们可以清晰地看到Karate生成的请求URL以及服务器解析到的参数。
以下是 httpbin.org/anything 返回响应中的关键部分：
{
"args": {
"filters[end_date]": "Sat Nov 19 2022 23:59:59 GMT-0300",
"filters[start_date]": "Fri Nov 18 2022 10:14:59 GMT-0300",
"id": "60"
},
"headers": {
// ... 其他头部信息 ...
},
"method": "GET",
"origin": "X.X.X.X",
"url": "https://httpbin.org/anything?filters[start_date]=Fri+Nov+18+2022+10%3A14%3A59+GMT-0300&filters[end_date]=Sat+Nov+19+2022+23%3A59%3A59+GMT-0300&id=60"
}从响应中我们可以观察到：
- args 字段： 服务器成功地将 filters[start_date] 和 filters[end_date] 识别为独立的参数，并且其值也完全正确。这证明了 param 关键字能够正确地传递带有方括号的参数名。
- url 字段： 生成的请求URL为 https://httpbin.org/anything?filters[start_date]=Fri+Nov+18+2022+10%3A14%3A59+GMT-0300&filters[end_date]=Sat+Nov+19+2022+23%3A59%3A59+GMT-0300&id=60。可以看到，方括号被正确地保留在参数名中，同时参数值中的空格和特殊字符（如冒号）也被Karate自动进行了URL编码。
这完美符合了我们的预期，解决了 def query 无法处理这类复杂参数的问题。
5. 注意事项与最佳实践
在使用Karate Framework处理GET请求参数时，请注意以下几点：
-
param 与 def query 的选择：
- 当参数名简单，不包含特殊字符（如方括号、点号等），或者参数数量较多且结构扁平时，使用 def query = {key1: 'value1', key2: 'value2'} 依然是简洁高效的选择。Karate会将其内部转换为 param 形式。
- 当参数名包含方括号 []、点号 . 等特殊字符，或需要精确控制单个参数的名称和值时，param 关键字是更可靠和推荐的方法。
- URL 编码： Karate会自动对 param 关键字后的参数值进行URL编码。因此，在定义参数值时，应提供原始的、未编码的字符串。例如，'Fri Nov 18 2022 10:14:59 GMT-0300' 会被正确编码为 Fri+Nov+18+2022+10%3A14%3A59+GMT-0300。
- 日期格式： 示例中的日期字符串是直接作为值传递的。在实际应用中，如果API对日期格式有严格要求，可能需要先使用Karate的JavaScript表达式或内置函数来格式化日期字符串，然后再赋值给 param。
- 可读性和维护性： 对于少量复杂参数，使用多个 param 语句可以提高脚本的可读性。对于大量动态生成的复杂参数，可以考虑结合JavaScript函数来构建参数映射，然后循环使用 param。
总结
通过本文，我们学习了如何在Karate Framework中有效地处理包含方括号和日期范围等复杂结构的GET请求参数。关键在于理解 param 关键字的用法，它提供了比 def query 更精细的控制，能够确保参数名和参数值被正确地解析和URL编码。掌握这一技巧，将有助于您在Karate中更灵活、准确地进行API自动化测试。
