跳至主要内容
短.be

幂等性

同一操作无论执行多少次结果都不变的特性。在 API 设计中保障重复请求安全处理的关键概念。

2026 年 8 月 25 日 / 约 1 分钟阅读

短链接

幂等性 (Idempotency) 是指同一操作执行一次和执行多次的结果完全相同的特性。数学表达为 f(f(x)) = f(x)。在 Web API 设计中,这是防止网络故障或超时导致重试时产生重复处理的重要概念。

HTTP 方法的幂等性在规范中有明确定义。GET、PUT、DELETE 是幂等的,POST 是非幂等的 (每次执行可能创建新资源)。这里所说的幂等,指的是同一请求发送多次后服务器端产生的结果与只发送一次相同。返回的响应并不一定相同,例如 DELETE 第一次通常返回 200,之后因目标已不存在而返回 404,这并不违反幂等性。

在短链接服务的 API 设计中,幂等性是核心课题。对同一 URL 发送两次缩短请求时,应该生成两个不同的短链接,还是返回同一个短链接?幂等设计下,相同输入始终返回相同的短链接。这样即使因网络错误而重试,也不会生成重复的短链接。

实现幂等性的常见手法是使用 Idempotency Key (幂等键)。客户端在请求中附加唯一键 (如 UUID),服务器缓存该键对应的处理结果。当收到相同键的请求时,不再重新处理而是直接返回缓存结果。Stripe 的支付 API 是这一手法的典型代表。

短链接服务中的幂等性实现通常结合 URL 规范化。对输入 URL 进行规范化后计算哈希值,相同哈希值返回相同的短码。这样 "https://example.com/page" 和 "https://example.com/page/" 就会映射到同一个短链接。

这篇文章对您有帮助吗?

相关术语

短链接服务架构

短链接服务的内部设计,涵盖 ID 生成、数据库设计、缓存策略和重定向处理机制。

API 密钥

用于认证和控制 API 访问的字符串。用于识别调用者身份并限制访问权限。

API 速率限制

限制客户端在特定时间内可以发送的 API 请求数量,防止滥用和保护服务稳定性。

Base62 编码

使用 62 个字母数字字符 (a-z, A-Z, 0-9) 来表示数据的编码方式。广泛用于短链接的短码生成。

URL 规范化 (写法统一)

将表示形式不同但指向同一资源的多个 URL 转换为统一标准格式的处理。对防止重复内容至关重要。

307 重定向

HTTP/1.1 中的临时重定向状态码,严格保持原始请求方法不变。

相关文章

网址缩短 API 使用指南 - 通过程序生成短链接

解说如何通过程序使用网址缩短服务的 API。介绍请求格式、响应结构和实现示例。

图解网址缩短原理 - 重定向的技术背景

结合 HTTP 响应示例和 Base62 编码计算实例,详细解说网址缩短服务实现重定向的技术原理。

缩短 GitHub 的长 URL 提升开发工作流效率

详解如何用短链接管理 GitHub 中容易变长的 Issue、Pull Request、blob 路径等 URL。涵盖 README 中的应用、CI/CD 通知链接优化、文档站点的短链接导航、git.io 停用后的替代方案,以及开源项目中的实践案例。

常见问题

为什么 API 需要幂等性?
网络故障或超时导致请求失败时,客户端会重试。没有幂等性保障,重试可能导致重复处理 (重复扣款、重复注册等)。有了幂等性,重试就是安全的。
Idempotency Key 如何实现?
客户端在请求头中附加 UUID (如 Idempotency-Key: 550e8400-...),服务器将该键和处理结果缓存到 Redis 等存储中。收到相同键的请求时,直接返回缓存结果而不重新处理。
GET 请求一定是幂等的吗?
按 HTTP 规范,GET 不仅是幂等的,还是 safe (安全) 的方法,也就是具有只读语义。服务器端更新访问日志或统计数据本身并未被禁止,关键在于发出 GET 的客户端并没有要求服务器改变状态。浏览器预取、爬虫和缓存都是基于这一前提发送 GET 请求的,因此如果用 GET 修改数据,变更就会在无人预期的时刻发生。需要改变状态时应使用 POST、PUT、DELETE。

把知识用到真实链接上

免费缩短网址