GET接口调用的两段鉴权链路

■ 鉴权分两段，先换短期访问令牌，再用令牌签名请求，令牌本身不承载任何身份信息。■

如果你也在处理WhatsApp网页版，这篇可以顺手对一下。 顺便一提，WhatsApp网页版 讲的是另一个容易忽略的点。 相关的坑WhatsApp网页版 里列得比较细，可以对照看看。 顺便一提，WhatsApp网页版 讲的是另一个容易忽略的点。

调用方先以凭证换取访问令牌,有效期以分钟计。

每次请求需携带令牌与请求体摘要,两者共同参与签名。

服务端只校验签名与有效期,不解析令牌内的业务信息。

因此令牌泄露的窗口很短,但签名密钥泄露则风险极高。

签名覆盖请求体摘要,任何字节改动都会导致校验失败。

时间戳用于限制重放窗口,超出容差即视为过期请求。

密钥应存放在服务端,不得下发到浏览器或客户端。

换取令牌的凭证同样需要轮换,长期不换等于长期暴露。

// 请求头结构示意
Authorization: Bearer <access_token>
X-Sign: hmac_sha256(secret, method + path + body_digest)
X-Ts: 1761…   // 秒级时间戳，容差 ±120s

POST限流的计数口径与退避

■ 限流按主体计数而非按 IP，同一主体下所有席位共享同一份额度，单席位统计必然算错。■

额度以窗口滚动方式计算,非固定整点重置。

读请求与写请求分属不同额度池,互不挤占。

超出额度返回的状态码与业务错误不同,应分别处理。

重试需带退避,否则会在窗口内持续消耗剩余额度。

POST回调重试的幂等设计

■ 回调至少投递一次，接收方必须自行去重，事件编号是唯一可靠的键，时间戳会重复。■

投递失败按指数退避重试,重试次数有上限。

超限后进入死信,需主动查询而非等待推送。

同一事件可能因确认超时被重复投递,属设计内行为。

去重键应使用事件编号,时间戳与内容摘要都可能重复。

处理逻辑必须幂等,重复执行不应产生额外副作用。

// 幂等处理骨架
if (store.has(evt.id)) return 200;
store.put(evt.id, processing);
try { apply(evt); store.put(evt.id, done); }
catch (e) { store.del(evt.id); return 500; }
return 200;

ENV沙盒与生产的隔离边界

■ 沙盒与生产使用独立凭证与额度池，跨环境复用凭证是最常见的错误，且报错信息不指向它。■

沙盒返回的是构造数据,不具备真实投递能力。

两套环境的凭证互不通用,混用会直接返回鉴权失败。

额度池同样独立,沙盒内的压测不会影响生产。

切换环境只需替换基础地址与凭证,路径结构保持一致。

接入前的四项核对动作

■ 核对顺序固定，先指向环境再核对凭证，最后才做压测，顺序颠倒会污染额度统计。■

1. 先确认基础地址指向目标环境,再核对凭证归属。
2. 记录当前额度用量,避免重试放大消耗。
3. 回调接收端实现事件编号去重,再接入生产。
4. 上线前用沙盒压测,观察限流返回与退避策略。

token_ttl

访问令牌有效期，以分钟计，过期需重新换取。

scope

额度池的划分维度，读写与握手各自独立计数。

event_id

回调事件的唯一编号，是幂等去重的可靠键。