规范#

请求主题#

规则#

请求主题的格式遵循 server/{serverNo}/{serviceName}/{version}/{topicSuffix}，其中：

示例#

例如，server/center-server/iot/v1/list-online-status 就是一个符合规则的请求主题示例。

请求结构 (Api request)#

规则#

• sub：子主题，仅在双向通信较为复杂的场景下使用，其他场景无需填写。其作用是在主题相同的情况下对不同业务进行区分。
• id：会话 ID 作为唯一标识符，用于区分不同客户端，需传入 MQTT 客户端 ID。MQTT 客户端 ID 的生成规则如下：
  • Web 客户端程序：user,{username},web,{sessionId}
  • App 客户端程序：user,{username},app,{sessionId}
  • 设备管理服务：device,{deviceNo},iot,{sessionId}
  • 设备 WebRTC 服务：device,{deviceNo},webrtc,{sessionId}
  • 采集服务器文件服务：server,{serverNo},file,{sessionId}
  • 中心或采集服务器数据服务：server,{serverNo},iot,{sessionId}
  • 中心服务器设备服务：server,{serverNo},device,{sessionId}
• reply: MQTT 响应消息主题路径，此为可选字段，仅在需要响应数据时才进行相应设置，响应端会通过该主题来返回相应的响应数据。这样的设计便于第三方系统进行对接，第三方系统可根据自身系统规范订阅主题，支持采用自有主题定义规范。此字段的设置是为了兼容不支持 MQTT 5.0 特性的客户端（对应 MQTT 5.0 中的 Response Topic）。
• replyNumberMax: 最大回复次数，该字段为可选字段。仅当需要回复响应数据超过 1 次时，才需进行相应设置。服务端已将范围控制在 1 - 10，若为空，默认值为 1。
• replyInterval: 回复间隔（秒），此为可选字段。仅在需要回复响应数据超过 1 次的情况下，才需进行设置。服务端已将该字段的范围控制在 1 - 10 秒，若该字段为空，则默认值为 1 秒。
• token: 身份认证令牌，专门用于接口权限的校验工作，以此确保接口使用的合法性与安全性。
• params: 传参，此为可选字段，仅在存在传参需求时才进行相应设置。

示例#

1{
2  "id": "user,admin,web,session-id-xxx",
3  "token": "token-xxx",
4  "reply": "user/admin/web/session-id-xxx/rx/resp/server/center-server/iot/v1/list-online-status",
5  "params": {
6    "mqttClientIdPrefixes": [
7      "user,admin,web",
8      "user,admin,app",
9      "device,asr-1,webrtc",
10      "device,asr-1,iot",
11      "server,center,iot",
12      "server,center,file"
13    ]
14  }
15}

响应主题#

规则#

由请求结构中的 reply 字段指定，若该字段为空，则不进行回复。

示例#

例如，user/admin/web/session-id-xxx/rx/resp/server/center-server/iot/v1/list-online-status , 第三方系统可根据自身系统规范订阅主题，支持采用自有主题定义规范

响应结构 (Api response)#

规则#

• sub：子主题，仅在双向通信较为复杂的场景下使用，其他场景无需填写。其作用是在主题相同的情况下对不同业务进行区分。
• id：会话 ID 作为唯一标识符，用于区分不同客户端，需传入 MQTT 客户端 ID。MQTT 客户端 ID 的生成规则如下：
  • Web 客户端程序：user,{username},web,{sessionId}
  • App 客户端程序：user,{username},app,{sessionId}
  • 设备管理服务：device,{deviceNo},iot,{sessionId}
  • 设备 WebRTC 服务：device,{deviceNo},webrtc,{sessionId}
  • 中心或采集服务器数据服务：server,{serverNo},iot,{sessionId}
  • 中心服务器设备服务：server,{serverNo},device,{sessionId}
  • 采集服务器文件服务：server,{serverNo},file,{sessionId}
• reply: MQTT 响应消息主题路径，此为可选字段，仅在需要响应数据时才进行相应设置，响应端会通过该主题来返回相应的响应数据。这样的设计便于第三方系统进行对接，第三方系统可根据自身系统规范订阅主题，支持采用自有主题定义规范。此字段的设置是为了兼容不支持 MQTT 5.0 特性的客户端（对应 MQTT 5.0 中的 Response Topic）。
• status: 响应状态码，其默认值为 200，该状态码能够直观地反映出请求响应的大致情况。
  • 200: 成功执行请求，没有发生任何错误。
  • 400: 对象验证失败时抛出。常见场景包括：直接通过验证器（如 Validator）对对象进行校验（如 validator.validate(object)），或在框架（如 Spring、Hibernate）自动触发验证逻辑时（如服务层参数校验、JPA 实体持久化前的约束检查）。当对象的属性违反 @NotEmpty、@Size、@Pattern 等验证注解定义的规则时，所有违反的约束会被收集为 ConstraintViolation 集合，最终封装成该异常，用于集中处理参数或实体的合法性校验失败问题。
  • 401: 身份验证异常，会在认证环节失败时出现。常见场景有：用户登录时输入的用户名或密码有误，无法通过验证；使用的令牌（如 JWT、OAuth2 令牌）无效、过期或者格式不对；请求头中缺少必要的认证信息，像基本认证的 Authorization 头；用户尝试使用禁用、锁定或过期的账户登录。此时，Spring Security 会抛出该异常，阻止用户继续访问受保护资源。
  • 403: 拒绝访问异常，通常发生在用户已通过认证（登录）但缺乏访问目标资源权限的场景，例如请求的 URL 或方法所需角色、权限表达式（如 hasRole、hasAuthority）与用户实际权限不匹配，匿名用户或 “记住我” 用户访问受限资源，自定义访问决策逻辑拒绝（如 AccessDecisionVoter 投票失败），以及请求方法、CSRF 校验、会话权限变更等配置导致的授权失败。核心原因是用户认证通过但授权（权限检查）未通过。
  • 422: 业务逻辑验证失败。这意味着虽然请求本身可能是有效的，但在尝试执行特定业务功能时发现了问题。例如，如果某个设备ID不存在于系统中，那么即使请求格式正确，也会因为找不到相关联的数据而产生此类错误。同样地，具体的原因会在error字段中给出。
  • 500: 发生了内部服务器错误，这通常意味着后端代码遇到了某种未预料的情况（如数据库操作失败）。此时，用户界面只显示"System Error"，但详细的错误信息记录下来以供开发者诊断问题。
  • 1000: 出现于 HTTP 请求 / 响应的消息转换过程失败时，主要场景包括：请求体（如 JSON/XML）无法转换为目标对象（格式错误、类型不匹配等），或响应体对象无法序列化为指定格式（如序列化规则冲突、字段无法处理），本质是数据格式与目标类型间的转换逻辑失败，常见于前后端数据格式不匹配或消息转换器配置问题。
  • 1001: 通常出现在控制器方法的参数验证失败场景。当使用 @Valid 或 @Validated 注解对方法参数（如实体类、基本类型或自定义参数）进行校验时，若客户端请求的参数不符合校验规则（如 @NotEmpty、@Size、@Pattern 等注解定义的约束），Spring 会在参数绑定过程中触发验证逻辑。若验证不通过，会将所有错误信息封装成 BindingResult，并抛出 MethodArgumentNotValidException。例如，前端传递的表单数据缺失必填字段、字符串长度超出限制、格式不符合正则要求等，都会导致该异常，其本质是参数绑定与校验失败的统一封装，便于集中处理请求参数的合法性问题。
• error: 错误描述信息，此为可选字段，仅在出现异常情况时才会返回相关内容，以便使用者清晰知晓出现问题的具体缘由。
• data: 响应数据，此为可选字段，仅在实际有数据需要返回时，才会呈现相应的内容。
• replyNumber: 回复数量，与请求结构中的 replyNumberMax 相对应，用于表明本次请求的回复次数。

示例#

1{
2  "id": "server,center,iot,session-id-xxx",
3  "status": 200,
4  "data": [
5    {
6      "mqttClientIdPrefix": "user,admin,web",
7      "onlineStatus": true
8    }
9  ]
10}