接入实践参考

本页给出“签名 + 业务调用 + 排查”三部分的接入实践，便于快速落地。

认证方式与端点统一说明可参考：认证方式与服务器端点。

1. 令牌管理建议

常见接入模式是使用一个统一的 Token Manager：

• 统一保存当前签名值（accessToken/apiKey）和过期时间。
• 对外只暴露一个取令牌方法（如 getApiKey()）。
• 业务代码不直接访问签名交换/换新接口，统一走 Token Manager。

这种方式能避免多个模块各自维护签名状态，减少并发下的令牌覆盖问题。

2. 签名更新建议

• 首次无签名时，调用签名交换接口获取首个签名。
• 临近过期窗口（5 分钟内）走换新接口，成功后覆盖本地变量。
• 换新失败时，可回落到签名交换接口拿新签名。

签名交换与换新接口说明：

• 基础接口/签名交换
• 基础接口/签名换新

3. 业务请求封装建议

建议统一封装请求入口，把以下逻辑放在一处：

• 取最新签名
• 自动附带认证头
• 记录 requestId
• 统一处理错误码

最小伪代码：

async function callVDP(path, init = {}) {
  const token = await getApiKey();
  const resp = await fetch(`${VDP_BASE_URL}${path}`, {
    ...init,
    headers: {
      ...(init.headers || {}),
      "X-Api-Key": token,
    },
  });

  const data = await resp.json().catch(() => ({}));
  const requestId = resp.headers.get("x-request-id") || data.requestId || "";
  return { ok: resp.ok, status: resp.status, requestId, data };
}

4. 连通性验证建议

接入初期可先调用验证接口，快速确认签名和链路正常：

• GET /api/proxy/base/hello-world

该接口成功返回 message: "helloworld"，同时带有 requestId。

5. 问题排查建议

• 报错排查时优先保留 requestId。
• 可在文档中心搜索框直接搜索 requestId 查看关联日志结果。