hyapp-server/docs/flutter对接/版本强更接口App对接.md

版本强更接口 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 处理，会导致已配置版本都被判定为有更新。

请求示例：

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

成功返回

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

{
  "code": "INVALID_ARGUMENT",
  "message": "platform is invalid",
  "request_id": "req_abc"
}