rhc: 命令行 HTTP 客户端

简介

rhc (Rust HTTP 客户端) 是一个用于存储和发送 HTTP 请求的命令行工具。它非常适合以命令行/终端为中心的工作流程，并旨在让您尽可能快速地选择和调度所需的请求，同时保持请求本身简单、易于编辑的文件，这些文件可以提交到源代码控制。

安装

使用 Cargo

cargoinstall rhc

从二进制文件（仅限 Mac）

您可以从 GitHub 发布页面 下载二进制文件。目前只有 macOS 的二进制文件。

用法

请求定义

基础

使用 rhc 至少需要一个 "请求定义" 文件。此类文件采用 TOML 格式，包含您要发送的单个 HTTP 请求（URL、方法、正文等）的信息。以下是一个示例，尝试将以下内容放入名为 test.toml 的文件中

[request]
url = "https://httpbin.org/get"
method = "GET"

然后尝试运行 rhc /path/to/test.toml。rhc 将向 https://httpbin.org/get 发送 GET 请求，您应该会看到状态码、头信息和正文打印到标准输出。

运行 rhc --help 将显示有关可用命令行参数的简要描述，其中大部分在本文档中有更详细的解释。

请求

请求定义文件中的 request 表指定要使用的方法和 URL。两者都是必需的。

method 键的有效值是 "GET"、"POST"、"PUT"、"DELETE"、"HEAD"、"OPTIONS"、"PATCH" 和 "TRACE"。

查询参数

您可以在 query 表中指定查询参数

[request]
url = "https://httpbin.org/get"
method = "GET"

[query]
params = [
  { name = "id", value = "12345" }
]

或者，您可以直接在 request.url 中指定它们

[request]
url = "https://httpbin.org/get?id=12345"
method = "GET"

头部

您可以在 headers 表下指定头部

[request]
url = "https://httpbin.org/get"
method = "GET"

[headers]
headers = [
  { name = "Accept-Language", value = "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5" },
  { name = "Authorization", value = "Bearer xyz" }
]

正文

您可以将请求正文指定为纯文本、JSON值或URL编码的数据。您必须在 body.type 键下指定您想使用这些正文类型中的哪一个，并在 body.content 键下指定正文本身。

[request]
url = "https://httpbin.org/post"
method = "POST"

# Plain text body
[body]
type = "text"
content = "Some plain text"

[request]
url = "https://httpbin.org/post"
method = "POST"

# JSON body
[body]
type = "json"
content = '''
{
  "some_key": "some value",
  "a_number": 123,
  "nested": {
    "inside": true,
    "other": null
  }
}'''

[request]
url = "https://httpbin.org/post"
method = "POST"

# URL-encoded body
[body]
type = "urlencoded"
content = [
  { name = "key1", value = "something" },
  { name = "あいうえお", value = "猪" }
]

请求中的 Content-Type 标头将自动设置为 text/plain、application/json 或 application/x-www-form-urlencoded。注意，对于JSON正文，建议使用 多行文本字符串（三引号）来包裹原始JSON值。这样，您可以在正文中使用双引号放置JSON字符串。

请注意，multipart/form-data 请求不支持。

元数据

一个可选的 metadata 表可以提供有关请求定义的额外信息，这些信息在发送请求时实际上并未使用。目前有一个可能的元数据键，即 description。这个可选的描述将在 rhc 的交互模式中显示（将在本文件的稍后部分解释）。

[metadata]
description = "GET example using httpbin"

[request]
url = "https://httpbin.org/get"
method = "GET"

变量

您可以在请求定义的大部分地方使用变量，对于值可能根据您发送请求的上下文而变化。变量由大括号包围表示。变量可以绑定的方式将在稍后解释，但首先，此示例显示了变量可以使用的所有地方

[request]
url = "https://httpbin.org/post?something={var1}" # In the URL
method = "POST"

[query]
params = [
  { name = "{the_name}", value = "{the_value}" } # In query parameters
]

[headers]
headers = [
  { name = "Authorization", value = "Bearer {token}" } # In headers
]

# In request bodies
[body]
type = "json"
content = '''
{
  "some_key": "{something}",
  "{something_else}": 123
}'''

绑定变量的方法之一是使用 -b 或 --binding 命令行参数

$ rhc -b token=xyz -b something=12345 definition.toml

绑定变量的其他方法涉及环境和 rhc 的交互模式，将在下一部分解释。

环境

环境是存储在 TOML 文件中的预定义变量组。它们具有以下格式

name = "Staging"
variables = [
  { name = "token", value = "xyz" },
  { name = "something", value = "12345" }
]

您可以使用 -e 或 --environment 参数指定要使用的环境文件

$ rhc -e staging.toml definition.toml

这样做，环境文件中定义的所有变量都将自动绑定，无需通过命令行指定（尽管您仍然可以这样做，并且通过命令行指定的绑定将具有更高的优先级）。

环境文件中定义的变量的名称和值必须是 TOML 字符串。您仍然可以使用变量作为，例如，JSON数字和布尔值

# In the request definition file:
[body]
type = "json"
content = '''
{
  "a_number": {var1},
  "a_bool": {var2}
}
'''

# In the environment file:
variables = [
  { name = "var1", value = "123" },
  { name = "var2", value = "true" }
]

交互模式

除了通过命令行参数指定请求定义、环境和绑定之外，您还可以使用 rhc 的交互模式来设置所有这些。

交互式选择请求定义

在没有指定请求定义文件的情况下运行 rhc 将会打开一个交互式界面，您可以直接从包含在您的基定义中的所有 TOML 文件中选择请求定义，默认情况下这是 ~/rhc/definitions，但可以通过 配置文件 进行自定义。您可以根据喜好组织此目录下的文件；例如，使用子目录表示同一 API 的请求定义分组

~/rhc/definitions
├── weather_api
│   ├── get_forecast.toml
│   └── get_historical_data.toml
├── twitter
│   ├── post_tweet.toml
│   ├── get_tweets.toml
...

在交互模式下，rhc 将最初显示它找到的所有请求定义文件的列表，如果有的话，还将显示它们的描述

您可以通过自由输入来过滤列表，使用模糊匹配

按 ENTER 键选择当前突出显示的请求定义文件。按 TAB 或 Shift-TAB 键将更改当前选定的环境，循环访问位于基本环境目录中的所有环境文件，默认情况下是 ~/rhc/environments。当前选定的环境名称将在提示符中显示。还有其他一些方便的快捷键可以使用

• Ctrl-c 将退出 rhc 而不发送任何请求
• Ctrl-w 将剪切到当前单词的开头，类似于 Readline 风格
• Ctrl-u 将清除当前查询
• Ctrl-p 或 向上箭头 将选择项向上移动
• Ctrl-n 或 向下箭头 将选择项向下移动

交互式绑定变量

rhc 要求在发送之前将所选请求定义文件中存在的所有变量绑定。这些绑定首先从所选环境文件中获取，然后从命令行参数 --bind / -b 中获取（如果有任何重叠，将覆盖环境文件中的绑定）。之后，如果仍有未绑定的变量，您将被提示交互式地输入它们的值

rhc 会保存您过去绑定到变量的值的记录，并会显示当前（变量名，环境）对之前使用过的值列表。当您输入时，显示的列表将根据您输入的内容进行模糊匹配进行筛选。按下 ENTER 将当前变量绑定到提示中输入的内容。另一方面，如果您想重新使用历史值，可以按 TAB 从“输入模式”切换到“历史选择”模式，此模式由出现在历史值列表中的 >> 光标表示。在此模式下，按 ENTER 将绑定所选的历史值，忽略提示中当前输入的内容。

否则，这里也适用上述相同的键映射。

配置文件

rhc 将按照以下顺序查找可选配置文件

1. 如果存在，使用带有 --config 参数指定的文件
2. 如果定义了 XDG_CONFIG_HOME ，则使用 $XDG_CONFIG_HOME/rhc/config.toml
3. 如果存在，使用 ~/.config/rhc/config.toml

如果上述文件均不存在，将使用默认配置。下面是一个示例配置文件，其中包含设置及其默认值的说明

# The directory to scan for request definition files when run in interactive
# mode. Defaults to ~/rhc/definitions
request_definition_directory = "~/rhc/definitions"

# The directory to scan for environment files when run in interactive
# mode. Defaults to ~/rhc/environments
environment_directory = "~/rhc/environments"

# The file to store variable binding history in. Defaults to ~/.rhc_history
history_file = "~/.rhc_history"

# The maximum number of lines to save in the history file. Defaults to 1000.
max_history_items = 1000

# A timeout in seconds for establishing a TCP connection. Defaults to 30 seconds.
connect_timeout_seconds = 30

# A timeout in seconds for reading data. Defaults to 30 seconds.
read_timeout_seconds = 30

# A timeout in seconds for the entire request (until the request body finishes
# tranferring). Defaults to no timeout.
timeout_seconds = 30

# A theme to use to color JSON output. See below for more details.
theme = "~/rhc/one-half-light.tmTheme"

# Another way to sepcify a theme
# theme = "base16-ocean.dark"

# Various color settings. See below for more details.
[colors]
default_fg = "blue"
default_bg = "indexed(182)"
prompt_fg = "rgb(100, 150, 200)"

主题

(rhc 使用 syntect 库来突出显示 JSON 输出。配置文件中的 theme 键可以是映射到 默认 syntect 主题 的字符串，或者是一个包含 Sublime Text 语法定义 的文件路径。如果没有指定主题，将使用 syntect 中包含的“base16-eighties.dark”主题。

颜色

交互式rhc UI的各个部分均可自定义。值可以是基本终端颜色之一（如red、cyan、lightblue、lightmagents等），扩展的256种终端颜色之一（通过数字指定，例如indexed(50)），或者RGB颜色（指定方式如rgb(10, 20, 30)）。

可自定义的键有

• default_fg：未选择的交互选项的前景色
• default_bg：未选择的交互选项的背景色
• selected_fg：已选择的交互选项的前景色
• selected_bg：已选择的交互选项的背景色
• prompt_fg：提示信息的字体颜色
• prompt_bg：提示信息的背景色
• variable_fg：未绑定变量的字体颜色
• variable_bg：未绑定变量的背景色

许可证

根据您的选择，以下任一许可证

• Apache许可证2.0版本（LICENSE-APACHE或https://apache.ac.cn/licenses/LICENSE-2.0）
• MIT许可证（LICENSE-MIT或http://opensource.org/licenses/MIT）

可供选择。