GoLand 2025.2 Help

HTTP Client 变量

在构造 HTTP 请求时，您可以使用 变量对其各元素进行参数化。 变量可用于保存请求的主机、端口和路径、查询参数或值、标头值，或用于请求正文或外部文件中的任意值。

在请求中使用变量

  • 使用双花括号包裹变量，例如 {{variable}}。

变量名称可以包含字母、数字、下划线符号 _ 、连字符符号 - ，或点号 . （参见 以下关于变量名中点的说明）。

HTTP Client 中有几种类型的变量。 它们按优先顺序列出；如果变量名称冲突，将使用列表中优先级较高的值：

  • 环境变量定义于专用的环境文件中，可在任何 .http 文件中使用（若名称冲突，公共变量优先于私有变量）。

  • 在 响应处理器脚本中使用 client.global.set 方法定义的全局变量。

  • 定义于 .http 文件中，仅在该文件内可用的 就地变量。

  • 使用 request.variables.set 方法在请求前定义，仅在该请求中可用的 每个请求的变量。

此外，HTTP Client 提供具有动态生成值的 内置动态变量。 这些变量具有保留名称。

环境变量

环境变量可用于在项目中存储一组环境定义。 例如，您可以在请求中不直接提供主机名，而是在各环境中创建 {{host}} 变量：开发环境中使用本地主机名，生产环境中使用公共主机名。 然后，您可以使用当前 .http 文件编辑器顶部的 使用以下环境运行 列表来选择环境：

  • 无环境 ：选择此选项时，运行当前文件中的请求将不会使用任何环境。 如果您的请求中不包含任何变量，请选择此选项。

  • 环境名称（例如 production 或 development ）：选择的环境将用于当前文件中的所有请求，点击 运行按钮 时无需重复选择。 如果希望使用相同环境运行多个请求并避免每次运行时都进行选择，该选项将非常有用。

  • 运行前选择环境 ：选择此选项时，您每次点击 运行按钮 时必须选择一个环境。 如果您经常切换环境并希望在每次执行时明确选择环境以确保使用正确的环境，则此选项非常方便。

运行请求：选择环境

所选环境将在 查看结构请求时、 在浏览器中打开请求时、 执行请求时及为其 创建运行/调试配置时作为默认环境使用。

定义环境变量

环境变量定义在 环境文件中。

  1. 在请求编辑器面板顶部的 使用以下环境运行 列表中，选择要添加环境的位置：

    • 如果您希望环境为公共环境，请选择 添加环境到公共文件…。 这将把环境添加到 http-client.env.json 文件中。 此文件可以包含诸如主机名、端口或查询参数等常用变量，旨在与项目一同分发。

    • 如果您希望环境为私有环境，请选择 添加环境到私有文件…。 这将把环境添加到 http-client.private.env.json 文件中。 该文件可能包含密码、令牌、证书及其他敏感信息。 在 http-client.private.env.json 文件中指定的变量值将覆盖公共环境文件中的值。

  2. 在创建的文件中填充所需的变量。

    以下示例 http-client.env.json 环境文件定义了两个环境： development 和 production。 附加的 http-client.private.env.json 文件包含敏感的授权数据。

    { "development": { "host": "localhost", "id-value": 12345, "username": "", "password": "", "my-var": "my-dev-value" }, "production": { "host": "example.com", "id-value": 6789, "username": "", "password": "", "my-var": "my-prod-value" } }
    { "development": { "username": "dev-user", "password": "dev-password" }, "production": { "username": "user", "password": "password" } }

    示例 HTTP 请求如下：

    GET http://{{host}}/api/json/get?id={{id-value}} Authorization: Basic {{username}} {{password}} Content-Type: application/json { "key": "{{my-var}}" }

    在执行请求之前，GoLand 允许您使用请求编辑器面板顶部的 使用以下环境运行 列表选择执行环境。

    根据您的选择，生成的请求将为以下之一：

    GET http://localhost/api/json/get?id=12345 Authorization: Basic dev-user dev-password Content-Type: application/json { "key": "my-dev-value" }
    GET http://example.com/api/json/get?id=6789 Authorization: Basic user password Content-Type: application/json { "key": "my-prod-value" }

如果执行请求时变量未解析，GoLand 会显示通知，允许您快速创建、更新或选择其他执行环境。

HTTP 请求通知中未解析的变量

管理多个环境文件

您的项目可能包含多个目录，这些目录中包含 HTTP 请求文件及相应的环境文件。 在这种情况下，选择请求的环境时，下列部分可能可用：

  • 对于文件 显示当前及上级目录中存储的环境。

    如果您从此列表中选择了某个环境，HTTP Client 会尝试从当前目录中存储的文件（包括公共与私有文件）中查找； 如果当前目录中没有对应环境的文件，则会检查上级目录。

  • 来自整个项目 显示项目中除了当前和上级目录外的其他位置中存储的环境。 如果这些目录中的文件包含与 对于文件 区段中相同名称的环境，该环境将不会显示在列表中。

    如果您希望某个环境在项目中所有地方都可见，可以为其指定唯一名称。

HTTP Client 环境

我们通过一个示例来说明这一点。 假设您的项目结构如下：

root/http-client.env.json # public file with 'dev' environment and 'host' variable root/service1/http-client.private.env.json # private file with 'dev' environment and "key": "myKey1" variable root/service2/http-client.private.env.json # private file with 'dev' environment and "key": "myKey2" variable

当您选择 dev 环境时，存储在 service1 目录下的 .http 文件将使用 key 变量的 myKey1 值。 存储在 service2 目录下的 .http 文件将使用 key 变量的 myKey2 值。

如果私有文件中包含 host 变量， .http 文件将使用该值，因为私有文件的优先级高于公共文件。 否则，将使用公共文件中的值。

就地变量

就地变量的作用域是声明该变量的 .http 文件。 如果您希望在同一文件中的多个请求中引用相同的变量，请使用就地变量。

要创建就地变量，请在 HTTP 方法部分上方键入 @ ，然后输入变量名称。 例如：

@myhost = example.org GET {{myhost}}/users ### GET {{myhost}}/stats

每个请求的变量

您可以使用 request.variables.set(variableName, variableValue) 方法设置 HTTP 请求中所用变量的值。 将其写入包含在 {% ... %} 中的预请求脚本中，并置于您的 HTTP 请求之前。 例如：

< {% request.variables.set("firstname", "John") %} GET http://example.org/{{firstname}}

在预请求脚本中定义的变量仅在其后紧跟的一个请求中可用。

使用上下文操作 初始化变量 （Alt+Enter ）可快速添加就地变量或环境变量，或在预请求处理脚本中初始化变量。

初始化变量意图操作

在预请求脚本中，您还可以使用 HTTP Client Crypto API 基于加密哈希函数（如 SHA-1、SHA-256、SHA-512、MD5）生成 HTTP 签名，并将其作为变量传递给请求。 例如：

< {% const signature = crypto.hmac.sha256() .withTextSecret(request.environment.get("secret")) // get variable from http-client.private.env.json .updateWithText(request.body.tryGetSubstituted()) .digest().toHex(); request.variables.set("signature", signature) const hash = crypto.sha256() .updateWithText(request.body.tryGetSubstituted()) .digest().toHex(); request.variables.set("hash", hash) %} POST https://httpbin.org/post X-My-Signature: {{signature}} X-My-Hash: {{hash}} Content-Type: application/json

动态变量

动态变量在每次运行请求时都会生成一个值。 它们的名称以 $ 开头：

  • $uuid 或 $random.uuid ：生成一个通用唯一标识符（UUID-v4）

  • $timestamp ：生成当前 UNIX 时间戳

  • $isoTimestamp ：生成 UTC 时区的 ISO-8601 格式当前时间戳。

  • $randomInt ：生成 0 到 1000 之间的随机整数。

  • $random.integer(from, to) ：生成一个在 from （包含）与 to （不包含）之间的随机整数，例如 random.integer(100, 500)。 如果您未提供参数，则会生成一个介于 0 到 1000 之间的随机整数。

  • $random.float(from, to) ：生成一个在 from （包含）与 to （不包含）之间的随机浮点数，例如 random.float(10.5, 20.3)。 如果您未提供参数，则会生成一个介于 0 到 1000 之间的随机浮点数。

  • $random.alphabetic(length) ：生成一串长度为 length （必须大于 0）的大小写字母序列。

  • $random.alphanumeric(length) ：生成一串由大写字母、小写字母、数字和下划线组成的长度为 length （必须大于 0）的序列。

  • $random.hexadecimal(length) ：生成长度为 length （必须大于 0）的随机十六进制字符串。

  • $random.email ：生成一个随机电子邮件地址。

  • $exampleServer ：将替换为内置的 GoLand Web 服务器，仅可通过 HTTP Client 访问。 该变量用于 GraphQL 和 WebSocket 示例中。

更多动态变量

您可以生成其他类型的随机数据，例如地址、颜色和公司名称。 HTTP Client 支持来自 Java faker 库的以下类（及其不需要任何参数的方法）：

  • $random.address

  • $random.beer

  • $random.bool

  • $random.business

  • $random.ChuckNorris.fact

  • $random.code

  • $random.color

  • $random.commerce

  • $random.company

  • $random.crypto

  • $random.educator

  • $random.finance

  • $random.hacker

  • $random.idNumber

  • $random.internet

  • $random.lorem

  • $random.name

  • $random.number

  • $random.phoneNumber

  • $random.shakespeare

  • $random.superhero

  • $random.team

  • $random.university

开始输入 {{$random.}} 以获取可用变量的建议。

在请求的各部分中使用动态变量，例如 URL 参数或正文：

POST http://localhost/api/post?id={{$uuid}} { "time": {{$timestamp}}, "price": {{$random.integer(10, 1000)}}, }

在预请求处理脚本和响应处理脚本中，使用时无需使用花括号，类似于常规 JavaScript 变量。 例如：

< {% const longUUID = $random.uuid request.variables.set("generatedQuery", longUUID) %} GET https://examples.http-client.intellij.net/get ?generatedQuery={{generatedQuery}} > {% client.log(`Today is ${$isoTimestamp}`) %}

系统环境变量

在 HTTP Client 中，您可以使用操作系统中的环境变量。

若要访问这些变量，请使用 {{$env.ENV_VAR}} 语法，其中 ENV_VAR 是您的环境变量名称。 在预请求处理脚本和响应处理脚本中，使用时无需使用花括号，类似于常规 JavaScript 变量。 例如：

GET http://localhost:63345/{{$env.USER}} > {% const myUser = $env.USER client.log(myUser) %}

开始输入变量名称以获取可用变量的建议：

HTTP Client 中的系统环境变量

在变量中迭代集合

环境变量和 在预请求脚本中初始化的变量可以表示元素集合，例如 ID 或用户名列表。 当在 HTTP 请求中使用这类变量时，HTTP Client 会为此列表中的每个元素发送一个单独的请求。 GoLand 还支持针对此类变量的 JSONPath 表达式，可用于访问特定元素或元素子集，并为每个元素发送请求。

例如，若服务器可通过书籍 ID 返回书籍信息，您可以将 JSON 数组 [1,2,3,4,5] 赋值给变量 id ，然后将其用于正文或 URL 部分。

< {% request.variables.set("id", [1,2,3,4,5]) %} GET http://localhost:8080/books/{{id}}

HTTP Client 将连续发送五个请求，每个请求中使用集合中的下一个项替换变量。

类似地，您也可以在请求正文中使用集合。 在以下示例中，HTTP Client 将发送三个正文中值不同的请求： name: Alice、 name: Bob 和 name: Charlie。

< {% request.variables.set("name", ["Alice", "Bob", "Charlie"]) %} GET http://localhost:8080/users Content-Type: application/json { "name": {{name}} }

通过使用 JSONPath，您也可以访问数组中 JSON 对象的特定参数。 例如，在以下查询中，HTTP Client 将针对名为 users 的变量中的所有对象，为每个 name 值发送请求。

为了便于在变量中使用 JSONPath，GoLand 提供 JSONPath 代码辅助功能，包括已知 JSON 对象参数的补全、验证和高亮显示。 除 动态变量外，JSONPath 语言会 注入到所有 HTTP Client 变量（使用双花括号包裹）中。

GET http://localhost:8080/users/{{users[*].name}}
在变量中迭代集合

若要在循环中获取当前索引，在预请求脚本和响应处理脚本中使用 request.iteration() 方法。 例如， 0 表示正在处理数组中的第一个项，并正在发送第一个请求。

request.iteration() 示例

### Use request.iteration() < {% request.variables.set("clients", [ // test data {"id": 1, "firstName": "George", "lastName": "Franklin", balance: 100}, {"id": 2, "firstName": "John", "lastName": "Doe", balance: 1500}, {"id": 3, "firstName": "Eduardo", "lastName": "Rodriquez", balance: 10} ]) %} POST https://examples.http-client.intellij.net/post Content-Type: application/json { "clientId": {{$.clients..id}}, "firstName": "{{$.clients..firstName}}", "lastName": "{{$.clients..lastName}}", "balance": "{{$.clients..balance}}" } > {% client.log(request.iteration()) // prints 0 for 1st request, 1 for 2nd, 2 for 3rd let current = request.variables.get("clients")[request.iteration()] client.test(`Account ${current.lastName} has initial balance ${current.balance}`, () => { let responseBalance = jsonPath(response.body, "$.json.balance") client.assert(responseBalance == current.balance) }) %}

若要在循环中按索引获取值，请在预请求脚本和响应处理脚本中使用 request.templateValue(Integer) 方法。

request.templateValue() 示例

### Use templateValue < {% request.variables.set("books", [{ "books": { "title": "Ulysses", "year": 1922 } }, { "books": { "title": "Dune", "year": 1965 }}]) %} GET http://localhost:8080/books Content-Type: application/json { "bookTitle": "{{$.books..title}}", "bookYear": "{{$.books..year}}" } > {% let bookTitle = request.templateValue(0) client.log(`book title is: ${bookTitle}`) // prints Ulysses in 1st request, Dune in 2nd client.log(request.iteration()) let bookYear = request.templateValue(1) client.log(`book year is: ${bookYear}`) // prints 1922 in 1st request, 1965 in 2nd %}
最后修改日期： 2025年 9月 26日
探索 HTTP 请求语法OAuth 2.0 授权