GET/api/v1/app/updates
匿名,需App公共头,正式HTTPS及JWEJSON 响应接入指南 ↗

检查App版本升级

请求参数

登录前即可调用,八项公共请求头全部必填,X-Client-Type为app,平台android/ios。版本来源是安装包,渠道使用九渠道约定。无路径、查询参数或业务正文,不另传版本号。无需Bearer;主动携带时仍校验。

使用X-Channel、X-Platform、X-App-Version和X-App-Build判断升级,Accept-Language选择更新说明。未知或未传语言回退英文。正式必须HTTPS与AES/JWE,加密GET信封置于X-Budyoo-JWE;当前固定码dev保留明文兼容。响应no-store,不按安装ID或账号个性化推荐。

请求示例

base_url='https://api.budyoo.cn' # 当前dev;生产使用HTTPS和JWE
curl --fail-with-body "$base_url/api/v1/app/updates" \
  -H 'Accept: application/json' -H 'Accept-Language: zh-CN' \
  -H 'X-Client-Type: app' -H 'X-Platform: android' \
  -H 'X-App-Version: 1.0.0' -H 'X-App-Build: 100' \
  -H 'X-Channel: xiaomi' \
  -H 'X-Device-Id: 4d4ae3ea-6a4a-4f34-a292-8e94551851d7' \
  -H "X-Request-Id: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "X-Request-Timestamp: $(date +%s)000"

成功响应

HTTP200。以下为合成的已发布目标示例,不代表已存在实际可下载版本:

{
  "code": "SUCCESS",
  "message": "操作成功。",
  "data": {
    "channel": "xiaomi", "platform": "android", "currentVersion": "1.0.0", "currentBuild": 100,
    "language": "zh-CN", "channelSupported": true, "updateAvailable": true, "updateRequired": false,
    "latest": {
      "id": "11111111-1111-4111-8111-111111111111", "versionName": "1.4.0", "buildNumber": 140,
      "minimumVersion": "1.0.0", "packageSizeBytes": 25165824,
      "downloadUrl": "https://downloads.example.test/budyoo-1.4.0.apk", "releaseNotes": "修复已知问题"
    }
  },
  "errors": []
}
data字段 类型 可空 说明
channel/platform/currentVersion string 否 本次请求的发行渠道、平台及已安装版本
currentBuild integer(int64) 否 本次已安装构建号
language string 否 更新说明实际语言zh-CN/en/ja/ko
channelSupported boolean 否 是否九渠道之一;dev等未知渠道返回false,不套其他渠道的版本
updateAvailable boolean 否 存在同渠道发布中版本,且目标构建更大、目标展示版本不低于已安装版本
updateRequired boolean 否 有可升级目标,且目标配置forceUpdate=true或当前版本低于minimumVersion
latest object 是 仅updateAvailable=true时返回;否则为null
latest.id string(UUID) 否 发布记录编号
latest.versionName/minimumVersion string 否 新版本及最低支持版本
latest.buildNumber integer(int64) 否 目标构建号
latest.packageSizeBytes integer(int64) 否 管理员声明包大小,单位字节
latest.downloadUrl string 否 公开HTTPS安装包或商店页面地址
latest.releaseNotes string 否 当前语言纯文本更新说明

无当前发布、只有停用/迁移保留的未生效历史或没有更高版本时,updateAvailable=false、updateRequired=false、latest=null。不自动恢复被替换或停用的旧发布。版本数字逐段比较(1.10.0大于1.9.0),客户端版本后缀不参与数值比较;同展示版本更高构建可以更新,更高已安装构建或展示版本不建议降级。

管理端改为创建即发布;本App接口的方法、路径、请求头、响应字段和强更判断均保持不变。App无需处理后台状态或增加发布请求,原升级检查、弹窗及下载/商店跳转继续使用。新版API与管理网页配套发布后生效,旧测试内容不会由迁移自动发布。

失败响应

HTTP code 原因
400 INVALID_CLIENT_HEADERS 公共头缺失、重复或格式非法
400 INVALID_APP_VERSION 已知渠道与平台不符,例如app_store配android
401 UNAUTHORIZED 主动携带无效Bearer
403 FORBIDDEN 非App调用端
426 HTTPS_REQUIRED 当前环境不允许HTTP
503 SERVICE_UNAVAILABLE 数据库或Redis不可用

正式缺少JWE及加密错误按公共协议处理;错误码固定,message四语。示例:

{"code":"INVALID_APP_VERSION","message":"版本字段、发行渠道或下载地址不合法。","data":null,"errors":[]}

接入说明

启动或回到前台可按客户端策略查询,避免频繁轮询。推荐更新允许稍后处理;强制更新由App使用本响应展示,本接口不拦截全部业务API、不改变登录/注册/VIP状态。Flutter已接入升级查询、弹窗及商店跳转;本次管理端创建即发布不需要修改这些App流程,真实安装升级仍需单独验收。

客户端仅使用经HTTPS及JWE认证的响应,不能跳过证书验证;下载或跳商店遵循平台规则。服务端不验证安装包签名、文件摘要或URL可达性,包大小为管理员声明;目前不提供包上传、下载代理、灰度或商店自动发布。

本次381项服务器Java回归通过,包含创建后立即可查询、停用/跨渠道隔离、构建及数值版本比较、最低支持版本与强制更新、四语/英文回退、公共头、渠道平台边界及双向JWE;已断言App响应字段集合保持。创建即发布已与新版后台及V18配套上线;九个渠道真实查询仍均无更新,原九条占位记录仅迁移为未生效历史,未发布测试目标。真实创建/替换/停用闭环在隔离数据库与浏览器加密夹具中验证,不向联调客户端下发占位包。