PyCharm 2025.3 Help

HTTP 客户端变量

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

在请求中使用变量

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

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

变量类型

HTTP 客户端中有多种类型的变量。 它们在作用域和优先级上有所不同；如果变量名发生冲突，将使用列表中更靠上的变量的值。

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

    通过 client.variables.environment 或 request.environment 进行访问。

  • 全局变量 定义在 响应处理程序和预请求脚本中。

    通过 client.variables.global 或 client.global 进行访问。

  • 就地变量 定义在 .http 文件中，并且仅在同一文件内可用。

    通过 client.variables.file 进行访问。

  • 每次请求的变量 在请求之前定义，仅在随后紧接的单个请求中可用。

    通过 client.variables.request 或 request.variables 进行访问。

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

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

环境变量

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

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

  • 环境名称（例如 生产 或 开发 ）：所选环境将用于当前文件中的所有请求，点击 运行按钮 时无需再次选择。 如果您希望使用同一环境运行多个请求且不想在每次运行请求时都进行选择，这将十分有用。

  • <在运行前选择环境> ：选择此选项时，您每次点击 运行按钮 都需要选择一个环境。 如果您经常切换环境，并希望在每次运行时显式选择环境以确保使用所需环境执行请求，此选项会非常方便。

运行请求：选择环境

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

定义环境变量

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

  1. 在请求的编辑器面板顶部的 使用指定环境运行 列表中，选择您希望添加环境的位置：

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

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

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

    以下示例 http-client.env.json 环境文件定义了两个环境： 开发 和 生产。 附加的 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}}" }

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

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

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

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

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

管理多个环境文件

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

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

    如果您从此列表中选择环境，HTTP 客户端会尝试在当前目录中存储的文件（公共与私有）中查找该环境。 如果当前目录中没有包含该环境的文件，则会检查父目录。

  • 来自整个项目 显示存储在项目其他位置（不包括当前目录及父目录）中的环境。 如果这些目录中的文件包含与 对于文件 部分中的环境同名的环境，则不会在列表中显示。

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

HTTP 客户端环境

下面通过一个示例进行说明。 假设您的项目结构如下：

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 ：将被替换为 PyCharm 内置 Web 服务器，该服务器只能通过 HTTP 客户端访问。 该变量用于 GraphQL 和 WebSocket 示例。

更多动态变量

您还可以生成其他类型的随机数据，例如地址、颜色和公司名称。 HTTP 客户端支持来自 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 客户端中，您可以使用操作系统中的环境变量。

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

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

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

HTTP 客户端中的系统环境变量

遍历变量中的集合

环境变量和 在预请求脚本中初始化的变量可以表示一个元素集合，例如 ID 或用户名列表。 在 HTTP 请求中使用此类变量时，HTTP 客户端会为该列表中的每个元素发送单独的请求。 PyCharm 还支持对这类变量使用 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 客户端将连续发送五个请求，每个请求都会用集合中的后续项替换该变量。

同样，您也可以在请求正文中使用集合。 在以下示例中，HTTP 客户端将发送三个正文值不同的请求： 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 客户端将针对名为 users 的变量中的所有对象，为每个 name 值发送请求。

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

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年 12月 2日
探索 HTTP 请求语法OAuth 2.0 授权