极品工具 / 使用文档 / JFApi

JFApi 使用文档

2026 年 阅读约 20 分钟 开发工具 · 接口调试 Git-Native · Local-First

JFApi 是一款 Git-Native、Local-First 的现代 API 开发工具。像 Postman 一样调接口，但数据真正属于你——项目就是普通文件夹，直接用 Git 管理，不依赖任何云端。本文档带你从安装到高级用法完整上手。

1. 简介

JFApi 是面向开发者的桌面端 API 调试工具（Windows / Tauri 应用）。它继承了 Postman 类工具的调试体验，同时把「项目」设计为一个普通本地文件夹：集合、请求、脚本都以文件形式存放，天然适配 Git 版本管理与团队协作，数据不出本机。

Git 原生
项目即文件夹，直接纳入 Git，diff / 分支 / 回滚全由你掌控。
本地优先
所有数据保存在本机，不依赖云端账号，离线可用。
HTTP + WebSocket
HTTP 请求与 WebSocket 接口统一管理，左树紫色信号图标区分。
认证齐全
OAuth2 三种授权模式、JWT、Bearer、Basic 等，Token 自动注入。
脚本与签名
Pre-request / Tests 脚本，内置 sha256 / hmac256，一行搞定请求签名。
本地 Mock 桩
内置 mock server，验证 OAuth2 / 登录 / 签名 / SSE / WebSocket。
JFApi 主界面
JFApi 主界面：左侧「演示项目」按 集合 → 接口 分层组织（Mock 测试服务 / WebSocket 演示 / 用户管理 API）

2. 快速开始

启动 JFApi 后会自动打开「最近一次打开的项目」；如果没有，则进入「打开 / 创建项目」页。项目就是一个普通文件夹，你可以选择已有文件夹，也可以新建一个空目录。

  1. 在「打开项目」页选择或创建一个本地文件夹作为项目根目录。
  2. 进入工作区，点击左侧树的 + 新建 创建集合 / 接口。
  3. 在右侧编辑器填入 URL、参数与 Body，点击 发送 查看响应。
提示：项目名在左侧树中以 [项目] 前缀标识；集合可任意嵌套层级，接口可随时「移动到」其他目录。

3. 项目与集合管理

左侧树以「项目 → 集合（目录）→ 接口」的层级展示全部内容，接口树区域独立滚动，底部广告区不遮挡列表。

  • 新建接口：无需弹窗，点击后直接创建，默认名为「新的接口」；HTTP 接口显示方法徽章，WebSocket 接口显示紫色信号图标。
  • 新建项目：通过左侧 + 新建 的弹窗创建。
  • 集合认证配置：选中集合/目录后，右侧「目录信息」面板可配置该目录下所有接口共用的认证信息。
  • 折叠 / 展开：左树节点带折叠展开图标，方便管理大型项目。
JFApi 目录信息面板
选中「用户管理 API」集合后，右侧展示目录信息面板（接口数 / 创建时间 / 可配置集合级认证）

4. 请求编辑

请求编辑器采用「调试 / 编辑 / 文档」三种模式切换（顶栏右侧）。未保存的配置改动会在左侧请求名旁显示红色 *。

方法与 URL

  • 方法徽章：GET POST PUT DELETE PATCH 等，HTTP 接口保留方法下拉；WebSocket 接口收到 ws:// / wss:// 时 URL 行显示紫色 WS 切换控件。
  • 输入 ws:// 前缀后 URL 自动切换为 WebSocket 模式。
  • 选中环境后，URL 中的域名部分会拆分为蓝色域名徽章 + 路径；切换到「不使用任何环境」时只显示路径。

Params / Headers

Query 参数与请求头都是「名称 / 值 / 描述」三列表格，Tab 键即可快速新增一行；值支持 {{变量}} 与 {{secret:key}} 自动补全。

Body

  • 新请求 Body 默认 JSON；JSON 又分「表单 / 源码」两种视图，表单带描述列（跨视图保持）。
  • 支持 form-data（文件字段带「选择文件」按钮）、x-www-form-urlencoded（支持变量补全）、XML（可编辑文本域）等类型。
  • GET / DELETE 请求默认停在 Params 标签，其余方法默认停在 Body 标签。
JFApi 请求编辑器
请求编辑器（编辑模式）：以「用户登录」为例，Body 表单字段中的密码可用动态函数 {{$hash.sha256('123456')}} 发送前加密

请求设置（Settings）

设置面板按左侧分类导航：连接与超时（超时、跟随重定向等）、TLS 校验（跳过 SSL 校验、客户端证书 mTLS）、SSE 响应与 Cookie（流式响应开关等）。

5. 环境 / 变量

右侧面板固定标题「环境 / 变量」，自上而下分区：环境管理 → Secret → App 全局变量 → 动态函数 → 变量预览。环境变量显示在面板顶部。

变量作用域链

变量按 Request（请求级）→ Environment（环境级）→ Global（全局级） 的优先级解析，后两者无集合级作用域。

  • 环境管理：独立弹窗维护环境与变量，普通变量 / Secret 敏感变量类型有清晰标注，输入框宽度统一。
  • 全局变量：独立弹窗管理，保持稳定顺序（新变量追加到末尾，已有变量原地更新），自动补全显示蓝色标识，使用 {{var}} 语法。
  • Secret 敏感变量：独立弹窗管理，密码框 + 「显示明文」切换，自动补全显示紫色标识，使用 {{secret:key}} 语法。
  • 动态函数：输入 {{$ 触发，涵盖哈希 / HMAC / AES / SM4 / RSA / 时间 / 随机数等（见第 16 节速查表）。
环境切换：切换环境时，手动输入的绝对 URL 不会被清空；全局变量与环境的本地覆盖值在切换时按规则合并。

6. 发送请求与响应

点击 发送 后，响应面板默认停留在 Body 标签。状态区以三行展示：状态码 / 耗时 / 大小、响应头、操作按钮。

  • 标签页：Body / Headers / Tests 等切换查看。
  • 复制：一键复制响应体，并弹出成功提示。
  • 存为示例：把本次响应保存到文档模式的「响应示例」。
  • 捕获 / 捕获管理：配置响应字段提取规则（见第 9 节）。
  • Headers：默认优先展示 content-length / content-type / date / server 等关键头，无关键头时展示全部；date 自动转为本地时间。
  • SSE 流式响应：开启「流式响应」后，响应区出现绿色「实时流式响应中」提示，正文逐段实时刷新，结束后自动切回完整视图。
JFApi 请求发送与响应
发送「用户登录」请求到本地 mock（127.0.0.1:9099）：200 OK，响应状态区（耗时 / 大小）+ Body 标签 + 响应头

7. 认证

在请求编辑器「认证（Authentication）」标签选择认证类型，配置值支持「显示明文」查看。常用类型：OAuth2、JWT（Bearer Token）、Bearer、Basic、API Key 等。

7.1 OAuth 2.0

支持 Client Credentials、Authorization Code、Refresh Token 三种 grant_type；Client Secret 支持 {{secret:key}} 引用。

  1. 认证类型选 OAuth 2.0，Grant Type 选所需模式。
  2. 填写 Token URL、Client ID / Secret、Scope 等；授权码模式还需 Auth URL、回调地址与授权码（先用浏览器打开 Auth URL 授权，把回调带出的 ?code= 填入）。
  3. 点击 获取 Token（或过期后 刷新 Token），成功后「访问令牌」只读框显示完整 token，可一键复制。
  4. 发送请求时后端自动注入 Authorization: Bearer <access_token>，无需手动填写。
  5. Token 过期前自动用 refresh_token 刷新；可把新 token 同步到全局变量或当前环境变量供其他接口复用。
说明：token 挂在当前请求的认证配置里；要在多个接口间复用，可通过「同步到变量」或直接复制 token 到目标请求的 Bearer 认证。

7.2 JWT（Bearer Token）

JWT 类型支持两种用法：

  • 直接输入：粘贴现成的 JWT 字符串，发送时作为 Bearer 注入。
  • 生成 JWT：填写 Header / Payload / 密钥，用 HS256 算法一键生成（仅限本地开发 / 测试环境使用，界面已标注提示）。

8. 脚本（Pre-request / Tests）

每个请求可在「脚本」标签编写前置（Pre-request）与断言（Tests）脚本，沙箱零依赖，内置加密能力。

Pre-request（发送前执行）

典型用途是对原始请求体计算 HMAC 签名并写入请求头。内置函数：

  • pm.crypto.sha256(msg) — SHA-256 摘要（hex 小写）
  • pm.crypto.hmac256(key, msg) — HMAC-SHA256 签名（hex 小写）
  • pm.crypto.jwtDecode(token) — 解码 JWT（不验签），返回 { header, payload, exp, expired }
签名示例：对原始请求体算 HMAC 并设置 X-Sign 头
// 前置脚本：对发送时的原始请求体做 HMAC-SHA256，写入 X-Sign 头 var secret = 'jfapi-demo-secret'; var sign = pm.crypto.hmac256(secret, pm.request.body || ''); pm.request.headers.push({ key: 'X-Sign', value: sign, enabled: true }); console.log('X-Sign =', sign);

脚本还可操作变量（pm.variables.get / set）、修改请求方法 / URL，在请求发出前完成任意改造。

Tests（发送后执行）

用于断言响应（pm.response.status、pm.response.body 等），结果在响应区「Tests」标签展示通过 / 失败计数。

脚本管理

脚本引用保存在请求配置中（随请求文件进 Git）。左树「脚本」入口可创建 / 重命名 / 删除脚本供多请求复用；脚本重命名会自动更新引用请求，避免断链。

9. 响应捕获（把响应字段存成变量）

把一次响应的 JSON 字段（如登录返回的 data.token）自动写入变量，后续接口直接用 {{data.token}} 引用，形成接口间的数据链路。

  1. 发送一个返回 JSON 的请求，在响应区状态行点 捕获，弹出新建捕获规则。
  2. 规则通过 JSON 路径指定字段，如 data.token、data.items[0].id；对话框会根据当前响应自动给出标量字段路径建议。
  3. 选择作用域（当前环境变量的本地值 / App 全局变量的本地值）与目标变量名后保存。保存的同时会立刻把当前响应对应字段写入该变量的本地值。
  4. 已启用的规则在之后每次成功返回 JSON 时自动应用，无需手动触发；捕获成功顶部弹出 toast 提示。

响应区状态行 捕获管理 打开规则列表，可增删改、启停、查看作用域 / 路径 / 变量名。规则随请求文件团队共享（进 Git）。

10. 文档模式

顶栏在 调试 / 编辑 / 文档 三种模式间切换。文档模式把接口渲染为只读结构化文档：

  • 展示请求行、Query / Headers 表（Name / Value / Description 列）、请求体（先字段表 Path / Type / Value / Description，再格式化的 JSON）。
  • 「接口定义」区域展示认证配置，其后附接口创建 / 修改时间（本地时间 YYYY-MM-DD HH:MM:SS）。
  • 维护「请求示例」与「响应示例」：请求示例用文本框，响应示例用 Monaco 编辑器（JSON）；示例随文档一起保存，便于存档 / 协作 / 演示。
  • WebSocket 接口的文档模式只展示连接地址（紫色 WS 徽标）、握手 Headers、连接配置（自动重连 / 心跳）、认证与示例消息（每条可复制），不出现 HTTP 的 Query / 请求体。

11. 历史调用

顶栏 历史调用 弹窗集中查看所有发送过的请求：

  • 左侧是历史列表（方法徽章 + URL），支持收藏与清空。
  • 右侧展示对应响应：状态 / 耗时 / 大小三行、响应头行、Body / Headers 等标签页，可存为示例。
  • 响应头默认优先展示关键头，无关键头时展示全部；date 会转为本地时间。

12. 导入导出

顶栏 导入导出 弹窗提供格式转换，支持双向：

  • 导入：Postman Collection（v2）、OpenAPI 3 / Swagger 2、cURL 命令，以及 JFApi 自有格式（保持原 id / 时间戳，覆盖导入对 Git 无差异）。
  • 导出：把整个项目导出为 Postman Collection（v2.1）或 JFApi 自有格式；单请求可用「复制为 cURL」导出。

导入后自动生成集合与请求文件，basic / bearer 认证、urlencoded / formdata / raw 请求体均会映射到对应编辑器。

13. 小工具

顶栏右上角 小工具 汇集一组轻量调试工具（不保存为接口，随用随测）。左侧为工具列表，点击切换右侧内容区。

WebSocket 连接

填写 ws:// / wss:// 地址、可加请求头，连接后逐条收发文本消息；断开或关闭时自动释放连接。

Curl 测试

把一段 cURL 命令直接发出去查看响应，无需本地安装 curl（由内置引擎解析并执行）：

  • 复制示例：一键填入示例命令并复制到剪贴板，随后自动解析。
  • 解析：实时把输入框内容解析成方法 / URL（method 徽章与 URL 即时刷新）。
  • 发送：基于当前输入框内容实时解析后执行，展示状态码、耗时、大小与响应体。
  • 另存为接口：把解析结果保存成项目里的正式接口（选择接口名称、方法、保存到目录，树形目录选择）；保存后自动打开该接口。

JWT 解码 / 签名

  • 解码验签：粘贴 JWT 立即解码 Header / Payload / exp，显示过期状态（绿=未过期、红=已过期、灰=无 exp）；填入 HS256 密钥即实时验签。
  • 签名生成：填 Header / Payload / 密钥，一键生成带 HS256 签名的 JWT 并复制（Ctrl/⌘+Enter 快捷生成）。
  • 解码 / 验签 / 签名均在内置 Web Crypto 完成，不需要后端、不落盘。

14. WebSocket 接口

JFApi 支持把 WebSocket 当作一类可保存、可管理的普通接口（与 HTTP 接口并列，左树以紫色信号图标区分）。

  • 新建：左侧树 → ＋ → 新建 WebSocket 接口，自动命名为「新的接口」，无需弹窗。
  • 地址：URL 行收到 ws:// / wss:// 时显示紫色 WS 切换控件，方法徽章不再显示协议下拉。
  • 交互：连接 → 在消息区输入文本 → 发送消息（逐条收发记录）→ 断开；连接状态实时记录。
  • 连接配置：支持自动重连、心跳检测。

可用内置 mock server 的 /ws/echo（回显）与 /ws/time（每 1s 推送时间）验证。

15. 本地 Mock 测试桩

项目内置一个本地 mock 服务，用于回归验证 OAuth2、登录、签名等真实 HTTP 用法，不依赖外网。

# 启动（默认 http://127.0.0.1:9099） node scripts/mock-server.js # 指定端口 node scripts/mock-server.js 8080

固定凭证

项值
Client IDtest-client
Client Secrettest-secret
授权码 codemock-auth-code
refresh_tokenmock-refresh-token-abc
签名密钥 APP_SECRETjfapi-demo-secret

接口一览

接口方法说明
/oauth/tokenPOSTOAuth2 换 token（client_credentials / authorization_code / refresh_token）
/oauth/authorizeGET模拟授权码页，返回固定 mock-auth-code
/protectedGET需 Bearer access_token，三种 grant 换到的 token 均有效
/openGET无需认证，恒 200
/loginPOST用户名 + 密码登录，服务端按 sha256 存密码
/sign-checkPOSTHMAC-SHA256 请求体签名校验（Header X-Sign）
/streamGET流式（SSE），渐进输出文本块
/ws/echo · /ws/timeWSWebSocket 回显 / 定时推送
/healthGET存活探测

签名登录示例

对 /sign-check：sign = $hash.hmac256(APP_SECRET='jfapi-demo-secret', 原始请求体)（hex 小写）。可直接在 Headers 里用动态函数，或用前置脚本对 pm.request.body 计算（更稳妥，见第 8 节）。发送后应返回 {"code":0,"message":"签名校验通过"}；改错签名则返回 4001 签名不匹配，并附服务端期望的 server_expected_sign 供核对。

16. 动态函数速查

在任意值输入框输入 {{$ 触发动态函数自动补全。AES/SM4 的 key 与 IV 均为 16 字节 → 32 位 hex（如 00112233445566778899aabbccddeeff）。

函数作用
$hash.sha256(x) / $hash.sha512(x)SHA-256 / 512 摘要（hex）
$hash.md5(x)MD5（hex）
$hash.sm3(x)国密 SM3（hex）
$hash.hmac256(key, msg) / $hash.hmac512(key, msg)HMAC 签名（hex）
$aes.encrypt(keyHex, ivHex, text)AES-128-CBC 加密（输出 base64）
$sm4.encrypt(keyHex, ivHex, text)SM4-CBC 加密（输出 base64）
$rsa.encrypt(pubKeyPem, text)RSA 公钥加密（PEM，输出 base64）
$timestamp / $datetime(...)时间戳 / 格式化时间
$uuid / $random.uuidUUID
$base64(x)Base64 编码
$random.string / $random.int / $random.hex / $random.select造数
提示：动态函数也可用于 Secret 引用（{{secret 触发），配合自动补全的类型标识快速插入。

17. 常见问题

证书相关

  • 配置了证书仍报「解析客户端证书失败」：确认文件确实是 .pfx / .p12（PKCS#12）且密码正确；RSA / 密钥类型需与证书匹配。
  • 跳过 SSL 校验后仍连不上自签名服务端：确认测试服务端确已启动、端口（如 9443）未被占用。
  • 换证书后旧连接仍有效：JFApi 会对「证书文件 + 密码」组合区分连接缓存；不同证书自动使用不同连接，无需手动清理。

签名相关

  • 动态函数签名与请求不一致：Header 里的动态函数要求括号内的请求体字符串与发送时逐字节一致，一旦 Body 被格式化 / 转义就可能不匹配——改用前置脚本对 pm.request.body 计算更稳妥。
  • RSA PEM 含字面 \n：工具会自动把字面 \n 转换为真实换行，避免解析失败。

—— 文档完 ——

返回极品工具首页