autumn/JChargePointProtocol
1
0
Fork 0
mirror of https://gitee.com/san-bing/JChargePointProtocol synced 2026-06-20 23:19:41 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
ea0feba4c1f0d7a899af57e210e15d009f310b74
JChargePointProtocol/docs/开发者指南.md

367 lines
12 KiB
Markdown
Raw Normal View History

wiki生成
2025-10-28 14:39:06 +08:00
# 开发者指南
<cite>
**本文档中引用的文件**
- [README.md](file://README.md)
- [pom.xml](file://pom.xml)
- [docker/start.sh](file://docker/start.sh)
- [docker/docker-compose.monolith.yml](file://docker/docker-compose.monolith.yml)
- [jcpp-app-bootstrap/src/main/resources/app-service.yml](file://jcpp-app-bootstrap/src/main/resources/app-service.yml)
- [jcpp-protocol-bootstrap/src/main/resources/protocol-service.yml](file://jcpp-protocol-bootstrap/src/main/resources/protocol-service.yml)
- [jcpp-app-bootstrap/src/main/java/sanbing/jcpp/JCPPServerApplication.java](file://jcpp-app-bootstrap/src/main/java/sanbing/jcpp/JCPPServerApplication.java)
- [jcpp-protocol-bootstrap/src/main/java/sanbing/jcpp/protocol/JCPPProtocolServiceApplication.java](file://jcpp-protocol-bootstrap/src/main/java/sanbing/jcpp/protocol/JCPPProtocolServiceApplication.java)
- [jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java)
- [jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolMessageProcessor.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolMessageProcessor.java)
- [jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java)
- [jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/v340/LvnengV340ProtocolBootstrap.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/v340/LvnengV340ProtocolBootstrap.java)
- [jcpp-app/src/main/java/sanbing/jcpp/app/service/impl/DefaultPileProtocolService.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/service/impl/DefaultPileProtocolService.java)
- [jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/RpcController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/RpcController.java)
- [jcpp-web-ui/package.json](file://jcpp-web-ui/package.json)
</cite>
## 目录
1. [环境搭建](#环境搭建)
2. [代码获取与构建](#代码获取与构建)
3. [本地运行](#本地运行)
4. [开发新协议](#开发新协议)
5. [调试技巧](#调试技巧)
## 环境搭建
在开始开发之前，需要安装以下必要的开发工具：
1. **JDK 21**：本项目基于Java 21开发，需安装JDK 21并配置JAVA_HOME环境变量。
2. **Maven**：用于构建Java后端模块，建议使用最新稳定版本。
3. **Node.js**：用于构建前端项目，建议使用LTS版本（如v18或v20）。
4. **Docker**：用于启动依赖服务（PostgreSQL, Redis, Kafka等），建议安装最新稳定版。
安装完成后，可通过以下命令验证：
```bash
java -version
mvn -version
node --version
docker --version
```
**Section sources**
- [pom.xml](file://pom.xml#L15-L20)
- [jcpp-web-ui/package.json](file://jcpp-web-ui/package.json#L1-L10)
## 代码获取与构建
### 代码获取
使用Git克隆项目仓库：
```bash
git clone https://github.com/sanbing-java/JChargePointProtocol.git
cd JChargePointProtocol
```
### 后端构建
项目包含多个Maven模块，主要后端模块包括`jcpp-app`和`jcpp-protocol-*`系列模块。
构建所有模块：
```bash
mvn clean install -DskipTests
```
仅构建特定模块（如`jcpp-app`）：
```bash
cd jcpp-app
mvn clean package -DskipTests
```
### 前端构建
前端项目位于`jcpp-web-ui`目录，使用npm进行构建。
进入前端目录并安装依赖：
```bash
cd jcpp-web-ui
npm install
```
构建生产版本：
```bash
npm run build
```
启动开发服务器：
```bash
npm start
```
**Section sources**
- [pom.xml](file://pom.xml#L100-L120)
- [jcpp-web-ui/package.json](file://jcpp-web-ui/package.json#L10-L20)
## 本地运行
### 启动依赖服务
项目依赖PostgreSQL、Redis和Kafka等服务，可通过Docker Compose一键启动。
使用提供的启动脚本：
```bash
bash docker/start.sh
```
或手动执行Docker Compose命令：
```bash
docker-compose -f docker/docker-compose.postgres.yml -f docker/docker-compose.redis-standalone.yml -f docker/docker-compose.kafka.yml up -d
```
### 启动应用服务
项目包含两个核心启动模块：`jcpp-app-bootstrap`（应用后端）和`jcpp-protocol-bootstrap`（协议前置）。
1. 启动应用后端服务：
```bash
cd jcpp-app-bootstrap
mvn spring-boot:run
```
2. 启动协议前置服务：
```bash
cd jcpp-protocol-bootstrap
mvn spring-boot:run
```
服务启动后，可通过以下地址访问：
- 应用后端API：http://localhost:8080
- 协议服务gRPC端口：9090
- 管理后台：http://localhost:8080/page/dashboard
```mermaid
graph TD
A[Docker Compose] --> B[PostgreSQL]
A --> C[Redis]
A --> D[Kafka]
E[jcpp-app-bootstrap] --> B
E --> C
F[jcpp-protocol-bootstrap] --> D
F --> C
E --> G[前端UI]
F --> E
```
**Diagram sources**
- [docker/docker-compose.monolith.yml](file://docker/docker-compose.monolith.yml#L1-L20)
- [jcpp-app-bootstrap/src/main/resources/app-service.yml](file://jcpp-app-bootstrap/src/main/resources/app-service.yml#L1-L50)
- [jcpp-protocol-bootstrap/src/main/resources/protocol-service.yml](file://jcpp-protocol-bootstrap/src/main/resources/protocol-service.yml#L1-L50)
**Section sources**
- [docker/start.sh](file://docker/start.sh#L1-L20)
- [jcpp-app-bootstrap/src/main/java/sanbing/jcpp/JCPPServerApplication.java](file://jcpp-app-bootstrap/src/main/java/sanbing/jcpp/JCPPServerApplication.java#L1-L20)
- [jcpp-protocol-bootstrap/src/main/java/sanbing/jcpp/protocol/JCPPProtocolServiceApplication.java](file://jcpp-protocol-bootstrap/src/main/java/sanbing/jcpp/protocol/JCPPProtocolServiceApplication.java#L1-L20)
## 开发新协议
以实现一个新的充电桩协议为例，说明开发流程。
### 继承ProtocolBootstrap
创建新的协议启动类，继承`ProtocolBootstrap`抽象类。参考现有协议实现，如`YunkuaichongV150ProtocolBootstrap`。
```java
@ProtocolComponent("NEW_PROTOCOL_V100")
public class NewProtocolV100Bootstrap extends ProtocolBootstrap {
@Override
protected String getProtocolName() {
return "NEW_PROTOCOL_V100";
}
@Override
protected void _init() {
// 初始化逻辑
}
@Override
protected void _destroy() {
// 销毁逻辑
}
@Override
protected ProtocolMessageProcessor messageProcessor() {
return new NewProtocolMessageProcessor(forwarder, protocolContext);
}
}
```
### 实现消息处理器
创建消息处理器类，继承`ProtocolMessageProcessor`，实现上行和下行消息处理逻辑。
```java
public class NewProtocolMessageProcessor extends ProtocolMessageProcessor {
public NewProtocolMessageProcessor(Forwarder forwarder, ProtocolContext protocolContext) {
super(forwarder, protocolContext);
}
@Override
protected void uplinkHandle(ListenerToHandlerMsg listenerToHandlerMsg) {
// 处理上行消息
}
@Override
protected void doDownlinkHandle(SessionToHandlerMsg sessionToHandlerMsg) {
// 处理下行消息
}
}
```
### 定义命令类
根据协议规范定义上行和下行命令类，通常包含消息头、消息体、校验等字段。
### 配置文件注册
在`protocol-service.yml`中注册新协议的配置，包括监听端口、转发方式等。
```yaml
service:
protocols:
newProtocolV100:
enabled: true
listener:
tcp:
bind-port: 38021
forwarder:
type: kafka
```
```mermaid
classDiagram
class ProtocolBootstrap {
+init()
+destroy()
+health()
+getProtocolName()
+_init()
+_destroy()
+messageProcessor()
}
class NewProtocolV100Bootstrap {
+getProtocolName()
+_init()
+_destroy()
+messageProcessor()
}
class ProtocolMessageProcessor {
+uplinkHandleAsync()
+downlinkHandle()
+uplinkHandle()
+doDownlinkHandle()
}
class NewProtocolMessageProcessor {
+uplinkHandle()
+doDownlinkHandle()
}
ProtocolBootstrap <|-- NewProtocolV100Bootstrap
ProtocolMessageProcessor <|-- NewProtocolMessageProcessor
NewProtocolV100Bootstrap --> NewProtocolMessageProcessor : "creates"
```
**Diagram sources**
- [jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java#L1-L50)
- [jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolMessageProcessor.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolMessageProcessor.java#L1-L30)
- [jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java#L1-L20)
**Section sources**
- [jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolBootstrap.java#L1-L127)
- [jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolMessageProcessor.java](file://jcpp-protocol-api/src/main/java/sanbing/jcpp/protocol/ProtocolMessageProcessor.java#L1-L78)
- [jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java](file://jcpp-protocol-yunkuaichong/src/main/java/sanbing/jcpp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java#L1-L48)
- [jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/v340/LvnengV340ProtocolBootstrap.java](file://jcpp-protocol-lvneng/src/main/java/sanbing/jcpp/protocol/lvneng/v340/LvnengV340ProtocolBootstrap.java#L1-L48)
## 调试技巧
### 查看日志
应用日志默认输出到控制台，并保存在`logs/`目录下。关键日志文件包括：
- `logs/accesslog/`：HTTP访问日志
- `logs/gc/gc.log`：JVM GC日志
- `logs/heapdump/`：内存溢出时的堆转储文件
可通过配置`app-service.yml`调整日志级别：
```yaml
logging:
level:
sanbing: DEBUG
```
### 远程调试
通过JVM参数启用远程调试，修改启动脚本`docker/start.sh`：
```bash
export JAVA_OPTS_EXTEND="-Xdebug -Xrunjdwp:transport=dt_socket,address=0.0.0.0:8000,server=y,suspend=n"
```
在IDE中配置远程调试连接：
- 主机：localhost
- 端口：8000
- 调试器：Java
### RPC调用调试
通过`RpcController`提供的API接口发送调试指令：
```bash
curl -X POST http://localhost:8080/api/rpc/oneway \
-H "Content-Type: application/json" \
-d '{
"method": "startCharge",
"parameter": {"pileCode": "P123", "gunNo": "1"}
}'
```
```mermaid
sequenceDiagram
participant Dev as 开发者
participant IDE as IDE
participant App as jcpp-app-bootstrap
participant Protocol as jcpp-protocol-bootstrap
Dev->>IDE : 配置远程调试
IDE->>App : 连接调试端口8000
Dev->>App : 发送RPC指令
App->>Protocol : 通过Kafka转发
Protocol->>App : 处理协议消息
App-->>Dev : 返回响应结果
```
**Diagram sources**
- [jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/RpcController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/RpcController.java#L1-L70)
- [docker/start.sh](file://docker/start.sh#L15-L18)
- [jcpp-app-bootstrap/src/main/resources/app-service.yml](file://jcpp-app-bootstrap/src/main/resources/app-service.yml#L1-L10)
**Section sources**
- [docker/start.sh](file://docker/start.sh#L15-L18)
- [jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/RpcController.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/adapter/controller/RpcController.java#L30-L150)
- [jcpp-app/src/main/java/sanbing/jcpp/app/service/impl/DefaultPileProtocolService.java](file://jcpp-app/src/main/java/sanbing/jcpp/app/service/impl/DefaultPileProtocolService.java#L1-L1000)
Reference in New Issue Copy Permalink