From 3cf58fe72c95aaa6c9712b91dc332f6b83779b4c Mon Sep 17 00:00:00 2001 From: zhengwr Date: Thu, 2 Jul 2026 10:10:47 +0800 Subject: [PATCH] =?UTF-8?q?refactor(flow):=20id=20=E5=87=80=E5=8C=96?= =?UTF-8?q?=E6=8A=BD=20BpmnIdSanitizer,=E8=A1=A5=E5=8F=AF=E9=80=86=20resto?= =?UTF-8?q?re+=E7=A2=B0=E6=92=9E=E6=B6=88=E8=A7=A3(D7=20=E5=9C=B0=E5=9F=BA?= =?UTF-8?q?)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ProcessDiagramController.sanitizeBpmnIds 的中文 id→安全 ASCII 净化逻辑抽成 BpmnIdSanitizer(sanitize 返 Result{xml,idMap} / restore 逆向还原),为 D7「发布存量 流程 key 不变」打地基。 - 双射保证:同文档两个不同中文 id hash 碰撞时基名追加 -2/-3 序号,生成 id 亦不与既有 合法 id 冲突;非碰撞场景净化输出与旧实现逐字节一致(查看器零回归)。 - restore 前缀安全:复用 ID_ATTR 正则逐属性值精确匹配,不裸 String.replace 子串替换 (n1 不误伤 n1x);映射外 ASCII id(设计器新增节点)原样保留。 - ProcessDiagramController.sanitizeBpmnIds 改为委托,原包级签名/行为不变。 测试:新增 BpmnIdSanitizerTest 7 例(中文全引用面 restore 逐字节还原/撞哈希 中Aa~中BB 双射/restore n1~n1x 前缀安全/合法 NCName 不改写/混合只映射中文/空 XML 防御); 既有 ProcessDiagramControllerTest 4 例零修改仍绿;flowable-service 全模块 65 测试通过。 Co-Authored-By: Claude Fable 5 --- .../eip4/flowservice/api/BpmnIdSanitizer.java | 125 ++++++++++++++ .../api/ProcessDiagramController.java | 57 +----- .../flowservice/api/BpmnIdSanitizerTest.java | 163 ++++++++++++++++++ 3 files changed, 293 insertions(+), 52 deletions(-) create mode 100644 flowable-service/src/main/java/com/eip4/flowservice/api/BpmnIdSanitizer.java create mode 100644 flowable-service/src/test/java/com/eip4/flowservice/api/BpmnIdSanitizerTest.java diff --git a/flowable-service/src/main/java/com/eip4/flowservice/api/BpmnIdSanitizer.java b/flowable-service/src/main/java/com/eip4/flowservice/api/BpmnIdSanitizer.java new file mode 100644 index 0000000..0d9d59e --- /dev/null +++ b/flowable-service/src/main/java/com/eip4/flowservice/api/BpmnIdSanitizer.java @@ -0,0 +1,125 @@ +package com.eip4.flowservice.api; + +import java.util.LinkedHashMap; +import java.util.LinkedHashSet; +import java.util.Map; +import java.util.Set; +import java.util.regex.Matcher; +import java.util.regex.Pattern; + +/** + * BPMN id 净化/还原(可逆双射)。 + * + *

迁移的 1512 个真实流程里,1445 个的 process id 就是中文(如「总包合同交底」),BPMN 常把中文用作 + * process/diagram/节点 id。bpmn-js / moddle 的 NCName 校验拒非 ASCII id → 整图无法渲染,且 moddle-xml + * 在 import 前就会拒中文 id。{@link #sanitize} 把非法(非 ASCII NCName)id 及其全部引用一致重写为安全 + * ASCII id(稳定哈希),保存原→净化映射;{@link #restore} 依映射逆向还原——发布存量流程时把中文原 key + * 原样写回引擎,保证 process key 不变(D7 硬需求)。

+ * + *

双射保证:同一文档内两个不同中文 id 若哈希相同(Java String.hashCode 存在碰撞),基名冲突时 + * 追加 {@code -2}/{@code -3} 序号;生成的净化 id 亦不与文档内既有合法 id 冲突。故净化后引用不串、restore + * 可精确逆向。非碰撞场景下净化输出与历史实现({@code "n"+hex(hashCode)})逐字节一致,保住查看器回归。

+ * + *

restore 前缀安全:还原一律复用 {@link #ID_ATTR} 正则逐个属性值精确匹配,绝不裸 {@code String.replace} + * 子串替换——否则净化 id {@code n1} 会误伤前缀相同的 {@code n1x}。映射外的 id(如设计器新增的 ASCII 节点)原样保留。

+ */ +final class BpmnIdSanitizer { + + private BpmnIdSanitizer() { + } + + /** id/引用类属性(值须为合法 NCName);name/value 等展示属性不在内,避免改坏中文节点名。 */ + static final Pattern ID_ATTR = Pattern.compile( + "\\b(id|bpmnElement|sourceRef|targetRef|attachedToRef|processRef|default)\\s*=\\s*\"([^\"]+)\""); + + /** 净化结果:{@code xml}=净化后 XML;{@code idMap}=原 id→净化 id(双射,供 {@link #restore} 逆向)。 */ + record Result(String xml, Map idMap) { + } + + /** + * 把 BPMN 里非法(非 ASCII NCName)的 id 及其全部引用一致重写为安全 ASCII id。 + * 只重写 id/引用类属性,name 等展示属性不动。返回净化 XML 与「原 id→净化 id」映射。 + */ + static Result sanitize(String xml) { + if (xml == null || xml.isEmpty()) { + return new Result(xml, Map.of()); + } + // 先登记文档内所有合法 id,占位保证生成的净化 id 不与既有合法 id 冲突(双射 + restore 安全)。 + Set used = new LinkedHashSet<>(); + Matcher scanLegal = ID_ATTR.matcher(xml); + while (scanLegal.find()) { + String val = scanLegal.group(2); + if (isValidNcName(val)) { + used.add(val); + } + } + // 收集非法 id → 唯一净化 id;基名冲突(含 hash 碰撞)时追加 -2/-3… 保双射。 + Map map = new LinkedHashMap<>(); + Matcher scan = ID_ATTR.matcher(xml); + while (scan.find()) { + String val = scan.group(2); + if (!isValidNcName(val) && !map.containsKey(val)) { + String base = "n" + Integer.toHexString(val.hashCode() & 0x7fffffff); + String safe = base; + int seq = 2; + while (used.contains(safe)) { + safe = base + "-" + seq++; + } + map.put(val, safe); + used.add(safe); + } + } + if (map.isEmpty()) { + return new Result(xml, Map.of()); + } + return new Result(rewrite(xml, map), map); + } + + /** + * 依 {@code idMap}(原→净化)逆向还原:把净化 id 精确写回原 id。映射外的 id(如新增 ASCII 节点)原样保留。 + * 逐个属性值精确匹配(复用 {@link #ID_ATTR}),前缀安全。 + */ + static String restore(String xml, Map idMap) { + if (xml == null || xml.isEmpty() || idMap == null || idMap.isEmpty()) { + return xml; + } + Map inverse = new LinkedHashMap<>(); + for (Map.Entry e : idMap.entrySet()) { + inverse.put(e.getValue(), e.getKey()); + } + return rewrite(xml, inverse); + } + + /** 逐个 id/引用类属性值按 {@code map} 精确替换(命中才换,未命中原样)。前缀安全:只锚定完整属性值。 */ + private static String rewrite(String xml, Map map) { + Matcher rw = ID_ATTR.matcher(xml); + StringBuilder sb = new StringBuilder(); + while (rw.find()) { + String attr = rw.group(1); + String val = rw.group(2); + String repl = map.getOrDefault(val, val); + rw.appendReplacement(sb, Matcher.quoteReplacement(attr + "=\"" + repl + "\"")); + } + rw.appendTail(sb); + return sb.toString(); + } + + /** ASCII NCName:首字符字母/下划线,其余字母/数字/下划线/连字符/点;非 ASCII(中文等)视为非法。 */ + private static boolean isValidNcName(String s) { + if (s == null || s.isEmpty()) { + return false; + } + char c0 = s.charAt(0); + if (!((c0 >= 'A' && c0 <= 'Z') || (c0 >= 'a' && c0 <= 'z') || c0 == '_')) { + return false; + } + for (int i = 1; i < s.length(); i++) { + char c = s.charAt(i); + if (!((c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') + || c == '_' || c == '-' || c == '.')) { + return false; + } + } + return true; + } +} diff --git a/flowable-service/src/main/java/com/eip4/flowservice/api/ProcessDiagramController.java b/flowable-service/src/main/java/com/eip4/flowservice/api/ProcessDiagramController.java index 1022e99..8749cd6 100644 --- a/flowable-service/src/main/java/com/eip4/flowservice/api/ProcessDiagramController.java +++ b/flowable-service/src/main/java/com/eip4/flowservice/api/ProcessDiagramController.java @@ -109,63 +109,16 @@ public class ProcessDiagramController { return ResponseEntity.ok(resp); } - /** id/引用类属性(需为合法 NCName;name/value 等展示属性不在内,避免改坏中文节点名)。 */ - private static final java.util.regex.Pattern ID_ATTR = java.util.regex.Pattern.compile( - "\\b(id|bpmnElement|sourceRef|targetRef|attachedToRef|processRef|default)\\s*=\\s*\"([^\"]+)\""); - /** - * 把 BPMN 里非法(非 ASCII NCName)的 id 及其全部引用一致重写为安全 ASCII id(稳定哈希), - * 使 bpmn-js 能解析渲染。只重写 id/引用类属性,name 等展示属性不动。同步重映射 active/finished 节点 id。 + * 把 BPMN 里非法(非 ASCII NCName)的 id 及其全部引用一致重写为安全 ASCII id,使 bpmn-js 能解析渲染, + * 并同步重映射 active/finished 节点 id。净化算法委托 {@link BpmnIdSanitizer}(含可逆映射与 hash 碰撞消解)。 */ static String sanitizeBpmnIds(String xml, List active, List finished) { - if (xml == null || xml.isEmpty()) { - return xml; - } - // 1. 收集所有非法 id 值 → 安全 id 映射 - java.util.Map map = new java.util.LinkedHashMap<>(); - java.util.regex.Matcher scan = ID_ATTR.matcher(xml); - while (scan.find()) { - String val = scan.group(2); - if (!isValidNcName(val) && !map.containsKey(val)) { - map.put(val, "n" + Integer.toHexString(val.hashCode() & 0x7fffffff)); - } - } - if (map.isEmpty()) { - return xml; - } - // 2. 仅重写 id/引用类属性(appendReplacement 精确,不误伤 name=) - java.util.regex.Matcher rw = ID_ATTR.matcher(xml); - StringBuilder sb = new StringBuilder(); - while (rw.find()) { - String attr = rw.group(1); - String val = rw.group(2); - String repl = map.getOrDefault(val, val); - rw.appendReplacement(sb, java.util.regex.Matcher.quoteReplacement(attr + "=\"" + repl + "\"")); - } - rw.appendTail(sb); - // 3. 同步重映射返回的当前/历史节点 id + BpmnIdSanitizer.Result r = BpmnIdSanitizer.sanitize(xml); + Map map = r.idMap(); active.replaceAll(id -> map.getOrDefault(id, id)); finished.replaceAll(id -> map.getOrDefault(id, id)); - return sb.toString(); - } - - /** ASCII NCName:首字符字母/下划线,其余字母/数字/下划线/连字符/点;非 ASCII(中文等)视为非法。 */ - private static boolean isValidNcName(String s) { - if (s == null || s.isEmpty()) { - return false; - } - char c0 = s.charAt(0); - if (!((c0 >= 'A' && c0 <= 'Z') || (c0 >= 'a' && c0 <= 'z') || c0 == '_')) { - return false; - } - for (int i = 1; i < s.length(); i++) { - char c = s.charAt(i); - if (!((c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') - || c == '_' || c == '-' || c == '.')) { - return false; - } - } - return true; + return r.xml(); } /** 读流程定义 BPMN XML(getProcessModel 返回部署的 BPMN 资源流)。读失败返回 null(前端降级)。 */ diff --git a/flowable-service/src/test/java/com/eip4/flowservice/api/BpmnIdSanitizerTest.java b/flowable-service/src/test/java/com/eip4/flowservice/api/BpmnIdSanitizerTest.java new file mode 100644 index 0000000..2f309fd --- /dev/null +++ b/flowable-service/src/test/java/com/eip4/flowservice/api/BpmnIdSanitizerTest.java @@ -0,0 +1,163 @@ +package com.eip4.flowservice.api; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.util.LinkedHashMap; +import java.util.Map; + +import org.junit.jupiter.api.Test; + +/** + * BpmnIdSanitizer 可逆双射单测:净化(中文 id→安全 ASCII)与还原(restore)严格互逆, + * 覆盖 hash 碰撞消解、restore 前缀安全、合法 id 不动、混合场景。 + * + *

非碰撞净化输出须与 ProcessDiagramController 旧实现逐字节一致(由既有 ProcessDiagramControllerTest 兜底), + * 本类聚焦「可逆」这一新增契约。

+ */ +class BpmnIdSanitizerTest { + + /** 中文 process id + processRef/sourceRef/targetRef/default/attachedToRef 全引用面净化→restore 须逐字节还原。 */ + @Test + void 净化后还原_逐字节等于原文() { + String xml = """ + + + + + + + + + + + + + + + + + + """; + + BpmnIdSanitizer.Result r = BpmnIdSanitizer.sanitize(xml); + + // 中文 id 不再出现在 id/引用类属性中;name 展示属性照旧保留中文 + assertThat(r.xml()).doesNotContain("id=\"总包合同交底\""); + assertThat(r.xml()).doesNotContain("processRef=\"总包合同交底\""); + assertThat(r.xml()).doesNotContain("attachedToRef=\"审批\""); + assertThat(r.xml()).contains("name=\"总包合同交底\""); + assertThat(r.xml()).contains("name=\"审批人\""); + // idMap 覆盖全部 5 个中文 id(合法 ASCII id 不入 map) + assertThat(r.idMap()).containsOnlyKeys("总包合同交底", "审批", "超时", "回退", "通过"); + + // restore 逐字节还原 + assertThat(BpmnIdSanitizer.restore(r.xml(), r.idMap())).isEqualTo(xml); + } + + /** + * hash 碰撞消解:Java String.hashCode 下 "中Aa" 与 "中BB" 撞哈希('A'*31+'a' == 'B'*31+'B' == 2112), + * 二者又都是非法 NCName(含中文)→ 旧实现会撞成同一净化 id(非双射)。sanitize 须给两者不同净化 id,restore 仍完整还原。 + */ + @Test + void 撞哈希两中文id_净化后仍双射可逆() { + // 前置自证:确实撞哈希 + assertThat("中Aa".hashCode()).isEqualTo("中BB".hashCode()); + + String xml = """ + + + + + + + """; + + BpmnIdSanitizer.Result r = BpmnIdSanitizer.sanitize(xml); + + String s1 = r.idMap().get("中Aa"); + String s2 = r.idMap().get("中BB"); + // 双射:两净化 id 互不相同(否则 sourceRef/targetRef 引用会串) + assertThat(s1).isNotNull(); + assertThat(s2).isNotNull(); + assertThat(s1).isNotEqualTo(s2); + // 碰撞消解序号:其一为基名,另一为基名 +"-2" + assertThat(s1 + "|" + s2).containsPattern("-2"); + // 净化后中文 id 消失 + assertThat(r.xml()).doesNotContain("中Aa"); + assertThat(r.xml()).doesNotContain("中BB"); + // restore 逐字节还原(引用不串) + assertThat(BpmnIdSanitizer.restore(r.xml(), r.idMap())).isEqualTo(xml); + } + + /** + * restore 前缀安全:idMap 同时含净化 id "n1" 与 "n1x"(后者以前者为前缀)。 + * 裸 String.replace("n1",..) 会把 "n1x" 误伤成 "x";必须锚定完整属性值精确匹配。 + */ + @Test + void restore前缀安全_n1不误伤n1x() { + Map idMap = new LinkedHashMap<>(); + idMap.put("原A", "n1"); + idMap.put("原B", "n1x"); + String xml = ""; + + String out = BpmnIdSanitizer.restore(xml, idMap); + + assertThat(out).isEqualTo(""); + assertThat(out).doesNotContain("原Ax"); // 无前缀误伤 + assertThat(out).doesNotContain("n1x"); + assertThat(out).doesNotContain("n1\""); + } + + /** 全合法 NCName id:不改写,idMap 为空,restore 无副作用。 */ + @Test + void 合法NCName_id不改写_映射为空() { + String xml = "" + + ""; + + BpmnIdSanitizer.Result r = BpmnIdSanitizer.sanitize(xml); + + assertThat(r.idMap()).isEmpty(); + assertThat(r.xml()).isEqualTo(xml); + // 空 idMap 的 restore 原样返回 + assertThat(BpmnIdSanitizer.restore(xml, r.idMap())).isEqualTo(xml); + } + + /** 混合:部分中文部分合法,只映射中文者;合法 id 原样保留;restore 还原。 */ + @Test + void 混合_只映射中文id_合法id原样保留() { + String xml = "" + + ""; + + BpmnIdSanitizer.Result r = BpmnIdSanitizer.sanitize(xml); + + assertThat(r.idMap()).containsOnlyKeys("审批流程"); + assertThat(r.xml()).contains("id=\"legalTask\""); + assertThat(r.xml()).contains("targetRef=\"legalTask\""); + assertThat(r.xml()).doesNotContain("审批流程"); + assertThat(BpmnIdSanitizer.restore(r.xml(), r.idMap())).isEqualTo(xml); + } + + /** restore 只回写映射内 id;净化后新增的 ASCII 节点 id(不在 idMap)原样保留。 */ + @Test + void restore只回写映射内id_新增ascii_id保留() { + Map idMap = new LinkedHashMap<>(); + idMap.put("审批", "n5"); + // n9 是设计器新增节点,不在 idMap → restore 不得改动 + String xml = "" + + ""; + + String out = BpmnIdSanitizer.restore(xml, idMap); + + assertThat(out).isEqualTo("" + + ""); + } + + /** null/空 XML 防御:不抛,idMap 为空。 */ + @Test + void 空xml不抛_映射为空() { + assertThat(BpmnIdSanitizer.sanitize(null).idMap()).isEmpty(); + assertThat(BpmnIdSanitizer.sanitize("").idMap()).isEmpty(); + assertThat(BpmnIdSanitizer.restore(null, Map.of())).isNull(); + assertThat(BpmnIdSanitizer.restore("", Map.of())).isEqualTo(""); + } +}