hailin
/
rwadurian
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
rwadurian/frontend/mobile-upgrade/docs/API.md

8.1 KiB
Raw Permalink Blame History

Mobile Upgrade Admin - API 文档

概述

本文档描述 Mobile Upgrade Admin 前端与 Admin Service 后端的 API 交互。

基础配置

环境变量

# .env.local
NEXT_PUBLIC_API_URL=http://localhost:3000

API 客户端配置

// src/infrastructure/http/api-client.ts
export const apiClient = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3000',
  timeout: 30000,
  headers: {
    'Content-Type': 'application/json',
  },
})

API 端点

版本管理 API

Base URL: /api/v1/versions

1. 获取版本列表

端点: GET /api/v1/versions

查询参数:

参数 类型 必填 说明
platform string 否 平台筛选：android 或 ios
includeDisabled boolean 否 是否包含已禁用版本，默认 true

请求示例:

// 获取所有版本
const response = await apiClient.get('/api/v1/versions')

// 获取 Android 版本
const response = await apiClient.get('/api/v1/versions?platform=android')

// 只获取已启用版本
const response = await apiClient.get('/api/v1/versions?includeDisabled=false')

响应示例:

[
  {
    "id": "uuid-1234",
    "platform": "android",
    "versionCode": 100,
    "versionName": "1.0.0",
    "buildNumber": "100",
    "downloadUrl": "https://example.com/app-1.0.0.apk",
    "fileSize": "52428800",
    "fileSha256": "abc123...",
    "changelog": "1. 新增功能A\n2. 修复问题B",
    "isForceUpdate": false,
    "isEnabled": true,
    "minOsVersion": "8.0",
    "releaseDate": "2024-01-01T00:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]

2. 获取单个版本

端点: GET /api/v1/versions/:id

路径参数:

参数 类型 说明
id string 版本 ID (UUID)

请求示例:

const response = await apiClient.get('/api/v1/versions/uuid-1234')

响应: 单个 AppVersion 对象

3. 创建版本

端点: POST /api/v1/versions

请求体:

interface CreateVersionInput {
  platform: 'android' | 'ios'
  versionCode: number
  versionName: string
  buildNumber: string
  downloadUrl: string
  fileSize: string
  fileSha256: string
  changelog: string
  isForceUpdate: boolean
  minOsVersion?: string
  releaseDate?: string
}

请求示例:

const response = await apiClient.post('/api/v1/versions', {
  platform: 'android',
  versionCode: 101,
  versionName: '1.0.1',
  buildNumber: '101',
  downloadUrl: 'https://example.com/app-1.0.1.apk',
  fileSize: '52428800',
  fileSha256: 'sha256hash...',
  changelog: '修复已知问题',
  isForceUpdate: false,
  minOsVersion: '8.0'
})

响应: 创建的 AppVersion 对象

4. 更新版本

端点: PUT /api/v1/versions/:id

请求体:

interface UpdateVersionInput {
  downloadUrl?: string
  fileSize?: string
  fileSha256?: string
  changelog?: string
  isForceUpdate?: boolean
  isEnabled?: boolean
  minOsVersion?: string | null
  releaseDate?: string | null
}

请求示例:

const response = await apiClient.put('/api/v1/versions/uuid-1234', {
  changelog: '更新的更新日志',
  isForceUpdate: true
})

响应: 更新后的 AppVersion 对象

5. 删除版本

端点: DELETE /api/v1/versions/:id

请求示例:

await apiClient.delete('/api/v1/versions/uuid-1234')

响应: 无内容 (204)

6. 切换版本状态

端点: PATCH /api/v1/versions/:id/toggle

请求体:

{
  "isEnabled": true
}

请求示例:

await apiClient.patch('/api/v1/versions/uuid-1234/toggle', {
  isEnabled: false
})

响应: 无内容 (204)

7. 上传版本文件

端点: POST /api/v1/versions/upload

请求类型: multipart/form-data

表单字段:

字段 类型 必填 说明
file File 是 APK 或 IPA 文件
platform string 是 android 或 ios
versionName string 是 版本号，如 1.0.0
buildNumber string 是 构建号，如 100
changelog string 否 更新日志
isForceUpdate boolean 否 是否强制更新，默认 false
minOsVersion string 否 最低系统版本
releaseDate string 否 发布日期 (ISO 8601)

请求示例:

const formData = new FormData()
formData.append('file', file)
formData.append('platform', 'android')
formData.append('versionName', '1.0.0')
formData.append('buildNumber', '100')
formData.append('changelog', '首次发布')
formData.append('isForceUpdate', 'false')

const response = await apiClient.post('/api/v1/versions/upload', formData, {
  headers: {
    'Content-Type': 'multipart/form-data',
  },
  timeout: 300000, // 5分钟超时，适用于大文件
})

响应: 创建的 AppVersion 对象

移动端检查更新 API

检查版本更新

端点: GET /api/app/version/check

注意：此端点不使用 /api/v1 前缀

查询参数:

参数 类型 必填 说明
platform string 是 android 或 ios
currentVersion string 是 当前版本号，如 1.0.0
currentBuild string 否 当前构建号

请求示例:

GET /api/app/version/check?platform=android&currentVersion=1.0.0&currentBuild=100

响应示例:

{
  "hasUpdate": true,
  "isForceUpdate": false,
  "latestVersion": {
    "versionName": "1.1.0",
    "buildNumber": "110",
    "downloadUrl": "https://example.com/app-1.1.0.apk",
    "fileSize": "55000000",
    "changelog": "1. 新功能\n2. 性能优化",
    "minOsVersion": "8.0"
  }
}

错误处理

错误响应格式

{
  "statusCode": 400,
  "message": "错误描述",
  "error": "Bad Request"
}

常见错误码

状态码 说明
400 请求参数错误
404 资源不存在
409 资源冲突（如版本已存在）
413 文件过大
500 服务器内部错误

前端错误处理

// API 客户端拦截器
apiClient.interceptors.response.use(
  (response) => response,
  (error) => {
    const message = error.response?.data?.message || '请求失败'
    return Promise.reject(new Error(message))
  }
)

// 组件中使用
try {
  await deleteVersion(id)
  toast.success('删除成功')
} catch (err) {
  toast.error(err.message || '操作失败')
}

数据类型定义

AppVersion

interface AppVersion {
  id: string                    // UUID
  platform: 'android' | 'ios'   // 平台
  versionCode: number           // 版本代码（用于比较）
  versionName: string           // 版本名称（显示用）
  buildNumber: string           // 构建号
  downloadUrl: string           // 下载地址
  fileSize: string              // 文件大小（字节）
  fileSha256: string            // 文件 SHA256 校验值
  changelog: string             // 更新日志
  isForceUpdate: boolean        // 是否强制更新
  isEnabled: boolean            // 是否启用
  minOsVersion: string | null   // 最低系统版本要求
  releaseDate: string | null    // 发布日期
  createdAt: string             // 创建时间
  updatedAt: string             // 更新时间
}

VersionListFilter

interface VersionListFilter {
  platform?: 'android' | 'ios'
  includeDisabled?: boolean
}

相关文档