Java充电桩协议库JCPP：统一云快充、南网104等协议解析与实践

简介：JAVA 充电桩协议库（JCPP）配套完整开源充电平台源码，面向充电桩运营平台开发者、协议对接工程师及物联网学习者，解决多厂商充电桩协议适配、互联互通、多租户与分时计费等核心问题。包内包含 586 个文件，整合 SpringCloud、MySQL、Netty 与 uniapp 技术栈，尤其以 468 个 Java 源文件为主，配合 XML/YML/Properties 配置、Proto 协议定义、TSX 前端组件及 Dockerfile、SQL 脚本，覆盖后端服务、协议解析、管理后台、小程序和模拟桩完整链路。压缩包大小约 1.06MB，目录结构清晰，适合快速搭建环境并二次开发。已有 72 人学习，适合希望落地充电桩云平台并深入理解云快充 1.5/1.6、南网 104、互联互通等多协议细节的中高级开发者。

1. 充电桩协议库JAVA实现：为什么说JCPP是绕不开的集成层

做充电运营平台的朋友应该都有过这种经历：平台本身跑得挺稳，但接充电桩时被协议折腾到怀疑人生。云快充一套报文，南网104又是另一套，京能、绿能、挚达、星星、领充、EN+各自为政，每个桩企的文档风格还不一样，有的给完整示例，有的只甩过来一个 PDF 让你自己对着抓包。这个 JAVA 充电桩协议库 JCPP（Java Charging Pile Protocol）就是干这个事的——把国内主流的充电桩协议统一封装成一套可调用的接口，让上层业务不用关心底层报文差异。它对充电协议做了抽象，屏蔽了各家桩企的私有字段、时序和鉴权方式，适合正在做充电平台、桩企管理后台或者新能源运营系统的 Java 工程师直接拿来用。

2. 协议库的技术底座：JCPP 的模块划分与选型理由

2.1 协议解析层的设计思路：状态机 + 报文适配

JCPP 这类协议库最核心的不是通信，而是报文解析。充电桩和平台之间走的是 TCP 长连接，报文格式从十六进制到 JSON 都有，而且同一个协议里还存在版本差异。JCPP 的做法是典型的"协议适配器 + 状态机"两层结构：适配器负责把桩端发来的原始字节流转成内部统一的事件模型，状态机负责跟踪每把充电枪当前处于什么阶段——空闲、插枪、鉴权、充电中、结束。

这样做的好处是上层业务不用关心桩端到底什么时候会主动上报状态。你只需要监听充电状态变更事件，剩下的事情状态机帮你兜住。比如云快充协议里，桩端可能会在充电过程中多次推送实时数据，每次推送的字段还不完全一样，有电压电流、有SOC、有累计电量。如果这些数据直接抛给上层，业务方就得自己拼状态，很容易漏算。JCPP 把同一充电订单的多次上报合并成一个连续的状态流，业务层拿到的永远是"当前订单的最新完整快照"。

// 协议层处理入口：统一接收桩端上报的原始报文 public class ProtocolDispatcher { private final Map<String, ProtocolAdapter> adapters; public void onReceive(String pileCode, byte[] rawData) { // 根据桩编码找到对应协议适配器，如 CloudQuickAdapter / SouthNet104Adapter ProtocolAdapter adapter = adapters.get(pileCode); // 适配器将原始报文解析为统一的 ChargeEvent ChargeEvent event = adapter.decode(rawData); // 事件交给状态机，由状态机决定是否更新订单快照 stateMachine.handle(pileCode, event); } }

这段代码是整个协议库的入口逻辑：pileCode是桩的唯一编码，它决定了走哪个适配器；decode把不同协议的报文转成统一的ChargeEvent；状态机只认事件，不认协议。也就是说，不管底层是十六进制帧还是 JSON，到了状态机这一层全是同一种对象。关键参数是pileCode到适配器的映射关系，这个映射一定要确保每个桩编码只对应一个协议，否则同一个桩同时被两个适配器解析，状态会直接乱掉。

2.2 七种协议栈的差异：云快充、南网104等如何共存

JCPP 支持云快充、南网104、京能、绿能、挚达、星星、领充、EN+ 这些协议，但它们的差异不是一个模子里刻出来的。云快充是国内运营平台覆盖率最高的协议，报文偏 JSON，字段命名和国标接近，文档也相对规范，适合做主协议。南网104 是偏电力系统风格的协议，报文里有大量 BCD 编码的小数字段，像 BCD 码的电量、BCD 的电压，解析时得注意字节序和压缩格式。

京能和绿能的协议介于两者之间，走的也是 TCP 长连接，但心跳和鉴权时序有各自的规定。挚达、星星、领充、EN+ 这些桩企协议更多是私有协议，有的基于 Modbus 变种，有的在 TCP 层直接定义了私有帧头。JCPP 的设计原则是"协议隔离、数据统一"——每种协议一个包，互不依赖，编译期就避免互相污染。这样当你只需要接云快充时，可以只引入对应模块，不需要把整个协议库全量加载。

实际集成时，JCPP 暴露的接口是相同的，区别只在配置上：

# jcpp-config.properties # 云快充协议配置 jcpp.protocol.cloudquick.pile-prefix=CQ jcpp.protocol.cloudquick.host=127.0.0.1 jcpp.protocol.cloudquick.port=8300 # 南网104协议配置 jcpp.protocol.southnet104.pile-prefix=SN jcpp.protocol.southnet104.host=127.0.0.1 jcpp.protocol.southnet104.port=8400

pile-prefix是桩编码前缀，框架通过前缀快速路由到对应协议栈。host和port是平台侧开启的监听端口，桩端主动连过来。注意这里的方向：常规情况下是桩主动连平台，所以平台侧是个 TCP Server，而不是去连桩。很多新手第一次接协议时默认平台是客户端，容易把方向搞反。如果一个平台同时接多个协议，就把每个协议的监听端口分开，避免端口冲突。

2.3 加桩流程中 JCPP 扮演的角色

运营平台加一个新型号的桩时，最怕的是"桩上线了但数据全乱"。JCPP 把加桩流程拆成了三个可验证的节点：通道注册、心跳保持、业务上报。通道注册阶段会校验桩编码和协议类型是否匹配，不匹配直接拒绝连接，而不是等到后面解析报文时抛异常。心跳保持阶段由 JCPP 内部定时器驱动，不需要业务层参与，如果协议要求 30 秒一次心跳，你只需要在配置里写好间隔即可。

业务上报阶段是真正处理充电数据的地方。JCPP 会把实时数据、账单数据、故障数据分开路由，各自对应一个事件回调。这样平台侧的架构就可以按业务域拆分处理逻辑，不需要一个类里堆几百个 if-else。所以在团队里，后端同学只需要关注事件回调里的业务实现，协议细节全部由 JCPP 消化。

3. 落地集成：把 JCPP 跑起来的完整操作

3.1 依赖引入与初始化的顺序

拿到 JCPP 源码包后，不要急着改业务代码，先把协议库作为一个独立模块编进项目。它是标准的 Maven 工程，目录结构里协议实现都在src/main/java下跟着包名走，resources下是协议模板和配置样例。如果只是做桩端协议适配，建议把它打成 jar 引入现有 Spring Boot 或 SSM 项目，避免源码直接混进业务工程里。

# 先编协议库本体，跳过测试减少干扰 mvn clean install -DskipTests # 编译产物会生成在 target/jcpp-core-x.x.x.jar

这里有个习惯问题：我一般会先把协议库单独装到本地仓库，业务工程通过坐标依赖引用。这样协议库升级时，业务代码不用重新编译，只要换 jar 版本即可。-DskipTests要保留，协议库的测试依赖模拟桩端环境，本地没有模拟器时跑测试很容易报连接超时，跟代码质量没有关系。

依赖引入后，初始化顺序很关键。先初始化协议路由表，再启动 TCP 监听，最后再执行业务监听器注册。顺序反了会出现在监听器还没就绪时，桩端已经连上来并推送数据，导致部分事件丢失。JCPP 内部有事件缓冲队列，但队列有上限，满时会丢弃最旧的事件，所以初始化顺序不要省。

3.2 协议通道绑定与桩端握手

桩端上线第一个动作是发送握手报文，附上桩编码和协议版本号。JCPP 拿到这个报文后做两件事：核对桩编码前缀是否存在于路由表，然后回发握手确认帧。这个握手过程不是简单的 TCP accept，而是协议层业务握手——没通过校验的连接会被直接关闭，即使 TCP 层面还通着。

// 通道启动示例：注册监听端口并绑定协议 public void startGateway() { JcppGateway gateway = new JcppGateway(); // 端口 8300 跑云快充协议 gateway.registerListener(8300, "CLOUD_QUICK", (channel, event) -> { if (event.getType() == EventType.CHARGING_PUSH) { // 实时电量上报，这里更新充电中订单 handleChargingData(event.getPileCode(), event.getPayload()); } }); // 端口 8400 跑南网104协议 gateway.registerListener(8400, "SOUTH_NET_104", (channel, event) -> { if (event.getType() == EventType.ORDER_FINISH) { // 订单结束，这里结算账单 settleOrder(event.getPileCode(), event.getPayload()); } }); gateway.start(); }

这段代码展示了 JCPP 最典型的用法：registerListener把端口和协议绑定，第二个参数是协议类型，第三个参数是事件回调。EventType.CHARGING_PUSH表示充电过程中的实时数据推送，EventType.ORDER_FINISH表示充电订单结束。业务层只需要判断事件类型，不需要知道报文长什么样。参数说明：如果同一协议需要部署多个端口，比如按区域拆分，每秒新增的registerListener调用会创建独立的协议处理器实例，彼此状态互不影响。

3.3 一个下单充电的最小实现

充电业务里最常用的操作是远程启动充电。对应到 JCPP 里，就是向下发一条启动充电指令，并等待桩端返回确认。不同协议的指令帧格式不同，但经过 JCPP 封装后，调用方式收敛为一个方法：

public void startCharge(String pileCode, String orderId, int gunNo, int feePolicyId) { StartChargeRequest request = new StartChargeRequest(); request.setOrderId(orderId); request.setGunNo(gunNo); request.setFeePolicyId(feePolicyId); // 协议库根据 pileCode 自动选用对应协议的启动帧格式 CommandResult result = jcppGateway.sendStartChargeCommand(pileCode, request); if (result.isSuccess()) { // 启动指令被桩端确认，订单状态转为"充电中" orderService.markCharging(orderId); } else { // 桩端拒绝或超时，需要记录原因码 orderService.markFailed(orderId, result.getErrorCode()); } }

这里值得留意的是sendStartChargeCommand的返回值只代表"桩端确认收到指令"，并不代表"枪已经开始充电"。云快充协议里，平台下发启动后，桩端可能延迟几秒才真正吸合继电器，所以更稳的做法是监听后续的充电状态推送事件，以推送事件作为订单状态流转的最终依据。feePolicyId是计费策略编号，不同桩群可能维护不同的费率模板，这个参数要确保在桩端已存在，否则桩端会返回"计费策略不存在"而拒绝启动。

4. 协议参数对照：云快充、南网104等充电桩协议报文要点

拿到协议库后，第一件事不是写代码，而是先建立一张参数对照表。不同协议的心跳间隔、报文头格式、计费精度差别很大，把这些参数摸清楚，后面排查问题会快很多。

这张表是我从 JCPP 源码的协议模板里整理的，不同版本可能略有出入。重点看两个字段：心跳间隔和计费字段精度。心跳间隔直接决定桩的离线判定时间，如果平台侧设置的心跳超时太短，桩端偶尔网络抖动就会被误判离线。计费字段精度是账目的关键，南网104 的 4 位小数精度如果按 2 位去解析，长期跑下来账单金额会出偏差。JCPP 在解析时已经按各协议原生的精度处理了，但如果你在业务层二次计算时用了double，小数的精度损失会被放大，这一点下文避坑部分会再提。

报文格式差异直接关系到传输层的解析方式。云快充的 JSON 报文可以直接用 Jackson 映射对象，但南网104 的 BCD 编码需要先把二进制帧转成字符串，再按字段长度切分。JCPP 已经把这一层封装好了，但你排查问题时要知道这个背景：看到日志里出现乱码一样的十六进制内容，那不是日志编码坏了，而是 BCD 报文的原始形态。

5. 避坑指南：充电桩协议库 JAVA 集成常见问题与排查

5.1 现象：桩端持续连接又断开，日志反复出现“握手失败”

原因：桩编码前缀没有正确映射到协议类型。JCPP 的路由规则是按pile-prefix匹配，如果配置里写了CQ前缀，但实际桩编码以CZ开头，协议库无法识别，直接拒绝握手。

解决：核对桩端实际编码的前几位字符，统一修改配置。另外注意，有些桩企允许自定义桩编码前缀，如果现场桩编码被人为改过，要和桩端运维确认后用新前缀配置，而不是凭文档猜测。

5.2 现象：订单结算金额与桩端屏幕显示不一致，差几分钱

原因：典型的计费精度丢失。以云快充为例，协议里电量单位是“度”，精度到小数点后 2 位，但部分平台在业务层为了计算方便，先把电量转成double再乘电价，double在乘除中会引入无规律的精度误差。

解决：业务层统一用BigDecimal，并且明确 scale。电量、电价、服务费全部按协议定义的小数位截取，乘完后再截取一次，不要依赖数据库的浮点字段去约等。JCPP 解析出的原始电量是字符串或BigDecimal，不要为了图省事转成double再处理。

5.3 现象：充电过程中实时数据推送会偶发丢一条，但桩端显示正常

原因：事件队列积压。JCPP 内部有有界事件队列，当业务回调处理速度跟不上桩端上报频率时，队列满了会丢弃新事件。尤其是云快充这类 30 秒推送一次的协议，如果业务回调里做了数据库写操作且没有超时控制，很容易积压。

解决：回调里不要做重活，数据落库走异步线程池，回调只负责把数据扔进线程池就返回。队列大小可以在配置里调大，但根因是消费速度不够，异步化才是正解。

5.4 现象：南网104协议下，电压电流解析出来数值偏大十倍或百倍

原因：BCD 编码解析时字节序错位。南网104 报文里电压字段用的是压缩 BCD 码，一个字节存两位数字，比如实际电压 220.5V，报文里存的是22 05两个字节。如果按普通十六进制直接转整数，会得到 0x2205 也就是 8709，自然偏大。

解决：JCPP 内部已处理了 BCD 转换，但如果你在业务层再次对原始报文做校验，不要用现成的十六进制字符串转整数。直接引用 JCPP 解析后的字段对象，或者通过工具方法BcdUtil.toInt(byte[])转换。

5.5 现象：多把枪同时充电时，订单数据互相串

原因：状态机的 key 没有细化到枪号。一个桩通常有多把枪，如果协议库里状态机的 key 只用了桩编码，那同一桩下两把枪的充电状态会互相覆盖。

解决：确认 JCPP 版本中状态机的 key 是否包含枪号。如果源码里只用了pileCode，改成pileCode + ":" + gunNo。我遇到过不少二次开发者在协议库上做定制，只改了报文解析，漏了这个状态隔离，导致并发充电时订单混乱，这是最容易翻车的点之一。

6. 从能用跑到好用：调试技巧与扩展新协议

先把一个最实用的调试手段拿出来：JCPP 的日志默认没有开关控制，你要在 Logback 里单独给协议包开 DEBUG 级别，这样才能看到原始报文。别小看这一步，排查问题的时候，没有原始报文等于盲人摸象。

<!-- logback.xml 中单独开启协议库的报文日志 --> <logger name="com.jcpp.protocol.codec" level="DEBUG"/> <logger name="com.jcpp.transport.handler" level="DEBUG"/>

开 DEBUG 之后，日志里会输出收发帧的完整内容。但注意，DEBUG 级别的报文日志会打印整个字节数组，如果有一把枪正在充电，数据量会很大，建议只在预发环境或者测试桩上打开，不要在生产环境全天开着。

验证协议库是否正常工作，最直接的方法是模拟桩端回包。把 JCPP 的监听端口视为平台侧服务，你可以在本地写一个测试脚本模拟桩端连接，逐条发送协议样例中的充电报文，观察 JCPP 事件回调是否被正确触发。

# 用 nc 模拟桩端，发送一条云快充心跳报文（十六进制帧样例） printf '{"type":"heartbeat","pile_code":"CQ000001","ts":"2025-05-20 10:00:00"}' | nc -q 5 127.0.0.1 8300

这里要强调的是，nc发送的是样例报文，实际业务中被 JCPP 封装的握手报文不会这么简单。所以我一般更推荐直接用协议库自带的模拟器包，如果源码包里没有，就整理日志里抓到的真实桩端报文，做成离线回放脚本，每次改完代码都用同一组报文跑回归。这样改协议库不会引入新的解析回归。

扩展新协议时，不要从零写适配器。先从现有协议里复制一个结构最接近的适配器，比如新增一个和云快充报文风格类似的桩企协议，就复制CloudQuickAdapter，改报文类型映射和必填字段校验，然后跑一遍回放脚本。JCPP 的适配器接口是关键：decode是入口，encode是出口，指令下发路径改encode，上报解析路径改decode，两边独立验证。

从那以后我每次接新协议都会先走一遍这个流程：先抄最接近的适配器，改完立刻用报文回放做回归，最后再写业务对接。这套流程救过我很多次，尤其是南网104 那种 BCD 编码的协议，不靠回放脚本很难在一个下午内把字段全部对齐。希望帮到你。

本文还有配套的精品资源，点击获取