96 lines
3.6 KiB
Markdown
96 lines
3.6 KiB
Markdown
# 小程序接口与 WebView 版本一致性方案
|
|
|
|
## 目标
|
|
- 小程序获取接口地址与 WebView 地址。
|
|
- 判断版本一致性与可用性。
|
|
- 不可用时提示用户退出小程序重新打开。
|
|
|
|
## 总体思路
|
|
采用“配置中心 + 启动校验 + 缓存兜底 + 失效提示”的方案：
|
|
1. 小程序启动时请求配置中心接口获取最新配置。
|
|
2. 校验小程序版本、API版本、WebView版本一致性。
|
|
3. 校验失败则提示退出重启；通过则写入缓存并使用配置。
|
|
4. 配置接口不可用时使用缓存，缓存失效则提示退出重启。
|
|
|
|
## 配置中心接口
|
|
- 方法: `GET`
|
|
- 路径: `/api/open/app/config`
|
|
|
|
### 返回示例
|
|
```json
|
|
{
|
|
"app": {
|
|
"minVersion": "1.2.0",
|
|
"latestVersion": "1.3.5",
|
|
"forceUpdate": true
|
|
},
|
|
"api": {
|
|
"baseUrl": "https://api.xxx.com",
|
|
"version": "2026-03-16",
|
|
"minClientVersion": "1.2.0"
|
|
},
|
|
"webview": {
|
|
"baseUrl": "https://m.xxx.com",
|
|
"version": "2026-03-16",
|
|
"minClientVersion": "1.2.0"
|
|
},
|
|
"ttlSeconds": 3600,
|
|
"disabled": false,
|
|
"disableReason": ""
|
|
}
|
|
```
|
|
|
|
### 字段说明
|
|
- `app.minVersion`: 最低可用小程序版本。
|
|
- `app.latestVersion`: 最新版本号。
|
|
- `app.forceUpdate`: 是否强制更新。
|
|
- `api.baseUrl`: API 入口地址。
|
|
- `api.version`: API 版本号（用于一致性校验）。
|
|
- `api.minClientVersion`: API 允许的最小客户端版本。
|
|
- `webview.baseUrl`: WebView 入口地址。
|
|
- `webview.version`: WebView 版本号（用于一致性校验）。
|
|
- `webview.minClientVersion`: WebView 允许的最小客户端版本。
|
|
- `ttlSeconds`: 配置缓存有效期（秒）。
|
|
- `disabled`: 服务下线开关。
|
|
- `disableReason`: 下线原因。
|
|
|
|
## 小程序启动校验流程
|
|
1. 小程序 `App.onLaunch` 请求 `/api/open/app/config`。
|
|
2. 校验顺序：
|
|
- `disabled == true` → 提示“服务暂不可用，请退出小程序重新打开”。
|
|
- `当前版本 < app.minVersion` → 提示强更并阻断。
|
|
- `api.version != webview.version` → 提示“版本不一致，请退出小程序重新打开”。
|
|
- `当前版本 < api.minClientVersion` 或 `当前版本 < webview.minClientVersion` → 提示强更。
|
|
3. 校验通过：
|
|
- 缓存配置（本地 `storage`）。
|
|
- 全局设置 API baseUrl 与 WebView baseUrl。
|
|
|
|
## 缓存与兜底策略
|
|
- 配置接口失败：
|
|
- 如果本地缓存存在且未过期 → 使用缓存。
|
|
- 若缓存过期或不存在 → 提示“配置获取失败，请退出小程序重新打开”。
|
|
|
|
## 提示文案建议
|
|
- 版本不一致：
|
|
- “当前版本不一致，请退出小程序并重新打开以获取最新配置。”
|
|
- 服务不可用：
|
|
- “服务暂不可用，请退出小程序重新打开。”
|
|
- 配置获取失败：
|
|
- “配置获取失败，请退出小程序重新打开。”
|
|
|
|
## WebView 入口处理
|
|
- WebView URL 必须由配置中心下发，避免在客户端写死。
|
|
- 进入 WebView 前再次校验缓存是否过期；过期则重新拉取。
|
|
|
|
## 前端需要完成的部分
|
|
1. 在 `App.onLaunch` 拉取 `/api/open/app/config`，并写入本地缓存。
|
|
2. 实现版本校验逻辑（`app.minVersion`、`api.version`、`webview.version`、`minClientVersion`）。
|
|
3. 校验失败时弹窗提示，并引导退出小程序重新打开。
|
|
4. 缓存过期或接口失败时，优先使用缓存；无缓存则提示退出。
|
|
5. WebView 入口统一从配置下发的 `webview.baseUrl` 拼接跳转。
|
|
6. 请求 API 时统一使用配置下发的 `api.baseUrl`。
|
|
|
|
## 可选扩展
|
|
- 灰度策略：按用户或设备下发不同配置。
|
|
- 公告字段：返回 `notice` 用于维护提示。
|