logan
045e8c65c3
- TestSchedule 新增可选 5 段 cron（分 时 日 月 周，本地时区），优先于 intervalMinutes；runLog 调度日志 - cron.ts 解析与匹配引擎 + 单测；scheduler 按最近下次触发时间调度 - ScheduleDialog / TestingView 支持 cron 输入与下次运行提示；AiCaseDialog 微调 - 服务端 internal/echo 调试回显端点；修复 model.ts 注释内 */ 导致的语法错误 - 全量 53 前端用例绿
117 lines
6.3 KiB
Markdown
117 lines
6.3 KiB
Markdown
# OpsxAPI
|
||
|
||
给运维和开发用的专业接口工作台 —— 对标 Apifox / Apipost 的自研替代。
|
||
|
||
**HTTP · GraphQL · WebSocket · SSE · Socket.IO · MQTT，一个工作台全搞定；数据全在本地。**
|
||
|
||
```
|
||
packages/core 数据模型 / 树操作 / 导入导出器（纯 TS，21 个单测）
|
||
packages/transport browser | gin-proxy | tauri-native + 流式/SSE/WS隧道/Socket.IO/MQTT 客户端
|
||
packages/ui 共享工作台 UI（集合树 / 多标签 / 编辑器 / 对话框）
|
||
apps/web Vite + React 入口（:5173）
|
||
apps/desktop Tauri 2 壳（frontendDist → web dist）
|
||
apps/server Gin：HTTP 代理 + 流式代理 + WebSocket 隧道（:8787）
|
||
```
|
||
|
||
核心原则：**一套 UI、一份请求契约，Web / Desktop 只换 Transport。**
|
||
|
||
## 功能总览
|
||
|
||
### 协议
|
||
- **HTTP/REST**：GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS；Params / Body（JSON·XML·Text·HTML·x-www-form-urlencoded·form-data）/ Headers / Cookies / Auth（Bearer·Basic·APIKey）
|
||
- **GraphQL**：Query + Variables 编辑、独立响应面板
|
||
- **WebSocket**：消息日志（收/发/系统分色）、快捷发送、握手 Header（经 Gin 隧道，绕开浏览器限制）
|
||
- **SSE**：断点续传（Last-Event-ID）、直连失败自动切 Gin 代理、事件按 `event:` 分发
|
||
- **Socket.IO**：事件监听（可 onAny）、emit 参数 JSON、path/transports/auth 连接选项
|
||
- **MQTT**：wss broker、主题订阅（通配符）、发布、QoS 0/1/2、自动重连
|
||
|
||
### 导入（粘贴 / 文件 / URL 三种来源，格式自动识别）
|
||
| 格式 | 说明 |
|
||
| --- | --- |
|
||
| OpenAPI 3.0 / 3.1 / Swagger 2.0 | JSON 或 YAML；Apifox 导出同格式直接可用 |
|
||
| Swagger URL | 经本地 Gin 代理拉取，避开 CORS |
|
||
| Postman Collection v2.0 / v2.1 | 含鉴权、变量、GraphQL body |
|
||
| Apipost 项目 | `api_collection` 宽容解析 |
|
||
| cURL | 引号 / 续行 / -d / -F / -u / --data-urlencode 全支持 |
|
||
| HAR 抓包 | 按域名分组、去重 |
|
||
| Insomnia 导出 | v3 / v4（workspace/group 层级） |
|
||
| Hoppscotch 集合 | 数组或单对象 |
|
||
| Markdown 接口文档 | 提取 ```curl 代码块 |
|
||
| OpsxAPI 备份 | 全量集合 + 环境 |
|
||
| YApi / Apidoc / Apizza / Eolink | 请先导出为 OpenAPI 或 Postman 格式再导入 |
|
||
|
||
导入后自动：tag→目录、`{path}` 参数→`{{变量}}` 并写入环境、schema→示例 body、security→鉴权配置。
|
||
|
||
### 导出
|
||
- OpenAPI 3.0（JSON / YAML，带 tag 分组）· Postman v2.1 · Markdown 接口文档 · 全量备份
|
||
- 单请求代码生成：cURL / JavaScript fetch / Python requests / Go net/http
|
||
|
||
### 工作台
|
||
集合树（搜索 / 右键菜单 / 拖拽移动 / 复制 / 重命名）· 多标签页 · 历史记录（点击回跳）
|
||
· 环境变量（多环境切换、`{{var}}` 全局替换）· 明暗双主题 · localStorage 自动持久化
|
||
|
||
## 怎么跑
|
||
|
||
```bash
|
||
make install # npm install（含 desktop 依赖）
|
||
./run.sh web # 浏览器：Gin(:8787) + Vite(:5173) ← 推荐
|
||
./run.sh gui # 桌面 Tauri 窗口（共用 Vite）
|
||
./run.sh all # 全开
|
||
./run.sh stop | status
|
||
```
|
||
|
||
打开 http://127.0.0.1:5173 —— 内置「示例集合」覆盖全部协议，开箱即用。
|
||
|
||
## 用户文档站（/docs）
|
||
|
||
Gin 内置产品文档，Markdown 嵌入二进制、SSR 渲染，随服务一键部署：
|
||
|
||
- 地址：`http://127.0.0.1:8787/docs`（开发态 `http://127.0.0.1:5173/docs`，Vite 已反代；工作台顶栏「📖 文档」直达）
|
||
- 布局：顶栏搜索 + 左侧分组导航（16 篇：开始使用 / 请求调试 / 数据管理 / 参考）+ 右侧本页目录
|
||
- 能力：全文搜索、代码块复制 + 高亮、提示块、上一页/下一页、反馈组件、打印导出 PDF、移动端响应式、404 页
|
||
- 内容在 `apps/server/internal/docs/content/*.md`，改完重新 `go build` 即生效
|
||
|
||
## 产品官网（/home）
|
||
|
||
Gin 内置营销单页，与 /docs 同为 SSR 嵌入交付（`internal/site`）：
|
||
|
||
- 地址：`/` 与 `/home` 双入口（开发态 `http://127.0.0.1:5173/home`）；文档站顶栏「官网」互链
|
||
- 区块：Hero（纯 CSS 产品界面 mock）/ 卖点 / 功能 / 六协议 / 导入导出生态 / 与 Apifox·Apipost 对比表 / 定价 / 让利计划 / 购买 FAQ / 联系 CTA / Footer
|
||
- 定价三档（标价/成交价分离）：个人版 ¥99/年、团队版 ¥99/人/年（入门锚点）；企业私有化版标价 **¥8,000/年 · ¥30,000 买断**，经早鸟/教育/多年预付/案例合作落在成交区间 ¥5,000–8,000/年、¥15,000–30,000
|
||
- 让利机制四项：早鸟创始价（前 20 席 5–7 折永久）、教育/开源 6–8 折、多年预付 8–9 折、案例换授权；销售原则：不直接降价，用「永久授权 + 1 年升级 + 5 人团队 1–2 年回本」回应预算顾虑
|
||
- 交付前替换：联系邮箱 `hello@opsxapi.dev`（template.html 内两处）与对比表脚注中的价格核对
|
||
|
||
## 服务端端点（apps/server）
|
||
|
||
| 端点 | 用途 |
|
||
| --- | --- |
|
||
| `GET /health` | 健康检查 |
|
||
| `POST /v1/proxy/http` | HTTP 代理（绕 CORS，全方法） |
|
||
| `POST /v1/proxy/http/stream` | NDJSON 流式代理（SSE / chunked） |
|
||
| `POST /v1/proxy/ws/connect` | WS 隧道：拨号目标（带自定义 Header），返回 sessionId |
|
||
| `GET /v1/proxy/ws/attach` | WS 隧道：浏览器 attach，双向桥接 |
|
||
| `POST /v1/proxy/ws/close` | 关闭隧道会话 |
|
||
|
||
浏览器直连 WS 无法带自定义 Header 时，transport 层自动走隧道；SSE 直连 CORS 失败自动切代理。
|
||
|
||
## 架构决策
|
||
|
||
- **一套 UI**：集合 / 编辑器 / 对话框全部在 `packages/ui`，Web 与桌面零分叉
|
||
- **判别联合数据模型**：`node.kind === "http"` 自动收窄 `node.data` 类型
|
||
- **实时会话不落盘**：WS/SSE/Socket.IO/MQTT 会话存模块级注册表，消息（500 条上限）与状态进 store
|
||
- **zustand 选择器必须返回稳定引用**：`?? []` 会触发 useSyncExternalStore 无限重渲染（踩过的坑）
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
make test # core 21 个单测：导入导出全格式往返、树操作、cURL 解析
|
||
cd apps/server && go test ./...
|
||
```
|
||
|
||
## P0 自动化演示（本地）
|
||
|
||
1. `./run.sh web` → http://127.0.0.1:5173
|
||
2. 进入自动化测试 → **装载回归示例** → **运行**（依赖本机 Gin `:8787/v1/echo`）
|
||
3. AI：**保存并运行** 与手动/定时共用同一执行器与报告
|
||
4. 定时：支持 5 段 Cron 或间隔；应用保持打开；见 `docs/HANDTEST-P0.md`
|