Posting

一个强大的终端 HTTP 客户端。

Posting 是一个 HTTP 客户端，类似于 Postman 和 Insomnia。作为一个 TUI 应用程序，它可以通过 SSH 使用，并支持高效的键盘操作工作流。您的请求以简单的 YAML 文件形式本地存储，便于阅读和版本控制。

一些主要特性包括："跳转模式"导航、带自动完成的环境/变量系统、由 tree-sitter 提供的语法高亮、Vim 按键、用户自定义主题、配置、"在 $EDITOR 中打开"以及用于快速访问功能的命令面板。

Posting 使用 Textual 构建。

安装

Posting 可以通过 pipx 安装：

pipx install posting

需要 Python 3.11 或更高版本。

更多安装方法（如 brew 等）将很快添加。

集合

请求直接以简单的 YAML 文件形式存储在文件系统中，后缀为 .posting.yaml - 易于阅读、理解和版本控制！

以下是它们的样子：

name: 创建用户
description: 向系统添加新用户。
method: POST
url: https://jsonplaceholder.typicode.com/users
body: 
  content: |-
    {
      "firstName": "John",
      "email": "john.doe@example.com"
    }
headers:
- name: Content-Type
  value: application/json
params:
- name: sendWelcomeEmail
  value: 'true'

要打开一个集合（包含请求的目录），使用 --collection 选项：

posting --collection path/to/collection

这将递归查找并在侧边栏显示请求。如果不提供目录，Posting 将使用默认的集合目录。你可以通过运行 posting locate collection 检查默认位置。

环境

你可以在 UI 中使用 ${VARIABLE_NAME} 或 $VARIABLE_NAME 语法使用变量。这些变量将被替换到发出的请求中。

可以使用 --env 选项加载 .env 文件。然后可以在 UI 中使用这些文件中的变量。

示例

假设你正在测试一个同时存在于 dev 和 prod 环境中的 API。

dev 和 prod 环境共享一些公共变量，但在许多方面也有所不同。我们可以通过使用单个 shared.env 文件来模拟这种情况，该文件包含环境之间共享的变量，然后使用 dev.env 和 prod.env 文件包含特定环境的变量。

# 文件：shared.env
API_PATH="/api/v1"
ENV_NAME="shared"

# 文件：dev.env
API_KEY="dev-api-key"
ENV_NAME="dev"
BASE_URL="https://${ENV_NAME}.example.com"

# 文件：prod.env
API_KEY="prod-api-key"
ENV_NAME="prod"
BASE_URL="https://${ENV_NAME}.example.com"

在 dev 环境中工作时，你可以使用 --env 选项加载所有共享变量和所有开发环境特定变量：

posting --env shared.env --env dev.env

这将加载 shared.env 中的所有共享变量，然后加载 dev.env 中的变量。由于 ENV_NAME 在两个文件中都出现，将使用最后指定的 dev.env 文件中的值。

请注意，你不需要重启来加载对这些文件的更改，所以你可以在 Posting 旁边用你选择的编辑器打开和编辑你的 env 文件。但是，自动完成和变量高亮直到 Posting 重启后才会更新。

如果你想允许使用主机上存在的环境变量（即那些未在任何 .env 文件中定义的变量），你必须将 use_host_environment 配置选项设置为 true（或设置环境变量 POSTING_USE_HOST_ENVIRONMENT=true）。

环境特定配置

由于所有 Posting 配置选项也可以指定为环境变量，我们也可以将环境特定配置放在 .env 文件中。本文档中有专门的"配置"部分更详细地介绍了这一点。

例如，如果你想在生产环境中使用浅色主题（作为一个微妙的提醒你在生产环境中！），你可以在 prod.env 文件中设置环境变量 POSTING_THEME=solarized-light。

请注意，配置文件优先于环境变量，所以如果你在 .env 文件和 config.yaml 中都设置了一个值，将使用 config.yaml 文件中的值。

命令面板

Posting 中的一些功能不需要专门的键盘快捷键（例如，切换到特定主题），而可以通过命令面板访问。

要打开命令面板，按 <kbd>ctrl</kbd>+<kbd>p</kbd>。

配置

Posting 可以使用配置文件、环境变量和/或 .env 文件进行配置。

配置值按以下优先顺序加载（从高到低）：

配置文件
环境变量
.env 文件

可用配置的范围将在未来大大扩展。

配置文件

你可以使用 YAML 为 Posting 编写配置。

可以使用命令 posting locate config 检查配置文件的位置。

以下是一个示例配置文件：

theme: galaxy
layout: horizontal
response:
  prettify_json: false
heading:
  visible: true
  show_host: false

环境变量

所有配置值也可以设置为环境变量。

只需在配置名称前加上 POSTING_ 前缀，并将其设置为环境变量。

对于嵌套的配置值，使用 __ 作为分隔符。因此，要将 heading.visible 设置为 false，你可以设置环境变量 POSTING_HEADING__VISIBLE=false。

例如，要将主题设置为 galaxy，你可以设置环境变量 POSTING_THEME=galaxy。

dotenv（`.env`）文件

Posting 还支持 .env（dotenv）文件，如果你想根据工作环境（例如，"dev" 与 "prod"）切换环境变量值，这些文件很有用。

你可以使用 --env 选项告诉 Posting 使用 .env 文件。这个选项可以多次提供以加载多个 .env 文件。

以下是一个示例 .env 文件：

POSTING_THEME="cobalt"
POSTING_LAYOUT="vertical"
POSTING_HEADING__VISIBLE="false"

Dotenv 文件与集合是分开的，尽管你可能希望将它们包含在集合中，以便于版本控制和与他人共享。

可用配置选项

配置键 (环境变量)	值 (默认值)	描述
`theme` (`POSTING_THEME`)	`"posting"`, `"galaxy"`, `"monokai"`, `"solarized-light"`, `"nautilus"`, `"nebula"`, `"alpine"`, `"cobalt"`, `"twilight"`, `"hacker"` (默认: `"posting"`)	设置应用程序的主题。
`load_user_themes` (`POSTING_LOAD_USER_THEMES`)	`true`, `false` (默认: `true`)	如果启用，从主题目录加载用户主题，允许在配置中指定并通过命令面板选择。
`load_builtin_themes` (`POSTING_LOAD_BUILTIN_THEMES`)	`true`, `false` (默认: `true`)	如果启用，加载内置主题，允许在配置中指定并通过命令面板选择。
`theme_directory` (`POSTING_THEME_DIRECTORY`)	(默认: `${XDG_DATA_HOME}/posting/themes`)	包含用户主题的目录。
`layout` (`POSTING_LAYOUT`)	`"vertical"`, `"horizontal"` (默认: `"horizontal"`)	设置应用程序的布局。
`use_host_environment` (`POSTING_USE_HOST_ENVIRONMENT`)	`true`, `false` (默认: `false`)	允许/拒绝在请求中使用主机环境变量，通过 `$env:` 语法。禁用时，只有在 `.env` 文件中明确定义的变量才可用。
`animation` (`POSTING_ANIMATION`)	`"none"`, `"basic"`, `"full"` (默认: `"none"`)	控制动画级别。
`response.prettify_json` (`POSTING_RESPONSE__PRETTIFY_JSON`)	`true`, `false` (默认: `true`)	如果启用，JSON 响应将被美化格式化。
`response.show_size_and_time` (`POSTING_RESPONSE__SHOW_SIZE_AND_TIME`)	`true`, `false` (默认: `true`)	如果启用，响应区域边框副标题将显示响应的大小和所用时间。
`heading.visible` (`POSTING_HEADING__VISIBLE`)	`true`, `false` (默认: `true`)	显示/隐藏应用程序标题。
`heading.show_host` (`POSTING_HEADING__SHOW_HOST`)	`true`, `false` (默认: `true`)	在应用程序标题中显示/隐藏主机名。
`heading.show_version` (`POSTING_HEADING__SHOW_VERSION`)	`true`, `false` (默认: `true`)	在应用程序标题中显示/隐藏版本。
`url_bar.show_value_preview` (`POSTING_URL_BAR__SHOW_VALUE_PREVIEW`)	`true`, `false` (默认: `true`)	在 URL 栏下方显示/隐藏变量值预览。
`pager` (`POSTING_PAGER`)	(默认: `$PAGER`)	用于分页文本的命令。
`pager_json` (`POSTING_PAGER_JSON`)	(默认: `$PAGER`)	用于分页 JSON 的命令。
`editor` (`POSTING_EDITOR`)	(默认: `$EDITOR`)	用于在外部编辑器中打开文件的命令。
`ssl.ca_bundle` (`POSTING_SSL__CA_BUNDLE`)	绝对路径 (默认: `未设置`)	CA 束文件/目录的绝对路径。如果未设置，将使用 Certifi CA 束。
`ssl.verify` (`POSTING_SSL__VERIFY`)	`true`, `false` (默认: `true`)	验证服务器身份。
`ssl.certificate_path` (`POSTING_SSL__CERTIFICATE_PATH`)	绝对路径 (默认: `未设置`)	客户端 SSL 证书文件或目录的绝对路径。
`ssl.key_file` (`POSTING_SSL__KEY_FILE`)	绝对路径 (默认: `未设置`)	客户端 SSL 密钥文件的绝对路径。
`ssl.password` (`POSTING_SSL__PASSWORD`)	密钥文件的密码。(默认: `未设置`)	如果密钥文件已加密，用于解密的密码。
`focus.on_startup` (`POSTING_FOCUS__ON_STARTUP`)	`"url"`, `"method", "collection"` (默认: `"url"`)	应用程序启动时自动聚焦 URL 栏、方法或集合浏览器。
`focus.on_response` (`POSTING_FOCUS__ON_RESPONSE`)	`"body"`, `"tabs"` (默认: `未设置`)	收到响应时自动聚焦响应选项卡或响应正文文本区域。
`text_input.blinking_cursor` (`POSTING_TEXT_INPUT__BLINKING_CURSOR`)	`true`, `false` (默认: `true`)	如果启用，输入小部件和文本区域小部件中的光标将闪烁。
`command_palette.theme_preview` (`POSTING_COMMAND_PALETTE__THEME_PREVIEW`)	`true`, `false` (默认: `false`)	如果启用，当光标悬停在主题上时，命令面板将显示所选主题的预览。这会降低光标移动速度，因此默认禁用。
`use_xresources` (`POSTING_USE_XRESOURCES`)	`true`, `false` (默认: `false`)	尝试创建名为 `xresources-dark` 和 `xresources-light` 的主题（参见下面的章节）

SSL 证书配置

Posting 可以从 .pem 文件加载自定义 CA 束。

最简单的方法是在您的 config.yaml 文件中：

ssl:
  ca_bundle: 'absolute/path/to/certificate.pem'

环境特定的证书

如果每个环境所需的 CA 束不同，您可以再次使用所有配置都可以设置为环境变量的原则，这些环境变量可以选择使用 --env 和 .env 文件设置和加载：

# dev.env
POSTING_SSL__CA_BUNDLE='/path/to/certificate.pem'

现在在 dev 环境中工作时加载 dev.env 文件，以确保使用 dev 环境的 CA 束：

posting --env dev.env

客户端证书

您可以指定本地证书作为客户端证书：

ssl:
  certificate_path: /path/to/certificate.pem
  key_file: /path/to/key.key  # 可选
  password: '***********'  # key_file 的可选密码

主题设置

将自定义主题放在主题目录中，Posting 将在启动时加载它们。主题文件必须以 .yaml 为后缀，但文件名的其余部分 Posting 不使用。

您可以通过在终端中运行 posting locate themes 来查看 Posting 将在哪里查找主题。

以下是一个示例主题文件：

name: example  # 在配置文件中使用此名称
primary: '#4e78c4'  # 按钮，固定表格列
secondary: '#f39c12'  # 方法选择器，一些次要标签
accent: '#e74c3c'  # 标题文本，滚动条，光标，焦点高亮
background: '#0e1726' # 背景颜色
surface: '#17202a'  # 面板等
error: '#e74c3c'  # 错误消息
success: '#2ecc71'  # 成功消息
warning: '#f1c40f'  # 警告消息
syntax: 'dracula'  # 自动切换语法高亮主题

# 可选元数据
author: Darren Burns
description: 一个带有蓝色主色调的深色主题。
homepage: https://github.com/darrenburns/posting

语法高亮

诸如 URL 栏、文本区域和包含变量的字段等语法高亮元素将根据主题中定义的语义颜色（primary、secondary 等）进行着色。

如果您想对语法高亮有更多控制，可以在主题文件中指定自定义语法高亮主题。下面的示例说明了在自定义语法高亮方面可用的一些选项。

text_area:
  cursor: 'reverse'  # 设置块光标的样式
  cursor_line: 'underline'  # 设置光标所在行的样式
  selection: 'reverse'  # 设置所选文本的样式
  gutter: 'bold #50e3c2'  # 设置装订线的样式
  matched_bracket: 'black on green'  # 设置匹配括号的样式
url:
  base: 'italic #50e3c2'  # 设置 URL 'base' 的样式
  protocol: 'bold #b8e986'  # 设置协议的样式
syntax:
  json_key: 'italic #4a90e2'  # 设置 JSON 键的样式
  json_number: '#50e3c2'  # 设置 JSON 数字的样式
  json_string: '#b8e986'  # 设置 JSON 字符串的样式
  json_boolean: '#b8e986'  # 设置 JSON 布尔值的样式
  json_null: 'underline #b8e986'  # 设置 JSON null 值的样式

X resources 主题

Posting 支持使用 X resources 进行主题设置。要使用此功能，请启用 use_xresources 选项（见上文）。

它需要 PATH 中有 xrdb 可执行文件，且 xrdb -query 必须返回以下变量：

Xresources	描述
*color0	主要颜色：用于按钮背景和固定表格列
*color8	次要颜色：用于方法选择器和一些次要标签
*color1	错误颜色：用于错误消息
*color2	成功颜色：用于成功消息
*color3	警告颜色：用于警告消息
*color4	强调颜色：用于标题文本、滚动条、光标、焦点高亮
*background	背景颜色
*color7	表面/面板颜色