企业官网建设流程全解析

YOURLS API实战：6个核心Action、HMAC签名认证与公开API搭建

【免费下载链接】YOURLS🔗 The 𝘥𝘦 𝘧𝘢𝘤𝘵𝘰 standard, self hosted, powerful and customizable, URL shortener in PHP项目地址: https://gitcode.com/gh_mirrors/yo/YOURLS

YOURLS API 是这款自托管 URL 缩短服务的核心能力，支持短链接创建、数据统计、链接展开等 6 个内置 Action，并提供用户名密码与 HMAC 签名两种认证方式。本文带你零基础上手 YOURLS API 实战：从最简短链接请求，到安全签名调用，再到一键搭建无需登录的公开 API，全部讲透。

一、认识 YOURLS API 入口

YOURLS 的 API 由根目录下的 yourls-api.php 统一处理。所有请求都指向这一个文件，通过action参数区分要执行的操作：

请求地址形如：

https://你的域名/yourls-api.php?action=shorturl&url=...

支持 GET 与 POST，输出格式通过format参数指定，可选json、xml、simple（纯文本，默认取短链接）三种，由 includes/functions-api.php 中的yourls_api_output()函数统一封装输出。

二、6 个核心 Action 逐个实战

API 内置 Action 在 yourls-api.php 中注册，共 6 个：

1. shorturl：最常用的创建短链

/yourls-api.php?action=shorturl&url=https://example.com&page=2&format=json

返回 JSON 中包含keyword、shorturl、statusCode等字段；加&format=simple则只返回短链本身，方便直接复制。指定keyword可以自定义短链后缀，例如action=shorturl&url=...&keyword=hello。

2. expand：反向解析短链

/yourls-api.php?action=expand&shorturl=hello&format=json

短链可以传完整地址（如https://ozh.in/abc）也可以只传关键词（abc），服务端会自动识别，逻辑见 includes/functions-api.php 中的yourls_api_expand()。

3. stats / db-stats / url-stats：数据统计三件套

• stats：filter支持top（点击最多）、bottom、last（最新）、rand，配合limit与start分页；
• url-stats：查询某条短链的点击数、最近访问时间等；
• db-stats：返回全站短链总数与点击总数，适合做仪表盘。

统计功能同样依赖 includes/functions-shorturls.php 中的查询实现，返回结果建议用json或xml格式解析。

4. version：快速探活

不带任何业务参数的action=version是验证 API 是否可用的最好方式，加db=1还能拿到数据库结构版本号。

远程调用参考

如果你的脚本不在 YOURLS 同一台服务器上，可以直接参考仓库自带的示例文件 sample-remote-api-call.txt（重命名为.php即可运行），其中演示了如何用 cURL 以 POST 方式携带username、password完成一次短链创建。

三、认证方式：从用户名密码到 HMAC 签名

方式一：用户名 + 密码

最直观的方式，请求中带上username与password即可通过鉴权（见 includes/functions-auth.php 的校验逻辑）。简单但凭据会出现在请求里，适合内网或测试场景。

方式二：signature 签名认证

生产环境推荐使用签名方式，YOURLS 的签名机制基于 HMAC（哈希消息认证码）：

1. 每个用户拥有唯一签名：服务端用站点密钥对api:用户名做 HMAC 哈希，截取前 32 位（长度可用auth_signature_length过滤器调整），即yourls_auth_signature()，见 includes/functions-auth.php；
2. 请求携带signature参数：服务端遍历已注册用户，用hash_equals()做时序安全比对，命中即放行；
3. 时效签名（timestamped signature）：进阶做法是再传timestamp参数，把sha256(timestamp + signature)作为最终signature值提交。默认哈希算法为 sha256，允许 sha384 / sha512，且时间戳偏差必须在 nonce 有效期内，可有效防重放。

这种方式的好处是：调用方只需持有签名（可安全存储在服务端），无需在请求中暴露密码，且签名可随时更换。相关测试用例参考 tests/tests/auth/SigTest.php。

💡 安全提示：私有模式下，未带认证信息的 API 请求会被直接拒绝；YOURLS_PRIVATE与YOURLS_USER等配置项定义在你的config/yourls-config.php中。

四、两行代码搭建公开 API

很多场景（论坛短链插件、博客编辑器等）希望 API 无需登录即可创建短链。YOURLS 官方提供了 sample-public-api.txt 模板，做法非常简单：

1. 把 sample-public-api.txt 复制一份，重命名为api.php，放在与yourls-api.php同目录；
2. 文件内容只有两行关键代码：define('YOURLS_PRIVATE', false);后require主 API 文件。

这样即使你的安装是私有模式（后台禁止匿名访问），api.php也能提供公开的短链创建入口。使用前请评估风险：公开 API 意味着任何人都能创建短链，建议配合插件做频率限制或来源校验。

五、动手清单与常见问题

✅快速自检清单

• 用action=version&format=json确认 API 通不通；
• 用action=shorturl&format=simple拿到第一条短链；
• 生产调用改走signature认证；
• 需要免登录集成时部署公开api.php；
• 用action=db-stats观察整体数据增长。

❓常见问题

• 报错 400 "Unknown or missing action"：action参数缺失或拼写错误，对照第二节的 6 个 Action 表检查；
• 返回 404 类错误：expand/url-stats的短链不存在，或shorturl未传url参数；
• stats 用 simple 格式没有数据：统计类 Action 必须使用json或xml格式；
• 签名一直不通过：确认时间戳未过期、哈希算法在允许列表内（默认 sha256），并检查客户端与服务端时钟是否同步。

想继续深入，可以从 includes/functions-api.php 阅读 Action 封装逻辑，或参考 sample-public-front-page.txt 与 sample-remote-api-call.txt 两个官方示例，把 YOURLS 变成你整个技术栈里的链接枢纽。

【免费下载链接】YOURLS🔗 The 𝘥𝘦 𝘧𝘢𝘤𝘵𝘰 standard, self hosted, powerful and customizable, URL shortener in PHP项目地址: https://gitcode.com/gh_mirrors/yo/YOURLS