Logo
CEEGAPI

CEEGAPI

业务代码

面向充换电业务的数据集成服务

PythonMQTThttpsDocker

CEEGAPI 项目简介

1. 简介

CEEGAPI 是一个面向充换电业务的数据集成服务，用于从指定第三方 API 稳定获取充电设备数据，完成协议封装、数据清理与转换后，将结果发布到后端订阅通道。

2. 项目背景

该项目来源于所在公司的实际业务需求：公司后端系统需要接入外部充电平台的数据，但对方接口存在协议封装、加密签名、Token 鉴权、序列号、字段格式和运行稳定性等对接成本。项目的目标是把这些复杂细节收敛到一个可长期运行的中间层中。

在业务链路上，项目负责从指定 API 获取充电枪状态、电站统计等数据，对返回内容进行解密、清洗、字段转换和点位映射，并将可用数据发布到后端订阅接口中。当前实现中，后端订阅通道主要通过 MQTT 设备点位发布完成。

3. 核心功能及亮点

  • 中电联/客户接口协议封装：项目统一处理 OperatorID、Data、TimeStamp、Seq、Sig 等外层报文字段，并封装 AES 加密、HMAC-MD5 签名和 HTTP 请求逻辑。实际价值是把容易出错的协议细节集中管理，业务代码只需要关注“查什么数据”，减少现场联调时的重复排错。

  • 可长期运行的轮询服务：项目支持按配置周期轮询多个充电枪和可选电站统计目标，并通过批次拆分、并发执行和失败隔离来控制接口调用节奏。实际价值是让数据采集从一次性脚本升级为持续运行的服务，单个设备请求失败不会直接拖垮整轮采集。

  • Token 与 Seq 的统一生命周期管理：项目实现了进程内共享的 Token 缓存、刷新、失效处理和线程安全 Seq 生成。实际价值是避免多线程轮询时重复获取 Token、重复序列号或认证失败后继续使用旧 Token，从而提高长期运行的稳定性。

  • 数据清理、计算与发布闭环：项目会清理枪口编号，解密并解析接口返回的 Data，将外部 ConnectorID 映射为内部设备点位，并根据三相平均电流和平均电压计算功率 P，再发布到 MQTT。实际价值是把外部平台的原始响应转换成后端可以直接订阅和消费的业务数据。

  • 工程化调试与部署能力：项目提供 CLI、手工启停脚本、分层结构化日志、debug/production 发布模式、单元测试以及 Docker/Docker Compose 部署配置。实际价值是兼顾开发调试、现场排障和生产部署，降低接口对接项目从“能跑一次”到“能稳定运行”的落地成本。

4. 学习过程

这个项目是一个边学边做、边联调边重构的工程化过程。

  • 原型验证阶段：项目从基础 AES 加解密、配置驱动的接口客户端和 token 调试开始，先解决“请求能否按对方格式发出去、返回能否正确解出来”的核心问题。

  • 协议收敛阶段：后续提交围绕 T/CEC 102.4 相关规则、客户确认的字段格式、Token 请求方式、充停电接口参数差异不断调整，说明项目不是一次写完，而是在真实接口联调中逐步修正协议理解。

  • 模块化阶段：随着接口数量增加，项目把客户端、加密签名、HTTP 传输、配置模型、Token 服务、Seq 服务等能力拆开，形成了更清晰的分层结构。这一阶段体现了“关注点分离”和“可测试设计”的思路。

  • 数据发布阶段：项目新增 MQTT 发布模块，把接口采集结果转成后端订阅所需的设备点位数据，并通过 debug/production 模式区分调试日志和真实发布，逐步从接口调用工具演进为业务数据中间层。

  • 长期运行优化阶段：后续提交集中处理轮询调度、并发轮询、日志密度、Token 失效、认证失败隔离、功率单位修正和 Docker 打包，体现了从“功能可用”到“服务可运行、可排障、可部署”的工程化迭代。

在这个过程中，项目综合运用了配置驱动设计、分层架构、适配器/传输抽象、依赖注入、线程安全状态管理、任务调度、结构化日志和测试驱动的验证思路。

5. 技术栈

  • Python：作为项目主要开发语言，用于实现接口客户端、轮询服务、数据处理和命令行入口。

  • requests：用于向第三方 API 发送 HTTP JSON 请求，是 CEC 接口调用的底层传输能力。

  • cryptography：用于实现 AES-128-CBC 加解密，满足接口中 Data 字段加密传输的要求。

  • HMAC-MD5 / hashlib：用于生成接口签名 Sig，保证请求符合对方平台的验签规则。

  • paho-mqtt：用于将清洗后的设备点位数据发布到 MQTT，供后端订阅消费。

  • dataclasses / typing.Protocol：用于定义配置模型、运行时服务对象和可替换的传输接口，提高代码结构清晰度和测试便利性。

  • threading / concurrent.futures：用于实现线程安全的 Token、Seq 管理和多任务并发轮询。

  • unittest：用于覆盖 AES、CEC 客户端、Token 服务、轮询服务、MQTT 发布、日志和启停充电等关键逻辑。

  • Docker / Docker Compose：用于容器化部署长期轮询服务，便于在目标环境中以固定配置运行。

6. 项目成果

项目已经形成从配置读取、Token 获取、CEC API 调用、数据解密清洗、功率计算、点位映射到 MQTT 发布的完整链路，能够稳定获取充电设备相关数据，并将其转换为后端可订阅的业务数据。

相比最初的一次性接口调试脚本，当前项目已经具备长期运行所需的关键能力：统一配置、自动 Token 管理、线程安全 Seq、周期轮询、失败隔离、日志分层、调试/生产模式切换和容器化部署。它解决了外部充电平台数据接入中的协议复杂、联调反复、运行状态难排查等问题，为公司后端系统提供了稳定的数据接入基础。