接手一个温湿度传感器的项目，要把底层串口通信封装成RESTful API，让App和云端通过HTTP调用。听着简单，实际调试时踩了一堆坑。
## 硬件返回格式和文档不一致
第一次调 `GET /api/v1/sensor/temperature`，返回的是 `temp=25.6` 这种纯文本，而我的解析器等的是JSON。用串口工具抓硬件日志才发现，固件版本太老，输出就是老格式。
核心原则：别信文档，亲自抓原始数据。
## 调试工具
API层我用Postman和curl。开发板上跑的是轻量HTTP Server，比如ESP32的esp_http_server。
“`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连接建立慢，默认timeout不够。改成10秒，硬件端加重连机制后稳定了。
## 幂等性：一个隐蔽的坑
设备有个 `POST /api/reset` 恢复出厂设置。连续按两次，设备直接卡死。硬件收到reset指令后重启，过程中又收到第二个请求，状态机乱了。
解决办法：API层加pending标志，处理期间拒绝新请求，返回 `409 Conflict`。文档里不会写这个，全靠踩出来。
## 日志系统
ESP32上开UART输出调试日志，API响应头加 `X-Debug-Id`，每次请求生成唯一ID，方便把日志和请求关联。客户端收到500错误时，用这个ID查服务端错误栈。
但硬件内存有限，别在API服务里记太多东西。我最初把完整请求体写日志文件，跑了一天Flash就写坏了。后来只记请求ID、时间戳和状态码，详细错误只在调试模式打到串口。
## 最后
智能硬件API调试就是不断“猜-验证-修正”。硬件不像纯软件，没法一键重启远程服务器，每次烧录固件都得插线等。多用Wireshark或tcpdump抓包，问题有时出在路由器、电源适配器或隔离芯片上，不全是代码的锅。
ID:4596
