系统状态API¶
本文档引用的文件 - rest_api.c - rest_api.h - config.h - network_manager.h - ble_gateway.h - config_manager.c
目录¶
简介¶
系统状态API是ESP32-S3蓝牙网关系统的核心RESTful API端点，提供实时的系统运行状态信息。该API通过/api/status端点的GET方法，向客户端返回设备的完整运行状态，包括固件版本、设备标识、运行时间、内存使用情况、网络连接状态、BLE扫描状态等关键信息。
本API设计用于监控和诊断目的，为系统管理员和开发者提供实时的设备健康状况和运行指标。响应数据采用JSON格式，便于各种编程语言和工具的解析和处理。
项目结构¶
系统状态API位于ESP32-S3蓝牙网关项目的REST API模块中，采用模块化设计，与其他系统组件保持松耦合的关系。
graph TB
subgraph "REST API模块"
REST[rest_api.c]
RESTH[rest_api.h]
end
subgraph "配置管理"
CFG[config.h]
CM[config_manager.c]
end
subgraph "网络管理"
NM[network_manager.h]
end
subgraph "BLE网关"
BG[ble_gateway.h]
end
subgraph "外部依赖"
CJSON[cJSON库]
HTTPD[ESP-IDF HTTP服务器]
end
REST --> CFG
REST --> CM
REST --> NM
REST --> BG
REST --> CJSON
REST --> HTTPD图表来源 - rest_api.c - rest_api.h - config.h
章节来源 - rest_api.c - rest_api.h
核心组件¶
系统状态API由以下核心组件构成：
主要功能模块¶
- REST API处理器: 处理HTTP请求和生成JSON响应
- 配置管理器: 提供设备配置信息
- 网络管理器: 获取网络连接状态
- BLE网关: 汇总BLE设备扫描状态
- JSON序列化: 使用cJSON库生成标准JSON格式
数据源接口¶
- 配置管理器接口：
config_manager_get() - 网络管理器接口：
network_manager_get_status() - BLE网关接口：
ble_gateway_get_device_count()
章节来源 - rest_api.c - config_manager.c
架构概览¶
系统状态API采用分层架构设计，确保各组件职责明确且相互独立。
sequenceDiagram
participant Client as 客户端
participant HTTPD as HTTP服务器
participant API as REST API处理器
participant Config as 配置管理器
participant Net as 网络管理器
participant BLE as BLE网关
Client->>HTTPD : GET /api/status
HTTPD->>API : 调用api_status_handler()
API->>Config : 获取配置信息
API->>Net : 获取网络状态
API->>BLE : 获取BLE设备数量
API->>API : 组装JSON响应
API-->>HTTPD : 返回JSON数据
HTTPD-->>Client : HTTP 200 + JSON
Note over Client,HTTPD : 成功响应流程图表来源 - rest_api.c
章节来源 - rest_api.c
详细组件分析¶
API端点定义¶
系统状态API端点在REST API模块中注册，使用标准的HTTP GET方法。
| 属性 | 值 |
|---|---|
| 方法 | GET |
| 路径 | /api/status |
| 内容类型 | application/json |
| 认证 | 无需认证 |
响应数据结构¶
系统状态API返回的JSON对象包含以下顶级字段：
基础信息字段¶
| 字段名 | 数据类型 | 描述 | 示例值 |
|---|---|---|---|
gateway_id |
字符串 | 网关设备唯一标识符 | "ESP32S3-BLE-Gateway-001" |
firmware |
字符串 | 固件版本号 | "1.0.0" |
uptime |
数字 | 系统运行时间（秒） | 12345 |
heap_free |
数字 | 可用堆内存大小（字节） | 81920 |
网络状态字段¶
| 字段名 | 数据类型 | 描述 | 示例值 |
|---|---|---|---|
network.connected |
布尔值 | 网络连接状态 | true |
network.ip |
字符串 | 当前IP地址 | "192.168.1.100" |
network.interface |
字符串 | 活跃网络接口 | "ETH" 或 "WIFI" |
BLE状态字段¶
| 字段名 | 数据类型 | 描述 | 示例值 |
|---|---|---|---|
ble.devices |
数字 | 发现的BLE设备数量 | 15 |
请求处理流程¶
flowchart TD
Start([接收HTTP请求]) --> CreateObj[创建JSON根对象]
CreateObj --> AddBaseInfo[添加基础信息]
AddBaseInfo --> GetNetStatus[获取网络状态]
GetNetStatus --> AddNetStatus[添加网络状态]
AddNetStatus --> GetBLECount[获取BLE设备数量]
GetBLECount --> AddBLEStatus[添加BLE状态]
AddBLEStatus --> SerializeJSON[序列化为JSON字符串]
SerializeJSON --> SetHeaders[设置HTTP响应头]
SetHeaders --> SendResponse[发送HTTP响应]
SendResponse --> Cleanup[清理内存]
Cleanup --> End([请求处理完成])
AddBaseInfo --> AddGatewayID[添加gateway_id]
AddBaseInfo --> AddFirmware[添加firmware]
AddBaseInfo --> AddUptime[添加uptime]
AddBaseInfo --> AddHeap[添加heap_free]图表来源 - rest_api.c
章节来源 - rest_api.c
错误处理机制¶
系统状态API采用统一的错误处理策略：
| 错误场景 | HTTP状态码 | 错误描述 | 处理方式 |
|---|---|---|---|
| 正常请求 | 200 | 请求成功处理 | 返回JSON状态数据 |
| 内存不足 | 500 | 内存分配失败 | 返回标准错误响应 |
| 网络异常 | 503 | 服务不可用 | 返回服务暂时不可用 |
性能特性¶
系统状态API具有以下性能特征：
- 响应时间: 通常小于50毫秒
- 内存使用: 动态分配，峰值约2KB
- CPU开销: 低，主要为JSON序列化操作
- 并发支持: 支持多客户端并发访问
章节来源 - rest_api.c
依赖关系分析¶
系统状态API与多个内部模块存在依赖关系，形成清晰的依赖层次结构。
graph TB
subgraph "API层"
API[REST API处理器]
end
subgraph "服务层"
Config[配置管理服务]
Network[网络管理服务]
BLE[BLE网关服务]
end
subgraph "基础设施层"
NVS[NVS存储]
HTTPServer[HTTP服务器]
cJSON[cJSON库]
end
API --> Config
API --> Network
API --> BLE
Config --> NVS
Network --> HTTPServer
BLE --> HTTPServer
API --> cJSON
Network --> cJSON
BLE --> cJSON图表来源 - rest_api.c
章节来源 - rest_api.c
关键依赖接口¶
| 依赖模块 | 接口函数 | 用途 |
|---|---|---|
| 配置管理器 | config_manager_get() |
获取设备配置信息 |
| 网络管理器 | network_manager_get_status() |
获取网络连接状态 |
| 网络管理器 | network_manager_is_connected() |
检查网络连接状态 |
| BLE网关 | ble_gateway_get_device_count() |
获取BLE设备数量 |
章节来源 - rest_api.c
性能考虑¶
系统状态API在设计时充分考虑了性能优化：
内存管理¶
- 使用栈分配的临时缓冲区避免动态内存碎片
- JSON对象在使用后及时释放，防止内存泄漏
- 字符串处理使用固定大小缓冲区
响应优化¶
- 采用紧凑的JSON格式减少传输数据量
- 避免不必要的数据复制操作
- 使用高效的字符串拼接方法
并发处理¶
- API处理器支持多任务并发调用
- 各子系统的状态查询采用非阻塞方式
- 避免长时间持有互斥锁
故障排除指南¶
常见问题及解决方案¶
1. API响应为空或格式错误¶
症状: HTTP 200但响应体为空 原因: JSON序列化失败或内存分配不足 解决: 检查系统可用内存，确认cJSON库正常工作
2. 网络状态显示异常¶
症状: network.connected始终为false
原因: 网络管理器初始化失败或网络接口未就绪
解决: 检查网络配置，确认以太网或WiFi模块正常工作
3. BLE状态不准确¶
症状: ble.devices计数异常
原因: BLE网关未正确初始化或扫描状态异常
解决: 重启BLE扫描服务，检查HCI传输层
4. 内存不足错误¶
症状: HTTP 500错误，日志显示内存不足 原因: 系统可用堆内存过低 解决: 优化其他组件内存使用，增加可用内存
调试建议¶
- 启用详细日志: 在开发环境中启用DEBUG级别日志
- 监控内存使用: 定期检查heap_free值变化趋势
- 验证接口状态: 使用curl命令测试API响应
- 检查依赖服务: 确认所有依赖模块正常运行
章节来源 - rest_api.c
结论¶
系统状态API为ESP32-S3蓝牙网关提供了完整、实时的系统监控能力。通过标准化的JSON接口，用户可以轻松获取设备的关键运行指标，包括硬件状态、网络连接情况和BLE扫描状态等重要信息。
该API设计简洁高效，具有良好的可扩展性和维护性，能够满足从个人开发者到企业级部署的各种应用场景需求。其模块化的架构设计也为未来的功能扩展奠定了坚实的基础。
建议在生产环境中定期监控API的响应时间和内存使用情况，确保系统长期稳定运行。同时，建议在客户端实现适当的重试机制和错误处理逻辑，提高系统的整体可靠性。