简介这是一份基于Java的CoAP协议实现源码包面向物联网开发者、Android服务端开发者和希望理解CoAP底层通信的读者。项目按功能拆分为app与coaplib两个部分app为Android服务器端代码coaplib包含Java服务器代码与客户端测试代码可直接用于学习CoAP资源发现、URI映射以及通过GET、POST、PUT、DELETE操作资源等机制。资源共297个文件其中262个Java源文件构成主体另有12个XML用于Android界面或配置配合gradle构建文件、properties配置和PNG图标等压缩包整体仅582KB结构清晰、便于快速导入分析。目前已有504人学习下载。通过这份源码读者既能掌握CoAP在Android端与普通Java服务端的落地写法也能结合描述中的协议特征理解UDP传输下的事务重传与资源描述方式适合作为课程设计、毕设或物联网项目的参考实现。1. 项目定位CoAP 协议服务端的 Java 实现覆盖 Android 与服务器两个场景做物联网设备接入时最容易被忽略的一环是设备侧和网关侧之间的通信协议。很多团队习惯性把 HTTP 一路推到传感器上但到了现场才发现设备内存以 KB 计、带宽以 Kbps 计HTTP 那套庞大的头部开销根本扛不住。CoAP 就是在这种场景下出现的轻量级协议它跑在 UDP 之上用极小的报文格式完成请求-响应交互而这份源码解决的正是服务端这一侧一个用 Java 写的 CoAP 服务端同时输出两套运行形态——Android 端可以作为局域网内的 CoAP 服务器运行纯 Java 端可以部署在任何常规 JVM 环境里。与其说这是个具体项目不如说是一套 IoT 设备接入的“服务端底座”适合做智能家居网关、工业传感器采集端、或任何需要跑在局域网内提供设备数据读写能力的开发者。2. 项目架构与技术选型UDP 之上的一棵资源树两个运行入口2.1 为什么是 CoAP报文小、连接轻、模型简单CoAP 和 HTTP 的请求-响应模型非常接近但它把数据报压缩到了一个惊人的程度。一个最小请求报文只有 4 字节头部加若干字节 URI相比 HTTP 动辄几百字节的头部完全是两个量级。这种设计不是为了炫技而是因为典型场景里的终端设备可能是 8 位单片机、可能有 64KB 内存、可能通过 LPWAN低功耗广域网模块联网每一字节都在消耗电量和流量。从实现者的角度CoAP 服务端本质上管理的是一棵资源树——每个资源节点对应一个 URI 路径支持 GET、POST、PUT、DELETE 四种标准方法。这种模型对写业务的人来说非常直接你要暴露一个温度传感器就建立一个传感器资源节点在它的 GET 处理器里返回当前温度值要允许远程控制开关就建立一个开关资源节点在 PUT 处理器里读取新状态并驱动硬件。相比 HTTP 服务端的 Servlet 或 Spring MVC 那套繁杂的映射规则CoAP 的资源树更接近“文件系统操作”的直觉。2.2 工程结构一份核心两套入口项目源码在结构上把核心逻辑和运行环境做了清晰切分。核心部分是一套与平台无关的 CoAP 协议处理代码包括报文编解码、消息类型处理、资源注册与分发而两个入口分别处理 Android 环境下和纯 Java 环境下的启动细节。Android 端使用前台服务持有网络线程纯 Java 端提供一个带 main 方法的启动类两边共用同一套协议核心和资源注册代码。这样的结构带来一个很实际的好处你可以先在 PC 上把整套服务端逻辑跑通、调试好再把这套代码挪到 Android 真机上部署而业务资源类不需要改动一行。对于智能网关这类场景开发流程通常就是“PC 上做模拟接入 → Android 设备上做真实接入”这种工程划分恰好贴合。2.3 依赖与运行环境整个服务端的核心边界纯 Java 端可以基于标准 JVM 运行除了 CoAP 协议库之外没有额外的框架级依赖。Android 端需要网络权限和前台服务权限在 Android 5.0 到 12 的范围内都能运行整个服务端在 Android 上以服务组件的形式存活适配了系统对后台运行的限制。代码中也能看到对网络状态变化的处理服务启动强制绑定 WIFI 并持有相应锁避免设备休眠导致 UDP 收包异常。从 socket 到业务响应链路经过三层传输层负责 UDP 数据报的接收和发送协议层负责 CoAP 报文的解析和封装路由层负责从报文中的 URI 找到对应资源处理器并执行业务逻辑。这种分层非常规整也让二次开发时定位问题变得简单——报文丢了看最底层路由错了看中间层业务不对看资源处理器。3. 核心模块拆解一个 CoAP 请求从 UDP 数据报进入系统的完整链路3.1 传输层UDP 单包接收与并发分发CoAP 服务端的传输层就是一个持续监听的 UDP socket。UDP 本身没有连接的概念服务端要做的就是在指定端口上不断接收数据报文然后把每个报文交给线程池处理。这里最需要注意的一个细节是缓冲区的长度——CoAP 报文最大长度受 UDP 限制但实际开发中建议给足缓冲区避免极端情况下截断报文。常见的做法是分配 2048 字节的缓冲区足以容纳绝大多数 CoAP 报文。// 服务端主循环骨架 byte[] buffer new byte[2048]; DatagramPacket packet new DatagramPacket(buffer, buffer.length); ExecutorService workerPool Executors.newFixedThreadPool(8); while (!serverSocket.isClosed()) { serverSocket.receive(packet); // 阻塞等待 UDP 数据报 byte[] data Arrays.copyOf(packet.getData(), packet.getLength()); InetSocketAddress sender new InetSocketAddress(packet.getAddress(), packet.getPort()); // 每个报文独立受理不阻塞后续收包 workerPool.execute(() - dispatchRequest(data, sender)); }这段逻辑看似简单但有一个非常容易被忽略的坑DatagramPacket的getData()返回的是整个缓冲区数组而getLength()才是本次接收的有效数据长度二者组合才能得到一个干净的报文。线程池的并发数取决于你对设备数量的预估如果只是几台设备做演示用4 到 8 个线程足够如果是上百台设备同时请求需要考虑调大线程池或使用无界队列来吸收瞬时压力。传输层的返回路径是同一条 socket 的send()方法。要给响应报文预留新的缓冲区不能复用接收缓冲区这在多线程并发响应时尤为重要——一个线程正在用data数组拼装响应另一个线程可能已经用同一个数组覆盖了内容这种跨线程数据竞争是 UDP 服务里最容易出现的隐蔽 bug。3.2 协议层报文头解析的字节操作CoAP 报文的头部是定长的 4 字节后面跟着变长的 Token 区、Options 区和 Payload 区。第一个字节的高 2 位是版本号、接着 2 位是消息类型、低 4 位是 Token 长度第二个字节是响应码其中前 3 位是类别请求、响应、空消息后 5 位是具体方法或状态码第三、四字节组成 16 位的消息 ID。// 手动解析 CoAP 报文头部的字节操作 byte firstByte data[0]; byte secondByte data[1]; int version (firstByte 6) 0x03; // 必为 01 int type (firstByte 4) 0x03; // 0x00CON 0x01NON 0x02ACK 0x03RST int tokenLength firstByte 0x0F; // Token 占用字节数0~8 int code secondByte 0xFF; // 0.01 GET / 0.02 POST / 0.03 PUT / 0.04 DELETE int messageId ((data[2] 0xFF) 8) | (data[3] 0xFF);参数说明type决定了这则消息是否需要确认。如果是 CON确认消息类型服务端收到后必须回一个 ACK否则对端会在超时后重传同一消息 ID 的报文如果是 NON非确认消息服务端只需处理请求、正常返回响应即可不单独回 ACK。很多刚接触 CoAP 的开发者会在 CON 消息上犯一个错误把业务响应当成了 ACK结果对端业务响应也没收到、确认也没等到消息一直重传。Options 区是变长编码的每个 Option 由 Delta、Length 和 Value 三部分组成Delta 表示相邻 Option 编号的差值。这种紧凑编码方式让 CoAP 的 URI 查询参数、内容格式、最大年龄等元数据能够被压缩到非常小的空间。在实际开发中这部分逻辑通常由 CoAP 协议库直接提供封装好的 API但了解字节结构对排查抓包问题非常关键——比如使用 Wireshark 查看报文结构时如果能定位到 URL 查询参数在 Options 区解析的正确结果就能判断是解析代码的问题还是报文本身的问题。3.3 路由层URI 到资源处理器的映射CoAP 服务端的资源模型是一棵树。树的根节点是服务器地址本身的资源列表子节点则对应 URL 中的路径段。在代码中一个典型的资源类长这样// 一个典型的温度传感器资源节点 public class TemperatureResource extends CoapResource { public TemperatureResource(String name) { super(name); // 声明支持可观察特性便于服务端主动推送变化 setObservable(true); } Override public void handleGET(CoapExchange exchange) { // 读取传感器当前值演示用固定值 String temperature 23.5; exchange.respond(ResponseCode.CONTENT, temperature); } Override public void handlePUT(CoapExchange exchange) { String payload exchange.getRequestText(); // 将字符串负载业务化例如修改温度阈值 exchange.respond(ResponseCode.CHANGED); } }创建资源之后把它注册到服务端的资源树上server.add(new TemperatureResource(temperature));这里add方法的第一个参数本质上是资源树里的一条路径。如果资源类构造时传入sensors/temperature那么客户端访问的 URI 就是coap://主机地址:5683/sensors/temperature如果客户端请求的路径无法匹配到任何资源服务端会返回 4.04 Not Found。实际项目里设备接入平台会为每个设备分配一组资源路径例如/devices/{deviceId}/temperature、/devices/{deviceId}/switch此时就需要按设备维度动态注册或查找资源而不是像演示那样静态创建。3.4 响应层消息 ID、Token 与观察者机制除了正常的请求-响应CoAP 还有两个与 HTTP 差异明显的机制Token令牌和 Observation观察。Token 是客户端在请求中附带的标识符服务端在响应中必须原样复制 Token这样客户端才能把响应匹配到发起请求的那个代码分支。对于同一资源上并发的多个请求通过 Token 可以区分是谁的响应。观察者机制实现起来更有趣客户端 GET 一个资源时附带 Observe 标记服务端会把这个客户端记录到该资源的观察者列表里之后资源状态发生变化时服务端会主动向所有观察者推送更新消息这与 HTTP 轮询完全不同。在你的服务端代码里这意味着资源对象的变更要能主动调用通知方法而不是等客户端来拉取。对于智能家居场景这是最值得优先改造的模块——开关状态变化、传感器告警都能做到秒级推送而不需要设备端反复轮询。4. 避坑指南跑 CoAP 服务端时踩过的五个常见问题4.1 Android 收不到任何 UDP 数据包现象服务在 Android 上启动后PC 端的客户端发送请求服务端完全没反应日志里连 socket 接收的痕迹都没有。原因Android 设备进入休眠状态后CPU 和网络硬件都会进入低功耗模式UDP socket 无法唤醒系统接收数据。另外 Android 6.0 以上的系统对隐式网络访问有更严格的省电策略锁屏几分钟后网络栈就冻结了。解决在服务启动时获取 WIFI 的WifiManager.WifiLock同时声明android.permission.WAKE_LOCK权限。代码里在onStartCommand中创建并持有锁onDestroy中释放。如果设备供应充足还可以同时使用PowerManager.WakeLock保持 CPU 唤醒但要注意这会增加耗电量。4.2 CON 消息请求一直重传但响应已经发出去了现象客户端收到业务响应但控制台仍在反复打印超时重传日志甚至在收到响应后还继续重传最终以超时收场。原因CoAP 协议规定 CON 消息必须由接收方单独返回一个 ACK 空报文不带业务负载业务响应是另一条消息。如果服务端在收到 CON 请求后只回了业务响应没有回 ACK 空报文或回 ACK 时没有正确复制消息 ID客户端就无法确认“收到”于是持续重传。解决确保处理逻辑对 CON 消息先发送 ACK 包、再发送独立响应包。在基于 CoAP 协议库实现时框架一般会自动处理空 ACK但如果使用了底层 API 自造报文这一环是必须自己做完的。4.3 客户端请求总是返回 4.04 Not Found现象客户端明确访问coap://192.168.1.100:5683/sensors/temperatureIP、端口都对但服务端返回 4.04抓包看确认报文已经到了。原因资源注册时用的是相对路径而客户端请求的路径中多了一个前缀。比如代码中注册了temperature但客户端请求的是/sensors/temperature路径匹配失败。解决明确资源注册的完整路径语义并在客户端联调前先在服务端打印出所有已注册资源路径与客户端实际请求路径做一次逐段比对。4.4 Android 服务被系统回收隔几分钟服务就没了现象手机锁屏放一会儿后coap 服务停止响应重新进入应用又恢复。这不是代码里主动关的而是系统杀的。原因Android 内存在紧张时系统会按一定优先级回收后台进程。普通 Service 在进程被回收后基本没有恢复机会锁屏状态下更是如此。解决把服务改为前台服务使用低优先级通知显示在通知栏降低进程被杀概率。服务内做软重启保护即监听系统网络变化的广播若是网络变化导致 socket 失效就自动重建 socket。这个做法能让服务在多数设备上长时间稳定运行。4.5 Payload 写太大导致请求直接“消失”现象客户端向服务端 POST 了一段几百字节的负载结果服务端连报文都没收到客户端报超时。原因UDP 报文在以太网环境下最大不超过 1500 字节左右但某些路由器的分片处理能力很差一旦 IP 分片之后任一帧丢失整个报文全部丢弃。CoAP 报文默认支持的分块传输模式Block-wise在直接接收 UDP 原始报文时并不自动启用。解决服务端启用 CoAP 协议库中的分块传输支持能力同时客户端对超过 64 字节的负载显式启用分块传输。在代码层面就是对资源类声明支持块传输协议库会自动处理请求数据的重组与响应数据的拆分。此外避免在一条报文中塞入大量查询参数能有效减少分片概率。5. 运行指南两种环境下的编译、部署与验证5.1 纯 Java 服务端Gradle 编译与启动整个工程建议使用 Gradle 或 Maven 管理。纯 Java 端启动入口是一个带有main方法的类核心逻辑只有三行创建 CoAP 服务端、注册资源、启动服务。具体命令如下# 编译整个工程并打可执行 jar gradle clean build # 运行纯 Java 服务端假设入口类路径为 com.demo.CoapServerMain java -jar build/libs/CoapServer.jar如果你的运行环境是 JDK 8 及以上且工程不依赖 Android SDK上面两条命令足以让服务在本地 5683 端口跑起来。日志输出里会打印注册的全部资源路径包括/.well-known/core这个 CoAP 标准要求的资源发现端点。5.2 Android 服务端真机部署与权限配置Android 端通过 Android Studio 构建出 APK 并在真机安装。关键配置在AndroidManifest.xml中manifest xmlns:androidhttp://schemas.android.com/apk/res/android !-- UDP socket 与 Wifi 锁需要这两个权限 -- uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.ACCESS_NETWORK_STATE / uses-permission android:nameandroid.permission.ACCESS_WIFI_STATE / uses-permission android:nameandroid.permission.WAKE_LOCK / uses-permission android:nameandroid.permission.FOREGROUND_SERVICE / application service android:name.CoapService / /application /manifest权限注释已经标清楚了每个权限的作用——INTERNET用于创建 socketWAKE_LOCK用于保持 CPU 和 Wifi 状态。Android 端需要注意一个细节如果测试时手机和 PC 连接的不是同一个热点例如手机开热点给 PC 上网或者反过来UDP 报文到达目标地址的路径会完全不同导致收包异常。调试时优先保持 PC 与 Android 设备在同一局域网段内。5.3 客户端联调用命令行工具验证服务端行为服务端跑起来之后需要验证它是否正确响应。如果开发机上装有coap-client工具可以直接用它发起请求# 发送 GET 请求获取温度资源的值 coap-client -m get coap://192.168.1.100:5683/sensors/temperature # 带详细调试信息查看报文中的 Token、Options、响应码 coap-client -m get -v 6 coap://192.168.1.100:5683/.well-known/core第一条命令作为功能自测第二条命令用于查看资源发现列表。.well-known/core是 CoAP 标准的资源发现端点里面会打印所有已注册资源的 URI 路径和属性。如果第二条约定的输出里没有你要访问的资源路径说明资源注册有问题——回到 3.3 节检查路径映射。这里建议每个资源在开发阶段都给 GET 方法加上简单可读的文本反馈方便直接用命令行排查。6. 二次开发与改造从资源模型到设备接入平台的落地路径6.1 改造一把资源树改造成设备影子模型如果只是跑通 Demo3.3 节那个温度资源已经够用。真实设备接入场景里通常没有“单一资源”的概念而是一台设备对应一组资源开关状态、运行时长、电量、告警事件、固件版本等。我的做法是引入一个设备管理器把设备数据存进一个 DeviceData 对象里资源处理器全部转化为对 DeviceData 的读写操作// 设备统一切换到设备影子模型后资源处理器的职责大幅简化 public class SwitchResource extends CoapResource { private final DeviceData deviceData; public SwitchResource(DeviceData deviceData) { super(switch); this.deviceData deviceData; } Override public void handleGET(CoapExchange exchange) { exchange.respond(ResponseCode.CONTENT, deviceData.isSwitchOn() ? on : off); } Override public void handlePUT(CoapExchange exchange) { String payload exchange.getRequestText().trim(); deviceData.setSwitchOn(on.equals(payload)); exchange.respond(ResponseCode.CHANGED); } }对于设备接入平台的语义来说改造后的 GET 不再直接读传感器硬件而是读一份内存缓存的数据PUT 也不再直接驱动 GPIO而是先写缓存、再异步通知硬件执行。这种解耦的价值在项目后续引入 MQTT 网关或云平台同步时尤其明显——设备影子可以作为云与端之间的缓冲层网络抖动时云侧读到的是设备的最后状态而不是因为网络中断读不到数据。6.2 改造二接入观察者模式实现状态主动推送观察者模式在 3.4 节提到过它落地到真实项目里最典型的需求场景是开关状态变化时服务端主动推送新状态给订阅方。这在智能家居网关项目里属于标配能力——客户端和网关在局域网内建立 Observe 关系后用户控制设备的操作不再需要客户端定时轮询。改造时需要注意观察者列表的容量控制一个资源如果同时被多个客户端观察服务端需要剔除心跳过期的观察者否则资源变化时会向死掉的对端持续推送浪费带宽。实现上我一般会给 DeviceData 加一个监听器列表当setSwitchOn()被调用时遍历所有注册观察者并调用changed()通知方法交由协议层封装成 CON 消息分发给每个观察者。这个过程中 Token 的匹配完全由协议层处理业务层只需保证回调发生在合适的线程即可。6.3 改造三与上层平台的数据同步如果你的项目最终需要接入云端CoAP 服务端在局域网内承担的职责是“南向接口”云端同步则是“北向接口”。建议在服务端的基础模块上增加一个定时同步器每 30 秒读取一次所有 DeviceData 变化状态通过 HTTP 或 MQTT 把增量数据上报到云端平台。此时影子模型的价值再次体现——同步器只需读取内存中的 DeviceData完全不用感知 CoAP 协议细节。反过来云端下发的指令也先进 DeviceData再由 Observe 机制推给终端设备形成闭环。我在几次项目里最深的感受是CoAP 服务端能不能跑通很多时候取决于你有没有把问题拆到正确的层级。凡是“响应时好时坏”“局域网可以外网不行”“服务跑几天挂一次”基本都能归因到传输层的网络锁和重传机制。从那以后我每完成一个改造点都要强制走一遍“本机客户端请求 → 抓包对比报文 → 检查观察者连接状态”的完整链路确认链路每个环节都符合预期才敢交付。希望这篇拆解能帮你把项目跑起来少走几趟我之前踩过的弯路。本文还有配套的精品资源点击获取