API使用指南

1.平台简介

智目大型结构体监测平台专注于大型结构体的自动化安全监测，实现对项目、设备、数据及预警的综合管理。平台采用层次化结构，提供从数据采集、传输、处理到存储与展示的全流程管理，为精密测量提供高效、稳定、可靠的解决方案。

1.1 技术架构

云平台API是云平台的后端实现，采用分层分布式架构设计：

服务端框架：基于Java 17的Spring Boot + MyBatis Plus企业级开发框架

通信协议：终端设备与服务端采用有线或5G无线通信链路

数据传输：高效加密序列化处理，采用Netty 4.1作为高性能网络通信框架

连接方式：通过TCP长连接实现稳定双向通信

API协议：遵循HTTP规范和HTTP/1.1协议，支持标准的HTTP GET/POST方法

实时通信：采用WebSocket协议（RFC 6455）实现实时数据推送

1.2 系统特点

✅ 高性能：访问速度快、并发处理能力强

✅ 高可靠：稳定性高、数据安全

✅ 易集成：方便用户快速集成到自己的UI环境中

✅ 云部署：支持公有云和私有云部署，公有云已部署在阿里云，可快速接入。私有云需要联系我们进行部署。

1.3 系统组成示意图

2.快速接入指南

API包含用户、项目、监测目标、设备等全面的管理接口。要求在使用时需要按特定顺序进行接入：

2.1 接入步骤

1. 用户认证

获取访问令牌

调用 /zhimu-api/user/getVerifyCode 获取验证码

调用 /zhimu-api/user/userLogin 进行用户登录

获取访问令牌 x-zm-token

权限说明：

SUPER_ADMIN：超级管理员，可管理所有租户

ADMIN：管理员，可管理本租户资源

USER：普通用户，只能查看本租户资源

对于只需API调用部分接口，不使用页面登录的情况，可联系我司生成租户管理员的token（可设置为永不过期），直接调用API。

2. 创建项目

项目是监测系统的基础单位

调用 /zhimu-api/project/createProject 创建项目

设置项目基本信息（名称、描述等）

项目创建后获得 projectId

注意事项：

需要管理员权限

项目名称在租户内唯一

3. 创建监测目标

监测目标是项目下的具体监测对象

调用 /zhimu-api/object/createObject 创建监测目标

关联到指定项目（使用 projectId）

监测目标创建后获得 objectId

注意事项：

需要管理员权限

一个项目可包含多个监测目标

4. 创建设备

设备（监测相机）是数据采集的硬件单元，需要关联在监测目标下

调用 /zhimu-api/device/createDevice 创建设备

关联到指定监测目标（使用 objectId）

设置设备序列号、位置坐标等

设备创建后获得 deviceId

注意事项：

设备序列号必须唯一

必须要创建设备后，平台才能允许设备连接并传递数据。

5. 配置监测点

通过Tools工具配置监测点

使用Tools设备管理工具连接设备

配置监测参数

设置监测点位置参数并保存到设备上

配置完成后关闭Tools工具切换到云平台模式。

Tools工具请联系我司提供

6. 配置告警规则

设置告警阈值

调用 /zhimu-api/alarm/createAlarmRule 创建告警规则

设置告警级别（WARNING/ERROR）

配置告警阈值和触发条件

启用告警规则

说明：

本步骤非必须，如果不需要平台提供告警，可以不配置告警规则。

支持多级告警（警告/错误）

监测目标阈值超限告警和目标识别告警需要配置告警规则才会触发

无数据告警和设备离线等异常告警系统会自动触发

实时告警数据通过WebSocket实时推送（具体查看Websocket文档）

历史告警数据可通过接口查询

通过以上步骤后，就可以正常使用平台API接口，其他接口根据实际需要进行选择调用。和设备交互的接口位于设备控制API组内，测点位移数据接口位于设备分组内。

说明：对于只想快速使用平台接口，仅获取设备位移数据的用户，我们可以支持完成前面的接入步骤，提供x-zm-token，用户直接调用对应的接口即可。

3. API 基础信息

设备出厂默认为用户提供了一个基于阿里云服务器的公有云环境供开箱测试和使用，如果用户希望在项目中部署自己的公有云或私有云，请与我司售后部门联系，获取详细的安装技术支持信息。

3.1 基础配置

认证方式: 请求头携带 x-zm-token

数据格式: JSON

字符编码: UTF-8

时间格式: ISO 8601 (UTC时间)

3.2 公有云地址

HTTP API URL: https://api.zhimu-tech.com

WebSocket API URL: wss://api.zhimu-tech.com/zhimu-api/ws

3.3 通用响应格式

所有接口都使用统一的响应格式：

{
  "success": true,
  "errorCode": "SUCCESS", 
  "errorMessage": "操作成功",
  "data": {}
}

响应字段说明：

字段	类型	说明
success	boolean	操作是否成功
errorCode	string	错误代码，成功时为 "SUCCESS"
errorMessage	string	错误信息或成功提示
data	object	响应数据，失败时为 null

3.4 分页响应格式

分页接口使用 PageList 格式：

{
  "success": true,
  "errorCode": "SUCCESS",
  "errorMessage": "操作成功", 
  "data": {
    "list": [],
    "totalCount": 0
  }
}

4. 错误码说明

错误码	HTTP状态码	说明
SUCCESS	200	操作成功
PARAM_ERROR	400	参数错误
USER_NOT_EXIST	404	用户不存在
USER_STATUS_ERROR	401	用户状态异常
USER_PASSWORD_ERROR	401	用户名或密码错误
USER_TYPE_ERROR	400	用户类型错误
VERIFY_CODE_ERROR	401	验证码错误
TOKEN_INVALID	401	Token无效
TOKEN_EXPIRED	401	Token已过期
MISSING_TOKEN	401	Token不存在
PERMISSION_DENIED	403	没有权限访问该接口
PROJECT_NOT_EXIST	404	项目不存在
DEVICE_NOT_EXIST	404	设备不存在
FILE_NOT_EXIST	404	文件不存在
SERVICE_ERROR	500	服务内部错误

5. 最佳实践

5.1. 认证管理

✅ 妥善保管访问令牌，避免泄露

✅ 定期刷新Token，避免过期

✅ 实现Token自动续期机制

5.2. 错误处理

✅ 检查响应中的 success 字段

✅ 根据 errorCode 进行相应的错误处理

✅ 实现重试机制处理网络错误

✅ 记录详细的错误日志

5.3. 性能优化

✅ 使用分页查询避免一次性加载大量数据

✅ 合理设置请求超时时间

✅ 使用WebSocket接收实时数据，避免频繁轮询

✅ 实现本地缓存减少重复请求

5.4. 数据安全

✅ 验证所有输入参数

✅ 使用HTTPS加密传输

✅ 定期更新访问令牌

✅ 实现数据备份和恢复机制

5.5. 监控告警

✅ 监控API调用成功率

✅ 设置告警阈值

✅ 记录关键操作日志

✅ 实现异常情况自动通知

6. 常见问题

Q1: Token过期如何处理？

A:Token过期时会返回 TOKEN_EXPIRED 错误码，客户端需要：

调用 /zhimu-api/user/refreshToken 刷新Token

如果刷新失败，重新进行用户登录

更新本地存储的Token

Q2: 如何获取实时监测数据？

A: 推荐使用WebSocket连接：

建立WebSocket连接

订阅相关主题（如设备心跳位移数据、设备状态、实时告警等）

实时接收推送的数据

对于设备监测点的实时位移数据，也可以通过HTTP接口循环拉取，参考接口 /zhimu-api/device/getMeasureLiveRecord 获取设备下监测点的实时位移。

Q3: 设备离线如何处理？

A: 设备离线时：

通过WebSocket接收设备状态变化通知

检查设备电源和网络连接

设备会自动重连，如果超过5分钟没有还处于离线状态，请联系我司获取技术支持。

Q4: 如何批量操作设备？

A: 目前API不支持批量操作，需要：

循环调用单个设备接口

控制并发数量避免服务器压力

实现操作结果汇总和错误处理

Q5: 文件上传大小限制？

A: 根据服务器配置：

建议单个文件不超过100MB

支持的文件类型：FIRMWARE/MAP/LOG/PHOTO/VIDEO

上传前建议计算文件MD5值

7. 技术支持

如有技术问题，请联系：

技术支持邮箱: support@zhimu-tech.com

API文档更新: 请关注项目更新日志

文档版本: v1.0.0

1.平台简介#

1.1 技术架构#

1.2 系统特点#

1.3 系统组成示意图#

2.快速接入指南#

2.1 接入步骤#

3. API 基础信息#

3.1 基础配置#

3.2 公有云地址#

3.3 通用响应格式#

3.4 分页响应格式#

4. 错误码说明#

5. 最佳实践#

5.1. 认证管理#

5.2. 错误处理#

5.3. 性能优化#

5.4. 数据安全#

5.5. 监控告警#

6. 常见问题#

Q1: Token过期如何处理？#

Q2: 如何获取实时监测数据？#

Q3: 设备离线如何处理？#

Q4: 如何批量操作设备？#

Q5: 文件上传大小限制？#

7. 技术支持#

1.平台简介

1.1 技术架构

1.2 系统特点

1.3 系统组成示意图

2.快速接入指南

2.1 接入步骤

3. API 基础信息

3.1 基础配置

3.2 公有云地址

3.3 通用响应格式

3.4 分页响应格式

4. 错误码说明

5. 最佳实践

5.1. 认证管理

5.2. 错误处理

5.3. 性能优化

5.4. 数据安全

5.5. 监控告警

6. 常见问题

Q1: Token过期如何处理？

Q2: 如何获取实时监测数据？

Q3: 设备离线如何处理？

Q4: 如何批量操作设备？

Q5: 文件上传大小限制？

7. 技术支持