设置会在首次请求之前应用于整个文件，`###` 用于分隔请求，指令可以重复、限制或验证某个请求。更多示例见：[`_examples/`](https://github.com/unkn0wn-root/resterm/blob/main/_examples)。

## CLI

`resterm run` 执行 `.http` / `.rest` 文件而无需打开 TUI，这正是 CI 所运行的方式。```bash
resterm run --request CreateUser requests.http

在 TUI 中，按 `g Shift+M` 即可从工作区启动相同的模拟服务器。

[CLI 文档](https://github.com/unkn0wn-root/resterm/blob/main/docs/cli.md) 涵盖了选择器、输出格式及更多示例。

## 键盘速查表

- 窗格焦点与布局
  - `Tab` / `Shift+Tab`：在侧边栏、编辑器和响应之间移动。
  - `g+r`、`g+i`、`g+p`：跳转到请求、编辑器或响应。
  - `g+h` / `g+l`：水平调整大小。当侧边栏聚焦时更改侧边栏宽度，否则调整编辑器/响应分割。
  - `g+j` / `g+k`：当编辑器/响应堆叠时调整其高度，在导航器中折叠或展开分支。
  - `g+v` / `g+s`：在行内布局和堆叠布局之间切换响应窗格。
  - `g+1`、`g+2`、`g+3`：最小化或恢复侧边栏、编辑器、响应。
  - `g+z` / `g+Z`：缩放聚焦的窗格，清除缩放。
- 环境与全局变量
  - `Ctrl+E`：切换环境。
  - `Ctrl+G`：检查捕获的全局变量。
- 帮助与命令
  - `?`：打开可搜索的离线帮助索引。
  - `K`（编辑器普通模式）：打开光标下指令、模板或关键字的帮助。
  - `:help <主题>` / `:man <主题>`：打开嵌入式主题；`:docs <主题>` 打开版本匹配的完整手册。
  - `Ctrl+O`：打开文件/工作区弹窗。输入以过滤，使用 `Up` / `Down` 滚动，使用 `Tab` 进入目录。
  - `:`：打开命令行。使用 `Up` / `Down` 选择建议，`Tab` 补全一项，或 `Enter` 接受并运行所选内容。路径参数（如 `:mock start --source` 和 `:edit`）会在同一弹窗中浏览文件系统。
- 响应
  - `Ctrl+V` / `Ctrl+U`：拆分响应窗格以进行并排比较。
  - `Ctrl+Shift+C` 或 `g y`（响应聚焦时）：复制整个 Pretty、Raw 或 Headers 标签页。
  - `g x`：在不发送请求的情况下显示当前请求的 Explain 预览。
  - `g e`：在外部编辑器中打开当前文件。

> [!TIP]
> 如果你只记得三个快捷键：
> - `Ctrl+Enter` 发送请求
> - `Tab` / `Shift+Tab` 切换窗格
> - `g+p` 跳转到响应

## 安装

**Linux / macOS（Homebrew）**```bash
brew install resterm

或使用 `wget`：```bash
wget -qO- https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.sh | bash

脚本会检测你的架构，下载最新版本并安装二进制文件。

### 手动安装

> [!NOTE]
> 手动安装辅助工具使用 `curl` 和 `jq`。请使用你的包管理器安装 `jq`（例如 `brew install jq`、`sudo apt install jq` 等）。

**Linux / macOS**```bash
# Detect latest tag
LATEST_TAG=$(curl -fsSL https://api.github.com/repos/unkn0wn-root/resterm/releases/latest | jq -r .tag_name)

# Download the matching binary (Darwin/Linux + amd64/arm64)
curl -fL -o resterm "https://github.com/unkn0wn-root/resterm/releases/download/${LATEST_TAG}/resterm_$(uname -s)_$(uname -m)"

# Make it executable and move it onto your PATH
chmod +x resterm
sudo install -m 0755 resterm /usr/local/bin/resterm

### 来源```bash
go install github.com/unkn0wn-root/resterm/cmd/resterm@latest

第一条命令用于报告是否有更新的版本可用。第二条命令负责下载、校验并就地安装。在 Windows 上，旧二进制文件会以 `resterm.exe.old` 的形式保留在新文件旁边，并在下次更新时被清理。

## 配置

- 环境是 JSON 文件（`resterm.env.json`），会在请求目录、工作区根目录或当前工作目录（CWD）中发现。一个文件可以定义命名环境或独立分组，例如 api、app 和 credentials，它们会合并为一个环境。Dotenv 文件（`.env`、`.env.*`）通过 `--env-file` 选择启用，且仅限单个工作区。参见[分组环境](https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md#grouped-environments)以及 `_examples/grouped/` 中的可运行示例。
- 配置按操作系统存储，并可通过 `RESTERM_CONFIG_DIR` 覆盖：
  - macOS：`~/Library/Application Support/resterm`
  - Windows：`%APPDATA%\resterm`
  - Linux/Unix：`~/.config/resterm`

## 模拟服务器

你可以在与请求相同的 `.http` 文件中定义模拟响应。

- 按查询、请求头或 JSON 请求体匹配传入请求，然后选择命名响应或默认响应。
- 返回一系列响应以用于轮询和重试测试。使用路径、查询、请求头或 Cookie 值来分别跟踪每个序列。
- 按固定时长延迟响应，或使用 `random`、`normal` 或 `jitter` 为每个请求提供不同的延迟。
- 基于路径、查询、请求头和请求体值构建响应，并支持用于动态数据的生成器。
- 使用 `@expect` 验证调用次数，或从 RestermScript 检查接收到的流量。
- 热重载源文件和夹具，并可选支持 TLS。

同一路由上的两种场景：```http
### Payment accepted
# @mock method=POST path=/payments name=accepted default=true latency=150ms
HTTP/1.1 202 Accepted
Content-Type: application/json

{"id":"pay_123","status":"pending"}

### Payment declined
# @mock method=POST path=/payments name=declined
# @match query={"mode":"decline"} headers={"X-Tenant":"demo"} json={"amount":0}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{"error":"amount must be positive"}

更多内容请参阅 [Mock Servers 参考文档](https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md#mock-servers)、[`resterm mock` CLI 指南](https://github.com/unkn0wn-root/resterm/blob/main/docs/cli.md#resterm-mock) 以及 [工作示例](https://github.com/unkn0wn-root/resterm/blob/main/_examples/mocks.http)。

## Headless

[`headless`](https://github.com/unkn0wn-root/resterm/blob/main/headless) 包是驱动 TUI 和 CLI 的同一引擎的公共 Go API。使用它可以在你自己的 Go 代码或 CI 中运行请求、工作流、断言、比较运行结果和配置文件。

如果你不想自己构建运行器，可以使用 [resterm-runner](https://github.com/unkn0wn-root/resterm-runner)。

## Collections

将工作区导出为 Git 友好的捆绑包，并导入到另一个工作区中。捆绑包携带包含校验和的 `manifest.json`，因此导入时会先验证文件完整性。环境值会以 `REPLACE_ME` 占位符的形式导出，因此机密信息永远不会离开你的机器。```bash
resterm collection export --workspace ./my-api --out ./shared/my-api-bundle
resterm collection import --in ./shared/my-api-bundle --workspace ./my-local-api

变成这样：```http
### POST https://api.example.com/login
# @auth basic demo secret
POST https://api.example.com/login
Content-Type: application/json

{"user":"demo"}

由于无法看到您提供的具体输入内容，我无法进行翻译。请提供需要翻译的文本内容。```http
# @use ./rts/helpers.rts
# @when env.has("feature")
# @assert response.statusCode == 200
GET https://api.example.com/users/{{= vars.get("user") }}
Authorization: {{= helpers.authHeader(vars.get("auth.token")) }}

示例：[`_examples/oauth2.http`](https://github.com/unkn0wn-root/resterm/blob/main/_examples/oauth2.http)。请参阅 [OAuth 2.0 文档](https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md#oauth-20-directive)。

### 工作流与脚本

工作流将命名请求串联起来，并可根据响应选择下一步：```http
### Sign in
# @workflow sign-in
# @step Login using=Login
// GetProfile and RefreshToken are request names.
// The first true condition runs the named request.
# @if last.statusCode == 200 run=GetProfile
# @elif last.statusCode == 401 run=RefreshToken
# @else fail="unexpected login response"

每个轮询周期都有自己独立的重试预算。示例：[`_examples/polling-retries.http`](https://github.com/unkn0wn-root/resterm/blob/main/_examples/polling-retries.http)。参见[轮询与重试文档](https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md#polling-and-retries)。

### 比较运行

`@compare` 针对至少两个环境运行同一个请求，并以其中一个结果作为基线：```http
### Compare health
# @compare dev stage prod base=prod
GET {{services.api.base}}/status

结果会显示在“时间线”标签页中，并可导出到 OpenTelemetry。示例：[`_examples/trace.http`](https://github.com/unkn0wn-root/resterm/blob/main/_examples/trace.http)。请参阅[追踪文档](https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md#timeline--tracing)。

### 流式传输（WebSocket 和 SSE）

`@sse` 记录服务器事件，而 `@websocket` 和 `@ws` 则编写 WebSocket 帧的脚本。两者都会在“流”标签页中生成记录：```http
### Events
# @sse duration=30s idle=10s max-events=5
GET https://api.example.com/events

### Chat
# @websocket idle=3s
# @ws send Hello
# @ws close 1000 done
GET wss://api.example.com/chat

服务器反射默认已启用。同时支持描述符集和流式调用。示例：[`_examples/grpc.http`](https://github.com/unkn0wn-root/resterm/blob/main/_examples/grpc.http)。参见 [gRPC 文档](https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md#grpc)。

### OpenAPI 导入

从本地 OpenAPI 文档或 `http(s)` URL 生成请求、模拟或两者兼有：```bash
resterm --from-openapi _examples/openapi-spec.yml --http-out api.http --openapi-mode both

Profiles 可以是文件级或工作区级的，同时也支持一次性内联隧道。示例：[`_examples/ssh.http`](https://github.com/unkn0wn-root/resterm/blob/main/_examples/ssh.http)。参见 [SSH 文档](https://github.com/unkn0wn-root/resterm/blob/main/docs/resterm.md#ssh-tunnels)。

### Kubernetes 端口转发

`@k8s` 会打开一个受管理的端口转发，指向 pod、service、deployment 或 statefulset：```http
### Service health
# @k8s namespace=default service=api port=http
GET http://api.default.svc.cluster.local/health