Skip to content

下载跳转(统计 + 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 作为并存能力。