HTTP API 测试（.lnh）

文件 → 新建 → 新建 API 测试会打开一个保存在 .lnh 文件中的 HTTP 客户端。一个文件代表一个端点（方法・URL・标头・ 正文），并在左侧列表中保存多个测试。每个测试都有用于 URL・标头・正文的 {name} 变量的值，以及最后一次执行的结果（状态・时间・日期・响应 标头和正文）。它还会显示等效的 curl 命令。同样的单次操作也可通过 CLI（http）和 MCP（http_request）使用。测试器使用 curl，Windows 10 和 11 已自带；如果缺少，LightNote 会在发送前打开安装向导。

发送并查看响应

Ctrl+Enter 发送请求。在响应返回之前，同一个按钮会变成停止 （或按 Esc），等待时会显示秒数。响应徽标显示状态和耗时，旁边是类型、大小以及测试 的运行时间。curl 行会跟随你的输入更新，并已替换所选测试的变量：旁边的按钮 复制该命令，其箭头还提供 PowerShell、Python、JavaScript、C# 和 HTTPie 的同等写法。把 curl 命令直接粘贴到 URL 中，会导入方法、标头和正文，而不会删除测试。

测试中没有值的变量会原样发送（URL 中留着 {id}，服务器会返回一个 不说明原因的错误）——变量标签页会突出显示它并给出名称。列表中每个测试旁的圆点是上次 状态的颜色，空心圆环表示尚未运行的测试。在响应中，正文上方的工具栏可以仅在屏幕上格式化 JSON/XML、自动换行、复制正文，并按原样保存到文件。

组装请求。参数标签页把 URL 的查询字符串显示为列表：编辑一行会改变 URL，编辑 URL 也会改变列表。身份验证标签页会自动组装标头——Basic、Bearer 或 API 密钥，放在标头或 URL 中——每个字段都接受 {variable}，让密钥留在环境里而不是文件里；如果标头标签页已有同名标头，则以它为准。在正文中，类型可选 JSON、XML、SOAP、表单、multipart（文本字段和文件）或以二进制发送的文件；没有手写 Content-Type 时会自动加上。相对文件路径从 .lnh 所在文件夹算起。使用 multipart 或文件时，复制按钮的箭头菜单会把 PowerShell 和 JavaScript 置灰，因为它们无法发送这种正文。选项标签页可以修改超时（默认 60 s）并让请求跟随重定向；不跟随时，显示的就是 3xx 本身。在较旧版本的 LightNote 中打开时，文件会在不带身份验证和类型的情况下发送，但绝不会变成另一个请求。对于带自有证书的本地服务器，不验证证书 (HTTPS) 可关闭验证：开启期间，响应一行会显示证书未验证，lnote http-run 的报告中也会注明。

阅读响应。正文在只读代码编辑器中打开，按响应类型高亮，支持折叠和窗口搜索（Ctrl+F）。Cookie标签页列出服务器要求保存的内容，时间线显示实际发出的请求（包括 curl 自己加上的标头）以及响应的原始标头。时间线只保存在内存中：其中包含 Authorization，而文件会进入 Git。

检查

检查标签页显示测试是否通过。每一行都会把响应的一部分——状态、某个 标头、整个正文、JSONPath（$.user.id、$.items[0].name、 $.items.length()）、XPath（//Price、 count(//Item)）或以毫秒计的时间——与期望值比较：等于、不等于、大于、小于、 包含、匹配正则表达式、存在或类型为。在 XPath 中会忽略名称前缀，因此 soap:Envelope 和 Envelope 是同一步。有检查时，由检查决定结果： 预期的 404 会通过，字段不对的 200 会失败。每项检查的结果显示在最后一列，摘要显示在响应徽标 旁边，列表中测试的圆点会变成绿色或红色。取消勾选某一行后，它仍保留在文件中，但不计入结果。

列表顶部的播放按钮会逐个运行文件中的所有测试，并显示通过了多少个。测试运行两次后， 响应正文上方的比较按钮会并排打开上一次和本次的运行，两侧的正文都已格式化。只保留上一次运行： 文件会进入 Git，过长的历史会让每次差异都充满噪音。

环境、捕获和整个文件夹

环境使用 JetBrains 和 VS Code 的开放格式：文件夹（或其上级）中的 http-client.env.json，每个环境一个对象—— {"dev": {"host": "http://localhost:8080"}}——旁边再放一个存放机密的 http-client.private.env.json，让它不进入 Git。同一环境中私有文件优先， $shared 适用于所有环境。URL 旁的选择器用来选择环境，导入和导出菜单可以创建该 文件。变量依次来自测试、捕获和环境，变量标签页会显示每个变量的来源。

捕获标签页会把响应的一部分——登录返回的 token、新建资源的 id——保存为变量，供此文件及同一文件夹中其他文件的后续测试使用。这样， 登录用的 .lnh 就能为另一个文件的认证调用提供值。捕获的值只保存在内存中，从不 写入文件。

文件夹就是集合：lnote http-run --path <文件夹> --env dev 会按自然顺序 （01-login 在 02-profile 之前）运行其中所有 .lnh， 只要有测试失败就以错误退出，适合用于 CI。同样的运行也可以通过 MCP 的 http_test_run 进行，让 AI 代理运行你编写的测试。默认不会修改文件； --save 会把每个测试的最后结果写入文件。

导入和导出

导入和导出 OpenAPI。 测试列表顶部的箭头按钮可打开导入 OpenAPI… 和导出 OpenAPI…。导入会读取 YAML 或 JSON 格式的规范，支持目前在用的三代 — Swagger 2.0、OpenAPI 3.0 和 3.1 — 并自动组装测试：路径中的 {parameters} 与 .lnh 的 {name} 变量语法完全一致，规范中声明的 示例会成为测试的取值，安全方案会变成 Authorization 请求头，而每个声明的服务器都会 成为一个独立的测试（预发布与生产并列）。由于一个 .lnh 只保存一个端点，包含 多个操作的规范会询问要导入哪一个 — 也可以一次全部保存，每个操作生成一个 .lnh 文件。

导出则走相反的方向，从文件生成一份 OpenAPI 3.0.3 规范：服务器、参数和请求体来自模板，示例 响应来自已记录的执行。它是一个骨架，而不是完整的契约 — .lnh 描述的是调用， 因此类型、描述和数据结构不会被重建。你的测试会保存在 x-lightnote-tests 字段中， 所以重新导入该文件时可以原样恢复。

导入 curl 命令。 在同一个按钮中，导入 curl 命令… 会打开一个粘贴框 —— 命令来自剪贴板而不是磁盘，若剪贴板中已有 curl，该框会自动填好。它能识别同一条命令流通的 三种方言：Chrome/Firefox 的复制为 cURL（单引号）、Windows 上的 Copy as cURL (cmd) （使用 ^），以及用 \ 换行的文档示例。方法取自 -X，未指定时 则推断：有请求体为 POST，没有则为 GET。

导入是逐字的：任何取值都不会自动变成 {name} 变量，因为猜测哪个令牌是机密会出错。 有几种情况会给出提示而不是含糊其辞 —— 来自文件的请求体（-d @文件）无法读取，multipart 上传（-F）也无法忠实复现，因此这些字段会以文本形式放进请求体，供你调整。

从其他工具导入。从其他工具导入… 可读取 .http/.rest 文件（VS Code 的 REST Client、JetBrains、Visual Studio）、Postman 集合或环境、Insomnia 导出（JSON 格式的 v4 或 YAML 格式的 v5）、浏览器通过全部另存为 HAR 保存的 HAR、Bruno 的 .bru（或通过导入 Bruno 文件夹… 导入整个文件夹），以及 SOAP 服务的 WSDL。格式按内容识别，而不是按扩展名。每个请求都会成为一个 .lnh，集合中的文件夹也会成为文件夹：可以选一个用于此文件，也可以一次全部保存。{{name}} 会变成 {name}，身份验证会变成标头，环境写入 http-client.env.json（来源标记为机密的值写入 .private），且不会更改已有的任何值；Bruno 的检查和捕获——以及 Postman 的 pm.response.to.have.status——会成为这里的检查和捕获。从 HAR 只导入 API 调用和页面，并把浏览器收到的响应作为最后一次执行；从 WSDL 为每个操作生成一个 SOAP 信封，带有 SOAPAction，每个字段都成为变量。

没有对应项的内容会原样保留，并加以说明：请求前后的脚本不会转换，动态变量（{{$guid}}）和链式引用保持原样，含变量的 Basic、multipart 正文和文件正文会进入身份验证标签页和正文的类型，来自另一台机器的文件路径会列出以便核对。保存集合时，这份报告会成为目标文件夹中的一篇笔记。导出为 .http… 以所选测试做反向转换：模板使用 {{name}}，值写成 @name = 值。