WebStorm 2025.2 Help

HTTP Client 变量

在构造 HTTP 请求时，您可以使用 变量来参数化其元素。 变量可以包含请求的主机、端口和路径，查询参数或其值、头信息值，或在请求正文或外部文件中使用的任意值。

在请求中使用变量

  • 使用两个大括号括起变量，例如 {{variable}}。

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

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

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

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

  • 就地变量定义在 .http 文件中，仅在相同文件中可用。

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

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

环境变量

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

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

  • 环境名称（例如 生产 或 开发 ）：所选环境将用于当前文件中的所有请求，在点击 运行按钮 时无需选择环境。 这对于要使用相同环境运行多个请求并希望避免每次都手动选择环境的情况非常有用。

  • 运行前选择环境 ：选择此选项后，每次点击 运行按钮 时都必须选择一个环境。 如果您经常切换环境并希望在每次运行时明确选择所需环境，则此方式很方便。

运行请求：选择环境

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

定义环境变量

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

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

    在执行请求之前，WebStorm 允许您通过位于请求编辑面板顶部的 使用以下方式运行 列表选择一个执行环境。

    根据您的选择，生成的请求将如下所示：

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

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

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 文件将使用 myKey1 的值作为 key 变量的值。 存储于 service2 目录下的 .http 文件将使用 myKey2 的值作为 key 变量的值。

如果私有文件中包含 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 ：将替换为 WebStorm 内置 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 Client 会为该列表中的每个元素发送单独的请求。 WebStorm 还支持用于此类变量的 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，WebStorm 提供 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 授权