介绍 ocpp-ws-io：面向 Node.js 的类型安全 OCPP 生态系统 ⚡
Source: Dev.to
概述
如果你曾为电动汽车（EV）充电行业构建软件，你一定知道 Open Charge Point Protocol (OCPP) 是充电桩与集中系统（CSMS）之间通信的公认标准。
然而，构建一个可扩展、可靠且安全的符合 OCPP 标准的系统极其困难。开发者常常要面对猜测负载结构、手动验证 JSON 模式、实现复杂的 WebSocket 帧以及处理连接中断等问题。
正因如此，我创建了 ocpp-ws-io——一个类型安全、可直接用于生产的 OCPP WebSocket RPC 客户端和服务器生态系统，基于 Node.js 并从头到尾使用 TypeScript 构建。
🚀 为什么还有另一个 OCPP 库？
构建 CSMS 或充电桩模拟器不应需要手写验证逻辑或冒着因负载错误而导致运行时错误的风险。ocpp-ws-io 通过以下方式解决这些问题：
- 🎯 端到端类型安全： 完全自动生成的 TypeScript 类型覆盖所有 OCPP 1.6、 2.0.1 和 2.1 方法。不再猜测
BootNotification负载应该是什么样子。 - 📐 严格的模式验证： 可选的严格模式，在业务逻辑处理消息之前进行内置的 JSON‑schema 验证。
- 🛜 内置路由器： 类似 Express/Hono 的路由器，实现模块化、整洁的代码和易于管理。
- 🔒 全面的安全性： 开箱即用支持 OCA 安全配置文件 0–3（普通 WS、Basic Auth、TLS + Basic Auth 和双向 TLS）。
- 🚦 DDoS 防护与速率限制： 基于 socket 层的令牌桶速率限制，针对每个站点和方法。
- 🔁 弹性恢复： 指数退避自动重连、Redis 状态同步，以及 幂等键，确保在重试时消息恰好一次送达。
- 🧩 框架无关： 可单独使用，也可无缝集成到 Express、Fastify、NestJS 或任何自定义 HTTP 服务器中。
- 📡 为规模而建： 多实例部署的 Redis 适配器，使用 Streams 实现持久化消息投递。
💻 代码胜于言辞
服务器 (CSMS)
import { OCPPServer } from "ocpp-ws-io";
const server = new OCPPServer({
protocols: ["ocpp1.6", "ocpp2.0.1"],
logging: { prettify: true, exchangeLog: true, level: "info" }, // Powered by voltlog-io!
});
// Authenticate incoming connections
server.auth((ctx) => {
console.log(`Connection attempt from ${ctx.handshake.identity}`);
ctx.accept({ session: { authorized: true } });
});
server.on("client", (client) => {
console.log(`${client.identity} connected via ${client.protocol}`);
// Type‑safe RPC handler
client.handle("ocpp1.6", "BootNotification", ({ params }) => ({
status: "Accepted",
currentTime: new Date().toISOString(),
interval: 300,
}));
});
await server.listen(3000);
console.log("⚡ OCPP Server running on port 3000");客户端 (充电桩模拟器)
import { OCPPClient, SecurityProfile } from "ocpp-ws-io";
const client = new OCPPClient({
endpoint: "ws://localhost:3000/api/v1/chargers",
identity: "CP001",
protocols: ["ocpp1.6"],
securityProfile: SecurityProfile.NONE,
});
// Handle commands from the central system
client.handle("Reset", ({ params }) => {
console.log("CSMS requested a Reset of type:", params.type);
return { status: "Accepted" };
});
await client.connect();
// Send an RPC request and await the result!
const response = await client.call("ocpp1.6", "BootNotification", {
chargePointVendor: "VendorX",
chargePointModel: "ModelY",
});
console.log("Central System response status:", response.status); // Type‑checked!🛜 类 Express 路由与中间件
ocpp-ws-io 的突出特性之一是其强大的 路由和中间件 系统，设计上与 Express 或 Hono 完全相同。这使您能够构建模块化、整洁且高度可管理的 CSMS 架构。
您可以拦截 HTTP Upgrade 请求（连接阶段），以及进出站的 OCPP RPC 消息（消息阶段）。
import { OCPPServer, defineMiddleware } from "ocpp-ws-io";
const server = new OCPPServer({ protocols: ["ocpp1.6"] });
// 1️⃣ Connection middleware: block bad IPs or rate‑limit before WebSockets even open!
const rateLimiter = defineMiddleware(async (ctx, next) => {
if (isRateLimited(ctx.handshake.remoteAddress)) {
ctx.reject(429, "Too Many Requests"); // Instantly drops the connection
} else {
await next();
}
});
server.use(rateLimiter);
// 2️⃣ Create dynamic routes with wildcard parameter extraction
const chargerRoute = server.route("/api/v1/chargers/:id");
chargerRoute.on("client", (client) => {
console.log(`Charger connected at endpoint: ${client.handshake.pathname}`);
// 3️⃣ Message middleware: log processing times for every single RPC call
client.use(async (ctx, next) => {
const start = Date.now();
await next();
console.log(`[${ctx.action}] took ${Date.now() - start}ms`);
});
client.handle("BootNotification", ({ params }) => ({
status: "Accepted",
currentTime: new Date().toISOString(),
interval: 300,
}));
});
await server.listen(3000);有关更高级的路由场景，请参阅文档：https://ocpp-ws-io.rohittiwari.me/docs/routing
🪵 一级结构化日志 (voltlog-io)
高吞吐量的 WebSocket 环境使用标准 console.log 调试简直是噩梦。这就是 ocpp-ws-io 内置 结构化 JSON 日志（由 voltlog‑io 提供支持）的原因。
只需一个配置开关，即可获得：
- 生产环境下极快的 JSON 日志记录。
- 本地开发时美观、彩色的输出，并附带延迟指标（
prettify: true）。
交换日志（exchangeLog: true）能够完美追踪每个入站（[IN]）和出站（[OUT]）的 OCPP 命令。
⚡ CP-101 → BootNotification [OUT]
✅ CP-101 ← BootNotification [IN] { latencyMs: 45 }🌐 The Browser Client
需要构建一个直接与充电桩或代理通信的 Web UI、CSMS 仪表盘或测试界面吗？我们还提供了一个零依赖的 Browser Client（ocpp-ws-io/browser），可在原生 JS、React、Vue 或 Svelte 中完美运行。服务器提供的严格类型安全也可以直接在浏览器中使用！
🛠️ ocpp-ws-cli 生态系统
没有强大开发者工具的库只能算是完成了一半工作。我们在核心 ocpp-ws-io 包的基础上发布了 ocpp-ws-cli —— OCPP 开发者的终极 CLI。
通过 npx ocpp-ws-cli 即可立即使用，这套工具彻底改变了你构建和测试后端的方式：
- 🎮
ocpp simulate– 虚拟充电桩，配备交互式终端 UI（启动序列、心跳、实时电压/电流/功率、插拔、RFID、故障状态）。 - 📡
ocpp mock– SSE 模拟服务器，持续推送虚拟的MeterValues、StatusNotification、Heartbeat数据，供前端开发使用。 - 🚄
ocpp bench– 吞吐量和延迟基准测试引擎，提供百分位指标和实时仪表盘。 - 💣
ocpp load-test– 分布式负载引擎，模拟数千个并发充电桩连接。 - 👾
ocpp fuzz– 协议混沌引擎，向你的 CSMS 发送大量畸形 JSON 负载，以测试严格模式的处理能力。 - 🔐
ocpp certs– 自动生成 4096 位根 CA 以及签名的服务器/客户端.pem证书，用于 OCA Profile 2 与 3 的测试。 - 🗂️
ocpp audit– 安全向导，执行自动化测试并生成 Markdown 路线图（audit‑report.md）。 - 📝
ocpp generate– 将自定义.json模式转换为.d.ts声明库，实现 100 % 类型安全。 - 🧪
ocpp test– 直接对你的服务器执行模块化的 OCTT 合规性测试套件。
🌟 加入我们
电动汽车基础设施生态系统正在快速增长，强大的开源工具将成为这种增长的支柱。无论您是在构建下一个大型 CSMS 平台、EV 充电应用，还是仅仅想了解行业，都可以尝试 ocpp-ws-io！
我们积极寻求反馈、问题和 pull request。请在下方评论中告诉我们您的想法。祝您充电愉快！ ⚡🚗