Java手写HJ212解析器：环保数采仪对接实战

简介这份资源面向从事环保监测系统开发的Java工程师提供国标HJ212协议污染源在线自动监控系统数据传输标准的解析实现参考帮助解决监测数据采集、编码解码与网络交互中的落地问题。压缩包共308个文件以197个class与100个java源码为主体另含少量xml、properties、classpath等配置与说明文件整体约327KB可直接导入Eclipse运行调试。资源围绕协议数据结构、XML/JSON载体解析、Socket与HTTP通信、异常处理等环节给出可复用的类与方法如解析器、数据转换器及配置工厂等模块便于读者理解协议字段映射与解析流程并在此基础上做二次开发或单元测试验证。目前已有5085人学习下载适合具备一定Java基础、希望快速上手HJ212协议解析的开发者参考借鉴。1. 环保数采仪对接为什么我最后选了 Java 手写 HJ212 解析去年接手一个环保在线监测项目现场数采仪每隔几分钟就往平台推一包数据格式是##0132QN...ST32CN...这种带包头包尾的 ASCII 串。一开始我想找现成库翻了一圈发现 HJ212 的 Java 实现要么年久失修要么把协议写死成固定字段换个污染物因子就得改代码。最后干脆自己撸了一套解析器把 HJ212 的组包、拆包、校验、字段映射全拆开写清楚。这篇就讲这个 Java 解析国标 HJ212 协议的项目怎么跑、怎么改适合正在做环保数采仪对接、污染物在线监测平台、或者需要把 h212 java 报文转成结构化数据的开发者。读完你能拿到一套能直接塞进 Spring Boot 的解析骨架也能看懂现场报文为什么老是校验不过。2. 协议结构拆解一包 HJ212 报文到底长什么样2.1 报文骨架与字段语义HJ212 的报文本质是一串 ASCII 文本结构固定为「包头 数据段 包尾」。包头是##包尾是\r\n实际现场常见或\r\n结尾解析时要兼容。数据段由若干字段编码值的键值对组成字段之间用;分隔最后一个字段后面也带;。核心字段有这么几个字段编码含义示例说明QN请求编号QN20240101120000001时间戳序号用于应答匹配ST系统编码ST3232 表示污染源在线监测CN命令编码CN20112011 上传污染物数据PW访问密码PW123456平台下发的口令MN设备唯一标识MNDEV001现场机编号Flag数据标志位Flag7位掩码表示是否含 CP/数据区CP数据区CPDataTime...真正的监测数据数据区CP里面又是一层包裹的键值对常见的有DataTime数据时间、a34013-Avg污染物因子编码-统计类型、Rtd实时值等。这里最容易翻车的是CP 内部的分隔符和外层一样是;但 CP 整体作为一个字段值出现所以拆包必须按「先找 CP再取到 之前」的顺序不能无脑 split。2.2 组包与拆包的核心代码先看拆包。我一般写一个Hj212Parser入口方法接收原始字符串返回一个Hj212Message对象。关键点是先做长度和包头包尾校验再逐层解析。public class Hj212Parser { // 解析入口raw 为现场收到的完整报文 public Hj212Message parse(String raw) { if (raw null || !raw.startsWith(##)) { throw new IllegalArgumentException(报文缺少包头 ##); } // 去掉包头兼容 和 \r\n 两种包尾 String body raw.substring(2); int endIdx body.indexOf(); if (endIdx 0) { endIdx body.indexOf(\r\n); } if (endIdx 0) { throw new IllegalArgumentException(报文缺少包尾); } body body.substring(0, endIdx); Hj212Message msg new Hj212Message(); // 先定位 CP因为 CP 内部也有分号不能直接整体 split int cpIdx body.indexOf(CP); String headPart cpIdx 0 ? body.substring(0, cpIdx) : body; parseHead(headPart, msg); if (cpIdx 0) { String cpPart body.substring(cpIdx 3); msg.setCp(parseCp(cpPart)); } return msg; } private void parseHead(String head, Hj212Message msg) { // 头部字段用 ; 分隔逐个 keyvalue 填充 for (String kv : head.split(;)) { if (kv.isEmpty()) continue; int eq kv.indexOf(); if (eq 0) continue; String key kv.substring(0, eq).trim(); String val kv.substring(eq 1).trim(); switch (key) { case QN: msg.setQn(val); break; case ST: msg.setSt(val); break; case CN: msg.setCn(val); break; case PW: msg.setPw(val); break; case MN: msg.setMn(val); break; case Flag: msg.setFlag(val); break; default: msg.putExtra(key, val); } } } }这段代码的逻辑说明parse先做包头校验再用indexOf()找包尾避免split把 CP 内部内容切碎。cpIdx定位CP的位置把报文切成「头部」和「数据区」两段分别处理。parseHead里用switch映射标准字段未知字段丢进extramap这样现场新增字段不会导致解析失败。参数上raw必须是完整报文如果现场是流式读取需要先按包尾切出完整帧再调用。组包是反向操作应答报文尤其重要。平台收到数据后要回QN...;ST...;CN...;PW...;MN...;Flag...;CP...其中 QN 必须和请求一致否则现场机会重发。public String buildAck(Hj212Message req, String cpBody) { StringBuilder sb new StringBuilder(##); sb.append(QN).append(req.getQn()).append(;); sb.append(ST).append(req.getSt()).append(;); sb.append(CN).append(req.getCn()).append(;); sb.append(PW).append(req.getPw()).append(;); sb.append(MN).append(req.getMn()).append(;); sb.append(Flag).append(req.getFlag()).append(;); if (cpBody ! null !cpBody.isEmpty()) { sb.append(CP).append(cpBody).append(); } sb.append(\r\n); return sb.toString(); }buildAck的每个字段都从请求对象里取保证 QN 回填正确。cpBody是应答数据区内容比如DataTime20240101120000;。注意包尾用\r\n部分现场机只认这个结尾反而不认这个差异后面避坑章节会细说。3. 工程落地从 Maven 依赖到 Spring Boot 接口跑通3.1 项目目录与依赖这个解析器我按「协议层 业务层 接入层」三层拆。目录结构大致如下hj212-parser/ ├── pom.xml ├── src/main/java/com/example/hj212/ │ ├── protocol/ # 协议层组包拆包、校验 │ │ ├── Hj212Parser.java │ │ ├── Hj212Message.java │ │ └── Hj212Validator.java │ ├── service/ # 业务层字段映射、入库 │ │ ├── PollutantService.java │ │ └── FactorMapping.java │ └── web/ # 接入层HTTP/TCP 入口 │ └── Hj212Controller.java └── src/main/resources/ └── application.yml依赖很轻核心就 Spring Boot Web 加一个 JSON 库不需要额外协议库。pom.xml里关键部分dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId /dependency /dependencies为什么不用现成 HJ212 库血泪经验是那些库大多把因子编码写死成枚举现场换个a34013之外的因子就得改源码重新打包。自己写协议层因子映射放配置表改起来只动 YAML。3.2 校验模块CRC 与长度校验HJ212 的校验分两块一是包头包尾和字段完整性二是部分版本要求的 CRC 校验。CRC 用 CRC16/IBM多项式 0xA001对##之后到之前的内容计算。校验不通过直接丢弃并记日志不要抛异常打断整个接收循环。public class Hj212Validator { // CRC16/IBMHJ212 常用校验算法 public static int crc16(String data) { int crc 0xFFFF; for (int i 0; i data.length(); i) { crc ^ data.charAt(i); for (int j 0; j 8; j) { if ((crc 0x0001) ! 0) { crc (crc 1) ^ 0xA001; } else { crc 1; } } } return crc 0xFFFF; } public boolean validate(Hj212Message msg) { // 必填字段检查 if (msg.getQn() null || msg.getCn() null || msg.getMn() null) { return false; } // CN2011 时必须有 CP 数据区 if (2011.equals(msg.getCn()) msg.getCp() null) { return false; } return true; } }crc16的入参是去掉包头包尾后的字符串返回值是 16 位整数。validate只做业务必填校验CRC 校验放在接入层按需开启因为不是所有现场机都带 CRC 字段。参数上msg.getCn()为2011表示上传污染物数据2051是平台下发指令不同 CN 的必填字段不一样实际项目里我会用一张MapString, SetString配置每个 CN 的必填字段比硬编码 if 好维护。3.3 接入层一个 HTTP 接口收报文现场数采仪有的走 TCP有的走 HTTP 转发。这里给 HTTP 入口Spring Boot 一个 Controller 就够。RestController RequestMapping(/hj212) public class Hj212Controller { private final Hj212Parser parser new Hj212Parser(); private final Hj212Validator validator new Hj212Validator(); private final PollutantService pollutantService; public Hj212Controller(PollutantService pollutantService) { this.pollutantService pollutantService; } PostMapping(/receive) public String receive(RequestBody String raw) { Hj212Message msg parser.parse(raw); if (!validator.validate(msg)) { return ##ERROR\r\n; // 校验失败回错误帧 } pollutantService.save(msg); // 业务入库 return parser.buildAck(msg, DataTime msg.getDataTime() ;); } }receive方法接收原始字符串先解析再校验通过后入库并回 ACK。返回的 ACK 里DataTime从请求数据区取保证时间一致。注意RequestBody String raw不要用对象接收因为报文不是 JSON用 String 最稳。如果现场是 TCP 长连接把这段逻辑挪到 Netty 的channelRead里解析和应答逻辑完全复用。4. 避坑与排查现场报文解析失败的 5 个真实原因4.1 包尾不统一导致整包丢弃现象日志里大量「报文缺少包尾」但抓包看报文明明完整。原因不同厂商数采仪包尾有的用有的用\r\n还有的\r\n都带。解决解析时先找找不到再找\r\n两者都兼容同时把原始报文的前 50 个字符打进日志方便比对。4.2 CP 数据区被 split 切碎现象DataTime解析出来是空或者因子值错位。原因外层用;split 时CP 内部的;也被切开导致 CP 字段只剩前半段。解决先indexOf(CP)定位CP 之后的内容整体作为数据区再单独解析不要和外层一起 split。这个坑我踩过一次排查了两小时才发现是分隔符冲突。4.3 因子编码大小写与前后缀不一致现象a34013-Avg能入库A34013-Avg就匹配不上。原因现场机因子编码大小写不统一有的还带-Avg、-Max后缀。解决因子映射表统一转小写后缀用正则-(Avg|Max|Min|Rtd)$剥离后再查表查不到就落原始编码进扩展表不要直接丢数据。4.4 QN 未回填导致现场机重发现象平台明明回了 ACK现场机还是每隔几分钟重发同一包。原因ACK 里的 QN 和请求不一致或者 ACK 包尾格式不对。解决ACK 的 QN 必须原样回填请求的 QN包尾按现场机要求用\r\n排查时把请求 QN 和应答 QN 并排打日志一眼就能看出对不对。4.5 编码问题导致中文与特殊字符乱码现象报文里带设备名称等中文时解析出乱码。原因HJ212 标准是 ASCII但部分厂商塞了 GBK 中文。解决接收时按字节读先尝试 ASCII 解码失败再按 GBK 兜底入库前统一转 UTF-8。这个属于玄学问题不同厂商行为不一样日志里保留原始字节最保险。5. 二次开发把解析器改造成可配置的因子映射引擎这套代码真正值钱的地方不是解析本身而是「协议层和业务层解耦」之后二次开发只动配置不动核心。我一般把因子映射抽成一张表放application.yml或者数据库新增污染物因子时改配置即可。hj212: factors: a34013: 烟尘 a34014: 二氧化硫 a34015: 氮氧化物 a34016: 氧含量 stat-types: - Avg - Max - Min - Rtd对应的映射类读配置把a34013-Avg拆成「因子编码 统计类型」再查表得到中文名和单位。这样现场新增因子运维改 YAML 重启即可不用开发介入。Component ConfigurationProperties(prefix hj212) public class FactorMapping { private MapString, String factors new HashMap(); private ListString statTypes new ArrayList(); // 把 a34013-Avg 解析成 [a34013, Avg] public String[] splitFactor(String raw) { for (String stat : statTypes) { String suffix - stat; if (raw.endsWith(suffix)) { return new String[]{raw.substring(0, raw.length() - suffix.length()), stat}; } } return new String[]{raw, Rtd}; // 无后缀默认实时值 } public String nameOf(String code) { return factors.getOrDefault(code.toLowerCase(), code); } // getter/setter 省略 }splitFactor按配置的统计类型后缀匹配匹配不到默认Rtd避免现场漏后缀导致整条数据丢弃。nameOf查不到时返回原编码保证数据不丢。验证方法很简单拿一包真实报文跑单测断言解析出的因子数量和中文名符合预期再故意改一个因子编码确认走的是兜底分支而不是抛异常。还有一个改造方向是加「报文回放」能力。把现场抓到的原始报文存成文本文件写一个ReplayRunner批量喂给解析器对比入库结果。我一般在新版本上线前跑一遍历史报文回放确认解析结果和旧版本一致再发布。从那以后我每次改解析逻辑都强制走一遍回放加单测再也不敢直接改完就发。希望帮到你。本文还有配套的精品资源点击获取