mirror of https://gitee.com/san-bing/JChargePointProtocol synced 2026-07-14 02:37:57 +08:00

Files

三丙 fa9524d302 wiki生成

2025-10-28 14:39:06 +08:00

19 KiB

Raw Blame History

云快充协议实现

**本文档中引用的文件** - [YunkuaichongV150ProtocolBootstrap.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java) - [YunkuaichongV160ProtocolBootstrap.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v160/YunkuaichongV160ProtocolBootstrap.java) - [YunkuaichongV170ProtocolBootstrap.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v170/YunkuaichongV170ProtocolBootstrap.java) - [YunKuaiChongProtocolMessageProcessor.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/YunKuaiChongProtocolMessageProcessor.java) - [ProtocolBootstrap.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java) - [ProtocolCmd.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/annotation/ProtocolCmd.java) - [ProtocolCommandRouter.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/routing/ProtocolCommandRouter.java) - [DownlinkController.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/adapter/DownlinkController.java) - [YunKuaiChongDownlinkCmdExe.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/YunKuaiChongDownlinkCmdExe.java) - [YunKuaiChongV150HeartbeatULCmd.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/cmd/YunKuaiChongV150HeartbeatULCmd.java) - [TcpChannelHandler.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/listener/tcp/TcpChannelHandler.java) - [YunKuaiChongProtocolConstants.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/YunKuaiChongProtocolConstants.java) - [DownlinkCmdEnum.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/domain/DownlinkCmdEnum.java)

简介

云快充协议是一个专为电动汽车充电站设计的通信协议实现，采用模块化架构支持多个协议版本（v150、v160、v170），提供了完整的上行和下行消息处理能力。该协议实现了基于Netty的高性能TCP通信，支持心跳检测、远程控制、参数配置等核心功能。

项目结构

云快充协议的项目结构遵循分层架构设计，主要包含以下模块：

graph TB
subgraph "协议API层"
API[Protocol API]
Bootstrap[Protocol Bootstrap]
MessageProcessor[Message Processor]
end
subgraph "云快充实现层"
V150[Version 1.5.0]
V160[Version 1.6.0]
V170[Version 1.7.0]
Constants[Protocol Constants]
end
subgraph "命令处理层"
UplinkCmd[Uplink Commands]
DownlinkCmd[Downlink Commands]
Router[Command Router]
end
API --> Bootstrap
Bootstrap --> MessageProcessor
MessageProcessor --> V150
MessageProcessor --> V160
MessageProcessor --> V170
V150 --> UplinkCmd
V150 --> DownlinkCmd
Router --> UplinkCmd
Router --> DownlinkCmd

图表来源

章节来源

核心组件

YunkuaichongV150ProtocolBootstrap

YunkuaichongV150ProtocolBootstrap 是云快充协议的核心入口点，负责协议的初始化和配置。它继承自 ProtocolBootstrap ，实现了协议的基本生命周期管理。

主要特性：

协议标识：使用 @ProtocolComponent 注解标记协议名称
消息处理器：创建并返回 YunKuaiChongProtocolMessageProcessor 实例
版本支持：支持 v150、v160、v170 三个版本

初始化流程：

sequenceDiagram
participant Bootstrap as YunkuaichongV150ProtocolBootstrap
participant Parent as ProtocolBootstrap
participant Processor as MessageProcessor
participant Listener as TCP Listener
Bootstrap->>Parent : init()
Parent->>Parent : loadConfig(protocolName)
Parent->>Parent : createForwarder()
Parent->>Listener : new TcpListener()
Bootstrap->>Processor : new YunKuaiChongProtocolMessageProcessor()
Processor->>Processor : initializeRouters()
Processor-->>Bootstrap : 返回处理器实例

图表来源

YunKuaiChongProtocolMessageProcessor

这是协议消息处理的核心组件，负责解析原始字节流并路由到具体的命令处理器。

核心功能：

上行消息处理：解析TCP接收到的原始字节流
下行消息处理：处理来自REST API的下行请求
命令路由：使用 ProtocolCommandRouter 进行命令分发
校验和验证：支持多种校验和算法

章节来源

架构概览

云快充协议采用分层架构，从底层的网络通信到高层的业务逻辑处理：

graph TB
subgraph "应用层"
REST[REST API Controller]
GRPC[gRPC Service]
end
subgraph "协议层"
Bootstrap[Protocol Bootstrap]
MessageProcessor[Message Processor]
Router[Command Router]
end
subgraph "传输层"
TCP[TCP Listener]
ChannelHandler[TCP Channel Handler]
end
subgraph "网络层"
Netty[Netty Framework]
Codec[Message Codec]
end
REST --> Bootstrap
GRPC --> Bootstrap
Bootstrap --> MessageProcessor
MessageProcessor --> Router
Router --> ChannelHandler
ChannelHandler --> TCP
TCP --> Netty
Netty --> Codec

图表来源

详细组件分析

协议命令注解系统

@ProtocolCmd 注解是云快充协议命令映射的核心机制：

classDiagram
class ProtocolCmd {
+int value()
+String[] protocolNames()
}
class YunKuaiChongV150HeartbeatULCmd {
+execute(TcpSession, YunKuaiChongUplinkMessage, ProtocolContext)
}
class ProtocolCommandRouter {
-Map~String,T~ executorMap
+getExecutor(String, int) T
+registerExecutor(Class)
}
ProtocolCmd --> YunKuaiChongV150HeartbeatULCmd : "注解"
ProtocolCommandRouter --> YunKuaiChongV150HeartbeatULCmd : "路由"

图表来源

注解机制工作原理：

扫描阶段：ProtocolCommandRouter 使用反射扫描带有 @ProtocolCmd 注解的类
注册阶段：将命令字与执行器类建立映射关系
路由阶段：根据协议名称和命令字查找对应的执行器

章节来源

上行命令处理流程

上行命令处理是协议的核心功能之一，负责解析设备发送的消息：

flowchart TD
Start([接收TCP消息]) --> ValidateHeader["验证协议头<br/>0x68开头"]
ValidateHeader --> ParseLength["解析数据长度字段"]
ParseLength --> ValidateBounds["边界检查<br/>确保消息完整"]
ValidateBounds --> ExtractFields["提取关键字段<br/>序列号、加密标志、帧类型"]
ExtractFields --> ChecksumValidation["校验和验证<br/>支持LE和BE两种格式"]
ChecksumValidation --> Success{"校验成功?"}
Success --> |否| LogError["记录错误日志"]
Success --> |是| ParseBody["解析消息体"]
ParseBody --> RouteCommand["路由到命令处理器"]
RouteCommand --> ExecuteCmd["执行具体命令"]
ExecuteCmd --> End([处理完成])
LogError --> End

图表来源

YunKuaiChongProtocolMessageProcessor.java

下行命令处理流程

下行命令处理负责响应REST API请求，向设备发送控制指令：

sequenceDiagram
participant Controller as DownlinkController
participant Session as TcpSession
participant Processor as MessageProcessor
participant Router as CommandRouter
participant Executor as CmdExecutor
participant Channel as TCP Channel
Controller->>Session : 查找会话
Session->>Processor : onDownlink(downlinkMsg)
Processor->>Processor : convertToCmd(downlinkCmd)
Processor->>Router : getExecutor(protocolName, cmd)
Router-->>Processor : 返回执行器
Processor->>Executor : execute(session, message, context)
Executor->>Executor : encodeAndWriteFlush()
Executor->>Channel : 写入TCP缓冲区
Channel-->>Controller : 返回响应

图表来源

章节来源

协议版本管理

云快充协议支持多个版本，每个版本都有自己的 ProtocolBootstrap 实现：

版本差异对比

功能特性	v150	v160	v170
基础协议	✓	✓	✓
并行启动	✗	✓	✓
新增命令	心跳、登录、对时	并行启动命令	交易记录命令
向后兼容	✓	✓	✓

版本兼容性策略

graph LR
subgraph "版本兼容性"
V150[v1.5.0]
V160[v1.6.0]
V170[v1.7.0]
end
subgraph "共享组件"
Common[公共命令集]
Router[统一路由]
Processor[通用处理器]
end
V150 --> Common
V160 --> Common
V170 --> Common
Common --> Router
Router --> Processor

图表来源

章节来源

命令处理机制

上行命令处理

以心跳命令为例，展示完整的命令处理流程：

classDiagram
class YunKuaiChongV150HeartbeatULCmd {
+execute(TcpSession, YunKuaiChongUplinkMessage, ProtocolContext)
-pingAck(TcpSession, YunKuaiChongUplinkMessage, byte[], byte)
}
class YunKuaiChongUplinkCmdExe {
<<abstract>>
+execute(TcpSession, YunKuaiChongUplinkMessage, ProtocolContext)*
+uplinkMessageBuilder(String, TcpSession, YunKuaiChongUplinkMessage)
+encodeAndWriteFlush(DownlinkCmdEnum, int, int, ByteBuf, TcpSession)
}
class YunKuaiChongUplinkMessage {
+int getCmd()
+byte[] getMsgBody()
+int getSequenceNumber()
+int getEncryptionFlag()
}
YunKuaiChongUplinkCmdExe <|-- YunKuaiChongV150HeartbeatULCmd
YunKuaiChongV150HeartbeatULCmd --> YunKuaiChongUplinkMessage : "使用"

图表来源

YunKuaiChongV150HeartbeatULCmd.java

下行命令处理

下行命令处理涉及REST API调用到设备响应的完整流程：

flowchart TD
RESTReq[REST请求] --> Controller[DownlinkController]
Controller --> Session[查找TCP会话]
Session --> MsgProc[MessageProcessor]
MsgProc --> Converter[命令转换器]
Converter --> Router[CommandRouter]
Router --> Executor[命令执行器]
Executor --> Encoder[消息编码]
Encoder --> TCP[发送到设备]
Controller --> Success[HTTP 200]
Controller --> Timeout[HTTP 408]
Controller --> NotFound[HTTP 404]
Controller --> Error[HTTP 500]

图表来源

章节来源

消息编解码流程

TCP消息处理

TcpChannelHandler 负责Netty框架层面的消息处理：

sequenceDiagram
participant Netty as Netty Channel
participant Handler as TcpChannelHandler
participant Processor as MessageProcessor
participant Stats as Metrics
Netty->>Handler : channelRead0(msg)
Handler->>Handler : process(msg)
Handler->>Processor : uplinkHandleAsync()
Processor->>Stats : 记录统计信息
Processor-->>Handler : 处理完成
Handler->>Handler : writeAndFlush()
Handler->>Netty : 写入响应

图表来源

TcpChannelHandler.java

消息格式规范

云快充协议的消息格式采用固定长度头部加可变长度体的设计：

字段	长度	描述
标识符	1字节	固定值 0x68
数据长度	1字节	包含头部的总长度
序列号	2字节	请求-响应配对
加密标志	1字节	0=明文，1=加密
帧类型	1字节	命令字
消息体	可变	具体命令数据
校验和	2字节	CRC校验

章节来源

性能考虑

异步处理机制

协议采用异步处理模式，避免阻塞主线程：

消息队列：使用Netty的事件循环处理消息
并发控制：支持多线程并发处理
内存优化：使用ByteBuf进行零拷贝操作

缓存策略

命令路由缓存：ProtocolCommandRouter 使用ConcurrentHashMap缓存命令映射
会话管理：TCP会话状态缓存
统计信息：实时监控指标缓存

错误处理

快速失败：无效消息立即丢弃
优雅降级：部分功能不可用时保持核心功能
日志记录：详细的错误日志便于问题排查

故障排除指南

常见问题及解决方案

1. 协议版本不匹配

症状：设备无法识别命令 解决方案：检查协议版本配置，确保客户端和服务端版本一致

2. 校验和错误

症状：日志显示校验失败 解决方案：检查消息编码和传输过程中的数据完整性

3. 命令路由失败

症状：未知命令错误日志 解决方案：确认命令注解配置正确，检查命令处理器注册

4. TCP连接问题

症状：连接频繁断开 解决方案：检查网络稳定性，调整心跳间隔配置

章节来源

YunKuaiChongProtocolMessageProcessor.java

结论

云快充协议实现展现了现代通信协议设计的最佳实践：

主要优势

模块化设计：清晰的分层架构便于维护和扩展
版本兼容性：支持多版本并保持向后兼容
高性能：基于Netty的异步处理机制
可扩展性：灵活的命令路由机制支持新功能添加
可靠性：完善的错误处理和监控机制

技术特色

注解驱动开发：简化命令注册和映射
统一消息处理：标准化的消息编解码流程
灵活的版本管理：支持协议演进和向后兼容
完善的监控体系：实时性能监控和错误追踪

19 KiB Raw Blame History Unescape Escape

云快充协议实现

目录

简介

项目结构

核心组件

YunkuaichongV150ProtocolBootstrap

主要特性：

初始化流程：

YunKuaiChongProtocolMessageProcessor

核心功能：

架构概览

详细组件分析

协议命令注解系统

注解机制工作原理：

上行命令处理流程

下行命令处理流程

协议版本管理

版本差异对比

版本兼容性策略

命令处理机制

上行命令处理

下行命令处理

消息编解码流程

TCP消息处理

消息格式规范

性能考虑

异步处理机制

缓存策略

错误处理

故障排除指南

常见问题及解决方案

1. 协议版本不匹配

2. 校验和错误

3. 命令路由失败

4. TCP连接问题

结论

主要优势

技术特色

19 KiB

Raw Blame History