YunStack-IoT 文档

Appearance

API 接口规范 ​

通用约定 ​

请求前缀 ​

所有 API 以 /api/v1 为前缀。

统一响应格式 ​

json
{
  "code": "00000",
  "msg": "Success",
  "data": {}
}
字段类型说明
codestring状态码，00000 表示成功
msgstring提示信息
dataobject/array响应数据

分页响应 ​

json
{
  "code": "00000",
  "msg": "Success",
  "data": { "list": [], "total": 100 },
  "page": { "pageNum": 1, "pageSize": 10, "total": 100 }
}

认证 ​

  • 使用 JWT Bearer Token
  • 请求头：Authorization: Bearer <token>
  • 公开接口无需认证

认证模块 /api/v1/auth ​

方法路径认证说明
GET/auth/captcha无获取图形验证码
POST/auth/register无用户注册
POST/auth/login无账号密码登录
POST/auth/wx/miniapp/code-login无微信小程序 code 登录
POST/auth/wx/miniapp/phone-login无微信手机号登录
DELETE/auth/logoutJWT登出
POST/auth/refresh-token无刷新 Token

登录 ​

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "123456",
  "captchaId": "uuid",
  "captchaCode": "abcd"
}

Response:
{
  "code": "00000",
  "msg": "Success",
  "data": {
    "accessToken": "eyJhbG...",
    "refreshToken": "eyJhbG..."
  }
}

微信小程序登录 ​

POST /api/v1/auth/wx/miniapp/code-login

{ "code": "wx_login_code" }

Response: { "code": "00000", "data": { "accessToken": "...", "refreshToken": "..." } }

用户管理 /api/v1/users ​

所有接口需 JWT 认证

方法路径角色说明
GET/users/me任意获取当前用户信息
PUT/users/profile任意更新个人资料
PUT/users/password任意修改密码
GET/users任意用户列表（分页）
POST/usersadmin创建用户
GET/users/:id/form任意获取用户详情
PUT/users/:idadmin更新用户
DELETE/users/:idsadmin批量删除用户
PATCH/users/:id/statusadmin启用/禁用用户
PATCH/users/:id/password/resetadmin重置密码

角色管理 /api/v1/roles ​

所有接口需 JWT 认证

方法路径角色说明
GET/roles/options任意角色选项列表
POST/rolesadmin创建角色
GET/roles任意角色列表（分页）
GET/roles/:id/form任意角色详情
PUT/roles/:idadmin更新角色
DELETE/roles/:idadmin删除角色

文件管理 /api/v1/files ​

所有接口需 JWT 认证（无角色限制）

方法路径说明
POST/files上传文件（multipart/form-data）
POST/files/url获取文件 URL
DELETE/files删除文件

文件上传 ​

POST /api/v1/files
Content-Type: multipart/form-data

file: <binary>
directory: "avatars"  (可选)

Response: { "code": "00000", "data": { "url": "https://..." } }

产品管理 /api/v1/products 🆕 ​

所有接口需 JWT 认证

方法路径角色说明
GET/products任意产品列表（分页）
POST/productsadmin创建产品
GET/products/:id任意产品详情
PUT/products/:idadmin更新产品
DELETE/products/:idadmin删除产品
GET/products/:id/thing-model任意获取产品物模型
POST /api/v1/products
{
  "id": "p_relay_4ch",
  "name": "四路继电器",
  "thingModel": { "version":"1.0", ... },  // 物模型 JSON
}

Response: { "code":"00000", "data": { "id":"p_relay_4ch", ... } }

设备管理 /api/v1/devices 🆕 ​

所有接口需 JWT 认证

方法路径角色说明
GET/devices任意设备列表（分页、搜索、按产品筛选）
POST/devicesadmin设备录入（手动注册）
GET/devices/:id任意设备详情（含影子状态）
PUT/devices/:idadmin更新设备信息（不含名称修改，命名请用 PATCH /name）
DELETE/devices/:idadmin删除设备
PATCH/devices/:id/name任意修改设备名称（配网完成后调用）
POST/devices/:id/control任意下发控制指令
GET/devices/:id/telemetry任意查询历史数据

设备注册 ​

POST /api/v1/devices
{
  "productId": "p_relay_4ch",
  "name": "客厅继电器",
  "physicalId": "A1B2C3D4E5F6"   // MAC 地址
}

Response:
{
  "code": "00000",
  "data": {
    "id": "d1a2b3c4-...",          // Logical ID (平台分配)
    "secret": "uuid-secret",        // Device Secret (平台生成)
    "productId": "p_relay_4ch",
    "name": "客厅继电器",
    "physicalId": "A1B2C3D4E5F6",
    "isOnline": false,
    "shadow": {}
  }
}

设备控制 ​

POST /api/v1/devices/d1a2b3c4-.../control
{
  "params": {
    "relay_1": true,
    "relay_2": false
  }
}

Response: { "code":"00000", "msg":"指令已下发" }

控制流程：API → 后端发布 MQTT sys/{pid}/{did}/thing/service/property/set → 设备执行。

历史数据查询 ​

GET /api/v1/devices/d1a2b3c4-.../telemetry?start=2026-05-01&end=2026-05-16&keys=relay_1,temperature

Response:
{
  "code": "00000",
  "data": [
    { "time": "2026-05-16T10:00:00Z", "relay_1": 1, "temperature": 45.2 },
    { "time": "2026-05-16T10:01:00Z", "relay_1": 0, "temperature": 44.8 }
  ]
}

固件升级 /api/v1/firmware 🆕 ​

升级操作需 admin 角色，查看状态任意角色可访问

方法路径角色说明
GET/firmware/versions任意固件版本列表
POST/firmware/uploadadmin上传固件文件
POST/firmware/upgradeadmin触发设备升级（单设备/批量）
GET/firmware/upgrade/:taskId/status任意查询升级任务进度

设备自动注册 /api/v1/devices/register 🆕 ​

无需认证（设备端调用，设备首次连接时由 EMQX 直连 PostgreSQL 认证后触发注册）

POST /api/v1/devices/register
Headers: X-Device-Key: <productKey>:<deviceSecret>

{
  "productKey": "p_relay_4ch",
  "physicalId": "A1B2C3D4E5F6",
  "clientId": "A1B2C3D4E5F6"
}

Response:
{
  "code": "00000",
  "data": {
    "deviceId": "d1a2b3c4-...",
    "mqttTopics": {
      "status": "sys/p_relay_4ch/d1a2b3c4-.../thing/event/property/post",
      "control": "sys/p_relay_4ch/d1a2b3c4-.../thing/service/property/set",
      "config": "sys/p_relay_4ch/d1a2b3c4-.../thing/config/set"
    }
  }
}

WebSocket 实时推送 /ws ​

需 JWT 认证，用于前端接收设备实时状态

事件方向说明
device.status服务端 → 客户端设备上下线通知
device.shadow服务端 → 客户端设备影子状态变更

系统监控 /api/v1/system ​

所有接口需 JWT + admin 角色

方法路径说明
GET/system/status获取服务器运行状态
POST/system/status/email发送状态报告邮件

系统状态响应 ​

json
{
  "code": "00000",
  "data": {
    "os": { "platform": "darwin", "type": "Darwin", "arch": "arm64", "hostname": "server" },
    "cpu": { "model": "Apple M1", "cores": 8, "speed": 2400 },
    "memory": { "total": "16 GB", "used": "8.5 GB", "free": "7.5 GB", "usage": "53.12%" },
    "uptime": "5天 12小时 30分 15秒",
    "timestamp": "2026-05-15T10:00:00.000Z"
  }
}

错误码 ​

HTTP 状态码 ​

状态码说明
200成功
400请求参数错误
401未认证
403无权限
404资源不存在
429请求过于频繁
500服务器内部错误

业务错误码 ​

code说明场景
00000成功正常响应
A0001参数校验失败缺少必填字段、格式错误
A0002用户不存在登录、查询
A0003密码错误登录、修改密码
A0004Token 过期需刷新或重新登录
A0005验证码错误登录
A0100设备不存在查询、控制
A0101设备离线控制指令下发时设备不在线
A0102设备未注册设备首次连接时未找到产品
A0103设备认证失败Secret 不匹配
A0104设备控制超时MQTT 指令下发后未收到回复
A0105设备已存在重复注册 (同 physicalId)
A0200产品不存在查询、创建
A0201物模型格式错误创建/更新产品
A0300MQTT 服务异常Broker 连接断开
A0301固件文件无效上传文件不是合法 .bin
A0302固件版本已存在同产品下版本号重复
A0303OTA 任务失败设备离线或正忙
B0001权限不足角色不符
B0002账号已禁用登录
C0001文件上传失败OSS 错误 / 格式不支持

使用约定 ​

json
// 成功
{ "code": "00000", "msg": "Success", "data": {...} }

// 业务错误
{ "code": "A0101", "msg": "设备离线，指令无法下发" }

// 无 data 字段，前端只需检查 code !== "00000" 判定错误

AI 编码指引: 后端所有异常通过 HttpExceptionFilter 统一处理。业务异常抛 BadRequestException('设备离线')，Filter 自动映射到对应 code。前端只需判断 res.code !== '00000' 展示错误提示。

全局中间件 ​

组件说明
HelmetHTTP 安全头
CORS跨域支持
ValidationPipe请求参数校验（whitelist + transform）
ThrottlerGuard全局限流（60秒/60次）
RequestLogger请求日志
TransformInterceptor响应格式统一包装
HttpExceptionFilter异常统一处理

Copyright © 2026 - YunStack-IoT. All Rights Reserved.