【鸿蒙优选三方库】@ohos/coap：让鸿蒙设备说上 IoT 的母语

传感器跑在电池供电的 MCU 上，HTTP 的 TCP 握手加几百字节 header 太奢侈，MQTT 还得部署 Broker。CoAP 基于 UDP，报文头只有 4 字节，还能组播——这才是受限设备的原生语言。@ohos/coap 让鸿蒙手机直接说这门语言。

📦 仓库地址 ｜ ohpm install @ohos/coap ｜ v2.0.22 ｜ Apache-2.0

---

它解决什么问题

CoAP 是 IETF 为受限设备设计的类 HTTP 协议，复用 REST 语义（GET/POST/PUT + URI），但跑在 UDP 上。IoT 领域用得很广，智能家居、农业监测、工业传感器都常见。

问题是 libcoap 是 C 库。要在 ArkTS 里用，得自己写 NAPI 胶水、调 C API、处理异步回调。

@ohos/coap 基于 libcoap v4.3.1 封装好了：客户端发请求，服务端注册处理器，全用 ArkTS。

---

核心能力

能力	说明
CoAP 客户端	GET / POST / PUT
双调用风格	Promise 与 Callback 任选
CoAP 服务端	注册处理器，鸿蒙设备也能被连
组播支持	一次请求，多设备各自响应
块传输	CoapBlockMode 处理大报文分块
Native 日志	一行开关，直接看 libcoap 内部报文

最容易被忽略的优势是组播：局域网里发现设备，一次广播就能拿到所有响应，不用逐个轮询。HTTP 和 MQTT 都做不到这点。

---

30 秒上手

import {
  CoapClient, CoapRequestMethod, CoapRequestType,
  CoapResponseCode, CoapBlockMode,
} from '@ohos/coap'

CoapClient.setNativeLogOpen(true)  // 调试时开，上线前关

// 每个实例对应一次请求，不可复用
const client = new CoapClient()
client.setBlockMode(CoapBlockMode.COAP_BLOCK_USE_LIBCOAP)

const data = await client.request(
  'coap://192.168.1.50:5683/sensor',
  CoapRequestMethod.GET,
  CoapRequestType.COAP_MESSAGE_CON,   // 单播用 CON（要确认）
)

if (data.code === CoapResponseCode.SUCCESS) {
  console.info('传感器数据: ' + data.message)
}

当服务端接收设备推送：

import { CoapServer } from '@ohos/coap'

const server = new CoapServer()
server.handle('sensor/upload', (request) => {
  const payload = JSON.parse(request.payload)
  console.info(`收到推送: ${payload.temp}°C`)
  return { code: '2.04', payload: 'OK' }
})
server.start('coap://0.0.0.0:5683')

权限要声明 ohos.permission.INTERNET 和 ohos.permission.GET_NETWORK_INFO。

---

社区已解决的典型问题

日志明文打印远端 IP（#112）
messageHandler / session / remoteIp 日志直接输出 IP 地址，有隐私合规风险。已修复。上线前记得 setNativeLogOpen(false)，最好把它绑到构建配置上避免忘记。

长时间运行内存增长（#110）
质量加固修复了部分内存泄漏。长连接监控场景建议用 DevEco Profiler 盯一下内存趋势。

能否一次广播收多个设备响应（#97）
可以。CoAP 协议支持组播，服务端 handler 会被每个响应设备分别触发。局域网设备发现用组播比逐个轮询高效得多。

并发请求崩溃（#95）
增加了锁与 try-catch 保护。但最佳实践仍是每个请求用独立的 CoapClient 实例——官方文档明确写了实例不可复用。

CVE 漏洞（#109）
已修复 CVE-2026-2901。IoT 涉及设备通信安全，关注 Release 及时升级。

---

适合谁用

• 智能家居 / 农业监测 / 工业传感器：受限设备接入
• 局域网设备发现：组播一次搞定
• 手机直连设备：不需要中间服务器或 Broker
• 鸿蒙设备当服务端：暴露资源供其他 CoAP 客户端访问
• 想替代 HTTP 降功耗：4 字节报文头 vs 几百字节

90 个 Issue 已关闭，从隐私合规到并发崩溃都有记录。做 IoT 前先翻一遍，能省不少事。