af233e1628
All checks were successful
Build and Deploy (tool.xpcool.com) / build-and-deploy (push) Successful in 1m6s
视觉体系（核心是「令牌 → TDesign 桥接」） - 新增 tokens.scss：--tk-* 设计令牌（青玉 Jade 单一强调色、冷调中性色阶、 圆角/间距/字号/z-index/动效规范、按语言切换字体栈） - 新增 tdesign-theme.scss：--tk-* → --td-* 桥接（含完整冷调灰阶 1-14） → 60+ 个未改动的存量工具页零成本继承新配色与圆角 - index.scss 重写：只过渡颜色、统一 focus-visible、reduced-motion 降级 - 新增 v-reveal 滚动进入指令 布局与交互 - MainLayout 重写：毛玻璃 sticky 顶栏 + 三区布局 + 页脚（含备案号） - 新增 CommandPalette（⌘K/Ctrl+K）、LocaleSwitch（显示语言代码不用国旗）、 ThemeSwitch（三态；图标显示生效 mode、菜单勾选用户偏好 preference） - SideNav 重写：内联筛选、可折叠分组持久化、活动态指示条、需联网标记 - HomeView 重写：左对齐 Hero + 真实可用搜索 + 概览数字条 + 服务端工具专区 国际化与主题 - vue-i18n 11 + zh-CN/en-US/ja-JP/ko-KR 完整语言包（58 个工具名与描述全译） - helpers 取词带中文兜底；index.html 防闪烁内联脚本与 store 三处同步 - 主题三态 light/dark/auto，preference 与 mode 分离 服务端对接（service.xpcool.com /api/service/open/tools/*） - 新增 openTools.ts：接口元数据与调用函数共用同一份路径定义 - 改造/新建 6 页：ip-info、uuid、hash（服务端 MD5 两端口径对比）、 timestamp（服务端时钟 + 时钟偏移）、random-string、api-status - 均为「本机 / 服务端」双模式，默认本机、不自动打网络请求 - 后端未实现的 5 个接口用 BackendPending 如实标注，不伪装可用 修复 - 空分类渲染缺陷（health/study/travel 无工具却渲染空区块），分类 9 → 6 - UnoCSS panel 快捷类补内边距；IpInfoView 漏 onBeforeUnmount； SideNav 末尾 import；HomeView 错误导入 SUPPORTED_LOCALES 其他 - 新增 src/config.ts 集中站点常量，页脚展示备案号并链工信部核验 - docs/api-contract.md 按线上实际重写；PROJECT_STATE.md 全面更新 - 构建通过：vue-tsc --noEmit + vite build
158 lines
6.1 KiB
Markdown
158 lines
6.1 KiB
Markdown
# 后端接口契约 · tool.xpcool.com
|
||
|
||
后端为 `service.xpcool.com`（GoFrame v2）。前端统一走 `src/api/client.ts`，
|
||
已实现的接口封装在 `src/api/openTools.ts`。
|
||
|
||
> ⚠️ 本文件曾经是一份"待实现清单"（`/api/tools/*`）。2026-09-14 已按**线上实际部署**重写：
|
||
> 落地在 `/api/service/open/tools/*` 的 5 个接口**已经上线可用**，其余仍是待实现。
|
||
|
||
## 通用约定
|
||
|
||
- **Base URL**：环境变量 `VITE_API_BASE`，默认 `https://service.xpcool.com`（见 `.env.example`）。
|
||
未配置时前端仍可用默认值，不会白屏。
|
||
- **统一响应格式**（GoFrame `MiddlewareHandlerResponse` 信封）：
|
||
```json
|
||
{ "code": 0, "message": "OK", "data": { ... } }
|
||
```
|
||
- `code = 0` 成功；非 0 失败，`message` 为可读错误信息（前端直接展示给用户）。
|
||
- **方法**：**一律 POST**，URL 不带任何参数（查询参数、路径参数都禁止），入参全部走 JSON Body。
|
||
这是本项目 2026-08-27 起的强制接口设计规范。
|
||
- **鉴权**：无（公开工具站）。
|
||
- **CORS**：后端 `CORS` 中间件已开启，允许跨域。
|
||
- **超时**：前端 `DEFAULT_TIMEOUT = 10000ms`，超时与网络不可达在 `describeStatus()` 中区分提示。
|
||
|
||
---
|
||
|
||
## 一、已实现接口（5 个）
|
||
|
||
前缀：`/api/service/open/tools`
|
||
|
||
| # | 路径 | 说明 | 前端封装 |
|
||
| --- | --- | --- | --- |
|
||
| 1 | `POST /api/service/open/tools/ip` | 客户端 IP + 内网判定 | `fetchClientIp()` |
|
||
| 2 | `POST /api/service/open/tools/time` | 服务端当前时间 | `fetchServerTime()` |
|
||
| 3 | `POST /api/service/open/tools/uuid` | 唯一 ID | `fetchUuid(short)` |
|
||
| 4 | `POST /api/service/open/tools/md5` | 文本 MD5 | `fetchMd5(text)` |
|
||
| 5 | `POST /api/service/open/tools/random` | 随机字符串 | `fetchRandomString(length, type)` |
|
||
|
||
后端源码位置：`api/open/tools/<name>/<name>.go` + `internal/controller/open/<name>.go`。
|
||
路由挂载：`internal/cmd/cmd.go` 中 `s.Group("/api/service/open", ...)`。
|
||
|
||
### 1. `POST /tools/ip`
|
||
|
||
请求体：`{}`
|
||
|
||
```json
|
||
{ "code": 0, "message": "OK", "data": { "ip": "1.2.3.4", "internal": false } }
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| ip | string | 服务端看到的来源 IP |
|
||
| internal | bool | 是否为内网/私网地址 |
|
||
|
||
> 注意：**不返回归属地**（国家/省/市/ISP）。前端「IP 信息查询」页对此如实说明，不做猜测。
|
||
> 若要补归属地，需后端接入离线 IP 库后新增字段，前端预留位置。
|
||
|
||
### 2. `POST /tools/time`
|
||
|
||
请求体：`{}`
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "OK",
|
||
"data": { "timestamp": 1757788000, "dateTime": "2026-09-14 01:45:00", "date": "2026-09-14" }
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| timestamp | int | Unix 秒 |
|
||
| dateTime | string | `2006-01-02 15:04:05`（时区取决于服务端配置，前端不推断） |
|
||
| date | string | `2006-01-02` |
|
||
|
||
前端用它做两件事：显示服务端时间、估算本机时钟偏移。
|
||
偏移量基于 `timestamp`（Unix 秒，与时区无关），并补偿半个往返耗时，误差上界为 `rtt/2`。
|
||
|
||
### 3. `POST /tools/uuid`
|
||
|
||
请求体：`{ "short": false }`
|
||
|
||
```json
|
||
{ "code": 0, "message": "OK", "data": { "uuid": "a1b2c3d4e5f6..." } }
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| short | bool | true 返回 8 位短码；false 返回 32 位 ID |
|
||
|
||
前端服务端模式下一律**并发**调用 n 次（接口一次只返回一个），因此数量上限压到 10。
|
||
|
||
### 4. `POST /tools/md5`
|
||
|
||
请求体：`{ "text": "ping" }`（`text` 非空，后端有校验）
|
||
|
||
```json
|
||
{ "code": 0, "message": "OK", "data": { "md5": "b6f3a1..." } }
|
||
```
|
||
|
||
用于「哈希计算」页的**两端口径对比**：同一段文本前端（spark-md5）与后端各算一次。
|
||
比对统一折成小写，大小写只是展示层选择。
|
||
|
||
### 5. `POST /tools/random`
|
||
|
||
请求体：`{ "length": 8, "type": "alnum" }`
|
||
|
||
```json
|
||
{ "code": 0, "message": "OK", "data": { "value": "aB3xK9Qz" } }
|
||
```
|
||
|
||
| 字段 | 类型 | 约束 |
|
||
| --- | --- | --- |
|
||
| length | int | `1 - 128`（`v:"min:1|max:128"`，前端常量 `RANDOM_MAX_LENGTH = 128`） |
|
||
| type | string | `alnum` \| `digits` \| `letters`（`v:"in:alnum,digits,letters"`） |
|
||
|
||
---
|
||
|
||
## 二、待实现接口
|
||
|
||
以下工具在「在线服务」分类中，但后端尚无对应接口。
|
||
前端已用 `BackendPending` 组件如实标注「接口尚未上线」，**不会伪装成可用**；
|
||
后端实现后把对应页面的 `BACKEND_*_READY` 常量改为 `true`（或去掉开关）即可自动生效。
|
||
|
||
| 工具 | 建议路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| 汇率换算 | `POST /api/service/open/tools/exchange-rate` | `{ from, to, amount }` |
|
||
| 快递查询 | `POST /api/service/open/tools/express-query` | `{ no }` |
|
||
| 手机号归属地 | `POST /api/service/open/tools/phone-locate` | `{ phone }` |
|
||
| 网络测试 | `POST /api/service/open/tools/network-test` | `{ type: ping\|tcp\|dns, host, port, timeout }` |
|
||
| 网络测速 | `POST /api/service/open/tools/speedtest/*` | 下载返回随机二进制流，上传接收二进制流 |
|
||
|
||
上述字段设计沿用旧契约（见 git 历史中的 2026-08-24 版本），仅路径前缀从 `/api/tools/*` 迁到
|
||
`/api/service/open/tools/*`，并统一改为 POST + 纯 body 传参。
|
||
|
||
## 三、连通性自检
|
||
|
||
前端内置「服务端接口状态」页（`/api-status`），逐个探测上面 5 个已实现接口的
|
||
可用性与响应耗时。接口清单来自 `OPEN_TOOL_ENDPOINTS`，**新增接口只需在 `openTools.ts`
|
||
补一条元数据**，「接口状态」页与首页的接口计数会自动同步。
|
||
|
||
2026-09-14 实测（`curl` 直连线上）：
|
||
|
||
| 接口 | 结果 |
|
||
| --- | --- |
|
||
| `/tools/ip` | HTTP 200 |
|
||
| `/tools/time` | HTTP 200 |
|
||
| `/tools/uuid` | HTTP 200 |
|
||
| `/tools/md5` | HTTP 200 |
|
||
| `/tools/random` | HTTP 200 |
|
||
|
||
## 四、前端接入说明
|
||
|
||
1. 复制 `.env.example` 为 `.env`，按需覆盖 `VITE_API_BASE`（不填也能跑，默认线上地址）。
|
||
2. `pnpm dev` / `pnpm build`。
|
||
3. 新增后端接口时：
|
||
- 在 `src/api/openTools.ts` 补 `OpenEndpoint` 元数据 + 调用函数；
|
||
- 在对应工具页接入，并补 `src/i18n/locales/*.ts` 的 `page.*` 文案（**四语言都要补**）。
|