simpleWebUtils API 文档

UA echo / UA 解析

GET /ua

回显请求的 User-Agent 头(纯文本)

GET /ua/analyze

结构化解析 User-Agent(浏览器、操作系统、设备等),返回 JSON

GET /ua/html

以 HTML 页面展示 User-Agent 解析结果

IP 地理查询

GET /ip

回显客户端 IP(纯文本)。经 CDN/反向代理访问时按 CF-Connecting-IP、True-Client-IP、X-Client-IP、X-Original-Forwarded-For、X-Forwarded-For、X-Real-IP 头识别真实来源

GET /ip/analyze

基于 GeoLite2-City 数据库查询客户端 IP 的地理位置(国家、城市、经纬度等),返回 JSON;客户端 IP 的 CDN/反代头识别与 /ip 相同

GET /ip/html

以 HTML 页面展示客户端 IP 及其地理位置查询结果;客户端 IP 的 CDN/反代头识别与 /ip 相同

Status code reference

GET /code/:code

以该状态码作为响应状态返回(空响应体),任意数字均可,用于测试客户端对状态码的处理

参数位置默认值说明
code path — HTTP 状态码,如 200、418;任意数字均可
GET /code/detail/:code

返回该状态码的参考信息 JSON:描述、MDN 与 http.cat 链接;未收录的码返回 400

参数位置默认值说明
code path — HTTP 状态码,需在参考表内,如 404
GET /code/html/:code

以 HTML 页面展示该状态码的描述(页面状态恒为 200,被测码只体现在页面内容里)

参数位置默认值说明
code path — HTTP 状态码,需在参考表内,如 404

Minecraft MOTD 查询

GET /minecraft/bedrock/:server

查询 Bedrock 服务器 MOTD 与在线人数(RakNet unconnected ping,UDP);端口缺省 19132;目标地址经 SSRF 防护,拒绝 loopback/私网/链路本地/组播地址

参数位置默认值说明
server path — 服务器地址(域名或 IP)
GET /minecraft/bedrock/:server/:port

查询 Bedrock 服务器 MOTD 与在线人数(RakNet unconnected ping,UDP);端口缺省 19132;目标地址经 SSRF 防护,拒绝 loopback/私网/链路本地/组播地址

参数位置默认值说明
server path — 服务器地址(域名或 IP)
port path 19132 服务器端口
POST /minecraft/bedrock

查询 Bedrock 服务器 MOTD 与在线人数(RakNet unconnected ping,UDP);端口缺省 19132;目标地址经 SSRF 防护,拒绝 loopback/私网/链路本地/组播地址;参数经 JSON body 传递

参数位置默认值说明
server body — 服务器地址(域名或 IP),必填
port body 19132 服务器端口
GET /minecraft/java/:server

查询 Java 服务器 MOTD 与在线人数(Server List Ping,TCP);端口缺省 25565;目标地址经 SSRF 防护,拒绝 loopback/私网/链路本地/组播地址

参数位置默认值说明
server path — 服务器地址(域名或 IP)
GET /minecraft/java/:server/:port

查询 Java 服务器 MOTD 与在线人数(Server List Ping,TCP);端口缺省 25565;目标地址经 SSRF 防护,拒绝 loopback/私网/链路本地/组播地址

参数位置默认值说明
server path — 服务器地址(域名或 IP)
port path 25565 服务器端口
POST /minecraft/java

查询 Java 服务器 MOTD 与在线人数(Server List Ping,TCP);端口缺省 25565;目标地址经 SSRF 防护,拒绝 loopback/私网/链路本地/组播地址;参数经 JSON body 传递

参数位置默认值说明
server body — 服务器地址(域名或 IP),必填
port body 25565 服务器端口
GET /minecraft/bedrock/html/:server

以 HTML 页面展示 Bedrock MOTD 查询结果:§ 颜色码渲染为彩色样式;查询失败(SSRF 拒绝、超时、解析失败)返回 400 HTML 错误卡片

参数位置默认值说明
server path — 服务器地址(域名或 IP)
GET /minecraft/bedrock/html/:server/:port

以 HTML 页面展示 Bedrock MOTD 查询结果:§ 颜色码渲染为彩色样式;查询失败(SSRF 拒绝、超时、解析失败)返回 400 HTML 错误卡片

参数位置默认值说明
server path — 服务器地址(域名或 IP)
port path 19132 服务器端口
GET /minecraft/java/html/:server

以 HTML 页面展示 Java MOTD 查询结果:§ 颜色码渲染为彩色样式;查询失败(SSRF 拒绝、超时、解析失败)返回 400 HTML 错误卡片

参数位置默认值说明
server path — 服务器地址(域名或 IP)
GET /minecraft/java/html/:server/:port

以 HTML 页面展示 Java MOTD 查询结果:§ 颜色码渲染为彩色样式;查询失败(SSRF 拒绝、超时、解析失败)返回 400 HTML 错误卡片

参数位置默认值说明
server path — 服务器地址(域名或 IP)
port path 25565 服务器端口
GET /minecraft/bedrock/badge/:server

Bedrock 服务器在线状态徽章(shields 风格 SVG,恒 200,可直接以 <img> 嵌入外站):在线绿色 online 当前/上限,超时或不可达红色 offline,其他错误灰色 offline;结果缓存 60 秒;查询复用 MOTD 端点的 SSRF 防护,拒绝 loopback/私网/链路本地/组播地址时返回 400

参数位置默认值说明
server path — 服务器地址(域名或 IP)
GET /minecraft/bedrock/badge/:server/:port

Bedrock 服务器在线状态徽章(shields 风格 SVG,恒 200,可直接以 <img> 嵌入外站):在线绿色 online 当前/上限,超时或不可达红色 offline,其他错误灰色 offline;结果缓存 60 秒;查询复用 MOTD 端点的 SSRF 防护,拒绝 loopback/私网/链路本地/组播地址时返回 400

参数位置默认值说明
server path — 服务器地址(域名或 IP)
port path 19132 服务器端口
GET /minecraft/java/badge/:server

Java 服务器在线状态徽章(shields 风格 SVG,恒 200,可直接以 <img> 嵌入外站):在线绿色 online 当前/上限,超时或不可达红色 offline,其他错误灰色 offline;结果缓存 60 秒;查询复用 MOTD 端点的 SSRF 防护,拒绝 loopback/私网/链路本地/组播地址时返回 400

参数位置默认值说明
server path — 服务器地址(域名或 IP)
GET /minecraft/java/badge/:server/:port

Java 服务器在线状态徽章(shields 风格 SVG,恒 200,可直接以 <img> 嵌入外站):在线绿色 online 当前/上限,超时或不可达红色 offline,其他错误灰色 offline;结果缓存 60 秒;查询复用 MOTD 端点的 SSRF 防护,拒绝 loopback/私网/链路本地/组播地址时返回 400

参数位置默认值说明
server path — 服务器地址(域名或 IP)
port path 25565 服务器端口

MCP server

GET /mcp

服务索引:serverInfo(含版本)与支持的方法列表(initialize、tools/list、tools/call)

POST /mcp

JSON-RPC 2.0 端点:method 支持 initialize、tools/list、tools/call;tools/call 提供 15 个 tool:bedrock_motd、java_motd(参数 server 必填,port 可选,默认 19132/25565)、hash_text(text)、ts_convert(t 可选,缺省当前时间)、jwt_decode(token)、dns_lookup(name)、url_encode/url_decode(text)、uuid_generate(无参)、base64_encode/base64_decode(text)、cidr_calc(addr 必填,bits 可选)、random_string(length/charset/chars 可选)、cron_next(expr 必填,tz/n 可选)、hmac_text(text、key);notification(无 id)返回 204

参数位置默认值说明
body body — JSON-RPC 2.0 请求体,如 {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"bedrock_motd","arguments":{"server":"example.com"}}}

请求头回显

GET /headers

以 JSON 回显请求的全部头,同名多值以 ", " 连接

GET /headers/html

以 HTML 页面展示请求的全部头,按头名字母序排列

UUID 生成

GET /uuid

返回一个随机生成的 UUID v4(JSON),每次调用结果不同

Base64 编解码

GET /base64/:text

对路径中的文本做标准 base64 编码,返回 JSON

参数位置默认值说明
text path — 待编码的文本
GET /unbase64/:text

对路径中的 base64 字符串解码,非法输入返回 400

参数位置默认值说明
text path — 待解码的 base64 字符串

URL 编解码

GET /urlencode/:text

对路径中的文本做 URL 编码(query 规则,空格变 '+'),返回 JSON

参数位置默认值说明
text path — 待编码的文本
GET /urldecode/:text

对路径中的 URL 编码文本解码,非法 % 序列返回 400

参数位置默认值说明
text path — 待解码的 URL 编码文本

Hash 摘要

GET /hash/:text

一次返回文本的 md5/sha1/sha256/sha512/sha3_256/sha3_512 摘要(hex 小写,JSON)

参数位置默认值说明
text path — 待计算摘要的文本
POST /hmac

以 {text, key} 请求体一次返回四种 HMAC(md5/sha1/sha256/sha512,hex 小写);key 不回显

参数位置默认值说明
text body — 待计算 HMAC 的文本
key body — HMAC 密钥(仅请求侧使用,响应不回显)

JWT 解码

GET /jwt/:token

解码三段式 JWT 的 header 与 payload,不验签,并把 exp/iat 数字声明转为 RFC3339 时间

参数位置默认值说明
token path — 待解码的 JWT(不验签)

时间戳转换

GET /ts

返回当前时间的 Unix 时间戳、RFC3339 与可读形式(UTC)

GET /ts/:t

解析 Unix 时间戳并返回 RFC3339 与可读形式(UTC),自动识别秒/毫秒

参数位置默认值说明
t path — Unix 时间戳,秒或毫秒

DNS 查询

GET /dns/:name

查询域名的 A/AAAA/CNAME/MX/TXT 记录,各类记录独立容错,返回 JSON

参数位置默认值说明
name path — 待查询的域名

CIDR 计算

GET /cidr/:addr

查询单个 IP 地址的子网信息;裸地址按单主机前缀处理(IPv4 /32、IPv6 /128)

参数位置默认值说明
addr path — IPv4 或 IPv6 地址,如 192.168.1.5 或 2001:db8::1
GET /cidr/:addr/:bits

计算 CIDR 前缀的网络地址、掩码、首/末主机、广播地址(仅 IPv4)与可用主机数(十进制字符串);主机位非零自动归一化为网络前缀并回显原始输入;IPv4 /31、/32 按 RFC 3021 语义不扣保留地址;非法地址、bits 非数字或越界(IPv4 > 32、IPv6 > 128)返回 400

参数位置默认值说明
addr path — IPv4 或 IPv6 地址,可带主机位,如 192.168.1.5
bits path — 前缀长度,非负整数;IPv4 上限 32,IPv6 上限 128

随机字符串生成

GET /random

用 crypto/rand 生成指定长度与字符集的随机字符串(拒绝采样,无模偏差)

参数位置默认值说明
length query 32 长度,1–1024
charset query alnum 字符集预设:alnum/hex/numeric/lower/upper/symbols,或 custom
chars query — charset=custom 时的自定义字符集,去重后须非空

Cron 表达式解析

GET /cron

按指定 IANA 时区解释 5 字段 crontab 表达式(含 @daily 等宏),返回未来 n 次运行时刻(RFC3339)

参数位置默认值说明
expr query — cron 表达式,5 字段 crontab 语法或 @daily/@midnight/@hourly/@weekly/@monthly/@yearly/@annually 宏
tz query UTC IANA 时区名,如 Asia/Shanghai;缺省按 UTC
n query 3 返回的未来运行次数,1–10

延迟响应

GET /delay/:seconds

等待指定秒数后返回 200 {"delay": seconds};秒数须为 1–10 的整数,非法或超限返回 400

参数位置默认值说明
seconds path — 延迟秒数,整数 1–10

请求回显

POST /echo

回显请求方法与原始请求体,返回 200 {"method": "POST", "body": <原样请求体>};空 body 为 ""

参数位置默认值说明
body body — 原样回显的请求体

HTTP 测试端点

GET /redirect/:n

自环重定向链:n>0 时 302 到 /redirect/(n-1),n=0 时 200 收尾;n 须为 0–20 的整数,非法或超限返回 400

参数位置默认值说明
n path — 剩余跳数,整数 0–20
GET /cookies

以 {"cookies": {...}} 回显当前请求携带的全部 cookie

GET /cookies/set/:k/:v

Set-Cookie 下发 k=v 后 302 到 /cookies,带 cookie jar 的客户端一次往返即可回读

参数位置默认值说明
k path — cookie 名
v path — cookie 值
GET /cookies/delete/:k

以过期属性(MaxAge<0)下发同名空 cookie 后 302 到 /cookies,落地回读即消失

参数位置默认值说明
k path — 要删除的 cookie 名
GET /gzip

返回固定 JSON 文档的 gzip 压缩响应(Content-Encoding: gzip),验证客户端解压路径

GET /bytes/:n

返回 n 个随机字节(application/octet-stream);n 须为 0–65536 的整数,非法或超限返回 400

参数位置默认值说明
n path — 随机字节数,整数 0–65536
GET /stream/:n

逐行 flush 输出 n 个 JSON 对象(每行含序号),验证客户端增量解析;n 须为 1–100 的整数,非法或超限返回 400

参数位置默认值说明
n path — 输出行数,整数 1–100

健康检查

GET /healthz

存活探针,恒返回 200 {"status": "ok"},供负载均衡器与容器编排系统轮询

OpenAPI 文档

GET /openapi.json

全站 OpenAPI 3.0.3 文档(JSON),由各 module 自描述元数据生成