core_wing_web/docs/API接口说明-固件管理.md

固件管理 API 接口文档

基本信息

• Base URL: http://localhost:8080
• 接口前缀: /firmware
• 请求头:
  • Accept-Language: zh_CN 或 en_US（可选，默认中文）

统一响应格式

所有接口返回格式统一为：

{
  "code": 200,
  "message": "操作成功",
  "data": {},
  "success": true
}

字段说明：

• code: 状态码（200-成功，500-失败）
• message: 提示消息（支持中英文国际化）
• data: 返回的数据
• success: 是否成功（true/false）

---

1. 根据ID查询固件

接口描述： 根据固件ID查询固件详细信息

请求方式： GET

请求路径： /firmware/{id}

路径参数：

参数名	类型	必填	说明
id	Long	是	固件ID

请求示例：

curl -X GET "http://localhost:8080/firmware/1" \
  -H "Accept-Language: zh_CN"

成功响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "firmwareName": "固件 v2.0.0",
    "firmwareSize": 2097152,
    "firmwareDescription": "新版本固件，优化性能",
    "firmwareType": "主控固件",
    "downloadUrl": "https://example.com/firmware/v2.0.0.bin",
    "createTime": "2025-01-15 10:30:00",
    "updateTime": "2025-01-15 10:30:00"
  },
  "success": true
}

失败响应示例：

{
  "code": 500,
  "message": "固件不存在",
  "data": null,
  "success": false
}

---

2. 分页查询固件列表

接口描述： 分页查询固件列表，支持按固件名称和固件类型筛选

请求方式： GET

请求路径： /firmware/page

请求参数（Query）：

参数名	类型	必填	默认值	说明
current	Long	否	1	当前页码
size	Long	否	10	每页大小
firmwareName	String	否	-	固件名称（模糊查询）
firmwareType	String	否	-	固件类型（精确查询）

请求示例：

# 查询第1页，每页10条
curl -X GET "http://localhost:8080/firmware/page?current=1&size=10" \
  -H "Accept-Language: zh_CN"

# 按固件名称模糊查询
curl -X GET "http://localhost:8080/firmware/page?current=1&size=10&firmwareName=v2"

# 按固件类型查询
curl -X GET "http://localhost:8080/firmware/page?current=1&size=10&firmwareType=主控固件"

# 组合查询
curl -X GET "http://localhost:8080/firmware/page?current=1&size=10&firmwareName=v2&firmwareType=主控固件"

成功响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "firmwareName": "固件 v2.0.0",
        "firmwareSize": 2097152,
        "firmwareDescription": "新版本固件，优化性能",
        "firmwareType": "主控固件",
        "downloadUrl": "https://example.com/firmware/v2.0.0.bin",
        "createTime": "2025-01-15 10:30:00",
        "updateTime": "2025-01-15 10:30:00"
      },
      {
        "id": 2,
        "firmwareName": "固件 v1.0.1",
        "firmwareSize": 1049600,
        "firmwareDescription": "修复了若干 bug 的版本",
        "firmwareType": "主控固件",
        "downloadUrl": "https://example.com/firmware/v1.0.1.bin",
        "createTime": "2025-01-14 09:20:00",
        "updateTime": "2025-01-14 09:20:00"
      }
    ],
    "total": 2,
    "size": 10,
    "current": 1,
    "pages": 1
  },
  "success": true
}

响应字段说明：

• records: 当前页的数据列表
• total: 总记录数
• size: 每页大小
• current: 当前页码
• pages: 总页数

---

3. 查询所有固件

接口描述： 查询所有固件列表（不分页）

请求方式： GET

请求路径： /firmware/list

请求示例：

curl -X GET "http://localhost:8080/firmware/list" \
  -H "Accept-Language: zh_CN"

成功响应示例：

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "firmwareName": "固件 v2.0.0",
      "firmwareSize": 2097152,
      "firmwareDescription": "新版本固件，优化性能",
      "firmwareType": "主控固件",
      "downloadUrl": "https://example.com/firmware/v2.0.0.bin",
      "createTime": "2025-01-15 10:30:00",
      "updateTime": "2025-01-15 10:30:00"
    },
    {
      "id": 2,
      "firmwareName": "固件 v1.0.1",
      "firmwareSize": 1049600,
      "firmwareDescription": "修复了若干 bug 的版本",
      "firmwareType": "主控固件",
      "downloadUrl": "https://example.com/firmware/v1.0.1.bin",
      "createTime": "2025-01-14 09:20:00",
      "updateTime": "2025-01-14 09:20:00"
    }
  ],
  "success": true
}

---

错误码说明

错误码	说明
200	请求成功
500	服务器内部错误

---

国际化支持

接口支持中英文双语，通过请求头 Accept-Language 或 lang 指定语言：

• zh_CN - 中文（默认）
• en_US - 英文

示例：

# 中文响应
curl -X GET "http://localhost:8080/firmware/1" \
  -H "Accept-Language: zh_CN"

# 英文响应
curl -X GET "http://localhost:8080/firmware/1" \
  -H "Accept-Language: en_US"

---

注意事项

1. 文件大小单位：firmwareSize 字段的单位是字节（Byte）
2. 时间格式：createTime 和 updateTime 的格式为 yyyy-MM-dd HH:mm:ss
3. 分页默认排序：分页查询默认按创建时间倒序排列（最新的在前面）
4. 模糊查询：分页查询中的 firmwareName 参数支持模糊匹配
5. 类型查询：分页查询中的 firmwareType 参数是精确匹配
6. 国际化：通过 Accept-Language 请求头可切换中英文响应消息