最近接手一个温湿度传感器项目，要把底层串口通信封装成RESTful API，让App和云端能通过HTTP直接调用。听起来简单，实际调试时坑一个接一个。
## 文档不可信，抓原始数据
最常见的问题：硬件返回格式和API文档不一致。
我用的传感器模组，官方AT指令集文档漏了几个关键字段。第一次调用 `GET /api/v1/sensor/temperature`，返回的是 `temp=25.6` 这种纯文本，而我的解析器等着JSON。排查半天，以为是网络截断，后来用串口工具直接抓硬件日志，才发现固件版本太老，输出的是旧格式。
核心原则：永远不要信任文档，亲自抓原始数据。
## 调试工具：curl和Python脚本
API层调试，Postman和curl最顺手。开发板上的服务端一般是轻量HTTP Server，比如ESP32的esp_http_server库。
控制智能灯具的curl命令：
“`bash
curl -X POST http://192.168.1.100/api/device/control \
-H “Content-Type: application/json” \
-d ‘{“led”: “on”, “brightness”: 80}’
“`
第一次返回 `400 Bad Request`，原因是JSON键名写成了 `LED`（大写），服务端严格区分大小写。多人协作时字段名随意定义、后端没做容错，这种错误太常见。解决办法：统一规范，服务端打印接收到的原始请求体。
批量验证用Python requests写自动化脚本：
“`python
import requests
url = “http://192.168.1.100/api/v2/sensor”
response = requests.get(url, timeout=5)
if response.status_code == 200:
data = response.json()
print(f”温度: {data[‘temperature’]}°C, 湿度: {data[‘humidity’]}%”)
else:
print(f”错误码: {response.status_code}, 响应: {response.text}”)
“`
这个脚本帮我定位了十几次超时——Wi-Fi信号弱，硬件端TCP连接建立太慢，requests默认timeout不够。改成10秒，硬件端加重连机制后稳定了。
API调试不只是API本身，底层网络、供电、固件都可能是瓶颈。
## 幂等性：reset接口的坑
设备有个 `POST /api/reset` 恢复出厂设置接口。连续按两次，设备直接卡死——硬件收到reset指令后，重启过程中又收到第二个请求，状态机混乱。
解决方案：API层加pending标志，处理期间拒绝新reset请求，返回 `409 Conflict`。文档里不会写这个，全靠踩出来。
## 日志系统
ESP32上开UART输出调试日志，同时在API响应头加 `X-Debug-Id` 字段，每次请求生成唯一ID，把日志和请求关联起来。客户端收到500错误时，凭这个ID查服务端错误栈。
但硬件内存有限，别在API服务里记太多调试信息。我最初把完整请求体写日志文件，跑了一天Flash写坏。后来只记请求ID、时间戳和返回状态码，详细错误只在调试模式打印到串口。
## 最后
智能硬件API调试就是“猜-验证-修正”的循环。硬件不像纯软件，没法一键重启远程服务器，每次烧录固件都得插线等待。多用抓包工具（Wireshark或tcpdump），别只盯着代码——问题可能出在路由器、电源适配器或隔离芯片上。
ID:4628
