89 lines
2.7 KiB
Markdown
89 lines
2.7 KiB
Markdown
# 客户端软件包
|
||
|
||
以下是客户端软件包相关接口的API文档。
|
||
|
||
## 查看最新版本
|
||
|
||
查询指定客户端（`identity`）的最新版本信息，若带 `canary=true` 且当前登录用户在灰度范围内，则查询范围覆盖灰度版，否则仅返回正式版。
|
||
|
||
- 请求地址：/client/software/latest
|
||
- 请求方式：GET
|
||
|
||
### 请求参数
|
||
|
||
| 参数名称 | 是否必传 | 类型 | 描述 |
|
||
|:-----|:-----|:-----|:-----|
|
||
| identity | 是 | String | 客户端标识，示例：devco |
|
||
| canary | 否 | Boolean | 传true则查询范围覆盖灰度版，否则只查正式版；不传等同于false |
|
||
|
||
### 请求示例
|
||
|
||
```bash
|
||
curl -X GET {gateway}/client/software/latest?identity=devco&canary=true
|
||
```
|
||
|
||
### 响应参数
|
||
|
||
| 参数名称 | 类型 | 描述 |
|
||
|:-----|:-----|:-----|
|
||
| code | Number | 返回码（200=成功） |
|
||
| msg | String | 提示信息 |
|
||
| data | Object | 版本信息；无匹配版本时为 null |
|
||
| data.releaseId | String | 版本记录 ID（Long 序列化为字符串） |
|
||
| data.versionNo | String | 版本号，如 1.0.0 |
|
||
| data.releaseTime | String | 发布时间，格式 yyyy-MM-dd HH:mm:ss（GMT+8） |
|
||
| data.releaseNotes | String | 更新内容 |
|
||
| data.packageOssId | String | 安装包 OSS 主键（Long 序列化为字符串）；前端据此请求预签名下载地址 |
|
||
| data.packageName | String | 安装包文件名 |
|
||
| data.packageSize | Number | 安装包大小（字节） |
|
||
| data.packageSizeDisplay | String | 安装包大小展示文案，如 12.50 MB |
|
||
| data.state | String | 版本状态：canary=灰度版、release=正式版 |
|
||
|
||
### 成功示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {
|
||
"releaseId": "1928374655647382",
|
||
"versionNo": "1.0.0",
|
||
"releaseTime": "2026-09-28 10:00:00",
|
||
"releaseNotes": "修复已知问题，优化启动速度",
|
||
"packageOssId": "1928374655647383",
|
||
"packageName": "devco-1.0.0-setup.exe",
|
||
"packageSize": 13107200,
|
||
"packageSizeDisplay": "12.50 MB",
|
||
"state": "release"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 无版本示例
|
||
|
||
查询范围内没有任何版本时，`data` 为 `null`：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 失败示例
|
||
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"msg": "错误信息"
|
||
}
|
||
```
|
||
|
||
### 备注
|
||
|
||
- 结果按 `releaseTime` 倒序取第一条，即为最新版本。
|
||
- 未登录（`LoginHelper.getLoginUser()` 为 null）时仅返回正式版，忽略 `canary`。
|
||
- `packageName`、`packageSize`、`packageSizeDisplay` 在数据库未记录安装包信息时，会尝试从 OSS 元数据补全；OSS 查询失败时保持为空，不影响接口返回。
|
||
- 下载安装包请调用 `GET /client/software/download/{ossId}`，其中 `ossId` 取 `data.packageOssId`。
|