tmp/devco-client.md

客户端软件包

以下是客户端软件包相关接口的API文档。

查看最新版本

查询指定客户端（identity）的最新版本信息，若带 canary=true 且当前登录用户在灰度范围内，则查询范围覆盖灰度版，否则仅返回正式版。

• 请求地址：/client/software/latest
• 请求方式：GET

请求参数

参数名称	是否必传	类型	描述
identity	是	String	客户端标识，示例：devco
canary	否	Boolean	传true则查询范围覆盖灰度版，否则只查正式版；不传等同于false

请求示例

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=正式版

成功示例

{
    "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：

{
    "code": 200,
    "msg": "操作成功",
    "data": null
}

失败示例

{
    "code": 500,
    "msg": "错误信息"
}

备注

• 结果按 releaseTime 倒序取第一条，即为最新版本。
• 未登录（LoginHelper.getLoginUser() 为 null）时仅返回正式版，忽略 canary。
• packageName、packageSize、packageSizeDisplay 在数据库未记录安装包信息时，会尝试从 OSS 元数据补全；OSS 查询失败时保持为空，不影响接口返回。
• 下载安装包请调用 GET /client/software/download/{ossId}，其中 ossId 取 data.packageOssId。