Skip to content

USER_GUIDE.md

Latest commit

 

History

History
207 lines (141 loc) · 10.8 KB

USER_GUIDE.md

File metadata and controls

207 lines (141 loc) · 10.8 KB
Raw

RustFox 用户使用手册

语言 / Language：简体中文 · English

面向最终用户。不需要安装 Rust、不需要任何命令行知识，下载、解压、双击即可使用。

  • 适用版本：RustFox 0.1.x
  • 支持平台：Windows 10/11、macOS 11+、Linux（常用桌面环境）

1. 安装与启动

1.1 Windows

方式 步骤
安装包（推荐） 下载 RustFox-<版本>-setup.exe → 双击运行 → 按提示完成安装 → 桌面出现 RustFox 快捷方式，开始菜单出现「RustFox」程序组

首次运行如弹出「Windows 已保护你的电脑」（SmartScreen），点击「更多信息」→「仍要运行」即可。这是因为安装包尚未购买代码签名证书，属正常现象。

1.2 macOS

  1. 下载 RustFox-<版本>-<架构>.dmg（Apple Silicon 选 aarch64，Intel 选 x64）

  2. 挂载后把 RustFox.app 拖入「应用程序」文件夹

  3. 解除隔离（重要）：应用未做 Apple 签名公证，较新的 macOS 会直接弹 「"RustFox"已损坏，无法打开。你应该将它移到废纸篓。」——应用本身没有损坏， 这只是 Gatekeeper 对未公证应用的拦截。打开「终端」执行：

    xattr -cr /Applications/RustFox.app

    （也可在「应用程序」里右键 RustFox.app → 显示简介 → 勾选「覆盖恶意软件保护」，效果相同。）

  4. 首次打开：右键 RustFox.app →「打开」，或「系统设置 → 隐私与安全性 → 仍要打开」——同样是未公证的正常提示

之后可从「启动台」或「应用程序」双击启动，也可固定到 Dock。

应用内「关于 → Check for Updates」的自动更新不受影响：更新器替换应用后不会重新打隔离标记，升级后可直接打开。

1.3 Linux

  1. 下载 rustfox-<版本>-amd64.deb（Debian/Ubuntu）或 .AppImage 直接运行
  2. Debian 系安装：sudo apt install ./rustfox-<版本>-amd64.deb

Linux 运行依赖系统的 WebKit/GTK 库（webkit2gtk-4.1、gtk-3）。启动报 libwebkit2gtk 缺失时，按发行版安装对应软件包。

1.4 首次启动

启动后自动初始化本地数据库（无需联网、无需注册），直接进入主界面：

┌─────────────────────────────── RustFox ───────────────────────────────┐
│ RustFox │ [选择项目 ▼] │ [未选环境 ▼] │       搜索接口 │ 反馈 │ 设置 ⚙ │
├─────────────────────────────────────────────────────────────────────────┤
│                          🦊  开始使用 RustFox                             │
│                   创建你的第一个项目，开始管理 API                            │
│                          [ 创建项目 ]                                      │
└─────────────────────────────────────────────────────────────────────────┘

2. 界面总览

区域 作用
顶部栏 项目切换、环境切换、Mock 状态、接口搜索、文档/Mock 菜单、设置入口
首页 统计卡片、项目卡片、创建/进入项目、快速请求
工作区 左侧目录树 + 顶部标签栏 + 接口编辑器 + 响应面板
设置页 环境变量、OpenAPI 导入导出、Mock Server、备份恢复

首页布局：

RustFox 首页布局

工作区布局：

RustFox 工作区布局

3. 项目管理

  • 首页点击「创建项目」，输入名称与基础地址（base_url，如 https://api.example.com）。
  • 进入项目后左侧为目录树：文件夹 / 接口分层管理；顶栏可切换项目。
  • 项目数据全部保存在本机（见第 8 节），可随时在设置页备份 / 恢复。

4. 编写与发送请求（核心功能）

工作区结构：

┌─ 项目树 ──────┬───────────────────────────────────────────────────────┐
│ ▾ my-app      │  [标签1 ●] [标签2]  ＋新建                              │
│  ▾ 用户模块    │  [GET ▼]  https://api.example.com/users/{id}  [保存][发送]│
│    GET 用户列表│  ┌ Params │ Headers │ Body │ Auth │ Tests │ Docs ───┐ │
│    POST 创建用户│  │ key        value                                  │ │
└───────────────┴─┴──────────────────────────────────────────────────┴─┘
步骤 操作
打开接口 点击左侧目录中的接口 → 在顶部标签栏打开（再次点击已在标签中则激活）
新建接口 标签栏「＋ 新建」，或目录中新建文件夹/接口
编辑参数 Params 标签插入 Query 参数；Headers 加请求头（启用开关控制是否随请求发送）
编辑 Body Body 标签：JSON / raw / url-encoded 三种模式，JSON 模式有「格式化 JSON」按钮
认证 Auth 标签选择认证方式（None / Basic / Bearer / API Key）
保存 点「保存」；未保存修改在标签标题上以 ● 标记，切换标签不会丢失草稿

发送请求：点绿色「发送」按钮，右侧显示状态码、耗时、大小、响应头与响应体；最近的请求自动记入「历史」（地址栏下方）。

多个标签可同时编辑不同接口，每个标签独立草稿；关闭未保存标签会先提示。

4.1 变量

请求中的任何位置支持 {{变量名}}：

  • {{base_url}}、{{token}} 等来自当前环境（设置页）
  • 项目变量在设置页「项目变量」配置
  • 发送与「生成代码」「压测」时自动完成替换，无需手改

5. 环境管理

设置页 →「环境管理」：

  • 「新建环境」输入环境名与变量（键/值）。
  • 顶部栏切换环境，发送请求时自动替换变量。
  • ⚠️ 环境变量值在保存时自动加密存储（AES-256-GCM）。请勿删除数据目录中的 master.key，删除后已加密变量将无法解密（可用备份 JSON 找回明文）。

6. 自动化测试

工作区 Tests 标签：给接口配置 JSON 测试脚本（请求前变量、响应提取、断言），支持：

  • pre_request：请求前注入变量
  • extract：从响应提取变量传递给后续接口（按目录顺序传递）
  • assertions：状态码 / 响应体包含 / JSONPath 值 / 响应耗时等断言

保存后点击「运行测试」，可选择当前接口 / 当前文件夹 / 整个项目；结果自动存入测试历史（保留最近 20 条，可展开查看、删除）。

压测（并发基准）

Tests 页「压测」区：输入并发数与总请求数（默认 10 并发 × 100 次）→「开始压测」。结果：成功/失败数、总耗时、QPS、平均耗时、P50/P90/P99 分位耗时、错误示例（最多 5 条）。

7. 客户端代码生成

地址栏「生成代码」→ 选择语言：

  • cURL / JavaScript (fetch) / Java / Go (net/http) / Rust（另支持 Python / PHP）

生成的是渲染后的完整请求（含变量替换、认证头、启用中的请求头），带语法高亮，直接复制进你的工程即用。

8. Mock Server（本地接口模拟）

设置页 →「Mock Server」：

设置页
  ┌ Mock Server ─────────────────────────────┐
  │ 启动 Mock   （监听 4010 端口，占用自动 +1） │
  │ 自定义 Mock 规则（可选，优先级高于响应示例） │
  └──────────────────────────────────────────┘
  • 启动后监听 http://127.0.0.1:4010，可按接口（收 4010→4001→…自动 +1 直到找到空闲）。
  • 未配置规则时返回接口的「响应示例」（在 Docs 标签保存的响应）。

响应路由 / 响应体模板变量：{{params.id}}、{{query.name}}、{{headers.X-Token}}、{{mock.uuid|email|name|word|timestamp|int}}。

  • 修改接口或 Mock 规则后需重启（关闭再启动）Mock 生效。

9. 备份与恢复 / 文档导出

功能 位置 说明
备份项目 设置页「备份当前项目」 导出全部接口、环境、Mock 规则、响应示例为 JSON 文件，保存在 backups/ 目录
恢复备份 设置页粘贴 JSON →「恢复」 创建为全新项目（ID 全部重新映射，绝不覆盖现有数据）
导出文档 工作区 Docs 标签（在打开的接口上） 生成项目 Markdown 文档，保存到 exports/

10. 数据在哪（备份意味着存好数据安全）

所有数据在本机「系统数据目录 / RustFox」：

平台 路径
Linux ~/.local/share/RustFox/
macOS ~/Library/Application Support/RustFox/
Windows %APPDATA%\RustFox\
  • rustfox.db：主数据库（项目/接口/环境/Mock 规则/历史）
  • master.key：环境变量加密密钥（勿删）
  • backups/、exports/：备份与导出目录

一键备份建议：复制整个 RustFox 数据目录到外部存储即可完整迁移。

11. 常见问题（FAQ）

问题 处理
双击后没有反应 Windows 便携版需解压完整再运行；macOS 首次需右键「打开」绕过未签名提示；Linux 缺 WebKit 库（见 1.3）
提示“不是来自已识别开发者” macOS 首次打开：右键 →「打开」；或系统设置 → 隐私与安全性 允许
SmartScreen 警告 点「更多信息 → 仍要运行」，开源无签名正常现象
环境变量显示乱码/密文 master.key 丢失导致，用备份 JSON 恢复（第 9 节）
Mock 端口被占用 自动 +1 换端口；或先停掉占用方
导入 OpenAPI 失败 支持 OpenAPI 3.0 / Swagger 2.0 / Postman 集合 v2.1（JSON 或 YAML）；3.1+ 请先降级转换
数据库损坏？ 不会自动修复，但 backups/ 的 JSON 可完整重建所有数据
反馈问题 顶栏「反馈」自动生成本机诊断报告（路径提示），提交到 GitHub Issues 时附上即可

12. 反馈与支持

  • 顶栏右上方「反馈」按钮 → 一键生成本机环境/日志摘要报告 → 提交到项目仓库 Issue
  • 数据、部署、进阶指南见 README.md 与 docs/DEPLOY.md