93 lines
3.0 KiB
Markdown
93 lines
3.0 KiB
Markdown
# 版本强更接口 App 对接
|
||
|
||
## 接口地址
|
||
|
||
`GET /api/v1/app/version`
|
||
|
||
公开接口，不需要 `Authorization`。
|
||
|
||
## Header
|
||
|
||
| Header | 必填 | 说明 |
|
||
| --- | --- | --- |
|
||
| `X-App-Code` | 否 | App 编码，默认 `lalu`。 |
|
||
| `X-App-Package` | 否 | App 包名；当前 `com.org.laluparty` 可解析为 `lalu`。 |
|
||
| `X-App-Platform` | 条件必填 | `android` 或 `ios`；query `platform` 为空时读取该 header。 |
|
||
| `X-App-Build-Number` | 条件必填 | 当前客户端编译版本号；query `build_number` 为空时读取该 header。 |
|
||
| `X-App-Version` | 否 | 当前客户端展示版本号，只用于日志排查。 |
|
||
|
||
## Query 参数
|
||
|
||
| 参数 | 必填 | 类型 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `platform` | 条件必填 | string | `android` 或 `ios`；优先级高于 `X-App-Platform`。 |
|
||
| `build_number` | 条件必填 | int64 | 当前客户端编译版本号；优先级高于 `X-App-Build-Number`。 |
|
||
|
||
`platform` 必须通过 query 或 header 传入。`build_number` 对 App 端必须传；服务端缺省时按 `0` 处理，会导致已配置版本都被判定为有更新。
|
||
|
||
请求示例：
|
||
|
||
```http
|
||
GET /api/v1/app/version?platform=android&build_number=100
|
||
X-App-Code: lalu
|
||
X-App-Platform: android
|
||
X-App-Build-Number: 100
|
||
X-App-Version: 1.1.0
|
||
```
|
||
|
||
## 成功返回
|
||
|
||
```json
|
||
{
|
||
"code": "OK",
|
||
"message": "ok",
|
||
"request_id": "req_abc",
|
||
"data": {
|
||
"app_code": "lalu",
|
||
"platform": "android",
|
||
"version": "1.2.0",
|
||
"build_number": 120,
|
||
"force_update": true,
|
||
"download_url": "https://example.com/lalu.apk",
|
||
"description": "修复已知问题",
|
||
"has_update": true,
|
||
"current_build_number": 100,
|
||
"updated_at_ms": 1710000000000,
|
||
"server_time_ms": 1710000001234
|
||
}
|
||
}
|
||
```
|
||
|
||
返回字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `app_code` | string | 服务端解析后的 App 编码。 |
|
||
| `platform` | string | `android` 或 `ios`。 |
|
||
| `version` | string | 后台配置的最新展示版本号，只用于展示。 |
|
||
| `build_number` | int64 | 后台当前最高编译版本号。 |
|
||
| `current_build_number` | int64 | 服务端收到的客户端编译版本号。 |
|
||
| `has_update` | bool | `build_number > current_build_number` 时为 `true`。 |
|
||
| `force_update` | bool | 当前客户端落后且后台最新版本标记强更时为 `true`。 |
|
||
| `download_url` | string | 更新跳转地址；Android 通常是 APK 下载页，iOS 通常是 App Store 链接。 |
|
||
| `description` | string | 更新说明，可为空。 |
|
||
| `updated_at_ms` | int64 | 后台版本配置更新时间，Unix epoch milliseconds。 |
|
||
| `server_time_ms` | int64 | gateway 返回时间，Unix epoch milliseconds。 |
|
||
|
||
## 错误码
|
||
|
||
| HTTP 状态码 | `code` | 触发条件 |
|
||
| --- | --- | --- |
|
||
| `400` | `INVALID_ARGUMENT` | `platform` 为空或不是 `android` / `ios`。 |
|
||
| `502` | `UPSTREAM_ERROR` | gateway 读取后台版本配置失败。 |
|
||
|
||
错误返回仍使用统一 envelope：
|
||
|
||
```json
|
||
{
|
||
"code": "INVALID_ARGUMENT",
|
||
"message": "platform is invalid",
|
||
"request_id": "req_abc"
|
||
}
|
||
```
|