SDK 接入文档

Appearance

服务端接入说明 ​

职责说明 ​

业务服务端在整个接入方案中承担以下职责：

  • 定时调用底层配置接口，拉取加密配置
  • 将密文缓存（不解密、不修改）
  • 向客户端暴露自有接口，返回缓存的密文

重要：服务端只做"获取 → 缓存 → 转发"，不需要也不应该对密文进行任何解密或修改。

环境说明 ​

环境域名
测试环境https://dcapi.dc-dev.cc
正式环境https://api.dc-server.cc

第一步：定时拉取配置接口 ​

接口信息 ​

# 正式环境
GET https://api.dc-server.cc/sdk/getAvailableDomainList

# 测试环境
GET https://dcapi.dc-dev.cc/sdk/getAvailableDomainList

建议调用频率 ​

每 10 分钟拉取一次。

响应格式 ​

json
{
  "code": 0,
  "msg": "success",
  "data": "<AES-256-GCM 加密字符串>"
}
字段类型说明
codenumber0 表示成功，非 0 表示失败
msgstring状态描述
datastring密文字符串，直接存储，不解密

第二步：缓存策略 ​

为什么必须缓存

服务端定时去 DMP 拉取域名列表，并在本地缓存一份。SDK 加载时从服务端缓存获取最新的上报接口域名返回给 SDK；后台定时任务持续从 DMP 获取最新域名列表并更新服务端本地缓存。这样即便 DMP 服务接口不通，服务端依然可以从缓存中拿到数据返回给 SDK，保障上报链路不中断。

核心原则 ​

情况处理方式
本次拉取成功更新缓存，保存最新密文 data
本次拉取失败，有历史缓存沿用上次成功的缓存，不清空，保障可用性
本次拉取失败，无任何历史缓存向客户端返回明确的错误状态，由客户端决策兜底

存储选择 ​

密文是普通字符串，可存储在：

  • Redis（推荐，TTL 可设为 30 分钟兜底）
  • 数据库（MySQL、PostgreSQL 等）
  • 应用内存（单节点简单场景，重启后丢失）

建议记录最后一次成功拉取的时间，方便排查问题。

第三步：向客户端提供接口 ​

业务服务端需暴露一个自有接口，供客户端在启动时调用，返回当前缓存的密文：

推荐响应格式 ​

json
{
  "code": 0,
  "msg": "success",
  "data": "<密文字符串，与拉取时一致>"
}

接口设计要点 ​

  • 直接返回缓存中的密文字符串，不做任何转换或解密
  • 无缓存时，返回明确的错误码，不要返回空字符串（客户端需要靠此判断是否跳过初始化）
  • 建议在响应中附加缓存更新时间，方便客户端或运维判断数据新鲜度（可选）

完整流程示意 ​

定时任务（每 10 分钟）
    │
    ├─── GET https://api.dc-server.cc/sdk/getAvailableDomainList  # 正式环境
    │
    ├─── 成功？
    │       ├─ 是 → 更新缓存（覆盖旧值）
    │       └─ 否 → 保留上次缓存（不清空）
    │
客户端请求业务服务端接口
    │
    └─── 返回缓存中的密文 data（原样返回）

多语言示例 ​

以下示例均为完整可运行参考实现，涵盖定时拉取、缓存管理和对外接口。

注意事项 ​

不要解密

data 字段是密文，服务端绝对不应该尝试解密。解密由 SDK 内部完成，服务端只需原样存储和转发。

缓存 TTL 建议

如果使用 Redis 存储，建议将 TTL 设置为 30 分钟（拉取间隔的 3 倍），以防止极端情况下缓存过期导致客户端拿不到数据。