logan
ec9a7b8695
- 删「打印/导出 PDF」按钮与「是否有帮助」反馈组件（静态站无后端，纯摆设）及未使用 SVG 图标 - 文档去 Tauri/Gin 等实现层名词（本地代理/隧道等用户语义保留） - 5 页 markdown 首行 H1 与页面标题去重 - homepage dist 同步重建
93 lines
5.2 KiB
Markdown
93 lines
5.2 KiB
Markdown
联调时后端接口没就绪？OpsxAPI 内置 **Mock.js 风格的数据生成器**，两种用法覆盖绝大多数场景：
|
||
|
||
1. **显式表达式** —— 在参数值、Body 中直接写 `@cname`、`@integer(1,100)`；
|
||
2. **智能匹配** —— 开启后按**字段名**自动套用规则表（`username` → 姓名、`email` → 邮箱…），一行不用写。
|
||
|
||
## 开启与配置
|
||
|
||
「设置 → 数据生成」（或请求编辑器的 Mock 工具按钮）：
|
||
|
||
- **启用 Mock 数据**：总开关，关闭后 `@` 表达式按普通文本原样发送；
|
||
- **智能 Mock 匹配**：JSON Body 字段值未写表达式时，按字段名匹配规则自动生成；
|
||
- **智能匹配规则表**：内置 **61 条**默认规则（用户名、邮箱、手机号、价格、时间戳……），数据类型（string / number / integer / boolean）、匹配方式（通配符 / 完全匹配 / 正则）、匹配规则（如 `*name*`）、Mock 表达式、备注与启用开关，支持搜索、新增、删除与恢复默认。
|
||
|
||
规则**从上到下**匹配，先命中先用；类型需与 JSON 字段实际类型一致（KV 参数一律按 string 匹配）。
|
||
|
||
## 表达式速查
|
||
|
||
| 表达式 | 说明 | 示例输出 |
|
||
| --- | --- | --- |
|
||
| `@cname` | 中文姓名 | `王国强` |
|
||
| `@email` | 邮箱 | `kx8f2@qq.com` |
|
||
| `@phone` | 手机号 | `138****2733` 形式 11 位 |
|
||
| `@id` | 身份证号 | 18 位 |
|
||
| `@guid` | UUID / GUID | `3f2b…-…` |
|
||
| `@integer(1, 100)` | 整数 | `42` |
|
||
| `@float(1, 9999, 2)` | 小数（保留 2 位） | `128.50` |
|
||
| `@boolean` | 布尔 | `true` |
|
||
| `@string(8, 16)` | 随机字符串 | `aZ3k…` |
|
||
| `@datetime(YYYY-MM-DD HH:mm:ss)` | 日期时间 | `2026-09-17 14:30:00` |
|
||
| `@date(YYYY-MM-DD)` / `@time(HH:mm:ss)` | 日期 / 时间 | — |
|
||
| `@timestamp` | 毫秒时间戳 | `1760000000000` |
|
||
| `@url` / `@domain` / `@ip` | URL / 域名 / IPv4 | — |
|
||
| `@province` / `@city(true)` / `@county(true)` | 省市区 | `广东省深圳市南山区` |
|
||
| `@ctitle(4, 12)` / `@csentence(10, 24)` | 中文标题 / 句子 | — |
|
||
| `@image(200x200)` | 图片地址 | picsum 随机图 |
|
||
| `@pick("A", "B", "C")` | 从列表中选择 | `B` |
|
||
|
||
未列出的写法会**原样发送**，可放心与真实值混用。
|
||
|
||
## 在请求中使用
|
||
|
||
**Params / x-www-form-urlencoded / form-data**：值一栏直接填表达式。
|
||
|
||
```text
|
||
username = @cname
|
||
page = @integer(1, 10)
|
||
```
|
||
|
||
**JSON Body**：叶子值写表达式，或交给智能匹配：
|
||
|
||
```json
|
||
{
|
||
"username": "@cname",
|
||
"email": "@email",
|
||
"age": "@integer(18, 60)",
|
||
"vip": "@boolean"
|
||
}
|
||
```
|
||
|
||
Body 工具栏提供两个辅助按钮：
|
||
|
||
- **智能填充**：按规则把 JSON 各字段值批量替换为对应 `@` 表达式，生成可编辑的 Mock 模板；
|
||
- **Mock 预览**：即时查看发送时实际生成的数据，不必真的发请求。
|
||
|
||
## 生效范围
|
||
|
||
- 生效：Query 参数、JSON / XML / Text Body、x-www-form-urlencoded、form-data、GraphQL Variables；
|
||
- 不生效：Headers、Cookies、鉴权字段（避免意外改坏签名与令牌）。
|
||
|
||
> 提示：Mock 在**发送瞬间**求值，同一请求每次发送都会得到新数据；预览结果仅供核对格式。
|
||
|
||
## 本地 Mock 服务（/mock）
|
||
|
||
除了发送时的离线 Mock，还能把接口**发布成本地 Mock 服务**，给前端 / 同事直接联调（类似 Apifox 的 Mock URL）：
|
||
|
||
1. 登录并切换到「我的空间」或团队空间（Mock 按空间隔离）；
|
||
2. HTTP 请求 URL 行点 **Mock 链接** → 选择响应状态码与延迟 → **发布**（一次发布当前空间集合内全部 HTTP 接口）；
|
||
3. 得到地址：`http://127.0.0.1:8787/mock/{空间随机地址}{路径}`（每空间一个 16 位随机片段，不可枚举、不暴露归属），例如 `http://127.0.0.1:8787/mock/9f2c7a1b3d5e4f60/api/users`。
|
||
|
||
特点：
|
||
|
||
- **独立监听端口**：Mock 服务默认跑在 `0.0.0.0:8798`（可用环境变量 `OPSXAPI_MOCK_ADDR` 修改），与主服务 8787 分离，内网同事按 `http://本机内网IP:8798/mock/{地址}{路径}` 直连；
|
||
- **Mock 管理页**：活动栏「Mock」视图集中管理已发布路由 —— 方法 / 路径 / 状态码 / 响应格式 / 延迟（0–5s）/ 启用开关，支持保存草稿、一键发布全部、试运行与 GET /demo 示例；
|
||
- **访问控制**：可开启 Bearer 密钥校验（只存摘要、可随时替换）；来源默认仅本机与内网网段，公网访问需显式设置 `OPSXAPI_MOCK_ALLOW_PUBLIC=1`；
|
||
- **一键建 Mock**：HTTP 编辑器可「用本次响应创建 Mock」，把真实返回直接变成 Mock 模板；
|
||
- **每次请求随机生成**：响应模板里的 `@cname`、`@integer(...)` 等表达式由服务端实时求值；
|
||
- 发布时自动把智能 Mock 规则烘焙进模板（开启智能匹配时）；
|
||
- 非 GET 接口可用 `?_method=POST` 快速验证；延迟最高 5 秒，用于模拟慢接口 / loading 态。
|
||
|
||
### 频率限制（防滥用）
|
||
|
||
本地 Mock 服务按 **IP + 空间** 限流：**20 QPS（每秒 20 次）或 60 QPM（每分钟 60 次）**，超限返回 `429` 与 `Retry-After: 60`。依据[服务条款](/terms)：未经授权或滥用行为平台有权采取限流、暂停服务等措施；**通过技术手段规避限流属于违规行为**。Mock 定位是联调辅助，请勿当作对外流量服务使用。
|