API 调用示例 - 云端版本管理系统

1. 检查更新

检查指定软件是否有新版本可用（支持通过名称或ID查询）

GET /api/v1/check-update

请求参数

参数名	类型	必填	说明
方式一：通过名称查询（推荐）
product	string	是	产品名称（支持中文）
software	string	是	软件名称（支持中文）
current_version	string	是	当前版本号（如：1.0.0）
方式二：通过配对ID查询
product_id	number	是	产品ID
software_id	number	是	软件ID
current_version	string	是	当前版本号（如：1.0.0）

cURL

Python

JavaScript

# 检查更新（通过名称）
curl "http://localhost:10008/api/v1/check-update?product=openwrt&software=pcie_app¤t_version=1.0.0"

# 检查更新（通过配对ID）
curl "http://localhost:10008/api/v1/check-update?product_id=2&software_id=5¤t_version=1.0.0"
                

import requests

# 检查更新（通过名称）
def check_update(product, software, current_version):
    url = f"http://localhost:10008/api/v1/check-update"
    params = {
        "product": product,
        "software": software,
        "current_version": current_version
    }

    response = requests.get(url, params=params)
    return response.json()

# 检查更新（通过配对ID）
def check_update_by_id(product_id, software_id, current_version):
    url = f"http://localhost:10008/api/v1/check-update"
    params = {
        "product_id": product_id,
        "software_id": software_id,
        "current_version": current_version
    }

    response = requests.get(url, params=params)
    return response.json()

# 使用示例
result = check_update("openwrt", "pcie_app", "1.0.0")
print(result)

result_id = check_update_by_id(2, 5, "1.0.0")
print(result_id)
                

// 检查更新（通过名称）
async function checkUpdate(product, software, currentVersion) {
    const url = new URL('http://localhost:10008/api/v1/check-update');
    url.searchParams.append('product', product);
    url.searchParams.append('software', software);
    url.searchParams.append('current_version', currentVersion);

    const response = await fetch(url);
    return response.json();
}

// 检查更新（通过配对ID）
async function checkUpdateById(productId, softwareId, currentVersion) {
    const url = new URL('http://localhost:10008/api/v1/check-update');
    url.searchParams.append('product_id', productId);
    url.searchParams.append('software_id', softwareId);
    url.searchParams.append('current_version', currentVersion);

    const response = await fetch(url);
    return response.json();
}

// 使用示例
checkUpdate('openwrt', 'pcie_app', '1.0.0').then(result => {
    console.log(result);
});

checkUpdateById('2', '5', '1.0.0').then(result => {
    console.log(result);
});
                

在线测试

查询方式：

产品名称：

软件名称：

当前版本：

2. 获取版本历史

获取指定软件的所有版本列表（公开API，无需认证，支持多种查询方式）

推荐：使用根查询接口 GET /api/v1/versions 配合查询参数，URL 更简洁，兼容性更好。

GET /api/v1/versions

查询参数（推荐方式）

参数名	类型	必填	说明
方式一：通过配对ID查询（推荐）
product_id	number	是	产品ID
software_id	number	是	软件ID
方式二：通过名称查询
product	string	是	产品名称
software	string	是	软件名称

GET /api/v1/versions/:productName/:softwareName

路径参数（兼容旧版）

参数名	类型	必填	说明
方式一：通过名称查询（推荐）
productName	string	是	产品名称（支持中文，需要URL编码）
softwareName	string	是	软件名称（支持中文，需要URL编码）
方式二：通过配对ID路径
productId	number	是	访问路径：`/api/v1/versions/id/:productId/:softwareId`
softwareId	number	是	软件ID

cURL

Python

JavaScript

# 方式一：根查询接口（推荐）
curl "http://localhost:10008/api/v1/versions?product_id=2&software_id=5"
curl "http://localhost:10008/api/v1/versions?product=openwrt&software=pcie_app"

# 方式二：通过名称路径
curl "http://localhost:10008/api/v1/versions/openwrt/pcie_app"

# 方式三：通过配对ID路径
curl "http://localhost:10008/api/v1/versions/id/2/5"
                

import requests

# 方式一：根查询接口（推荐）
def get_versions_by_ids(product_id, software_id):
    url = f"http://localhost:10008/api/v1/versions"
    params = {
        "product_id": product_id,
        "software_id": software_id
    }
    response = requests.get(url, params=params)
    return response.json()

# 方式二：通过名称路径
def get_versions_by_name(product, software):
    url = f"http://localhost:10008/api/v1/versions/{product}/{software}"
    response = requests.get(url)
    return response.json()

# 使用示例
versions = get_versions_by_ids(2, 5)
print(versions)
                

// 方式一：根查询接口（推荐）
async function getVersionsByIds(productId, softwareId) {
    const url = new URL('http://localhost:10008/api/v1/versions');
    url.searchParams.append('product_id', productId);
    url.searchParams.append('software_id', softwareId);
    const response = await fetch(url);
    return response.json();
}

// 方式二：通过名称路径
async function getVersions(product, software) {
    const response = await fetch(`http://localhost:10008/api/v1/versions/${product}/${software}`);
    return response.json();
}

// 使用示例
getVersionsByIds('2', '5').then(versions => {
    console.log(versions);
});
                

在线测试

查询方式：

产品名称：

软件名称：

3. 下载版本文件

下载指定软件版本的文件（支持名称或ID查询）

GET /api/v1/download/:productName/:softwareName/:version

路径参数

参数名	类型	必填	说明
方式一：通过名称下载
productName	string	是	产品名称（支持中文，需要URL编码）
softwareName	string	是	软件名称（支持中文，需要URL编码）
version	string	是	版本号（如：1.0.0）
方式二：通过配对ID下载（推荐）
productId	number	是	产品ID 访问路径：`/api/v1/download/id/:productId/:softwareId/:version`
softwareId	number	是	软件ID
version	string	是	版本号（如：1.0.0）

设计说明：

通过ID下载时需要同时提供 productId 和 softwareId，确保软件归属关系明确
通过名称下载时需要同时提供产品和软件名称，因为软件名称只在产品范围内唯一
ID方式更适合程序化调用，名称方式更直观易记

注意： 此接口直接返回文件流，浏览器会自动下载文件。

cURL

Python

JavaScript

# 下载文件（通过名称）
curl -O "http://localhost:10008/api/v1/download/openwrt/pcie_app/1.0.0"

# 下载文件（通过配对ID）
curl -O "http://localhost:10008/api/v1/download/id/2/5/1.0.0"
                

import requests

# 下载文件（通过名称）
def download_version_by_name(product, software, version, save_path):
    url = f"http://localhost:10008/api/v1/download/{product}/{software}/{version}"
    response = requests.get(url)

    with open(save_path, 'wb') as f:
        f.write(response.content)

    print(f"文件已保存到: {save_path}")

# 使用示例
download_version_by_name("openwrt", "pcie_app", "1.0.0", "update.zip")
                

// 下载文件（浏览器环境）
function downloadVersion(product, software, version) {
    const url = `http://localhost:10008/api/v1/download/${product}/${software}/${version}`;
    window.location.href = url;
}

// 使用示例
downloadVersion('openwrt', 'pcie_app', '1.0.0');
                

在线测试

查询方式：

产品名称：

软件名称：

版本号：

4. Python 客户端完整示例

自动检查更新并下载的 Python 客户端程序

import requests
import os
import sys

class UpdateClient:
    def __init__(self, base_url, product_id, software_id):
        self.base_url = base_url
        self.product_id = product_id
        self.software_id = software_id

    def check_update(self, current_version):
        """检查是否有新版本"""
        url = f"{self.base_url}/api/v1/check-update"
        params = {
            "product_id": self.product_id,
            "software_id": self.software_id,
            "current_version": current_version
        }

        try:
            response = requests.get(url, params=params)
            result = response.json()

            if result.get('success') and result.get('has_update'):
                return result['latest_version']
            return None
        except Exception as e:
            print(f"检查更新失败: {e}")
            return None

    def download_update(self, version, save_path):
        """下载指定版本"""
        url = f"{self.base_url}/api/v1/download/id/{self.product_id}/{self.software_id}/{version}"

        try:
            response = requests.get(url, stream=True)
            response.raise_for_status()

            with open(save_path, 'wb') as f:
                for chunk in response.iter_content(chunk_size=8192):
                    f.write(chunk)

            print(f"下载完成: {save_path}")
            return True
        except Exception as e:
            print(f"下载失败: {e}")
            return False

# 使用示例
if __name__ == "__main__":
    # 配置
    BASE_URL = "http://localhost:10008"
    PRODUCT_ID = 1
    SOFTWARE_ID = 1
    CURRENT_VERSION = "1.0.0"

    # 创建客户端
    client = UpdateClient(BASE_URL, PRODUCT_ID, SOFTWARE_ID)

    # 检查更新
    print(f"当前版本: {CURRENT_VERSION}")
    print("正在检查更新...")

    new_version = client.check_update(CURRENT_VERSION)

    if new_version:
        print(f"发现新版本: {new_version['version']}")
        print(f"发布说明: {new_version['release_notes']}")

        if new_version.get('force_update'):
            print("⚠️  此版本需要强制更新！")

        # 下载更新
        save_path = f"update_{new_version['version']}.zip"
        if client.download_update(new_version['version'], save_path):
            print("✓ 更新已下载，请手动安装")
    else:
        print("✓ 已是最新版本")
            

提示： 将此代码保存为 update_client.py，修改配置参数后即可使用。