OpenIM Chat Docs

Appearance

下载跳转（统计 + 302） ​

1. 接口定位 ​

  • 接口名称: 下载跳转（统计 + 302）
  • 所属域: chat/application
  • 业务目标: 客户端仅通过下载链接触发统计，服务端完成下载计数并 302 跳转到真实下载地址

2. 请求定义 ​

  • Method: GET
  • Path: /chatx/application/download
  • Query: versionID 必填
  • Query: versionID 或 platform + version 二选一
  • operationID: 兼容建议传入，但当前实现不强依赖
  • 鉴权: 无
  • 幂等性: 非严格幂等（服务端去重）

3. 请求参数 ​

Query 参数 ​

字段必填类型说明
versionID条件string版本记录 ID（ObjectID）
platform否string平台标识（如 ios、android）
version否string版本号（如 1.0.7）

Header 参数（可选） ​

字段必填类型说明
operationID否string链路追踪 ID

4. 响应行为 ​

该接口默认不返回 JSON 业务包裹，而是执行 HTTP 重定向：

  • 成功：302 Found，Location 为版本真实下载 URL
  • 失败：返回标准错误 JSON（如 versionID 非法、版本不存在）

5. 业务规则 ​

  • versionID 与 platform + version 二选一。
  • 传 versionID 时必须是合法的 Mongo ObjectID 字符串。
  • 未传 versionID 时必须同时提供 platform 与 version。
  • 服务端会先查版本并获取下载 URL。
  • 下载计数规则与 report_download 一致：
    • 同一 versionID + IP + UA，10 分钟内只计一次。
    • 同一 IP 按分钟限流，超限时不计数但仍可重定向下载。
  • 该模式用于降低前端接入复杂度，前端只需替换下载链接。

6. 错误码与失败场景 ​

错误码场景典型报错
1001versionID 为空versionID is required
1001versionID 非法invalid versionID
-版本不存在或数据库异常由底层错误链路返回

7. 示例 ​

浏览器直接访问 ​

text
GET /chatx/application/download?versionID=67ea6411c901bf3cb50ea001

浏览器访问（平台 + 版本号） ​

text
GET /chatx/application/download?platform=android&version=1.0.7

前端按钮链接 ​

html
<a href="/chatx/application/download?versionID=67ea6411c901bf3cb50ea001">下载</a>

fetch 示例（仅用于观察 302） ​

javascript
fetch("http://localhost:10010/chatx/application/download?versionID=67ea6411c901bf3cb50ea001", {
  method: "GET",
  redirect: "manual",
}).then((res) => {
  console.log(res.status, res.headers.get("location"));
});

8. 变更记录 ​

  • 2026-04-08: 新增下载跳转统计模式，保留 report_download 作为并存能力。