954b9e9d8a
All checks were successful
Build and Deploy (tool.xpcool.com) / build-and-deploy (push) Successful in 1m1s
- 添加 TerminalIcon, GitBranchIcon, ApiIcon, BrushIcon, SoundIcon, Table1Icon, LogoGithubIcon, ContrastIcon, Edit2Icon, ChartBarIcon, EarthIcon, GitMergeIcon, SettingIcon, CurrencyExchangeIcon, MobileIcon, WifiIcon, RocketIcon 等图标导入 - 新增 dev, design, health, study, travel, fun, online 七个工具分类 - 添加 SQL格式化、文本对比、JSON转代码、渐变生成器、占位图生成、 ASCII艺术、摩斯电码、正则可视化、Markdown表格、API构建器、 Gitignore生成器、代码转图片、颜色命名器、缩进转换、代码统计、 Hello World大全、JSON对比、环境变量解析、汇率换算、快递查询、 手机号归属地、IP信息查询、网络测试、网络测速等多个工具路由配置 - 新增 .env.example 配置文件模板 - 创建 docs/api-contract.md 后端接口契约文档 - 新增 api-builder 和 ascii-art 工具页面组件 - 更新 agents.md 添加接手必读指引和维护约定 - 创建 CHANGELOG.md 变更日志文档和工作日志记录
182 lines
5.2 KiB
Markdown
182 lines
5.2 KiB
Markdown
# 后端接口契约 · tool.xpcool.com
|
||
|
||
本文档定义工具箱「在线服务」分类所有工具的后端接口规范。
|
||
前端已通过 `src/api/client.ts` 统一请求，**后端按本文档实现接口即可直接接入**，前端无需改动。
|
||
|
||
## 通用约定
|
||
|
||
- **Base URL**：前端通过环境变量 `VITE_API_BASE` 配置（如 `https://api.xpcool.com`），未配置时页面显示「后端未接入」。
|
||
- **统一响应格式**（所有接口）：
|
||
```json
|
||
{ "code": 0, "message": "ok", "data": { ... } }
|
||
```
|
||
- `code = 0` 成功；非 0 失败，`message` 为可读错误信息（前端直接展示给用户）。
|
||
- **编码**：UTF-8；GET 参数走 Query String，POST 走 JSON Body，无需鉴权（公开工具站）。
|
||
- **CORS**：需要允许前端域名跨域（`Access-Control-Allow-Origin: *`）。
|
||
- 建议实现限流（如单 IP 每分钟 60 次），防止免费接口被刷。
|
||
|
||
## 接口一览
|
||
|
||
| # | 接口 | 说明 |
|
||
| --- | --- | --- |
|
||
| 1 | `GET /api/tools/exchange-rate` | 汇率换算 |
|
||
| 2 | `GET /api/tools/express-query` | 快递查询 |
|
||
| 3 | `GET /api/tools/phone-locate` | 手机号归属地 |
|
||
| 4 | `GET /api/tools/ip-info` | IP 信息查询 |
|
||
| 5 | `POST /api/tools/network-test` | 网络测试（ping / tcp / dns） |
|
||
| 6 | `GET /api/tools/speedtest/download` | 下载测速（返回随机二进制流） |
|
||
| 7 | `POST /api/tools/speedtest/upload` | 上传测速（接收二进制流） |
|
||
|
||
---
|
||
|
||
## 1. 汇率换算 `GET /api/tools/exchange-rate`
|
||
|
||
**参数**：`from`（源货币代码，如 CNY）、`to`（目标货币代码，如 USD）、`amount`（金额，可选，默认 1）
|
||
|
||
**响应 data**
|
||
|
||
```json
|
||
{
|
||
"from": "CNY",
|
||
"to": "USD",
|
||
"rate": 0.1398,
|
||
"amount": 100,
|
||
"result": 13.98,
|
||
"updated_at": "2026-08-24 17:00"
|
||
}
|
||
```
|
||
|
||
## 3. 快递查询 `GET /api/tools/express-query`
|
||
|
||
**参数**：`no`（快递单号）
|
||
|
||
**响应 data**
|
||
|
||
```json
|
||
{
|
||
"no": "SF1234567890",
|
||
"company": "顺丰速运",
|
||
"status": "在途",
|
||
"traces": [
|
||
{ "time": "2026-08-24 15:32", "desc": "快件已到达【深圳中转场】" },
|
||
{ "time": "2026-08-24 09:10", "desc": "快件已从【杭州】发出" }
|
||
]
|
||
}
|
||
```
|
||
|
||
## 4. 手机号归属地 `GET /api/tools/phone-locate`
|
||
|
||
**参数**：`phone`（11 位手机号）
|
||
|
||
**响应 data**
|
||
|
||
```json
|
||
{
|
||
"phone": "13800138000",
|
||
"area": "北京",
|
||
"carrier": "中国移动",
|
||
"postcode": "100000",
|
||
"updated_at": "2026-08-24 17:00"
|
||
}
|
||
```
|
||
|
||
## 5. IP 信息查询 `GET /api/tools/ip-info`
|
||
|
||
**参数**：`ip`（IPv4，可选；不传则查询请求方 IP）
|
||
|
||
**响应 data**
|
||
|
||
```json
|
||
{
|
||
"ip": "1.2.3.4",
|
||
"country": "中国",
|
||
"province": "广东",
|
||
"city": "深圳",
|
||
"isp": "电信",
|
||
"updated_at": "2026-08-24 17:00"
|
||
}
|
||
```
|
||
|
||
## 6. 网络测试 `POST /api/tools/network-test`
|
||
|
||
**请求体**
|
||
|
||
```json
|
||
{ "type": "ping", "host": "baidu.com", "port": null, "timeout": 5000 }
|
||
```
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| type | 是 | `ping` / `tcp` / `dns` |
|
||
| host | 是 | 主机名或 IP |
|
||
| port | tcp 必填 | 目标端口（1-65535），其他类型传 null |
|
||
| timeout | 否 | 超时毫秒，默认 5000 |
|
||
|
||
**响应 data**
|
||
|
||
```json
|
||
{
|
||
"type": "ping",
|
||
"host": "baidu.com",
|
||
"port": null,
|
||
"reachable": true,
|
||
"latency_ms": 23.5,
|
||
"detail": { "min_ms": 20.1, "avg_ms": 23.5, "max_ms": 28.3, "loss_pct": 0 }
|
||
}
|
||
```
|
||
|
||
各类型 `detail` 字段约定：
|
||
|
||
| type | detail 字段 | 说明 |
|
||
| --- | --- | --- |
|
||
| ping | `min_ms` / `avg_ms` / `max_ms` / `loss_pct` | 3 次探测的最小/平均/最大延迟（ms）与丢包率（0-100） |
|
||
| tcp | `tcp_connect_ms` | TCP 握手耗时（ms） |
|
||
| dns | `dns_resolve_ms` / `ip` | 解析耗时与解析出的 IP |
|
||
|
||
`reachable=false` 时 `latency_ms` 传 0，`detail` 传 `{ "error": "错误描述" }`。
|
||
|
||
## 7. 网络测速
|
||
|
||
### 下载测速 `GET /api/tools/speedtest/download?size=10485760`
|
||
|
||
- 返回 **200 + `application/octet-stream` 随机字节流**（不是 JSON），响应头需带 `Content-Length`（前端据此显示进度）。
|
||
- `size` 为请求的字节数（建议支持 5MB ~ 50MB）。
|
||
- 前端流式读取并按耗时计算下载 Mbps，无需后端返回额外数据。
|
||
|
||
### 上传测速 `POST /api/tools/speedtest/upload`
|
||
|
||
- 请求体：`application/octet-stream` 原始二进制（前端生成随机数据上传）。
|
||
- 响应 JSON：
|
||
|
||
```json
|
||
{ "code": 0, "message": "ok", "data": { "bytes": 5242880, "duration_ms": 812, "speed_mbps": 51.6 } }
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| bytes | 实际接收字节数 |
|
||
| duration_ms | 接收耗时（ms） |
|
||
| speed_mbps | 后端计算的上传速度（Mbps） |
|
||
|
||
> 建议：下载测速时每次生成新的随机数据（`crypto/rand`），避免被缓存/CDN 命中导致测速失真；响应头 `Cache-Control: no-store`。
|
||
|
||
---
|
||
|
||
## 错误示例
|
||
|
||
```json
|
||
{ "code": 40001, "message": "城市不存在，请检查输入", "data": null }
|
||
```
|
||
|
||
| code | 含义 |
|
||
| --- | --- |
|
||
| 40001 | 参数不合法（如城市不存在、单号格式错误） |
|
||
| 50001 | 上游数据源异常 |
|
||
| 50002 | 频率限制，请稍后重试 |
|
||
|
||
## 前端接入说明
|
||
|
||
1. 复制 `.env.example` 为 `.env`，填写 `VITE_API_BASE=https://api.xpcool.com`
|
||
2. 重启 `pnpm dev`，在线服务分类的工具即可请求
|
||
3. 后端实现时对照各接口的响应 `data` 字段，字段名保持一致即可（前端已按契约类型化）
|