开发者指南

目录

  1. 环境搭建
  2. 代码获取与构建
  3. 本地运行
  4. 开发新协议
  5. 调试技巧

环境搭建

在开始开发之前，需要安装以下必要的开发工具：

  1. JDK 21：本项目基于Java 21开发，需安装JDK 21并配置JAVA_HOME环境变量。
  2. Maven：用于构建Java后端模块，建议使用最新稳定版本。
  3. Docker：用于启动依赖服务（PostgreSQL, Redis, Kafka等），建议安装最新稳定版。

安装完成后，可通过以下命令验证：

java -version
mvn -version
docker --version

Section sources

  • [pom.xml](file://pom.xml#L15-L20)

后端构建

项目包含多个Maven模块，主要后端模块包括mp-app和mp-protocol-*系列模块。

构建所有模块：

mvn clean install -DskipTests

仅构建特定模块（如mp-app）：

cd mp-app
mvn clean package -DskipTests

启动依赖服务

项目依赖PostgreSQL、Redis和Kafka等服务，可通过Docker Compose一键启动。

使用提供的启动脚本：

bash docker/start.sh

或手动执行Docker Compose命令：

docker-compose -f docker/docker-compose.postgres.yml -f docker/docker-compose.redis-standalone.yml -f docker/docker-compose.kafka.yml up -d

启动应用服务

项目包含两个核心启动模块：mp-app-bootstrap（应用后端）和mp-protocol-bootstrap（协议前置）。

  1. 启动应用后端服务：
cd mp-app-bootstrap
mvn spring-boot:run
  1. 启动协议前置服务：
cd mp-protocol-bootstrap
mvn spring-boot:run

服务启动后，可通过以下地址访问：

  • 应用后端API：http://localhost:8080
  • 协议服务gRPC端口：9090
  • 管理后台：http://localhost:8080/page/dashboard
graph TD
A[Docker Compose] --> B[PostgreSQL]
A --> C[Redis]
A --> D[Kafka]
E[mp-app-bootstrap] --> B
E --> C
F[mp-protocol-bootstrap] --> D
F --> C
F --> E

Diagram sources

  • [docker/docker-compose.monolith.yml](file://docker/docker-compose.monolith.yml#L1-L20)
  • [mp-app-bootstrap/src/main/resources/app-service.yml](file://mp-app-bootstrap/src/main/resources/app-service.yml#L1-L50)
  • [mp-protocol-bootstrap/src/main/resources/protocol-service.yml](file://mp-protocol-bootstrap/src/main/resources/protocol-service.yml#L1-L50)

Section sources

  • [docker/start.sh](file://docker/start.sh#L1-L20)
  • [mp-app-bootstrap/src/main/java/com/witos/mp/MpServerApplication.java](file://mp-app-bootstrap/src/main/java/com/witos/mp/MpServerApplication.java#L1-L20)
  • [mp-protocol-bootstrap/src/main/java/com/witos/mp/protocol/MpProtocolServiceApplication.java](file://mp-protocol-bootstrap/src/main/java/com/witos/mp/protocol/MpProtocolServiceApplication.java#L1-L20)

开发新协议

以实现一个新的充电桩协议为例，说明开发流程。

继承ProtocolBootstrap

创建新的协议启动类，继承ProtocolBootstrap抽象类。参考现有协议实现，如YunkuaichongV150ProtocolBootstrap。

@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，实现上行和下行消息处理逻辑。

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中注册新协议的配置，包括监听端口、转发方式等。

service:
  protocols:
    newProtocolV100:
      enabled: true
      listener:
        tcp:
          bind-port: 38021
      forwarder:
        type: kafka

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

  • [mp-protocol-api/src/main/java/com/witos/mp/protocol/ProtocolBootstrap.java](file://mp-protocol-api/src/main/java/com/witos/mp/protocol/ProtocolBootstrap.java#L1-L50)
  • [mp-protocol-api/src/main/java/com/witos/mp/protocol/ProtocolMessageProcessor.java](file://mp-protocol-api/src/main/java/com/witos/mp/protocol/ProtocolMessageProcessor.java#L1-L30)
  • [mp-protocol-yunkuaichong/src/main/java/com/witos/mp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java](file://mp-protocol-yunkuaichong/src/main/java/com/witos/mp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java#L1-L20)

Section sources

  • [mp-protocol-api/src/main/java/com/witos/mp/protocol/ProtocolBootstrap.java](file://mp-protocol-api/src/main/java/com/witos/mp/protocol/ProtocolBootstrap.java#L1-L127)
  • [mp-protocol-api/src/main/java/com/witos/mp/protocol/ProtocolMessageProcessor.java](file://mp-protocol-api/src/main/java/com/witos/mp/protocol/ProtocolMessageProcessor.java#L1-L78)
  • [mp-protocol-yunkuaichong/src/main/java/com/witos/mp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java](file://mp-protocol-yunkuaichong/src/main/java/com/witos/mp/protocol/yunkuaichong/v150/YunkuaichongV150ProtocolBootstrap.java#L1-L48)
  • [mp-protocol-lvneng/src/main/java/com/witos/mp/protocol/lvneng/v340/LvnengV340ProtocolBootstrap.java](file://mp-protocol-lvneng/src/main/java/com/witos/mp/protocol/lvneng/v340/LvnengV340ProtocolBootstrap.java#L1-L48)

调试技巧

查看日志

应用日志默认输出到控制台，并保存在logs/目录下。关键日志文件包括：

  • logs/accesslog/：HTTP访问日志
  • logs/gc/gc.log：JVM GC日志
  • logs/heapdump/：内存溢出时的堆转储文件

可通过配置app-service.yml调整日志级别：

logging:
  level:
    com/witos: DEBUG

远程调试

通过JVM参数启用远程调试，修改启动脚本docker/start.sh：

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接口发送调试指令：

curl -X POST http://localhost:8080/api/rpc/oneway \
  -H "Content-Type: application/json" \
  -d '{
    "method": "startCharge",
    "parameter": {"pileCode": "P123", "gunNo": "1"}
  }'

sequenceDiagram
participant Dev as 开发者
participant IDE as IDE
participant App as mp-app-bootstrap
participant Protocol as mp-protocol-bootstrap
Dev->>IDE : 配置远程调试
IDE->>App : 连接调试端口8000
Dev->>App : 发送RPC指令
App->>Protocol : 通过Kafka转发
Protocol->>App : 处理协议消息
App-->>Dev : 返回响应结果

Diagram sources

  • [mp-app/src/main/java/com/witos/mp/app/adapter/controller/RpcController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/RpcController.java#L1-L70)
  • [docker/start.sh](file://docker/start.sh#L15-L18)
  • [mp-app-bootstrap/src/main/resources/app-service.yml](file://mp-app-bootstrap/src/main/resources/app-service.yml#L1-L10)

Section sources

  • [docker/start.sh](file://docker/start.sh#L15-L18)
  • [mp-app/src/main/java/com/witos/mp/app/adapter/controller/RpcController.java](file://mp-app/src/main/java/com/witos/mp/app/adapter/controller/RpcController.java#L30-L150)
  • [mp-app/src/main/java/com/witos/mp/app/service/impl/DefaultPileProtocolService.java](file://mp-app/src/main/java/com/witos/mp/app/service/impl/DefaultPileProtocolService.java#L1-L1000)
最近更新：:
Contributors: feng