IntelliJ IDEA 2025.1 Help

探索 HTTP 请求语法

本节介绍 HTTP 请求格式。 有关发送 HTTP 请求和查看 HTTP 响应的详细信息，请参阅 HTTP 客户端。

要在 IntelliJ IDEA 代码编辑器中编写 HTTP 请求，请使用以下通用语法：

Method Request-URI HTTP-Version Header-field: Header-value Request-Body

在 HTTP 请求中使用注释

  • 在请求中，使用 // 或 # 开始任何一行将其变成注释行。

    // A basic request GET http://example.com/a/

为 HTTP 请求设置名称

为了在 运行/调试配置、 Search Everywhere和 Run Anything中快速找到您的请求，您可以给它命名。

  • 在请求上方的 ###、 # @name 或 # @name = 旁边输入名称。

    输入 HTTP 请求名称

如果请求没有名称，IntelliJ IDEA 将使用其在请求文件中的位置（例如 #1 ）作为请求名称。 如果请求文件中包含多个同名请求，IntelliJ IDEA 会将请求位置编号附加到每个名称后面。 这将使每个请求名称唯一，以便您可以在 服务 工具窗口、运行/调试配置等中轻松找到所需的请求。

服务工具窗口中的 HTTP 请求

使用简短格式进行 GET 请求

  • 对于 GET请求，您可以省略请求方法并且只指定 URI。

    // A basic request https://example.com/a/

    在 Java 环境中，您可以使用 代码补全 Ctrl+Space 来根据已定义的 @Path 注解指定 URI。 对 Java 代码中 @Path 注释的任何更改都会反映在建议列表的内容中。

在单个文件中编写多个请求

  1. 通过在下方键入 ### 分隔符来标记请求的结束。

    // A basic request https://example.com/a/ ###

  2. 在分隔符下再写一个请求。

    // A basic request https://example.com/a/ ### // A second request using the GET method https://example.com:8080/api/html/get?id=123&value=content

将长请求分成几行

  • 将所有查询字符串行缩进，但第一行除外。

    // Using line breaks with indent GET http://example.com:8080 /api /html /get ?id=123 &value=content

  • 如果因查询字符串导致 URL 过长，您可以使用专用的上下文操作将每个查询参数放在新行上。 将文本光标放到查询字符串部分，按 Alt+Enter （显示上下文操作 ），然后选择 将查询形参放在单独的行中。

    GET https://example.com:8080/api/get/html?firstname=John&lastname=Doe&planet=Tatooine&town=Freetown
    GET https://example.com:8080/api/get/html? firstname=John& lastname=Doe& planet=Tatooine& town=Freetown

  • 同样，您可以在请求中格式化正文 Content-Type: application/x-www-form-urlencoded。 请将文本光标放置在正文处，按 Alt+Enter (显示上下文操作 )，然后选择 将form-urlencoded 形参放在单独的行中。

    POST https://ijhttp-examples.jetbrains.com/post Content-Type: application/x-www-form-urlencoded key1=value1&key2=value2&key3=value3&key4=value4&key5=value5
    POST https://ijhttp-examples.jetbrains.com/post Content-Type: application/x-www-form-urlencoded key1 = value1 & key2 = value2 & key3 = value3 & key4 = value4 & key5 = value5

    要配置 x-www-form-urlencoded 正文的换行，请使用 设置 | 编辑器 | 代码样式 | HTTP 请求 | 换行和大括号 | Form-urlencoded 形参换行。 要配置 = 之间以及 & 之前的空格，请使用 设置 | 编辑器 | 代码样式 | HTTP 请求 | 空格。

访问具有身份验证的 Web 服务

  • 根据您正在访问的网络服务，提供 基础或 摘要 授权头。

    // Basic authentication GET http://example.com Authorization: Basic username password ### // Digest authentication GET http://example.com Authorization: Digest username password

提供请求消息体

在请求中，在请求体的前面添加一个空行，并执行以下操作之一：

  • 请在此处输入请求正文：

    // The request body is provided in place POST https://example.com:8080/api/html/post HTTP/1.1 Content-Type: application/json Cookie: key=first-value { "key" : "value", "list": [1, 2, 3] }

    如果您将 Content-Type 标头字段的值设置为 支持的语言之一，那么相应的语言片段将会被 自动注入 到 HTTP 请求消息体中。 如果未指定 内容类型 ，您可以手动插入语言片段。

  • 在 Java 上下文中，您可以使用 代码补全 Ctrl+Space 来根据定义的 @Produces 注解指定 接受 标头字段的值。 任何对 Java 代码中 @Produces 注释的更改都会反映在建议列表的内容中。

  • 要从文件中读取请求正文，请键入 < 符号，后跟文件路径。

    // The request body is read from a file POST https://example.com:8080/api/html/post Content-Type: application/json < ./input.json

使用 multipart/form-data 内容类型

  • 将请求的 内容类型设置为 multipart/form-data。 要作为 multipart/form-data 消息的一部分发送文件，请在 Content-Disposition 标头中包含 filename 参数。

    POST https://example.com/api/upload HTTP/1.1 Content-Type: multipart/form-data; boundary=boundary --boundary Content-Disposition: form-data; name="first"; filename="input.txt" // The 'input.txt' file will be uploaded < ./input.txt --boundary Content-Disposition: form-data; name="second"; filename="input-second.txt" // A temporary 'input-second.txt' file with the 'Text' content will be created and uploaded Text --boundary Content-Disposition: form-data; name="third"; // The 'input.txt' file contents will be sent as plain text. < ./input.txt --boundary--

禁用后续重定向

当 HTTP 请求被重定向（收到 3xx 状态码）时，将返回重定向页面的响应。 在 服务 工具窗口中，您可以查看重定向的页面响应以及请求过程中发生的所有重定向。

您可能希望禁用跟随重定向。 在这种情况下，将返回实际的重定向响应头（如 301 或 302）。

  • 在请求之前，添加一行包含 @no-redirect 标签的注释。

    // @no-redirect example.com/status/301

如果您已经有一个重定向的请求，您可以点击 关闭 旁边的 Redirections 列表，位于 服务 工具窗口中。 这将向初始请求中添加 @no-redirect 标记。

HTTP 响应带有重定向

禁用将请求保存到请求历史

如有必要，您可以防止请求被保存到 请求历史记录。 在请求包含一些敏感数据而您不希望记录它的情况下，这可能会有所帮助。

  • 在请求之前，添加一行包含 @no-log 标签的注释。

    // @no-log GET example.com/api

禁用将接收到的 cookie 保存到 cookies jar

如有必要，您可以防止接收的 cookie 保存到 cookies jar。 这样您就可以避免手动从 http-client.cookies 文件中删除不需要的 cookies。

  • 在请求之前，添加一行包含 @no-cookie-jar 标签的注释。

    // @no-cookie-jar GET example.com/api

禁用编码

默认情况下，HTTP 客户端会将请求参数和正文编码为 ASCII 格式。 例如，您的请求参数中的斜杠字符将被发送为 %2F。 您可以禁用编码以按原样发送请求。

  • 在请求之前，添加一行包含 @no-auto-encoding 标签的注释。

    使用该标签时，请求参数和正文不会被编码：

    # @no-auto-encoding GET https://examples.com/api? name=@#$somebody& qwerty=%40%23%24

    生成的请求将按原样发送：

    https://examples.com/api?name=@#$somebody&qwerty=%40%23%24

    默认情况下，如果未使用该标签，编码将被启用。

    ### Default behavior GET https://examples.com/api? name=@#$somebody& qwerty=%40%23%24

    在此请求中，参数将被编码：

    https://examples.com/api?name=%40%23%24somebody&qwerty=%40%23%24

自定义 HTTP 请求超时

HTTP 客户端 在与服务器建立连接时有 60 秒的超时，同时在持续连接中等待新数据包也有 60 秒的超时。 您可以自定义这两个超时。

  • 要为已建立的连接中的新数据包设置超时时间，请在请求前添加带有 @timeout 标签的注释行。

    # @timeout 600 GET example.com/api

  • 要设置连接超时，请在请求前添加带有 @connection-timeout 标签的注释行。

    // @connection-timeout 2 m GET example.com/api

默认情况下，超时值以秒为单位，但您可以在值后添加明确的时间单位： ms 为毫秒， 秒 为秒， m 为分钟，例如 100&#xa0;ms 或 5 m。

使用变量

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

在请求中使用变量

  • 将变量用双花括号括起来，如 {{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}}" }

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

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

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

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

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

存储在 service1 目录中的 .http 文件将在您选择 dev 环境时使用 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 客户端 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 ：被替换为 IntelliJ IDEA 内置 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 客户端 会为此列表中的每个元素发送单独的请求。 IntelliJ IDEA 还支持这些变量的 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，IntelliJ IDEA 为您提供 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 %}

处理响应

您可以使用 JavaScript 处理响应。 在请求后输入 > 字符并指定 JavaScript 文件的路径和名称，或将响应处理程序脚本代码包装在 {% ... %} 中。

GET https://httpbin.org/get > /path/to/responseHandler.js
GET https://httpbin.org/get > {% client.global.set("my_cookie", response.headers.valuesOf("Set-Cookie")[0]); %}

有关更多信息，请参见 HTTP Response 处理 API 参考。

重定向响应

您可以将响应重定向到文件。 如果文件已存在，请使用 >> 创建一个带有后缀的新文件，并使用 >>! 重写该文件。 您可以指定绝对路径或相对于当前 HTTP 请求 文件的相对路径。 您还可以在路径中使用变量，包括环境变量和以下预定义变量：

  • {{$projectRoot}} 指向项目根目录

  • {{$historyFolder}} 指向 .idea/httpRequests/

以下示例 HTTP 请求在 HTTP 请求 文件旁边在 myFolder 中创建 myFile.json ，并将响应重定向到它。 如果文件已经存在，它会创建 myFile-1.json 。

POST https://httpbin.org/post Content-Type: application/json { "id": 999, "value": "content" } >> myFolder/myFile.json

以下示例 HTTP 请求在 myFile.json 中创建 .idea/httpRequests/ 。 如果文件已存在，它会覆盖文件。 它也会用位于项目根目录的 handler.js 脚本 处理响应。

POST https://httpbin.org/post Content-Type: application/json { "id": 999, "value": "content" } > {{$projectRoot}}/handler.js >>! {{$historyFolder}}/myFile.json
最后修改日期： 2025年 4月 24日
HTTP 客户端OAuth 2.0 身份验证