# HTTP 客户端变量

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com.cn/help/idea/llms.txt).

在编写 HTTP 请求时，您可以通过使用  variables 来参数化其元素。 变量可以保存请求的 host、port 和 path、查询参数或值、标头 值或请求正文中或外部文件中使用的任意值。

Procedure: 在请求中使用变量

* 将变量用双花括号括起来，如  `{{variable}}` 。

> **Note:**
> 如果需要在请求中使用大括号，但不希望它们被视为 HTTP 客户端变量，请使用 URL 编码格式：  `%7B`  表示  `{` ，  `%7D`  表示  `}` 。相当于。 例如：
>
>
>
>
> ```HTTP_REQUEST_FULL
> ### send URL-encoded {{variable}}
>
> GET https://www.example.com/search?q=%7B%7Bvariable%7D%7D
>
> ```

变量名称可以包含字母、数字、下划线符号  `_` 、连字符符号  `-`  或点符号  `。` （请参阅 [下面的说明](#note_about_dots) 了解变量名称中的点）。

## 变量类型

HTTP Client 中有几种类型的变量。 它们在作用域和优先级上有所不同；如果变量名称冲突，将使用列表中位置较高的变量的值。

* [环境变量](#environment-variables) 在专用环境文件中定义，可在任何 `.http` 文件中使用。 如果名称冲突，公共变量优先于私有变量。 使用 `client.variables.environment` 或 `request.environment` 访问。

* [全局变量](http-client-reference.html#global-variables-storage-reference) 在 [响应处理程序和预请求脚本](http-client-in-product-code-editor.html#using-response-handler-scripts) 中定义。 使用 `client.variables.global` 或 `client.global` 访问。

* [就地变量](#in-place-variables) 定义在 `.http` 文件中且仅在同一文件内可用。 使用 `client.variables.file` 访问。

* [请求级变量](#per_request_variables) 在请求前定义，并且仅在其后的单个请求内可用。 使用 `client.variables.request` 或 `request.variables` 访问。

* 此外，HTTP 客户端提供 [内置动态变量](#dynamic-variables)，其值是动态生成的。 此类变量有保留名称。

为了简化处理不同类型变量的过程，HTTP 客户端提供了单一访问点  `client.variables` 。 可以在预请求和响应处理程序脚本中使用它来访问所有变量作用域。 现有访问点（如  `client.global` 、  `request.environment`  和  `request.variables` ）也会保留。

> **Tip:**
> 从 2024.2 版本开始，IntelliJ IDEA 将 HTTP 请求中的所有变量（ [内置动态变量](#dynamic-variables) 除外）视为 JSONPath 表达式。 这有助于访问 [变量值中的集合](#collections-in-variables)。 这也意味着，如果在变量名称中使用点  `。` ，HTTP 客户端会期望其值与 JSON 数据匹配。 例如，  `{{client.host.url}}`  的值可以在  `dev`  环境文件中表示为：
>
>
>
>
> ```JSON
> {
> "dev":{
> "client": {
> "host": {
> "url": "example.org"
> }
> }
> }
> }
>
> ```
>
>
>
>
> ```HTTP_REQUEST_FULL
> # assuming an environment is selected, 'dev' in our case
>
> GET {{client.host.url}}
>
> ```
>
>
>
> 如果希望变量名称包含点，在 HTTP 请求中使用时，应将其括在引号和方括号中。 例如：
>
>
>
>
> ```JSON
> {
> "dev":{
> "client": {
> "host.url": "example.org"
> }
> }
> }
>
> ```
>
>
>
>
> ```HTTP_REQUEST_FULL
> GET {{client.['host.url']}}
>
> ```
>
>
>
> 有关在变量中使用 JSONPath 的更多示例，请参阅 [遍历变量中的集合](#collections-in-variables)。

## 环境变量

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

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

* 环境名称（如 生产环境 或 开发 ）：所选环境将用于当前文件中的所有请求，您在点击 ![运行按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.run.run.svg) 时无需选择它。 这在您想要使用相同的环境运行多个请求时非常有用，并且不希望每次运行请求时都选择它。

* <运行前选择环境> ：选择此选项后，每次点击 ![运行按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app.expui.run.run.svg) 时都必须选择一个环境。 如果您经常切换环境，并且希望在每次运行时明确选择它们以确保使用所需的环境执行请求，这将非常方便。

![运行请求：选择环境](https://resources.jetbrains.com.cn/help/img/idea/2026.3/调试配置](http-client-in-product-code-editor.html#http-request-run-debug-configurations)时用作默认环境。

Procedure: 定义环境变量

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

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

* 如果您希望环境是公开的，请选择 将环境添加到公共文件… 。 这会将环境添加到 `http-client.env.json` 文件。 此文件可以包含通用变量，例如主机名、端口或查询参数，并旨在与您的项目一起分发。

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

> **Tip:**
> 如果必要，您可以手动创建这些文件。

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

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

http-client.env.json:

```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"
    }
}

```

http-client.private.env.json:

```JSON
{
    "development": {
        "username": "dev-user",
        "password": "dev-password"
    },

    "production": {
        "username": "user",
        "password": "password"
    }
}

```

示例 HTTP 请求如下：

```HTTP_REQUEST
GET http://{{host}}/api/json/get?id={{id-value}}
Authorization: Basic {{username}} {{password}}
Content-Type: application/json

{
    "key": "{{my-var}}"
}

```

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

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

开发:

```HTTP_REQUEST
GET http://localhost/api/json/get?id=12345
Authorization: Basic dev-user dev-password
Content-Type: application/json

{
    "key": "my-dev-value"
}

```

生产环境:

```HTTP_REQUEST
GET http://example.com/api/json/get?id=6789
Authorization: Basic user password
Content-Type: application/json

{
    "key": "my-prod-value"
}

```

如果在执行请求时变量未解决，IntelliJ IDEA 将显示通知，让您能够快速创建、更新或选择不同的执行环境。

![HTTP 请求通知中的未解析变量](https://resources.jetbrains.com.cn/help/img/idea/2026.3/ps_http_client_unresolved_var.png)

> **Note:**
> 如果您在 IDEA 中使用 Git，  `http-client.private.env.json`  文件不会被 Git 跟踪。 但是，它并未添加到  `.gitignore` 文件中。 如果您使用第三方工具或通过终端提交您的更改，您可能需要手动添加  `http-client.private.env.json`  以防止在  `.gitignore`  共享机密信息：右键点击文件并选择  `Git | 添加到 .gitignore` 。

### 管理多个环境文件

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

* 对于文件 显示存储在当前和父目录中的环境。 如果从此列表中选择环境，HTTP 客户端 将尝试在当前目录中存储的文件（公共和私有）中找到它。 如果没有此环境的文件，它会检查父目录。

* 来自整个项目 显示了存储在项目中所有其他位置（当前目录和父目录之外）的环境。 如果这些目录中的文件包含与 对于文件 部分中的环境同名的环境，则不会在列表中显示。 如果您希望在项目中随处可见某个环境，可以为其指定一个唯一名称。

![HTTP 客户端 环境](https://resources.jetbrains.com.cn/help/img/idea/2026.3/http_client_environments.png)

让我们用一个示例来说明这一点。 假设您有以下项目结构：

```CONSOLE
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

```

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

如果私有文件包含  `host`  变量，那么  `.http`  文件将使用其值，因为私有文件优先于公共文件。 否则，他们将使用公共文件中的值。

## 就地变量

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

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

```HTTP_REQUEST_FULL
@myhost = example.org

GET {{myhost}}/users

###
GET {{myhost}}/stats

```

## 每个请求变量

您可以使用  `request.variables.set(variableName, variableValue)`  方法设置 HTTP 请求中使用的变量值。 请将其写入 HTTP 请求上方的  `{% ... %}`  中的预请求脚本。 例如：

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

```

在预请求脚本中定义的变量仅在脚本后随后的单个请求中可用。

使用   初始化变量   上下文操作（ `Alt+Enter` (Windows), `⌥ ⏎` (macOS), `⌥ ⏎` (IntelliJ IDEA Classic (macOS)), `⌥ ⏎` (macOS System Shortcuts), `Alt+Enter` (XWin), `Alt+Enter` (GNOME), `Alt+Enter` (KDE), `Alt+Enter` (Emacs), `Alt+Enter` (Sublime Text), `⌥ ⏎` (Sublime Text (macOS)), `Alt+Enter` (Visual Studio), `⌥ ⏎` (Visual Studio (macOS)), `Alt+Enter` (NetBeans), `Ctrl+1` (Eclipse), `⌘ 1` (Eclipse (macOS))），可快速添加就地或环境变量，或在预请求处理脚本中初始化变量。

![初始化变量意图操作](https://resources.jetbrains.com.cn/help/img/idea/2026.3/http_create_pre_request_variable.animated.gif)

在预请求脚本中，您还可以使用 [HTTP 客户端 Crypto API](http-client-crypto-api-reference.html) 生成基于加密哈希函数（如 SHA-1、SHA-256、SHA-512、MD5）的 HTTP 签名，并将它们作为变量传递给您的请求。 例如：

```HTTP_REQUEST_FULL
< {%
    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)` ：生成 `从` （包括）和 `为` （不包括）之间的随机整数，例如 random.integer(100, 500)。 如果您未提供任何参数，它会生成一个介于 0 和 1000 之间的随机整数。

* `$random.float(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` ：被替换为 IntelliJ IDEA 内置 web 服务器，只能使用 HTTP 客户端 进行访问。 变量用于 GraphQL 和 WebSocket [示例](http-client-in-product-code-editor.html#open-requests-collection)。

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

```JAVASCRIPT
POST http://localhost/api/post?id={{$uuid}}

{
    "time": {{$timestamp}},
    "price": {{$random.integer(10, 1000)}},
}

```

在预请求处理程序脚本和响应处理程序脚本中，像常规 JavaScript 变量一样使用它们，无需花括号。 例如：

```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 客户端支持 [Java faker](https://javadoc.io/doc/com.github.javafaker/javafaker/latest/com/github/javafaker/package-summary.html) 库中的以下类（以及这些类中不需要任何参数的方法）：

* `$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`

> **Tip:**
> 开始键入  `{{$random.}}`  以获取可用变量的建议。

#### 动态变量本地化

默认情况下，HTTP 客户端使用 [Java faker](https://javadoc.io/doc/com.github.javafaker/javafaker/latest/com/github/javafaker/package-summary.html) 库的默认区域设置（英语，美国）生成随机数据。 例如，以下请求

```JAVASCRIPT
                        @test = {{$random.address.fullAddress}}
###
< {%
    console.log($random.address.fullAddress)
%}

GET https://examples.http-client.intellij.net/get
                    
```

会生成一个按默认区域设置格式化的随机地址：  `Apt. 123 Main Street, Springfield, IL 12345` 。

要生成特定于区域的数据，可以显式指定 [受支持的区域设置之一](https://github.com/DiUS/java-faker?tab=readme-ov-file#supported-locales)，方法是使用  `locale`  修饰符：

```JAVASCRIPT
                        @testName = {{$random.locale.name.fullName("fr")}}
@testAddress = {{$random.locale.address.fullAddress("fr")}}
@testPhone = {{$random.locale.phoneNumber.cellPhone("fr")}}

< {%
    console.log("Name:", client.variables.file.get("testName"))
    console.log("Address:", client.variables.file.get("testAddress"))
    console.log("Phone:", client.variables.file.get("testPhone"))
%}

POST https://httpbin.org/post
Content-Type: application/json

{
  "name": "{{testName}}",
  "address": "{{testAddress}}",
  "phone": "{{testPhone}}"
}
                    
```

可以通过指定 [随机种子](https://en.wikipedia.org/wiki/Random_seed)，使本地化随机值具有确定性。 使用相同的种子和区域设置会在每次执行时生成相同的值。

在以下示例中，  `12`  是用于初始化随机生成器的随机种子：

```JAVASCRIPT
@testName = {{$random.locale.name.fullName("fr", 12)}}

```

## 系统环境变量

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

要访问它们，请使用  `{{$env.ENV_VAR}}`  语法，其中  `ENV_VAR`  是您的环境变量的名称。 在预请求处理程序脚本和响应处理程序脚本中，像常规 JavaScript 变量一样使用它们，无需花括号。 例如：

```HTTP_REQUEST_FULL
GET http://localhost:63345/{{$env.USER}}

> {%
    const myUser = $env.USER
    client.log(myUser)
%}

```

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

![HTTP 客户端中的系统环境变量](https://resources.jetbrains.com.cn/help/img/idea/2026.3/http_client_system_environment_variables.png)

## 遍历变量中的集合

[环境变量](#environment-variables)和 [在预请求脚本中初始化的变量](#per_request_variables)可以表示一个元素集合，例如，ID 或用户名列表。 当此类变量在 HTTP 请求中使用时，HTTP 客户端 会为此列表中的每个元素发送单独的请求。 IntelliJ IDEA 还支持这些变量的 JSONPath 表达式，使您能够访问特定元素或元素子集，并为每个元素发送请求。

例如，如果您有一个通过 ID 返回有关图书信息的服务器，您可以将一个 JSON 数组  `[1,2,3,4,5]` 分配给变量  `id` ，然后在主体或 URL 部分使用它。

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

```

HTTP 客户端 将发送五个连续请求，每个请求都会用集合中的后续项替换变量。

同样，您可以在请求主体中使用集合。 在以下示例中，HTTP 客户端 将发送三个请求，其主体中的值分别为：  `name: Alice` 、  `name: Bob`  和  `name: Charlie` 。

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

{
  "name": {{name}}
}

```

使用 JSONPath，您还可以访问数组中 JSON 对象的特定参数。 例如，在以下查询中，HTTP 客户端 将为名为  `users`  的变量内的所有对象的每个  `名称`  值发送请求。

为了便于在变量中使用 JSONPath，IntelliJ IDEA 为您提供 JSONPath 编码支持，包括已知 JSON 对象参数的自动完成、验证和高亮显示。 JSONPath 语言会 [注入](using-language-injections.html)到所有 HTTP 客户端变量（用双花括号括起）中， [动态变量](#dynamic-variables)除外。

```HTTP_REQUEST_FULL
GET http://localhost:8080/users/{{users[*].name}}

```

![遍历变量中的集合](https://resources.jetbrains.com.cn/help/img/idea/2026.3/http_client_iterate_over_collections_in_variables.png)

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

### request.iteration() 的示例

```HTTP_REQUEST_FULL
### 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() 示例

```HTTP_REQUEST_FULL
### 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

%}

```