219 lines
5.7 KiB
Plaintext
219 lines
5.7 KiB
Plaintext
# 版本检查接口集成说明
|
||
|
||
## 📋 接口信息
|
||
|
||
### 接口地址
|
||
```
|
||
GET /api/common/checkAppVersion
|
||
```
|
||
|
||
### 请求参数
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| version | String | 是 | 当前应用版本名称 (如: "1.0.3") |
|
||
| versionCode | String | 是 | 当前应用版本代码 (如: "3") |
|
||
| platform | String | 是 | 平台标识: 1=苹果, 2=安卓 |
|
||
|
||
### 请求示例
|
||
```
|
||
GET /api/common/checkAppVersion?version=1.0.3&versionCode=3&platform=2
|
||
```
|
||
|
||
## 📤 响应格式
|
||
|
||
### 成功响应
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"hasUpdate": true,
|
||
"version": "1.0.4",
|
||
"content": "1. 朋友圈增加评论回复、删除功能;\n2. 新增本机号码一键登录功能;\n3. 朋友圈列表展示当前位置;\n4. 修复已知bug,优化用户体验",
|
||
"downloadUrl": "https://example.com/app-release.apk",
|
||
"forceUpdate": false,
|
||
"minVersion": "1.0.0"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 响应字段说明
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| hasUpdate | Boolean | 是否有新版本 |
|
||
| version | String | 最新版本号 |
|
||
| content | String | 更新内容说明 |
|
||
| downloadUrl | String | 下载链接 |
|
||
| forceUpdate | Boolean | 是否强制更新 |
|
||
| minVersion | String | 最低支持版本 |
|
||
|
||
### 无更新响应
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"hasUpdate": false,
|
||
"version": "1.0.3",
|
||
"content": "",
|
||
"downloadUrl": "",
|
||
"forceUpdate": false,
|
||
"minVersion": "1.0.0"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🔧 客户端集成
|
||
|
||
### 1. 版本检查逻辑
|
||
```java
|
||
// 在VersionUpdateManager中调用
|
||
private void checkVersionFromServer(String currentVersion, int currentVersionCode) {
|
||
HashMap<String, String> params = new HashMap<>();
|
||
params.put("version", currentVersion);
|
||
params.put("versionCode", String.valueOf(currentVersionCode));
|
||
params.put("platform", "2"); // 平台: 1=苹果, 2=安卓
|
||
|
||
OKHttpHelper.get("/api/common/checkAppVersion", params, headers, new SimpleCallback<String>() {
|
||
@Override
|
||
public void onUiSuccess(String response) {
|
||
// 解析响应并显示更新弹窗
|
||
}
|
||
|
||
@Override
|
||
public void onUiFailure(int code, String msg) {
|
||
// 处理网络错误
|
||
}
|
||
});
|
||
}
|
||
```
|
||
|
||
### 2. 弹窗显示逻辑
|
||
```java
|
||
// 根据服务器响应决定是否显示更新弹窗
|
||
if (hasUpdate && !TextUtils.isEmpty(latestVersion)) {
|
||
showUpdateDialog(latestVersion, updateContent);
|
||
} else {
|
||
Log.d(TAG, "当前已是最新版本，无需更新");
|
||
}
|
||
```
|
||
|
||
## 📱 用户体验
|
||
|
||
### 1. 更新流程
|
||
1. **自动检查**: 应用启动3秒后自动检查版本
|
||
2. **弹窗显示**: 发现新版本时显示更新弹窗
|
||
3. **用户选择**: 用户点击"立即更新"按钮
|
||
4. **跳转更新**: 跳转到应用商店或下载页面
|
||
|
||
### 2. 更新策略
|
||
- **可选更新**: `forceUpdate = false`，用户可以选择稍后更新
|
||
- **强制更新**: `forceUpdate = true`，用户必须更新才能继续使用
|
||
- **最低版本**: 检查当前版本是否低于最低支持版本
|
||
|
||
## 🚀 服务器端实现建议
|
||
|
||
### 1. 版本比较逻辑
|
||
```java
|
||
// 服务器端版本比较示例
|
||
public boolean shouldUpdate(String currentVersion, String latestVersion) {
|
||
// 使用语义化版本比较
|
||
return compareVersions(currentVersion, latestVersion) < 0;
|
||
}
|
||
```
|
||
|
||
### 2. 数据库设计
|
||
```sql
|
||
-- 版本信息表
|
||
CREATE TABLE app_versions (
|
||
id INT PRIMARY KEY AUTO_INCREMENT,
|
||
version VARCHAR(20) NOT NULL,
|
||
version_code INT NOT NULL,
|
||
content TEXT,
|
||
download_url VARCHAR(500),
|
||
force_update BOOLEAN DEFAULT FALSE,
|
||
min_version VARCHAR(20),
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
|
||
);
|
||
```
|
||
|
||
### 3. 接口实现示例
|
||
```java
|
||
@GetMapping("/api/common/checkAppVersion")
|
||
public ResponseEntity<VersionCheckResponse> checkAppVersion(
|
||
@RequestParam String version,
|
||
@RequestParam String versionCode) {
|
||
|
||
// 查询最新版本信息
|
||
AppVersion latestVersion = versionService.getLatestVersion();
|
||
|
||
// 比较版本
|
||
boolean hasUpdate = versionService.shouldUpdate(version, latestVersion.getVersion());
|
||
|
||
// 构建响应
|
||
VersionCheckResponse response = new VersionCheckResponse();
|
||
response.setHasUpdate(hasUpdate);
|
||
response.setVersion(latestVersion.getVersion());
|
||
response.setContent(latestVersion.getContent());
|
||
response.setDownloadUrl(latestVersion.getDownloadUrl());
|
||
response.setForceUpdate(latestVersion.isForceUpdate());
|
||
|
||
return ResponseEntity.ok(response);
|
||
}
|
||
```
|
||
|
||
## 🔍 测试验证
|
||
|
||
### 1. 接口测试
|
||
```bash
|
||
# 测试版本检查接口
|
||
curl "http://localhost:8080/api/common/checkAppVersion?version=1.0.3&versionCode=3&platform=2"
|
||
```
|
||
|
||
### 2. 客户端测试
|
||
- [ ] 网络正常时版本检查
|
||
- [ ] 网络异常时错误处理
|
||
- [ ] 有更新时弹窗显示
|
||
- [ ] 无更新时不显示弹窗
|
||
- [ ] 强制更新逻辑
|
||
|
||
### 3. 边界情况
|
||
- [ ] 版本号格式异常
|
||
- [ ] 服务器返回数据异常
|
||
- [ ] 网络超时处理
|
||
- [ ] 应用在后台时的处理
|
||
|
||
## 📊 监控统计
|
||
|
||
### 1. 版本分布统计
|
||
- 各版本用户数量
|
||
- 更新成功率
|
||
- 更新失败原因分析
|
||
|
||
### 2. 性能监控
|
||
- 接口响应时间
|
||
- 错误率统计
|
||
- 用户行为分析
|
||
|
||
## 🎯 优化建议
|
||
|
||
### 1. 缓存策略
|
||
- 客户端缓存版本检查结果
|
||
- 避免频繁请求服务器
|
||
- 设置合理的缓存时间
|
||
|
||
### 2. 用户体验
|
||
- 支持增量更新
|
||
- 添加更新进度显示
|
||
- 支持后台下载
|
||
|
||
### 3. 安全考虑
|
||
- 验证下载链接安全性
|
||
- 防止恶意更新
|
||
- 签名验证
|
||
|
||
---
|
||
|
||
**注意**: 请确保服务器端接口 `/api/common/checkAppVersion` 已正确实现，并返回符合上述格式的JSON响应。
|