产品更新约 1 分钟阅读

Idempotency-Key:PDF 作业的安全重试

在 /api/v1/ 下的 POST 带 Idempotency-Key;成功响应在进程内内存缓存 24 小时,重启即丢,命中设 Idempotency-Replayed,不重跑。

PDF123 团队 · 更新于 2026-09-30
Idempotency-Key:PDF 作业的安全重试

multipart PDF 上传遇到网络超时与客户端重试,是常事。没有幂等键时,第二次 POST 可能把同一份合并、OCR 或压缩又跑一遍,白白多传一次、多算一遍。带上 Idempotency-Key,PDF123 就能把第一次成功的响应重放给你。

中间件做了什么

pdfx-server 里的服务端中间件只认变更型调用:对 /api/v1/ 下路径的 POST,其中包含 /api/v1/pipeline。GET 及其他方法原样通过。请求没有 Idempotency-Key 头,或者 trim 之后为空,op 就正常执行,不做缓存查找。

头存在时:

  1. 存储条目按主体 + 键索引。主体取自 X-API-KEY(记为 key:…),否则取 Authorization(记为 auth:…),都没有就用字面量 anon。这两个值经 SHA-256 哈希成映射键;请求体不参与其中。
  2. 24 小时内命中缓存,中间件就返回已存的状态码、内容类型、内容处置与正文,并设置 Idempotency-Replayed: true。
  3. 未命中就继续执行。只有成功的响应会被缓冲并存入(非成功响应不缓存,无法重放)。
  4. 响应体最多缓冲 100 MiB,重放时才能把文件字节重新发出去。缓冲不了的正文不会悄悄跳过缓存:该请求返回 HTTP 500,所以超限的响应会失败,而不是不带缓存地放行。

失败的作业可以用同一个键安全重试:失败不入库,下一次尝试成功后就成为缓存结果。别把同一个键用到不同的文件或参数上;缓存不哈希正文,只哈希主体与键。既不共享 API Key 也不共享 Authorization 的两个调用方不会撞车;匿名调用方则共享 anon 主体,必须各自选不同的键。

怎么发

为每个逻辑作业挑一个稳定的不透明字符串,UUID 就行:

curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -F "[email protected]"

匿名与 API Key 调用方都能用。先加水印再压缩的流水线,仍然应该为每一个想去重的 HTTP 请求发一个键:分步 POST 就每步一个,单次 /api/v1/pipeline 调用则一个键覆盖整条流水线。

工具页上的浏览器一次性作业(压缩、OCR 等)不需要你发明键,这个头是给会重试的客户端用的。发布在 /skills/pdf123.md 的 skill 在 pipeline 示例里带上 Idempotency-Key,也是同一个道理。

好用的客户端模式

  • 第一次 POST 之前先生成键,同一逻辑作业的超时重试都复用它。
  • 成功之后检查 Idempotency-Replayed: true,就能知道这次响应是又跑了一遍,还是来自缓存。
  • 文件、op 或参数一变就换键,哪怕主体没变。
  • 对 /api/v1/pipeline,一个键覆盖整次 POST,而不是内部每个步骤。

重放不是什么

重放不是持久化的作业队列。存储是进程内的(互斥锁护着的 HashMap),TTL 24 小时。过期之后,或者进程重启丢掉这份内存映射之后,同一个键会再把 op 跑一遍。多实例部署不共享这张映射,除非你在前面加一层共享存储;目前这套中间件是每进程一份。

把 Idempotency-Replayed: true 当作“这次响应来自缓存”的证据,而不是永久账本。它不表示 PDF 被重新处理过,也不延长 TTL。

更细的表面说明见 开发者 与 为 AI Agent 而建。压缩 这类工具页仍可用于不必发明键的浏览器一次性作业。

打开工具
在浏览器里完成处理,不加水印,文件处理完就会删除。
打开工具