tool.xpcool.com/docs/api-contract.md

后端接口契约 · 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 信封）：

  { "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

请求体：{}

{ "code": 0, "message": "OK", "data": { "ip": "1.2.3.4", "internal": false } }

字段	类型	说明
ip	string	服务端看到的来源 IP
internal	bool	是否为内网/私网地址

注意：不返回归属地（国家/省/市/ISP）。前端「IP 信息查询」页对此如实说明，不做猜测。 若要补归属地，需后端接入离线 IP 库后新增字段，前端预留位置。

2. POST /tools/time

请求体：{}

{
  "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 }

{ "code": 0, "message": "OK", "data": { "uuid": "a1b2c3d4e5f6..." } }

字段	类型	说明
short	bool	true 返回 8 位短码；false 返回 32 位 ID

前端服务端模式下一律并发调用 n 次（接口一次只返回一个），因此数量上限压到 10。

4. POST /tools/md5

请求体：{ "text": "ping" }（text 非空，后端有校验）

{ "code": 0, "message": "OK", "data": { "md5": "b6f3a1..." } }

用于「哈希计算」页的两端口径对比：同一段文本前端（spark-md5）与后端各算一次。 比对统一折成小写，大小写只是展示层选择。

5. POST /tools/random

请求体：{ "length": 8, "type": "alnum" }

{ "code": 0, "message": "OK", "data": { "value": "aB3xK9Qz" } }

字段	类型	约束
length	int	1 - 128（`v:"min:1
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.* 文案（四语言都要补）。