建模工具的难点不在把方框画到画布上,而在于方框背后那棵树是否自洽:元素归谁所有、图里显示哪些、连线端点落在哪条边上、删掉一个类时挂在它身上的关系和它在各张图里的显示引用要不要一起消失。本项目把一个 UML 建模器拆成两半——一半是 773 行零依赖的模型引擎,负责元素树、可见集、几何推导、结构校验、Java 生成与 .java 导入;另一半是 1460 行渲染层,只做 DOM 与 Canvas,不参与任何模型决策。引擎不碰窗口也不碰文件,因此在普通 Node 环境里就能把每个坐标、每条校验、每个生成文件逐项跑出来。

本文基于实际业务源码、当前鸿蒙工程配置与三张应用截图,梳理一份工程 JSON 从磁盘进入模型、被展开成模型树、被排到类图或时序图上、被校验、被翻译成 Java、又被 .java 反向读回模型的完整链路。需要先说明两点:本项目是独立编写的 JavaScript 壳应用,不是把上游 StarUML 移植到鸿蒙,界面与引擎都是重新实现的;本文执行了 JavaScript 语法检查与引擎级实测(36 元素样例装载、12 元素自动布局、锚点与时序坐标手算比对、10 条分级校验、3 个 Java 文件的生成与 3 个类型的正向导入、序列化往返与异常引用修复),以及一组静态一致性校验(8 条 IPC 双向对齐、21 种元素类型、5 种从未被创建的类型),没有运行 Electron 界面、没有执行 HAP 构建,也没有在鸿蒙设备上安装;三张截图只能证明界面结构,不能作为引擎正确性的证据。

欢迎加入开源鸿蒙 PC 社区:https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

AtomGit 仓库地址:https://atomgit.com/OpenHarmonyPCDeveloper/ohos_StarUML

说明:文中代码包含源码节选;未展示完整函数、对象或条件分支的片段需要结合原始上下文阅读,不能独立运行。

一、技术架构分析

1.1 整体架构

项目由鸿蒙工程、Electron 主进程、渲染层与模型引擎四部分组成:

  • 鸿蒙工程:electron 是 entry 模块,依赖 web_engine HAR;业务资源不在 electron 里,而是放在 web_engine 的 resfile/resources/app 目录,随包以资源文件形式落到应用安装目录下。
  • 主进程:232 行,只做两件事——建窗口、读写文件。它注册了 8 条请求响应通道,覆盖工程载入与保存、另存为、打开外部工程、批量读取 .java、按包结构落盘 .java、导出 PNG。
  • 渲染层:1460 行,维护一个 state 对象(当前模型、当前文件、来源、脏标记、选中元素、当前图、折叠状态、连接模式、代码文件列表、校验结果、生成选项、视图变换、拖拽现场),再按状态重绘模型树、图标签、Canvas、属性面板、成员面板、代码面板、校验面板。
  • 模型引擎:773 行,零外部依赖、ES5 语法、导出 41 个 API,涵盖元素增删、图可见集、锚点与时序布局、自动排布、成员文本解析、八类结构校验、Java 代码生成、.java 正向导入、JSON 序列化。

渲染层与引擎的关系是单向的:渲染层 require 引擎,引擎从不知道渲染层存在。引擎里没有任何 document、window、canvas、fs 的引用,这也是后面能在 Node 里直接 require 它、对每个函数下断言的原因。

主进程头部注释与实际注册的通道数量对不上,值得先记下来:注释第 4 行到第 5 行只列了 7 条通道(prj:load、prj:save、prj:saveAs、prj:open、prj:importJavaFiles、prj:exportCodeDir、prj:exportPng),而文件里实际有 8 个 ipcMain.handle 注册,多出来的是 prj:loadSample——也就是工具栏「载入示例」按钮走的通道,它比其余通道晚加,注释没跟着改。实测把主进程的注册列表与渲染层的调用列表对比,8 条全部一一对应,不存在只注册不调用或只调用不注册的通道,所以这处不一致只影响读注释的人,不影响运行。

页面侧还有一层收紧:index.html 的 CSP 是 default-src ‘self’,style-src 单独放开 ‘unsafe-inline’。由于没有写 script-src,脚本来源继承 default-src,内联脚本一律被拒;index.html 里也确实只有 renderer.js 一个外链脚本标签,没有一段内联 JS,两者是配套的。整个应用没有远程资源、没有外部字体、没有网络请求,所有界面元素都由本地 HTML、CSS、Canvas 与 JavaScript 拼出来。

1.2 技术方案

引擎的第一块基石是一张表。21 种元素类型全部登记在 TYPE_INFO 里,每种类型只用几个键描述它是什么、长什么样、默认多大,所有分发逻辑都查这张表,而不是写一长串 if-else:

var TYPE_INFO = {
  package: { label: '包', kind: 'tree', prefix: '«package» ' },
  class: { label: '类', kind: 'classifier', box: true, w: 170, h: 110 },
  interface: { label: '接口', kind: 'classifier', box: true, w: 170, h: 100, prefix: '«interface» ' },
  enumeration: { label: '枚举', kind: 'classifier', box: true, w: 160, h: 96, prefix: '«enum» ' },
  lifeline: { label: '生命线', kind: 'seq', box: true, w: 110, h: 320, prefix: '«lifeline» ' },
  model: { label: '模型', kind: 'tree' },
  // 树内节点(逻辑容器,不绘制)
  clsNode: { label: '类节点', kind: 'tree' },
  itfNode: { label: '接口节点', kind: 'tree' },
  enumNode: { label: '枚举节点', kind: 'tree' },
  attrNode: { label: '属性节点', kind: 'tree' },
  opNode: { label: '操作节点', kind: 'tree' },
  // 关系
  association: { label: '关联', kind: 'edge', line: 'solid', arrow: 'none' },
  generalization: { label: '泛化', kind: 'edge', line: 'solid', arrow: 'triangle' },
  realization: { label: '实现', kind: 'edge', line: 'dashed', arrow: 'triangle' },
  dependency: { label: '依赖', kind: 'edge', line: 'dashed', arrow: 'open' },
  unidirectional: { label: '单向关联', kind: 'edge', line: 'solid', arrow: 'open' },
  aggregation: { label: '聚合', kind: 'edge', line: 'solid', arrow: 'none', head: 'diamondOpen' },
  composition: { label: '组合', kind: 'edge', line: 'solid', arrow: 'none', head: 'diamondFill' },
  // 图
  classDiagram: { label: '类图', kind: 'diagram', canvas: true, w: 1400, h: 1000 },
  sequenceDiagram: { label: '时序图', kind: 'diagram', canvas: true, w: 1200, h: 800 },
  // 时序消息
  message: { label: '消息', kind: 'edge', line: 'solid', arrow: 'open', seq: true }
};

四个布尔位决定行为:box 表示有 x/y/w/h 需要绘制,canvas 表示它是图容器,seq 表示消息参与时序排位,head 表示两端要多画一个菱形。八种关系的线型与箭头也在这张表里,渲染层画线时直接读 info.line 与 info.arrow,因此新增一种关系只需要往表里加一行。

第二块基石是「图只存引用」。UML 的 model 与 view 是分开的:类属于包,图只记录「我显示哪些类」。这条规矩写在 addElement 的注释里,也写在 diagramBoxes 的分支里——类图取 visible 数组,时序图取自己 owned 的生命线,两种图的可见性来源完全不同。

第三块基石是图容器判定不能看实例字段。类图实例上并没有 canvas 字段(它只在 TYPE_INFO 里),所以判定必须回表:

// 图容器判定必须走 TYPE_INFO(元素实例上并不存在 canvas 字段)
function isDiagram(el) { var i = el && TYPE_INFO[el.type]; return !!(i && i.canvas); }
function genId(model, prefix) {
  prefix = prefix || 'el';
  var n = 1;
  while (model.elements && model.elements[prefix + '_' + n]) n++;
  return prefix + '_' + n;
}

genId 的编号规则是「从 1 开始找第一个空位」,删除中间元素后会产生空洞,新元素会复用空洞编号。实测新建模型后依次加包、类、类,得到的 id 是 package_1、class_1、class_2;再连加两个类,得到 class_3、class_4,说明编号是按类型分别递增的,且一旦有空位会回填。这带来一个副作用:删除 class_1 之后再加类,新类会拿到 class_1,如果外部有按 id 保存的引用(比如剪贴板),就会指向别人。引擎里没有剪贴板,模型内部所有引用都在删除时同步清理,所以不会出问题。

至于 id 前缀怎么来的,调用处写的是 type.replace(/[^a-z]/g, ‘’)——只保留小写字母。这意味着 classDiagram 变成 classiagram(大写 D 被删掉而不是转小写),sequenceDiagram 变成 sequenceiagram。内置样例工程的图 id 就正是 classiagram_1 与 sequenceiagram_1。这一处属于「看起来是意外、实际无害」的设计:id 只在模型内部使用,不做展示、不做排序,撞名风险由循环兜住。

第四块基石是校验分级。八类结构问题被判成 error、warn、hint 三档,排序后返回:error 优先(无名元素、关系缺端点、继承成环),warn 其次(同容器重名、关系自环),hint 最后(空壳类、标了 abstract 却没有抽象操作)。界面上的「问题」徽章只统计 error 加 warn,hint 不进徽章——这一点在第六章会单独解释,因为它是最容易被当成 bug 的交互。

1.3 数据模型与状态

引擎文件头用四行注释把数据模型写清楚了,这份契约后面所有函数都遵守:

// ES5、零外部依赖:模型树 + 关系索引 + 锚点/时序布局 + 结构校验 + Java 代码生成 + .java 正向导入 + JSON 序列化
// 数据模型:
//   element = { id, type, name, parent, owned:[ids], docs,
//               分类器: { attributes:[{name,type,visibility,default}], operations:[{name,visibility,params:[{name,type}],ret,abstract}], literals:[..], abstract, finaled }
//               图形: { x, y, w, h }
//   edge    = { id, type, source, target, name, parent, points:[{x,y}], order, docs }

所有元素平铺在一个以 id 为键的字典里,父子关系靠 parent 与 owned 双向记录。这种扁平结构的好处是查找 O(1)、遍历方便、序列化就是一个 JSON.stringify;代价是任何一次删除都必须自己维护一致性——owned 要摘除、引用它的边要删掉、各图的 visible 要除名,四件事一件都不能漏,这正是 removeElement 要写 15 行的原因。

渲染层的 state 对象则是另一套东西,它描述的是「界面现在处于什么状态」,不是模型:

var state = {
  model: null,
  file: null,
  source: 'empty',
  dirty: false,
  selectedId: null,
  currentDiagramId: null,
  collapsed: {},
  linkSource: null,
  linkType: 'association',
  deleteArmed: false,
  deleteTimer: null,
  codeFiles: [],
  codeActive: null,
  issues: null,
  opts: { withPackage: true, withGetters: false },
  view: { scale: 1, ox: 0, oy: 0 },
  drag: null
};

这里有三处状态是需要两个字段配合才成立的:deleteArmed 与 deleteTimer 组成「两步删除」的三秒窗口;linkSource 与 linkType 组成「点连接、再点目标」的两步连线;view 里的 scale/ox/oy 由每次重绘时算出的适应视图产物覆盖,拖拽命中测试要反解它才能把鼠标坐标换成模型坐标。opts 里的 withGetters 默认关闭、withPackage 默认开启,对应代码面板上两个开关按钮的初始状态。

四个层面的职责边界可以这样概括:引擎只认模型,不认 DOM;渲染层只改模型和重绘,不算数;主进程只碰文件,不解析模型;鸿蒙工程只负责把上面这些脚本和原生库装进包里。

二、环境准备

2.1 工程结构

业务代码全部位于 web_engine 模块的 resfile 目录下,共 7 个文件:

文件字节行职责
staruml-engine.js36967773模型、布局、校验、Java 生成与导入、序列化
renderer.js627501460状态、界面、Canvas 绘制与交互
main.js9384232窗口与 8 条 IPC 通道
index.html9281155工具栏、三栏主体、四个详情页签、关于弹层
styles/staruml.css16241未统计暗色主题与三栏布局
samples/demo-project.json18972未统计内置示例工程
package.json2039入口声明,main 指向 main.js

上面的目录里还有一个值得注意的事实:electron 模块的 build 目录下留了一整套中间产物,其中 intermediates/res/default/resources/resfile/resources/app 里也有一份 index.html、main.js、renderer.js、staruml-engine.js、samples/demo-project.json 与 styles/staruml.css。那是上一次构建时从 web_engine 拷贝过去的副本,不是第二份源码。改代码只改 web_engine 下那一份,build 目录随时会重生成。

原生库放在仓库根目录的 lib.unstripped 下:libelectron.so 共 1,143,668,440 字节(约 1.06 GB),libadapter.so 共 15,494,016 字节。这两个文件不进业务源码目录,只作为构建时的原生库输入,通过 build-profile 的 nativeLib.collectAllLibs 收集。

2.2 构建配置

根 build-profile.json5 声明了产物、编译目标与两个模块。与应用体积直接相关的两处是 nativeLib 收集策略与模块划分:

{
  "app": {
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.5(17)",
        "compatibleSdkVersionStage": "release",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "nativeLib": {
            "collectAllLibs": true
          }
        }
      }
    ],

下面的 modules 段把工程分成两块,electron 是源码入口,web_engine 是同级的 HAR:

"modules": [
    {
      "name": "electron",
      "srcPath": "./electron",
      "targets": [
        {
          "name": "default",
          "applyToProducts": [
            "default"
          ]
        }
      ]
    },
    {
      "name": "web_engine",
      "srcPath": "./web_engine"
    }
  ]
}

collectAllLibs 为 true 意味着原生库不做裁剪、全部进包。对于 Electron 这种自带 V8、ICU、资源包与约 1 GB 动态库的运行时来说,这一项决定了包体量级,也决定了它只能面向 2in1 桌面形态,而不能作为轻量移动应用分发。

应用级配置在 AppScope/app.json5:

{
  "app": {
    "bundleName": "com.huawei.ohos_electron",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "configuration": "$profile:configuration",
    "multiAppMode": {
      "multiAppModeType": "multiInstance",
      "maxCount": 1
    }
  }
}

2.3 本地验证方式

这次准备没有装任何新东西,靠三步就能把结论做完:

  • 语法检查:用 node --check 分别检查 staruml-engine.js、renderer.js、main.js,三个文件一次通过,没有任何语法错。这三个是工程里全部的 JavaScript 源文件,剩下的 css 与 json 不需要检查。
  • 引擎级实测:直接 require staruml-engine.js,在纯 Node 进程里用它的 41 个 API 建模型、加元素、算坐标、跑校验、生成 Java、反向导入、序列化往返。引擎零依赖、不引用 DOM、不引用 fs,所以这一步不需要任何模拟环境,也不需要装 Electron。
  • 静态对齐:渲染层与主进程依赖 electron 模块,无法独立运行(renderer.js 顶部就 require 拿 ipcRenderer,main.js 更是直接调用 app.disableHardwareAcceleration),因此这两个文件只能做语法检查加静态比对:主进程注册的通道与渲染层调用的通道是否一一对应、index.html 里的控件 id 与渲染层取用的 id 是否一一对应、CSS 类名与脚本里赋的类名是否对得上。

工程侧也不需要安装业务依赖。根 oh-package.json5 的 dependencies 是空对象,devDependencies 里只有测试框架 hypium;electron 模块的依赖只有一条,指向同级目录的 web_engine:

{
  "license": "",
  "devDependencies": {},
  "author": "",
  "name": "electron",
  "description": "Please describe the basic information.",
  "main": "",
  "version": "1.0.0",
  "dependencies": {
    "web_engine": 'file:../web_engine',
  }
}

这里有一处小的风格不一致:web_engine 的值用了单引号,而同一个文件里别的键都是双引号。json5 允许单引号,所以不影响解析,只是同一个文件里有两种引号习惯。

最后要交代验证边界。本文所有引擎级结论都来自 Node 进程,读的是与打包进 HAP 完全相同的那个文件路径(不是副本,也不是重新写一份),所以不存在「测试跑一套、上线跑另一套」的问题;但界面渲染、Canvas 实际绘制出的像素、系统对话框、导出文件的落盘,这些只能在运行时才能观察的东西,本文没有执行,也没有用截图冒充。

三、核心适配流程

3.1 工程装载链

打开应用时,渲染层在 init 的最后一步调用 prj:load,主进程按「用户工程 → 内置样例 → 空工程」三级回退给出文本:

// 载入当前工程:优先用户工程;无则从内置样例初始化(首次写回用户目录)
ipcMain.handle('prj:load', function () {
  var user = readFileSafe(canonicalProject());
  if (user != null) {
    currentFile = canonicalProject();
    return { success: true, text: user, source: 'user', file: currentFile };
  }
  var smp = readFileSafe(sampleProject());
  if (smp != null) {
    try {
      fs.writeFileSync(canonicalProject(), smp, 'utf-8');
      currentFile = canonicalProject();
    } catch (e) {
      currentFile = null;
    }
    return { success: true, text: smp, source: 'samples', file: currentFile };
  }
  currentFile = canonicalProject();
  return { success: true, text: '', source: 'empty', file: currentFile };
});

这里有两个设计选择。第一个是首次启动自动播种:如果用户目录下还没有工程文件,就把内置样例读出来、写进用户目录、再返回同一份文本。所以第一次打开应用看到的不是空画布,而是一个已经画好的图书馆管理系统;文件行显示来源为内置示例,工程名是图书馆管理系统。第二个是「读不到就当没有」:readFileSafe 把异常全部吞掉返回 null,文件不存在、没有权限、字符集不对,都走同一条回退路,不会把异常抛给渲染层。

渲染层拿到文本后并不直接信,而是交给 modelFromJson 校验,失败就退回空工程:

function loadFromText(text, info) {
  if (!text || !String(text).trim()) {
    var m0 = E.createModel((info && info.name) || 'untitled');
    E.addElement(m0, m0.rootId, 'classDiagram', { name: '类图1' });
    applyModel(m0, info || { file: null, source: 'empty' });
    setStatus('已创建空工程', 'ok');
    return;
  }
  var r = E.modelFromJson(text);
  if (!r.model) { setStatus(r.errors[0] || '工程无法解析,已回退为空工程', 'err'); loadFromText('', info); return; }
  if (r.errors.length) setStatus('工程已载入,忽略 ' + r.errors.length + ' 处异常引用', 'err');
  else setStatus('工程已载入', 'ok');
  applyModel(r.model, info);
}

注意第三行的细节:空文本也会建一个带「类图1」的模型,而不是留一个什么都没有的模型。这是为了让用户无论走哪条路径,界面上都至少有一张可以添加元素的图——否则工具栏「+ 添加」选「类」时会因为找不到容器而无处安放,只能弹一句错误。

装载完成后 applyModel 把模型交给 state,重置选中、连接、代码缓存、校验结果,用 pickDefaultDiagram 挑一张默认图(优先类图,其次时序图),再整体重绘一次。实测把内置样例交给 modelFromJson,得到 0 条错误,元素构成如下:

类型数量
model(根)1
package2
class9
interface2
enumeration1
lifeline4
message5
classDiagram1
sequenceDiagram1
关系(七种合计)10
元素总数36

七种关系分别是泛化 1、实现 2、关联 2、单向关联 1、依赖 2、聚合 1、组合 1,加上 5 条消息,连线总计 15 条,与界面徽章显示的「元素 36 连线 15」完全一致。两个包是 com.lib.model 与 com.lib.service,十二个分类器按包分居两侧:model 包里是 Book、EBook、Member、LoanRecord、IAuditable、MemberLevel,service 包里是 Catalog、BorrowService、ReportService、IBookStore、DbBookStore、Placeholder。类图的 visible 里有 12 项、owned 里有 10 条关系;时序图的 owned 里有 9 项,正好是 4 条生命线加 5 条消息。

把这份样例过一遍校验,结果是 0 条 error、0 条 warn、1 条 hint,唯一那条提示指向 Placeholder:它没有任何成员,被判为空壳类。也就是说,内置样例本身是一个结构干净、命名不冲突、继承不成环的工程,用它来演示功能不会一开屏就满屏报错——但它也不是完美的,Placeholder 的存在本身就是故意留的一个「空壳」样本,用来展示 hint 级提示的样子。

3.2 元素、图与可见集

新建元素只有一个入口 addElement,但它要同时应付四种情况:树节点、分类器、图和关系。处理方式是先查表,再按 kind 补默认字段,最后统一挂到父容器的 owned 里:

// 向容器添加元素(树节点/图形/关系统一入口)
function addElement(model, containerId, type, props) {
  var info = TYPE_INFO[type];
  if (!info) return null;
  var container = model.elements[containerId];
  if (!container) return null;
  props = props || {};
  var id = props.id || genId(model, type.replace(/[^a-z]/g, ''));
  var el = {
    id: id, type: type,
    name: props.name != null ? props.name : (info.kind === 'classifier' ? 'NewClass' : info.kind === 'edge' ? '' : 'New' + type.charAt(0).toUpperCase() + type.slice(1)),
    parent: containerId, owned: [], docs: props.docs || ''
  };
  if (info.kind === 'classifier') {
    el.attributes = []; el.operations = []; el.literals = [];
    el.abstract = false; el.finaled = false;
    el.stereotype = props.stereotype || (info.prefix ? info.prefix.replace(/[«» ]/g, '') : '');
  }
  if (info.box || info.canvas) {
    el.x = props.x != null ? props.x : 40;
    el.y = props.y != null ? props.y : 40;
    el.w = props.w != null ? props.w : (info.w || 1200);
    el.h = props.h != null ? props.h : (info.h || 800);
  }
  // 图:语义上只持有“显示引用”,元素本体仍归包所有(对齐 UML 的 model/view 分离)
  if (info.canvas) el.visible = props.visible || [];
  if (info.kind === 'edge') {
    el.source = props.source || null;
    el.target = props.target || null;
    el.points = [];
    if (info.seq) el.order = props.order != null ? props.order : nextMessageOrder(model, containerId);
  }
  model.elements[id] = el;
  container.owned.push(id);
  recomputeEdge(model, el);
  return el;
}

分类器默认 name 是 NewClass、默认构造型取自 TYPE_INFO 的 prefix 去掉书名号——所以新建接口自动带 interface、枚举自动带 enum、类没有 prefix 所以构造型为空。box 与 canvas 都补几何,默认落在 40,40,尺寸取自表(类 170×110、接口 170×100、枚举 160×96、生命线 110×320、类图 1400×1000、时序图 1200×800)。最后一行 recomputeEdge 是关键:关系一添加就立刻算出端点,而不是等到绘制时才临时求。

图的可见集读取分两个来源,这是 model/view 分离的落地处:

// 图可见集:类图取 visible 引用;时序图取图内拥有的生命线
function diagramBoxes(model, diagramId) {
  var d = model.elements[diagramId];
  if (!d) return [];
  if (d.type === 'sequenceDiagram') {
    return (d.owned || []).map(function (i) { return model.elements[i]; }).filter(function (e) { return e && e.type === 'lifeline'; });
  }
  return (d.visible || []).map(function (i) { return model.elements[i]; }).filter(function (e) { return e && !isEdge(e); });
}

类图里画什么由 visible 决定,元素本体仍在包里;时序图反过来,生命线和消息直接挂在图下面,因为没有「包里的生命线」这种语义。两种图共用同一个读取函数,调用方不必关心分支差异。实测在新建模型上依次显示类、类、接口,visible 从空变成三项,第四次显示同一个类返回 false 表示无变化;把接口隐藏后,diagramBoxes 立刻从三项变两项,而 diagramsShowing 反过来能由一个类查出「类图1」这张图正在显示它。

删除是这套扁平结构里唯一需要小心的地方,因为四件事必须同时做完:

// 从模型移除元素(级联删子元素与所连关系)
function removeElement(model, id) {
  var el = model.elements[id];
  if (!el || id === model.rootId) return false;
  var kids = (el.owned || []).slice();
  kids.forEach(function (c) { removeElement(model, c); });
  // 删除引用该元素的关系
  Object.keys(model.elements).forEach(function (k) {
    var e = model.elements[k];
    if (isEdge(e) && (e.source === id || e.target === id)) removeElement(model, k);
  });
  // 从各图可见集除名
  Object.keys(model.elements).forEach(function (k) {
    var e = model.elements[k];
    if (e.visible) e.visible = e.visible.filter(function (x) { return x !== id; });
  });
  var p = model.elements[el.parent];
  if (p) p.owned = p.owned.filter(function (x) { return x !== id; });
  delete model.elements[id];
  return true;
}

四件事是:递归删子元素、删所有以它为源或目标的边、从每一张图的 visible 里除名、从父容器的 owned 里摘掉,最后才从字典里 delete。顺序不能乱——如果先 delete,后面几个循环就再也找不到这个元素,边会变成悬空引用。根节点有单独保护,删除根直接返回 false。

实测在一个含包、两个类、一张类图、一条关联的小模型上删除第一个类:元素从 6 个降到 4 个(类本身加那条边),连线从 1 条变 0 条,类图 visible 从 2 项变 1 项,包的 owned 从 2 项变 1 项,四项清理全部到位。删除根节点返回 false。

界面层还要负责「新元素放在哪」。这一段是渲染层少数包含几何决策的代码:

function addElementByType(type, name) {
  var info = E.TYPE_INFO[type];
  if (!info) return;
  var cid = containerForNew(type);
  if (!cid) { setStatus('生命线只能加到时序图:请先切换到时序图再添加', 'err'); return; }
  var container = E.findEl(state.model, cid);
  var props = { name: name || '' };
  if (info.kind === 'classifier') props.name = name || 'NewClass';
  if (type === 'package') props.name = name || 'new.package';
  if (type === 'classDiagram' || type === 'sequenceDiagram') props.name = name || (type === 'classDiagram' ? '类图' : '时序图');
  if (type === 'lifeline') props.name = name || '对象 : Class';
  var el = E.addElement(state.model, cid, type, props);
  if (!el) { setStatus('添加失败', 'err'); return; }
  if (info.canvas) {
    el.x = 0; el.y = 0;
    state.currentDiagramId = el.id;
  } else if (type === 'lifeline') {
    var g = E.seqGeom(state.model, container);
    var x = 30;
    g.lifelines.forEach(function (ll) { x = Math.max(x, ll.x + ll.w + 60); });
    el.x = x; el.y = container.y + 16; el.w = 110;
    E.refreshDiagram(state.model, container.id);
  } else if (info.box) {
    // 语义元素挂包,同时显示到当前类图
    var d = currentDiagram();
    if (d && d.type === 'classDiagram') {
      var slot = freeSlot(state.model, d);
      el.x = slot.x; el.y = slot.y;
      E.showOnDiagram(state.model, d.id, el.id);
    }
  }
  state.selectedId = el.id;
  refreshIssues();
  markDirty();
  renderAll();
  setStatus('已添加' + info.label + ':' + (el.name || el.id), 'ok');
}

三件事在这里被定下来:新建的图坐标归零并立刻切换过去;新建的生命线横向排在已有生命线右侧(间距 60)、纵向贴着图顶;新建的类挂到当前包,同时被塞进当前类图的可见集,位置由 freeSlot 找一个不重叠的空位——优先放在最右侧元素右边 40 像素,如果会超出画布宽度就另起一行放在最下边 40 像素。容器选择由 containerForNew 决定:选中包就进包,选中图就回到图的父级,选中边就进边所在的图,选中类就进类所在的包,什么都没选就进根。

有一处默认名值得记一下:新建包默认叫 new.package,新建生命线默认叫对象 : Class,新建图默认叫类图或时序图。这些默认值让「随手点一下添加」不会得到一个空名字,从而避免立刻触发「存在无名元素」这条 error 级校验。

3.3 几何推导

本项目没有任何拖拽式端点拖柄,也没有手工输入连线坐标的入口。所有连线端点、所有消息高度、所有生命线长度都是算出来的——三个函数负责这件事。

第一个是矩形边界锚点,用来决定连线扎在方框的哪一边:

function borderAnchor(a, b) {
  // 从矩形 a 中心朝 b 中心的边界交点
  var cx = a.x + a.w / 2, cy = a.y + a.h / 2;
  var dx = (b.x + b.w / 2) - cx, dy = (b.y + b.h / 2) - cy;
  if (dx === 0 && dy === 0) return { x: cx, y: cy };
  var hw = a.w / 2, hh = a.h / 2;
  var s = (dx !== 0 ? hw / Math.abs(dx) : Infinity);
  var t = (dy !== 0 ? hh / Math.abs(dy) : Infinity);
  var k = Math.min(s, t);
  return { x: Math.round(cx + dx * k), y: Math.round(cy + dy * k) };
}

算法是取两矩形中心连线的方向向量,分别求它撞到水平边、垂直边所需的缩放系数 s 与 t,取较小者就是先撞到的那条边,交点即锚点,最后四舍五入到整数像素。这个方法不需要知道两个矩形谁在左上谁在右下,也不需要对关系类型做分支,八种关系共用同一套端点。

实测两个 170×110 的类,一个在 40,40,一个在 400,300:前者中心 125,95,后者中心 485,355,方向向量 360,260,t 先撞上(55/260 小于 85/360),代入得锚点 201,150;反向再算得 409,300。把后者整体下移 100 像素后重新推导,方向向量变成 360,360,两个系数相等,锚点变成 180,150 与 430,400,连线跟着变陡。两个矩形完全重合时方向向量为零,直接返回中心点,不会出现除零。

第二个是时序图坐标系。时序图不按普通方框排版,它有自己的三根参考线:顶部、头部盒高、底部:

function seqGeom(model, seq) {
  // 时序图坐标系:生命线顶部 y = seq.y+16,头部盒高 50,消息间距 48
  var lifelines = (seq.owned || []).map(function (i) { return model.elements[i]; })
    .filter(function (e) { return e && e.type === 'lifeline'; });
  var messages = (seq.owned || []).map(function (i) { return model.elements[i]; })
    .filter(function (e) { return e && e.type === 'message'; })
    .sort(function (p, q) { return (p.order || 0) - (q.order || 0); });
  var top = seq.y + 16;
  var bottom = top + 50 + Math.max(160, messages.length * 48 + 40);
  return { lifelines: lifelines, messages: messages, top: top, headH: 50, bottom: bottom };
}

三个常数决定了整个时序图的骨架:生命线顶部比图顶低 16 像素、头部盒固定 50 像素高、每条消息占 48 像素。底部取「头顶加头盒再加消息区」的较大值,消息区最少 160 像素。实测一张放在 40,40 的时序图,top 是 56,零消息时 bottom 是 266,四条消息时 bottom 变成 338——生命线会跟着长到 282。

第三个是消息落点。消息不按端点画线,而是按 order 换算成 y 坐标,横向直接取生命线中心:

// 消息端点自动落在生命线激活条上(x 居中、y 按 order)
function layoutMessage(model, msg) {
  var seq = model.elements[msg.parent];
  if (!seq) { msg.points = []; return; }
  var g = seqGeom(model, seq);
  var s = model.elements[msg.source], t = model.elements[msg.target];
  if (!s || !t) { msg.points = []; return; }
  var y = g.top + g.headH + 30 + (msg.order - 1) * 48;
  var x1 = s.x + s.w / 2;
  if (msg.source === msg.target) {
    // 自消息:从生命线向右伸出再回到自身(三点折线)
    msg.points = [{ x: Math.round(x1), y: y }, { x: Math.round(x1 + 70), y: y + 12 }, { x: Math.round(x1), y: y + 24 }];
  } else {
    msg.points = [{ x: Math.round(x1), y: y }, { x: Math.round(t.x + t.w / 2), y: y }];
  }
  // 生命线高度自动覆盖消息
  g.lifelines.forEach(function (ll) {
    ll.y = g.top; ll.h = (g.bottom - g.top);
  });
  // 消息排在末尾时增高生命线
  var maxY = y;
  g.messages.forEach(function (mm) { if (mm.points && mm.points.length) maxY = Math.max(maxY, mm.points[0].y); });
  g.lifelines.forEach(function (ll) { ll.h = Math.max(ll.h, maxY + 30 - g.top); });
}

公式是 y 等于 top 加头盒高再加 30,之后每条消息下移 48 像素。自消息被画成三点折线:向右探出 70 像素、下移 12、再折回原 x、下移 24,正好构成一个可见的回环,而不是一条退化的零长度线。函数末尾还会顺手把生命线高度撑到能盖住最后一条消息,所以加消息不需要单独调整生命线。

实测两条生命线分别放在 x=60 与 x=300,都是 110 宽,中心分别是 115 与 355。第一条消息 order 1,y 为 136,两端点 115,136 与 355,136;第二条 order 2,y 为 184;第三条是自消息,order 3,三点折线为 115,232 与 185,244 与 115,256,生命线高度同步变成 234;再补一条反向消息 order 4,y 为 280,生命线长到 282。四条消息的 y 间隔严格等于 48,没有一条是手工输入的。

第四个函数是自动排布,负责把一张图里所有可见元素重新摆一遍:

// 自动排布:同容器图形网格排布(按现有顺序)
function autoLayout(model, diagramId) {
  var d = model.elements[diagramId];
  if (!d) return 0;
  if (d.type === 'sequenceDiagram') {
    var g = seqGeom(model, d);
    var x = d.x + 30;
    g.lifelines.forEach(function (ll) { ll.x = x; x += ll.w + 60; });
    refreshDiagram(model, diagramId);
    return g.lifelines.length;
  }
  var boxes = diagramBoxes(model, diagramId);
  var cols = Math.max(1, Math.ceil(Math.sqrt(boxes.length)));
  var starts = colStart(model, boxes, cols);
  var maxH = 0;
  boxes.forEach(function (e) { maxH = Math.max(maxH, e.h); });
  boxes.forEach(function (e, i) {
    var c = i % cols, r = Math.floor(i / cols);
    e.x = d.x + 30 + starts[c];
    e.y = d.y + 30 + r * (maxH + 60);
  });
  refreshDiagram(model, diagramId);
  return boxes.length;
}

两种图的策略不同。时序图只做一维排布:生命线横向等间距拉开,第一根从图顶偏移 30 像素开始,之后每根前进「宽度加 60」,纵向完全交给 layoutMessage 决定。类图做二维网格:列数取元素个数的平方根向上取整,列宽取该列最宽元素的宽度加 60(这段在 colStart 里),行高取全体最高元素加 60,左上角从图顶偏移 30 像素开始,按添加顺序逐行填充。

实测内置样例的类图,12 个可见元素排成 4 列 3 行,列起点分别为 30、260、490、720,行起点为 30、200、370——因为所有类都是 170×110,行距正好等于 110 加 60。排布前的坐标是手工摆的:Book 在 60,60,Catalog 在 600,60,Iauditable 与 DbBookStore、MemberLevel、Placeholder 挤在最右侧 860 与 1100 两列,节奏并不均匀;排布后变成规整的 4×3。同样一张时序图排布后,四条生命线落在 x=70 与 240 与 410 与 580,间距 170,与生命线默认 110 宽加 60 留白一致。

3.4 结构校验分级

校验函数是整个引擎里唯一一个「一次性遍历全模型、到处收集问题」的地方。它不做修复,只把问题按严重程度分级返回:

// ========== 结构校验 ==========
function validateModel(model) {
  var probs = [];
  function push(level, id, msg) { probs.push({ level: level, id: id, msg: msg }); }
  var els = Object.keys(model.elements).map(function (k) { return model.elements[k]; });
  els.forEach(function (el) {
    // 关系的 name 允许为空(UML 关系通称不必命名)
    if (isEdge(el)) return;
    if (!String(el.name || '').trim()) push('error', el.id, '存在无名元素(' + (TYPE_INFO[el.type] ? TYPE_INFO[el.type].label : el.type) + ')');
  });
  // 同级重名
  var byParent = {};
  els.forEach(function (el) {
    if (!el.parent || isEdge(el)) return;
    var key = el.parent + '|' + String(el.name || '').toLowerCase();
    if (byParent[key]) push('warn', el.id, '「' + el.name + '」与同容器内另一元素重名');
    byParent[key] = 1;
  });
  // 关系端点
  allEdges(model).forEach(function (e) {
    if (!e.source || !e.target) push('error', e.id, '关系「' + (e.name || TYPE_INFO[e.type].label) + '」缺少端点');
    // 时序图自消息(生命线调用自身)是合法 UML,不算自环
    else if (e.source === e.target && e.type !== 'message') push('warn', e.id, '关系自环(源与目标相同)');
  });
  // 泛化环检测
  var gen = {};
  allEdges(model).forEach(function (e) {
    if (e.type === 'generalization' || e.type === 'realization') {
      (gen[e.source] = gen[e.source] || []).push(e.target);
    }
  });

前面这些都是线性扫描,真正需要算法的只有泛化环检测——把泛化与实现边抽成一张邻接表,然后用三色标记做深度优先搜索,遇到灰色节点说明回到自己身上了。

实测在一个刻意做坏的小模型上(两个同名类、一个无名类、一条缺端点的关联、一对互为泛化的类、一个自环关联、一个标了 abstract 但没有抽象操作的类、一条合法自消息),校验返回 10 条问题,分级为 error 3 条、warn 2 条、hint 5 条,且排序正确——error 全部排在前面。三条 error 分别指向无名元素、缺少端点、继承成环;两条 warn 分别指向同容器重名与关系自环;五条 hint 里包括两条空壳类提示、一条 abstract 提示,以及时序图那条自消息没有产生任何提示,说明自消息豁免生效了。

有一处输出格式上的不一致值得记下来:继承成环那条消息拼的是「继承出现环:A → a → A → class_1」,路径前半段用的是元素名,最后一段却是内部 id。原因是递归时把上游的名字拼进了栈,而报错时又把当前节点的 id 直接接在末尾。这不影响定位(点击那一行仍会跳到正确的元素),但读起来会混。相比之下,重名与端点的消息都用的是元素名,是可读的。

校验结果的上层用法有两个:一是面板里逐条列出,点击某条会把选中项切到问题元素并把当前图切到能显示它的那一张;二是工具栏的「问题」徽章,它只统计非 hint 的数量。这个口径差异导致一个常见误解——内置样例校验出来有 1 条问题,徽章却显示 0。原因就在 refreshIssues 里,统计时把 hint 排除了,见第六章 Q6。

3.5 Java 代码生成

代码生成是一个纯函数:吃一个模型,吐一组文件。它不做增量、不落盘、不碰对话框,落盘交给主进程的 exportCodeDir:

function genJava(model, opts) {
  opts = opts || {};
  var els = Object.keys(model.elements).map(function (k) { return model.elements[k]; });
  var classifiers = els.filter(isClassifier);
  var out = [];
  classifiers.forEach(function (t) {
    var pkg = ownerPackage(model, t);
    var lines = [];
    if (opts.withPackage && pkg && pkg.type === 'package') lines.push('package ' + javaPackageName(pkg.name) + ';', '');
    if (t.docs) lines.push('/**', ' * ' + t.docs, ' */');
    var ext = [], impl = [];
    allEdges(model).forEach(function (e) {
      if (e.source !== t.id) return;
      var tg = model.elements[e.target];
      if (!tg) return;
      if (e.type === 'generalization') ext.push(tg);
      else if (e.type === 'realization') impl.push(tg);
    });
    var mods = [];
    if (t.type === 'class' && t.abstract) mods.push('abstract');
    if (t.type === 'class' && t.finaled) mods.push('final');
    var JAVA_KIND = { class: 'class', interface: 'interface', enumeration: 'enum' }[t.type] || 'class';
    var head = JAVA_KIND + ' ' + sanitizeJavaName(t.name, 'Type');
    if (ext.length) head += ' extends ' + ext.map(function (x) { return x.name; }).join(', ');
    if (impl.length) head += (t.type === 'interface' ? ' extends ' : ' implements ') + impl.map(function (x) { return x.name; }).join(', ');
    lines.push(mods.concat([head]).join(' ').trim() + ' {');
    var body = [];
    if (t.type === 'enumeration' && (t.literals || []).length) {
      body.push('    ' + t.literals.map(function (l) { return sanitizeJavaName(l, 'L').toUpperCase(); }).join(', ') + ';');
    }
    (t.attributes || []).forEach(function (a) {
      body.push('    ' + javaVis(a.visibility, 'private') + ' ' + (a.type || 'String') + ' ' + sanitizeJavaName(a.name, 'field') +
        (a.default ? ' = ' + a.default : '') + ';');
    });
    if (t.type !== 'interface' && opts.withGetters) {
      (t.attributes || []).forEach(function (a) {
        var cap = String(a.name || '').charAt(0).toUpperCase() + String(a.name || '').slice(1);
        var capSafe = sanitizeJavaName(cap, 'V');
        body.push('', '    public ' + (a.type || 'String') + ' get' + capSafe + '() { return ' + sanitizeJavaName(a.name, 'field') + '; }',
          '    public void set' + capSafe + '(' + (a.type || 'String') + ' v) { this.' + sanitizeJavaName(a.name, 'field') + ' = v; }');
      });
    }
    (t.operations || []).forEach(function (o) {
      var sig = '    ' + ((t.type === 'interface' || o.abstract) ? 'abstract ' : '') +
        javaVis(o.visibility, 'public') + ' ' + (o.ret || 'void') + ' ' + sanitizeJavaName(o.name, 'op') + '(' +
        (o.params || []).map(function (p) { return (p.type || 'Object') + ' ' + sanitizeJavaName(p.name, 'arg'); }).join(', ') + ')';
      if (t.type === 'interface' || o.abstract) body.push(sig + ';');
      else body.push(sig + ' {', (o.ret && o.ret !== 'void' ? '        throw new UnsupportedOperationException("TODO");' : '        // TODO'), '    }');
    });
    lines.push(body.join('\n'));
    lines.push('}', '');
    out.push({
      path: (pkg && pkg.type === 'package' ? pkg.name.replace(/\./g, '/') + '/' : '') + sanitizeJavaName(t.name, 'Type') + '.java',
      name: t.name, type: t.type, code: lines.join('\n').replace(/\n{3,}/g, '\n\n')
    });
  });
  return out;
}

这段代码里有几个决定值得逐一说明。第一,父关系只认泛化与实现两种:只有 generalization 会变成 extends,只有 realization 会变成 implements,关联、依赖、聚合、组合、单向关联五类关系在代码里一律不出现。这与 Java 的类型系统是匹配的——其余四种关系只表达引用或语义,落成字段还是局部变量取决于实现细节,不应由建模器替用户决定。第二,接口的父关系是用 extends 而不是 implements,这是 Java 接口继承接口的写法,代码里专门做了分支。第三,一个类型只有一个包,由 ownerPackage 向上找最近一层包名,找不到就不输出 package 语句,文件就落在目标目录根部。

实测用一个小模型走一遍:建包 com.acme.shop,在包里放一个 abstract 类 Order(带一句说明、两个属性、两条操作)、一个接口 Payable(一条抽象操作)、一个枚举 Status(三个字面量 NEW、paid、2019),再在类图里加一条 Order 到 Payable 的实现关系,然后打开 getter/setter 开关生成。得到的产物如下:

文件类型关键产物
com/acme/shop/Order.javaclasspackage com.acme.shop; 与三行 Javadoc 注释;abstract class Order implements Payable {;两个 private 字段(id 无初值、amount 初值 0.0);两对 getter/setter;abstract public double total();;public String describe(String prefix) 方法体为抛 UnsupportedOperationException
com/acme/shop/Payable.javainterfacepackage com.acme.shop;;interface Payable {;abstract public boolean pay(double amount);
com/acme/shop/Status.javaenumerationpackage com.acme.shop;;enum Status {;NEW, PAID, _2019;

四个细节必须说清楚,因为它们直接决定生成出来的代码能不能用:

  • 类型本身不带可见性修饰符。第一行的类声明是 abstract class Order,不是 public abstract class Order。生成器只给成员配可见性(属性默认 private、操作默认 public),类型级始终不输出 public。包内可见的类仍然可以编译,只要调用方与它在同一个包里;但一旦跨包引用就会失败,而文件名已经按 public 类的习惯命名为 Order.java。这是源码里没有注释说明的一处保守选择。
  • 枚举字面量一律转大写并清洗。模型里写 paid、2019,生成出来是 PAID、_2019(首字符是数字就补下划线)。对 Java 枚举的主流写法(全大写)这是合理的,代价是模型里的原文与生成结果不再一一对应——在模型面板里看到 paid,在生成的代码里看到 PAID,来回一趟就对不上了。
  • 抽象方法的修饰符顺序是 abstract 在前、可见性在后,输出为 abstract public double total();。语法合法,但与普遍写法 public abstract 相反。接口里的方法也一样输出这一串。
  • 未实现的普通方法不是空实现。有返回值的方法体只有一句抛出 UnsupportedOperationException 并带 TODO 字样,返回 void 的方法体只有一行注释。这意味着生成出来的代码可以立即编译通过,但一旦真的调用到未实现的方法就会抛异常——它是显式的未实现信号,不是默默返回 null 的坑。

还有两处开关。把 package 开关关掉后,首行不再输出包语句,而是直接跟 Javadoc;把 getter/setter 开关关掉后,属性下面不会多出访问器。两个开关都是纯输出选项,不改模型。

实测内置样例的生成结果:12 个分类器对应 12 个 .java 文件,路径严格按包分两层——com/lib/model 下是 Book、EBook、Member、LoanRecord、IAuditable、MemberLevel,com/lib/service 下是 Catalog、BorrowService、ReportService、IBookStore、DbBookStore、Placeholder。文件名与类型名一致,两个包各自成目录,没有交叉。

这里有一个隐含问题需要提醒:落盘路径用的是包名的原构成(把点换成斜杠),而 package 语句用的是清洗后的包名(把非法字符换掉、关键字加前缀)。这两个处理对正常包名(com.lib.model 这类)结果一致;但对带了非法字符的包名就不一致了。实测把包命名为 com.2bad.class 时,package 语句输出是 com._2bad.pkgclass,而文件路径却是 com/2bad/class/Foo.java——目录结构与包声明不匹配,javac 会因为目录与包不一致而报错。这一条属于输入不合法时的边界行为,正常建模不会碰到,但值得记在第四章的一致性清单里。

3.6 Java 正向导入与往返

导入是生成的逆过程,但难度高得多:生成时你知道每个字段的含义,导入时只有一段文本。引擎的办法是先把注释与字符串内容掏空,保留括号结构,这样后面的扫描不会被注释里的 class 字样骗到:

// ========== .java 正向导入 ==========
function stripCode(src) {
  // 去注释与字符串内容(保留结构括号),返回 {src}
  var out = [], i = 0, n = src.length;
  while (i < n) {
    var c = src[i], d = src[i + 1];
    if (c === '/' && d === '/') { while (i < n && src[i] !== '\n') i++; continue; }
    if (c === '/' && d === '*') { i += 2; while (i < n && !(src[i] === '*' && src[i + 1] === '/')) i++; i += 2; continue; }
    if (c === '"' || c === "'") {
      var q = c; i++;
      while (i < n && src[i] !== q) { if (src[i] === '\\') i++; i++; }
      i++; out.push('""'); continue;
    }
    out.push(c); i++;
  }
  return out.join('');
}
function matchBrace(s, from) {
  var depth = 0;
  for (var i = from; i < s.length; i++) {
    if (s[i] === '{') depth++;
    else if (s[i] === '}') { depth--; if (depth === 0) return i; }
  }
  return -1;
}

字符串被整体替换成一对空引号,长度变了但结构位置不受影响;注释被整段扔掉。接着用正则扫类型声明,再用 matchBrace 从开括号向后配平找到配对的闭括号,得到一个完整的类型体。这一步不做 AST 解析——真正的做法就是括号计数,所以只要源文件括号平衡,即使里面有千奇百怪的写法也能切对。

真正难的是分辨「这是字段还是方法」。引擎的选择是只扫第一层成员,用深度计数跳过内部的所有子块:

// 只扫第一层成员
    var depth = 0, buf = '';
    for (var i = 0; i < body.length; i++) {
      var ch = body[i];
      if (ch === '{') { depth++; buf = ''; continue; }
      if (ch === '}') { depth--; buf = ''; continue; }
      if (ch === ';') {
        if (depth === 0 && buf.trim()) { var it = classifyMember(buf.trim()); if (it) pushMember(t, it, name); }
        buf = ''; continue;
      }
      if (depth === 0) {
        if (ch === '(') {
          // 方法:吃到匹配的 ) 再找 { 或 ;
          var j = i + 1, pd = 1;
          while (j < body.length && pd > 0) { if (body[j] === '(') pd++; else if (body[j] === ')') pd--; j++; }
          var sigTxt = buf + body.slice(i, j);
          var k = j;
          while (k < body.length && body[k] !== '{' && body[k] !== ';') k++;
          var tailCh = body[k];
          var mm = classifyMember(sigTxt + ';');
          if (mm) pushMember(t, mm, name);
          if (tailCh === '{') { var bc = matchBrace(body, k); i = (bc < 0 ? body.length : bc); depth = 0; buf = ''; continue; }
          i = k; buf = ''; continue;
        }
        buf += ch;
        if (ch === '\n' && !buf.trim()) buf = '';
      }
    }

遇分号就把缓存解析成字段,遇左括号就把方法签名吃到配对的右括号,然后看后面是 { 还是 ;:如果是方法体,直接跳到配对的闭括号并继续;如果是抽象方法或接口方法,下一条就是分号。这样一来,方法体里出现的 if、for、while、return 都不会被误识别为成员。

把解出来的类型写进模型时,还要处理图、包、重名与关系:

var res = { added: 0, renamed: 0, warnings: parsed.warnings, types: [] };
  var byName = {};
  parsed.types.forEach(function (t) {
    var nm = t.name;
    if (byName[nm.toLowerCase()]) { nm = uniqueName(model, pkgNode.id, nm); res.renamed++; }
    byName[t.name.toLowerCase()] = 1;
    var el = addElement(model, pkgNode.id, t.kind === 'interface' ? 'interface' : t.kind === 'enum' ? 'enumeration' : 'class', { name: nm });
    el.abstract = !!t.isAbstract; el.finaled = !!t.isFinal;
    el.attributes = t.fields.map(function (f) { return { name: f.name, type: f.type, visibility: '-', default: '' }; });
    el.operations = t.methods.map(function (mm) {
      var params = String(mm.params || '').split(',').map(function (s) {
        s = s.trim(); if (!s) return null;
        var toks = s.split(/\s+/); var pn = toks.pop();
        return { name: pn || 'arg', type: toks.join(' ') };
      }).filter(Boolean);
      return { name: mm.name, ret: mm.ret || 'void', visibility: t.kind === 'interface' ? '+' : 'public', params: params, abstract: t.kind === 'interface' };
    });
    el.literals = t.literals;
    el.x = diagram.x + 30 + (res.added % 3) * 230;
    el.y = diagram.y + 30 + Math.floor(res.added / 3) * 190;
    if (el.attributes.length || el.operations.length) el.h = Math.max(110, 70 + (el.attributes.length + el.operations.length) * 18);
    // 元素本体仍归包所有,仅参加到图的可见集
    showOnDiagram(model, diagram.id, el.id);
    res.types.push(el);
    res.added++;
  });

三个设计点:导入的新类型统一挂在包下(没有包名就挂在容器下),只往图里加引用,元素本体不进图;坐标按三列网格自动铺,行距 190、列距 230;高度按成员条数估算(70 加成员数乘 18,最少 110)。这样导入十几个文件后不会全叠在原点。

实测拿一段带包名、带构造器、带静态常量、带抽象方法、带方法体的 Java 源码导入,解出三个类型:abstract class Order(父类 BaseOrder、接口 Payable、字段 String id 与 double amount 与 int MAX、方法 double total() 与 String describe(String prefix) 与 boolean isPaid())、interface Payable(方法 boolean pay(double amount))、enum Status(字面量 NEW 与 PAID)。构造器 Order() 被正确跳过(判断依据是方法名等于类型名),方法体里的 if 与 return 也没被当成成员。导入结果是新增 3 个类型、0 次改名、0 条告警,并自动在包下建了一张名为 com.acme.shop 导入图的类图,位置在容器右侧 100,40,可见集里有两个类型。关系方面,Order 到 Payable 的实现边建成了,而 Order 到 BaseOrder 的泛化边因为 BaseOrder 不在模型里而没有创建——代码里的注释把这种情况写明为「按简单名在全模型中查找,找不到就跳过」。

这里有一处真实的保真度损失要说清楚:Java 源码里的可见性修饰符在导入时被忽略,字段一律记为 private、方法一律记为 public。所以一句 public static final int MAX = 10 导入后,变成了一个私有实例字段,static 与 final 两个语义都丢了。这是「只扫第一层成员的轻量解析」必然要付出的代价,不是随便漏写的。

更麻烦的是枚举的往返。用一份只含一句 enum Status { NEW, PAID; } 的源码导入,字面量被正确识别为两个,但扫描时第一层的 NEW, PAID 段既不是方法也不是以分号结尾的字段,却在后面遇到第一个分号时被带去分类,结果这个枚举同时多出了一个名为 PAID、类型为 NEW, 的字段。再把这份模型生成回去,得到的枚举体里除了正确的字面量行,又多出一行 private NEW, PAID;——这不是合法 Java。也就是说,模型到代码、代码到模型这条路对枚举不是无损的:一次导入再生成,枚举就坏了。这一点在第六章 Q5 会单独展开。

序列化是往返的另一个方向,它的规则很简单但有两个细节:

// ========== 序列化 ==========
function modelToJson(model, pretty) {
  var clean = { version: model.version, name: model.name, rootId: model.rootId, elements: {} };
  Object.keys(model.elements).forEach(function (k) {
    var e = model.elements[k], o = {};
    Object.keys(e).forEach(function (p) { if (p !== 'points' || (e.points && e.points.length)) o[p] = e[p]; });
    clean.elements[k] = o;
  });
  return JSON.stringify(clean, null, pretty === false ? 0 : 2);
}
function modelFromJson(text) {
  var errs = [];
  var raw;
  try { raw = JSON.parse(text); } catch (e) { return { model: null, errors: ['JSON 解析失败:不是合法工程文件'] }; }
  if (!raw || typeof raw !== 'object' || !raw.elements || typeof raw.elements !== 'object')
    return { model: null, errors: ['缺少 elements 字段,不是 StarUML 工程文件'] };
  var model = createModel(raw.name || 'imported');
  model.version = raw.version || 1;
  Object.keys(raw.elements).forEach(function (id) {
    var e = raw.elements[id];
    if (!e || !TYPE_INFO[e.type]) { errs.push('忽略未知元素类型: ' + (e && e.type)); return; }
    model.elements[id] = e;
    e.id = id;
    e.owned = (e.owned || []).filter(function (x) { return raw.elements[x]; });
  });
  if (!model.elements[model.rootId]) {
    var roots = Object.keys(model.elements).filter(function (k) { return model.elements[k].type === 'model'; });
    if (!roots.length) return { model: null, errors: ['找不到根节点'] };
    model.rootId = roots[0];
  }
  // 端点完整性
  Object.keys(model.elements).forEach(function (k) {
    var e = model.elements[k];
    if (!isEdge(e)) return;
    if (e.source && !model.elements[e.source]) { errs.push('关系 ' + k + ' 源端点丢失'); e.source = null; }
    if (e.target && !model.elements[e.target]) { errs.push('关系 ' + k + ' 目标端点丢失'); e.target = null; }
  });
  // 校验 parent 存在
  Object.keys(model.elements).forEach(function (k) {
    var e = model.elements[k];
    if (e.parent && !model.elements[e.parent]) { e.parent = model.rootId; model.elements[model.rootId].owned.push(k); errs.push('元素 ' + k + ' 容器丢失,已挂到根'); }
  });
  return { model: model, errors: errs };
}

两个细节:写盘时会丢掉空的 points 数组(只保留非空的),因为端点坐标随时可以由几何重算,存下来只是冗余;读盘时会做三类修复——未知类型直接忽略、端点丢失就把那一端置空、容器丢失就重挂到根。三类修复都是「尽量救回来」而不是「报错拒绝」,所以一个半损的工程文件还是能打开。

实测往返:把那个含包、类、接口、枚举、类图与一条实现关系的小模型序列化后再读回,0 条错误,元素数 7 对 7,二次序列化与原文本逐字节相同。测三份异常输入:给一段不是 JSON 的文本,返回解析失败;给一个没有 elements 的 JSON,返回缺少字段并拒绝;给一份同时含未知类型、断端点、丢了容器的工程,返回三条错误但模型仍然可用,被断的边目标端置空,丢容器的元素被挂到根。

最后一项实测暴露了一个真实缺陷:容器丢失的元素会被重复加入根的 owned。构造一份 root 的 owned 已经是两个 id、其中一个元素的 parent 指向不存在的容器的工程,读回来以后根的 owned 变成了三个元素,同一个 id 出现了两次。原因是重挂分支直接 push,没有先判断是否已经存在。这个重复项不会导致崩溃(子元素遍历会重复渲染一行,删一次之后才恢复正常),但它确实是数据不一致,已记入第四章的一致性清单。

四、鸿蒙稳定性适配

4.1 窗口创建与 GPU 合成:三个固定参数与一处静默失败

问题现象:Electron 壳应用在鸿蒙 PC 上第一帧容易出现白屏,或者窗口刚出现就退出进程,可重复性很差——同一台机器上有时正常,有时不正常;换成软件合成之后现象消失。

根因分析:Electron 在鸿蒙的窗口里不是直接拿到一块原生窗口,而是通过 XComponent 承载渲染输出,最终又交给系统的 GPU 合成。这条链路上任何一层在不支持硬加速的环境下失败,表现都是「画面出不来」而不是一个明确的错误码。项目对此的应对是干脆不用 GPU:在主进程加载最开始就关掉硬件加速,并且在创建窗口时一次性固定三个与合成相关的参数。

解决方案:两层且都在 app 就绪之前完成,一个参数都不依赖用户设置:

// 防 GPU 白屏:禁用硬件加速
app.disableHardwareAcceleration();

// 去掉顶部 File/Edit/View/Window/Help 默认菜单栏
Menu.setApplicationMenu(null);
function createWindow() {
  try {
    var display = screen.getPrimaryDisplay();
    var width = display.workAreaSize.width;
    var height = display.workAreaSize.height;

    // 防 XComponent 崩溃:frame: true + transparent: false + resizable: true
    mainWindow = new BrowserWindow({
      width: Math.floor(width * 0.94),
      height: Math.floor(height * 0.88),
      frame: true,
      transparent: false,
      resizable: true,
      title: 'StarUML - UML 建模',
      webPreferences: {
        nodeIntegration: true,
        contextIsolation: false
      }
    });

    mainWindow.loadFile('index.html');
  } catch (e) {
    console.warn('[StarUML] 创建窗口失败:', String(e && e.message));
  }
}

三个参数各自对应一种已知的失败模式:frame 为 true 表示用系统原生边框而不是自绘无边框窗(无边框需要额外的合成与命中区处理,正是 XComponent 链路里最脆的一段);transparent 为 false 表示不做透明背景(透明窗需要额外的 alpha 合成通道);resizable 为 true 表示保留系统缩放能力(禁缩放的固定尺寸窗在某些桌面环境下会走另一条尺寸同步路径)。注释里把这三个参数明确标成了「防 XComponent 崩溃」,说明它们是踩过坑之后的经验值,而不是随意选的。

窗口尺寸取工作区的 0.94 与 0.88,不占满全屏,给任务栏与边框留出余量。菜单栏被整个置空,因为所有功能都在页内工具栏上,留着默认英文菜单只会多出几个点了没反应的项。还有两处需要如实记下:窗口没有声明最小尺寸(没有 minWidth 与 minHeight),拖到极窄时三栏布局与画布只剩一点宽度,此时画布会把宽高各自压到 120 像素的下限,也就是说布局会被挤压到接近不可用而不会阻止;window-all-closed 里直接 app.quit(),没有写平台分支,所以关掉最后一个窗口就结束进程,行为与单窗口桌面应用一致。

教训:防御性参数没有“条件生效”这种写法,一旦定了就是全平台生效,所以必须写清它防的是什么——本例的注释把参数与崩溃现场直接对应起来,后来人才能判断能不能去掉。另一个教训是 createWindow 把整个函数包在 try/catch 里、失败只 console.warn 不弹错,好处是不会因为建窗失败而崩掉进程,代价是用户看到的是一个空白窗口而不是一句人话的错误。

4.2 生成代码落盘:包名来自用户输入与目录穿越

问题现象:把模型里的包重命名成含点路径的一串(例如 com.demo.model),点「生成到目录…」后,文件应该落在所选目录下的 com/demo/model 里;如果包名里被手工写进了向上跳的路径,文件也不应该落到目标目录之外。

根因分析:落盘路径不是固定的,它是「模型里的包名 + 类名 + .java」拼出来的,而包名是用户在属性面板里自由输入的字符串。凡是从用户输入拼路径的地方,就默认存在目录穿越的可能;一旦越出所选目录,应用就会在用户不知情的地方写文件。

解决方案:主进程在写入前对每一条路径做三层清洗,并对最终结果做一次包含性判定:

var dir = r.filePaths[0];
      var written = 0, skipped = 0;
      files.forEach(function (f) {
        if (!f || !f.path || f.code == null) { skipped++; return; }
        // 防目录穿越:清洗相对路径并限定在目标目录内
        var rel = String(f.path).replace(/\\/g, '/').replace(/^\/+/, '').replace(/(\.\.[\\/])+/g, '');
        var out = path.resolve(dir, rel);
        if (out.indexOf(path.resolve(dir)) !== 0) { skipped++; return; }
        try {
          fs.mkdirSync(path.dirname(out), { recursive: true });
          fs.writeFileSync(out, String(f.code), 'utf-8');
          written++;
        } catch (e) {
          skipped++;
        }
      });
      if (!written) return resolve({ success: false, error: '生成失败:没有文件写入成功' });
      resolve({ success: true, dir: dir, written: written, skipped: skipped });

三层清洗分别是:把反斜杠统一成正斜杠(避免 Windows 路径分隔符绕过正则)、去掉开头的斜杠(否则 resolve 会把它当成盘符根而不是相对路径)、删掉所有向上跳的段。删除用的正则是全局的,所以连着写的多段箭头跳也会被一次清掉。清洗完再用 path.resolve 拼成绝对路径,最后用一段前缀判定确认它仍在目标目录内;一旦不在,就计入跳过数而不写入。写入前还先建中间目录,所以多级包名不需要用户先手动建目录。

需要如实指出,这层判定用的是最朴素的字符串前缀比对,它在两个边界上并不严格:一,若目标目录本身就带同名前缀(比如选了 D:\out,而最终路径是 D:\out2\X.java),比对会通过;二,Windows 盘符大小写不一致时也可能误判。实际影响有限,因为前面的清洗已经把向上跳的段删干净了,这两条只会在后续维护里成为隐患。

教训:路径安全不能指望“用户不会那么写”,而要拿一条固定的清洗流水线把每一条拼出来的路径过滤一遍;同时,被跳过的文件必须计数回传给界面,否则用户以为全写成功而实际上少了几个文件。本例回传了 written 与 skipped 两个数,状态栏会同时显示。

4.3 静态一致性清单

本轮不改一行业务代码,只把源码里“注释与实现、结构体与用法、生成与解析”之间的矛盾列成一张清单。它们都不影响打开应用,但都会在某个具体操作上暴露:

编号位置现象影响
1main.js 头部注释注释列 7 条通道,实际注册 8 条只影响读注释的人,prj:loadSample 未被列入
2staruml-engine.js 的 TYPE_INFO五种树节点类型(clsNode 等)只有定义,全工程 0 次创建预留类型;但 modelFromJson 会接受它们,属于开口
3main.js 与引擎的异常处理通道没有统一的 try/catch 封装,读写异常散落在各 handler有的异常变成 success:false,有的被 readFileSafe 吞成 null
4modelFromJson 的重挂分支容器丢失的元素重挂到根时直接 push,不查重根的 owned 会出现重复 id
5未知类型的 owned 过滤过滤参照的是原始 JSON 而非入模后的元素被忽略的未知类型仍留在父容器的 owned 里
6genJava 的路径与包语句路径用包名原字面,语句用清洗后的包名包名含非法字符时目录与包声明不一致
7genJava 的类型声明类型级从不输出 public生成物只能包内可见,不符合通常习惯
8枚举导入往返字面量段同时被当作字段一次导入再生成,枚举体多出一行非法声明
9parseMember 的属性分支不认 Java 可见性词,private int x 会变成类型 private int配合默认 public 会生成 public private 这种非法修饰
10parseMember 的操作分支省略返回类型时正则错切(run() 解成 cal)必须写成 void run() 才能得到正确签名
11validateModel 的环提示路径前半段用名字、末尾用内部 id告警文案可读性下降,不影响定位
12窗口与生命周期无 minWidth 与 minHeight;window-all-closed 无平台分支极窄窗口下布局不可用;关最后一个窗口即退进程

十二条里只有第 8 与第 9 两条会产生“输出非法 Java”的后果,其余都是可读性、冗余或边界上的不严谨。这两条的共同点是:都被一个看起来合理的局部规则挡住了一眼——枚举的字面量段确实在遇分号前是裸文本,成员的 type 确实可以带空格——所以它们能活到发布而不被发现。

还有一处不属于缺陷、但必须在交付说明里写清的事实:应用名没有改。AppScope 的字符串资源里 app_name 的值仍是 Electron,vendor 仍是 example,bundleName 也还是模板的 com.huawei.ohos_electron。它们不影响功能,但如果要对外分发,这些标识就必须换掉,否则安装后在桌面上看到的名字会与实际产品对不上。

教训:一致性不能靠“写完看一眼”来保证,而要靠一张可重复跑的表。本轮的十二条里有五条(第 1、4、5、8、11)是把实测输出与源码对照才发现的,读代码时不显眼。

4.4 Canvas 尺寸与设备像素比

问题现象:在高分屏上,画布里的连线与文字看起来发虚,一像素细线变成两三个像素的灰带;而把同一张图导出成 PNG 后,图片尺寸又比屏幕上看到的区域大一圈。

根因分析:HTML 的 canvas 有两套尺寸:CSS 布局尺寸(clientWidth 与 clientHeight)与位图尺寸(width 与 height 属性)。若两者相等、而屏幕的设备像素比大于 1,浏览器就会把位图放大到物理像素上输出,结果是模糊;若按设备像素比把位图放大,则必须把绘图坐标同步缩放,否则内容只会画在左上角四分之一。

解决方案:每次重绘都重新计算一次位图尺寸与变换矩阵,并在同一个函数里把横纵两个比例都应用上:

function renderCanvas() {
  if (!ctx) return;
  var cw = Math.max(120, canvas.clientWidth || 400);
  var chh = Math.max(120, canvas.clientHeight || 300);
  var dpr = window.devicePixelRatio || 1;
  canvas.width = Math.floor(cw * dpr);
  canvas.height = Math.floor(chh * dpr);
  ctx.setTransform(1, 0, 0, 1, 0, 0);
  ctx.fillStyle = PAL.crust;
  ctx.fillRect(0, 0, canvas.width, canvas.height);
  var d = currentDiagram();
  if (!d || !state.model) { setHint('当前没有可显示的图。用工具栏「+ 添加」新建类图或时序图。'); return; }

后面的部分计算出图内容的包围盒、适应窗口的缩放比例与平移量,并把它们连同 dpr 一起写进 state.view:

var b = diagramBounds(state.model, d);
  var scale = Math.min(1, (cw - 28) / Math.max(1, b.w), (chh - 28) / Math.max(1, b.h));
  var ox = (cw - b.w * scale) / 2 - b.x * scale;
  var oy = (chh - b.h * scale) / 2 - b.y * scale;
  state.view = { scale: scale, ox: ox, oy: oy, dpr: dpr };
  ctx.setTransform(dpr * scale, 0, 0, dpr * scale, dpr * ox, dpr * oy);

这段的做法是:位图按 devicePixelRatio 放大,坐标变换一次性带上 dpr 与 scale 两个缩放与 ox/oy 两个平移,于是后面所有绘图代码都可以直接用模型坐标,不需要在任何一处手动乘 dpr。四个结果很关键:

  • 适应窗口的 scale 用三者的最小值,并且被封顶在 1。这意味着图只会被缩小以适应窗口,永远不会被放大;模型里 170 像素宽的类在高分屏上就是屏幕上的 170 个 CSS 像素宽,不会因为屏幕大而被拉伸。
  • 平移量按包围盒而不是按画布原点算,所以内容始终居中,而不是粘在左上角。
  • 网格线宽用 1 除以 scale 来补偿,这样无论缩放到多小,网格始终是一屏幕像素,不会变成一大块实色。
  • 鼠标命中测试走 worldPos,它用 CSS 像素减去 ox 再除以 scale 反解回模型坐标,全程不涉及 dpr。这一点必须对:鼠标事件给的是 CSS 像素,位图放大是 dpr 的事,两者一混就会把点击位置算到一半的地方。

导出 PNG 的现象也就有了解释:toDataURL 导的是位图,位图宽高已经被乘过 dpr,所以在 DPR 为 2 的机器上导出的图正好是屏幕上看到区域的两倍,另带一层深色底。这不是 bug,但必须知道,否则会以为是导出函数算错了尺寸。

教训:画布类应用要把“逻辑坐标”与“物理像素”的转换收在唯一一个函数里,其他地方一律用逻辑坐标;一旦有第二处手动乘设备像素比,坐标体系就裂了。

五、构建与部署

本文没有在本机执行 HAP 构建,也没有把包装到鸿蒙设备上,因此本章不描述任何构建耗时、签名结果或安装排障,只把工程里现存的模块关系、清单声明与产物落点整理清楚,并给出一份发布前应该核对、而本文尚未完成的清单。下面三张截图拍自本工程的界面,图 1 是打开后默认看到的类图,图 2 切到了时序图,图 3 是右下角的关于弹层。

图 1:领域模型类图视图。工具栏分五组:第一组是工程名输入与新建/打开/保存/另存为/载入示例;第二组是元素类型下拉、名称输入与添加/显示/隐藏;第三组是关系类型下拉与连接/取消;第四组是导入 Java、自动布局、生成代码、导出 PNG、校验、删除;最右是三个徽章,读到元素 36、连线 15、问题 0。左侧模型浏览器展开到类成员一级,中间 12 个方框分居两个包,连线上带 referencedBy 与 uses 与 checks 与 owns 四个标签,两端分别画着实心三角与小菱形;底部详情停在属性页签,显示模型名与「说明(写入 Javadoc)」。

图 2:借阅时序图视图。四条生命线头部分别是 member : Member、svc : BorrowService、catalog : Catalog、store : IBookStore,五条消息按 #1 到 #5 自上而下编号,其中 #4 reduceStock(1) 是自消息,被画成向右探出再折回的三点折线——与第三章 layoutMessage 的坐标推导一致。生命线上能看到若干矩形激活条,但它是按参与消息的最高最低点画出来的,不是单独编辑的对象。底部详情切到成员页签,逐行列出 Book 的 isbn、title、price、stock 四个属性,右侧每行带一个红色叉号的删除按钮。

图 3:关于弹层覆盖在时序图之上。弹层分三段:开源声明、免责声明、完全开源。声明里写明 Electron 基于 MIT 协议、交互设计参考 StarUML 等开源 UML 建模项目的通用使用习惯、全部代码使用 JavaScript 独立编写、不包含其任何源代码、遵循 Apache-2.0。这份声明也是判断项目性质的一个依据:它是对同类工具的交互习惯做了参考、代码从零写起的壳应用,不是把上游软件搬进包里。

5.1 工程联动与打包声明

entry 模块的声明决定了应用在桌面上长什么样、能不能被系统当成普通文档应用拉起:

{
  "module": {
    "name": "electron",
    "type": "entry",
    "srcEntry": "./ets/Application/AbilityStage.ets",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "2in1",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "metadata": [
      {
        "name": "client_id",
        "value": ""
      }
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:app_icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "launchType": "specified",
        "removeMissionAfterTerminate": true,
        "exported": true,

几个字段值得逐一看清。deviceTypes 只写了 2in1 与 tablet,没有 phone,这与前面说的“只能面向桌面形态”是同一件事;launchType 用的是 specified(单实例),即再次启动不会新建一个实例,而是把已存在的实例拉到前台,对一个要维护一份当前工程的应用来说这是正确选择;removeMissionAfterTerminate 为 true 表示进程结束后不再保留任务视图记录;exported 为 true 并配了 entity.system.home 与 entity.system.browsable 两个能力,才能出现在桌面上并被当作可浏览应用打开。模块里还声明了第二个能力 BrowserAbility(exported 为 false),以及一个 link 方案的 uri 唤起入口。

依赖侧的声明很短:electron 模块的 oh-package.json5 里就一条 web_engine 的 file: 引用,两个模块平行放在同一个 ohos_hap 目录下。业务源码不属于任何一个模块的源码目录,而是作为 web_engine 的 resfile 资源存在,因此它进包的方式是资源拷贝,不是编译。这也解释了为什么 renderer.js 里能直接 require(‘./staruml-engine.js’) 并用 require(‘electron’) 拿到 ipcRenderer——它本质上是在一个开启了 nodeIntegration 的页面环境里跑,与普通网页不同,所以 index.html 的 CSP 才需要把脚本来源收紧到 self。

web_engine 那边是 HAR,声明了自己的设备类型与权限清单:

{
  "module": {
    "name": "web_engine",
    "type": "har",
    "deviceTypes": [
      "tablet",
      "2in1"
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },

权限清单是这个 HAR 带来的,不是本应用的业务需求。清单里包括网络、证书管理、打印、剪贴板、位置、麦克风、摄像头、蓝牙、录屏等十余项,以“能力池”的方式随 HAR 一起提供;本应用实际用到的只有文件对话框与目录读写。这一点对发布审核有实际影响:应用声明了自己用不到的权限,审核时会被问到。本文只如实记录清单现状,不修改它。

5.2 产物落点与文件读写行为

运行期会在三处产生数据,路径都由主进程固定下来,不弹窗询问:

产物位置触发时机
当前工程文件userData 目录下的 StarUMLProject.json首次启动自动播种;「保存」直接覆盖
外部工程文件用户在对话框里选定的 .json「另存为」或「打开」后成为新的活动文件
生成的 Java 源码用户在对话框里选定的目录,按包名建子目录点「生成到目录…」
导出的图片用户在对话框里选定的 .png 路径点「导出PNG」
反向导入的源码不产生任何文件,只读入模型点「导入Java」

前三行里有一处行为需要特别注意:currentFile 是主进程里的一个模块级变量,它会被三个通道改写——保存、另存为、打开。这意味着「打开」一个外部工程之后,再点「保存」会直接覆写那个外部文件,中间没有任何确认。对一个要维护多份模型文件的用户来说,这是很容易踩到的一步;建议先用自己的副本做测试。

保存本身不做版本检查也不做备份,写盘就是一次 stringify 加一次 writeFileSync:

// 保存到当前活动工程文件
ipcMain.handle('prj:save', function (event, text) {
  var target = currentFile || canonicalProject();
  try {
    fs.mkdirSync(path.dirname(target), { recursive: true });
    fs.writeFileSync(target, String(text == null ? '' : text), 'utf-8');
    currentFile = target;
    return { success: true, file: target };
  } catch (e) {
    return { success: false, error: '保存失败' };
  }
});

写盘前先建目录是必要的:userData 目录在首次运行前可能还不存在。写入是整体覆盖而不是追加,所以一份工程文件永远完整而不是半个;但写失败时也只返回一句「保存失败」,没有把 errno 或系统消息带出来,排查时只能去翻控制台。

还有一条与用户体验相关的事实:工程是否脏只记录在渲染层的 state.dirty 里,关闭窗口时不检查脏标记。也就是说,改了模型没保存就直接关窗,改动会直接丢掉。这一点在代码里写得很清楚——window-all-closed 里就一句 app.quit(),没有任何保存提示。

5.3 发布前核对清单

下面是发布前必须确认、而本次工作未涉及的项目,逐项标注状态:

  1. HAP 构建与签名:未执行。本文给出的所有构建配置都是静态阅读结果,没有验证能跑出一份带签名的安装包。
  2. 安装与启动:未执行。首帧、窗口尺寸、高分屏下的绘制效果都未在设备上确认。
  3. 包体量:未测量。原生库两个文件合计约 1.16 GB,又开了 collectAllLibs,包体预计很大,但必须实测后才能写进交付材料。
  4. 应用名与图标:未替换。字符串资源里 app_name 仍为 Electron,vendor 仍为 example,bundleName 仍为模板的 com.huawei.ohos_electron。
  5. 权限裁剪:未做。web_engine 的权限清单包含本应用用不到的十余项,包括位置、麦克风、摄像头、蓝牙与录屏。
  6. 文件对话框:未验证。全部四个对话框(另存为、打开工程、选 Java 源文件、选生成目录与导出图片)在鸿蒙桌面上能否正常弹出、能否记住上次目录,都只能在设备上看。
  7. 大模型下的绘制:未测量。内置样例只有 36 个元素,上千元素的模型下 renderCanvas 的复杂度能否接受,没有测过。

这份清单里前两项是硬门槛,后面几项是上架审核会被追问的内容。本文能给出的只有静态结论:配置是自洽的、模块依赖是单向的、资源路径是固定的;至于跑起来是什么样,本章不做任何断言。

六、常见问题与解决方案

Q1 第一次启动就自动带出一个图书馆管理系统工程,这是不是装错了?

这不是装错,而是首次播种。主进程的 prj:load 按三级回退取工程文本:先读用户目录下的 StarUMLProject.json;读不到就读内置的 samples/demo-project.json,并把它写回用户目录;两者都读不到才返回空文本。所以第一次打开应用看到的总是内置样例,文件行会标明来源为内置示例。

这个行为的本意是降低冷启动难度:与其给用户一张空白画布,不如给一份能直接点开看的完整样例。但副作用是容易让人误以为自己的机器上还存着一份旧工程。区分办法是看文件行:来源写内置示例就是刚播种的,写用户工程才是你之前存过的那份。

想要真正的空工程,点两次「新建」(第一次只是把按钮变成待确认态,第二次才执行)。新建出来的模型里只有一张类图与一个带 main 方法的 Main 类,不是空白——这一处也是刻意的,因为没有图的话工具栏的「添加」无处安放。

如果想把样例找回来,随时点「载入示例」,它会无视当前工程直接重读内置文件并覆写用户工程。注意它是覆写,当前未保存的改动会丢失,且这个按钮没有像「新建」那样的两步确认。

Q2 点一次「删除」没反应,得点两次才行?

这是刻意的两步确认,不是按钮坏了。第一次点击不执行删除,只把按钮变成危险的确认态并把状态栏文案改成「再次点击删除确认」,同时启动一个三秒定时器;三秒内再点一次才真正删除,超过三秒自动恢复原样。键盘上的 Delete 与 Backspace 走的是同一个函数,所以行为完全一致。

设计动机是防止误删:删除是级联的,删一个类会连带删掉它的成员、所有指向它的关系、它在各张图里的显示引用。一旦误触,没有任何撤销入口可以救回来(引擎里也没有实现 undo)。用两步点击换掉一个撤销栈,是这类小工具常见的权衡。

操作上只需要知道两点:一是两次点击之间不能超过三秒;二是在输入框里打字时 Delete 与 Backspace 不会触发删除,因为键盘处理里先判断了目标是不是 input 或 textarea。

最后一处需要提醒的是提示位置。确认态的提醒只出现在底部状态栏一行小字与按钮的红色描边,不在画面中央;如果眼神在模型树或画布上,很容易漏掉。这也是本文认为此处最值得改进的地方:要么把待确认态做成明显的浮层,要么直接做一个可撤销的删除。

Q3 为什么「显示」和「隐藏」点了没反应,只有类图能生效?

因为这两个按钮只对类图有意义,而时序图的生命线根本不在可见集里。toggleShow 一开始就做了三道前置判断:必须同时选中了一个元素和一张图;选中的图必须是类图;选中的元素必须是分类器(类、接口、枚举)。任何一道不过就只在状态栏报一句原因,不做其他动作。

根因在两种图的可见性模型不同。类图的可见性存在 visible 数组里,元素本体属于包,所以「显示/隐藏」本质上是改数组;时序图的生命线直接挂在图下,是图的子元素,没有「属于包但未显示」这回事,因此也没有隐藏的概念——想让它不出现,只能删掉。

实际操作:想隐藏某个类,先切到类图再选类再点隐藏;想处理时序图里的生命线,先选中它再点删除(同样要两步)。画布上点击时序图时只有生命线头部 50 像素的区域能命中,点细长的虚线上不会选中任何东西,原因也在代码里写着:时序图只允许选中生命线头部盒。

这也意味着时序图有一个功能缺口:删了一条生命线,挂在它上面的消息会被级联删掉(它们是引用它的边),但没有任何提醒告诉你删了几条消息。删之前最好先看一眼图上有多少消息经过它。

Q4 按成员面板的提示写「private int x = 0」,生成的代码为什么报错?

因为成员面板右侧那句提示与实际解析器不一致,这是一个真实的 bug,不是写法问题。提示语写的是「UML 写法 + name : Type 或 Java 写法 private int x = 0」,但 parseMember 只认四种 UML 可见性符号(加号、减号、井号、波浪号),不认 public、private、protected 这几个词。

后果是 private 被当成类型的一部分:实测输入 private int x = 0,解析出来是 name 为 x、type 为 private int、visibility 为默认的加号。生成代码时属性默认可见性又添一层 public,最终字段声明变成 public private int x = 0;,两个修饰符重复且顺序非法,javac 会直接报错。

正确写法只有一种:用 UML 写法写,即减号 x : int = 0(- 表示 private)、加号 name : String、井号 stock : int 之类;也可以只写 x : int = 0,此时可见性默认取加号。想要无修饰的包可见,用波浪号。

同类问题还有一个:操作一栏省略返回类型时会被正则错切。实测输入 run() 解出来 name 为 n、返回类型为 ru;输入 calculate(a : int) 解出来 name 为 e、返回类型为 calculat。两者都是因为签名正则先吃掉一段非空白字符当返回类型。所以在操作一栏必须写完整的 void run() 或 int calc(a : int),不能只写方法名加括号。

Q5 导入的枚举再生成代码,为什么多出一行 private NEW, PAID;?

因为 enum 的字面量段在导入时被同时当成了字段,而生成器不知道它是字面量。这是一个往返不无损的问题,而不是单一端的错。

根因在导入的成员扫描。对于 enum Status { NEW, PAID; },类型体一开始就是裸文本 NEW, PAID,它既没有左括号也不是以分号分隔的完整声明,但扫描循环在遇到第一个分号时会把缓存的内容交给分类函数,而分类函数恰好能把它当作文本拆成「类型 NEW, 加 名称 PAID」。于是这个枚举同时拥有两个字面量(正确)与一个名为 PAID、类型为 NEW, 的字段(错误)。

生成端无从分辨,它看到枚举有字面量就输出字面量行,看到有属性就输出字段行,两者叠加就成了非法 Java。实测输出是两行:先 NEW, PAID; 字面量行,紧跟着 private NEW, PAID; 字段行。

规避办法是在导入后手动清掉:切到成员页签,那条多出来的属性会以「属性 1」的形式出现,点右侧的叉删掉即可;删完再生成就是干净的枚举。根本修法是在导入扫描里给 enum 的字面量前缀段加一条豁免——遇到枚举类型时,先把第一个分号之前的那一段整体收作字面量,不交给成员分类。本文不改源码,所以只记录现象与规避方式。

Q6 工具栏显示「问题 0」,可校验面板里明明有一条?

因为徽章与面板的统计口径不同。refreshIssues 拿到完整的校验结果后,往面板里填的是全部条目,而往徽章里只写非 hint 的条数。所以当校验结果只有提示级问题时,面板里能看到条目,徽章却是 0。

为什么 hint 不算问题。引擎把提示级归为“可以更好但不算错”的一类,目前只有两种:一是类标了 abstract 却没有抽象操作(建议直接改成接口);二是类或接口没有任何成员(空壳)。这两条对能不能用没有任何影响,所以被排除在计数之外。

内置样例正好撞上这个情况:它报了 1 条问题,指 Placeholder 是空壳,于是徽章显示 0。这不是数据对不上,而是设计如此。验证方式很简单:把那个空壳类删掉,或给它加一个属性,再点一次校验,面板会从一条变成「未发现结构问题」,而徽章前后都是 0——因为这唯一的提示从一开始就不计入徽章。

真正需要盯的是 error 与 warn 两类。error 三条分别是无名元素、关系缺端点、继承成环,只要出现就应该先修掉,因为前两条会让元素或连线在图上异常,第三条会让代码生成的 extends 直接递归。warn 两条是同容器重名与关系自环,前者会生成两个同名 .java 互相覆盖,后者在 UML 里通常意味着模型画错了。

Q7 导出的 PNG 为什么比屏幕上看到的大一倍,还带一圈深色边?

因为导的是位图,不是视口。renderCanvas 把 canvas 的 width 与 height 设置成了 CSS 尺寸乘设备像素比,在 DPR 为 2 的机器上,一块 900×420 的显示区域对应的位图是 1800×840;exportPng 直接调 toDataURL,拿到的就是这张大图。深色边则是画布底色:每一帧都会先把整张位图填成 PAL.crust 那种接近黑的颜色,再画图,导出的图自然也带这层底。

那圈“边”还包含内容四周的留白。绘制时会先算出内容的包围盒,然后按比例缩小并居中,因此内容周围总会留出一圈背景色;导出时不会裁掉这圈留白,因为裁切会让不同图上同一元素的大小不一致。

实际使用上,这意味着导出的图可以直接当插图用,不必担心高分屏下模糊;但如果要精确控制像素尺寸(比如做固定宽度的文档插图),得自己再缩一次。需要一张 1:1 图时,可以把窗口拖小到画面需要缩放的阈值之外再导,此时 scale 为 1,导出的图正好是视口的 dpr 倍。

还有一个边界需要知道:导出前会先重绘一次当前图,所以即使画布刚被遮挡过也不会导出一张空白;但只要当前没有选中任何图,按钮就只会报一句「没有可导出的图」,不会弹出文件对话框。

七、总结

本项目把一个 UML 建模器拆成“模型引擎 + 渲染层 + 文件通道”三层,三层的边界都很硬:引擎不碰 DOM 与文件,渲染层不算数学模型,主进程不解析模型。下面按模块把实现与实测结论放在一起:

模块实现方式本轮实测结论
模型与元素平铺字典 + parent/owned 双向36 元素样例装载 0 错误;删除级联四项清理均到位
图与可见集类图走 visible、时序图走 owned显示/隐藏不重复不误删;图间共享元素可反查
几何推导边界锚点、时序坐标系、消息排位、网格自动布局锚点 201,150 与手算一致;消息间隔恒为 48;12 元素排成 4×3
结构校验八类检查,分三级排序构造的坏模型报 10 条(错 3 警 2 提 5);样例仅 1 条提示
Java 生成纯函数吐文件列表3 个类型生成 3 个文件,包声明与包目录正确
Java 导入去注释字符串 + 括号配平 + 只扫第一层成员3 个类型导对,构造器与内层语句未误报;枚举往返有损
序列化丢空 points、读时三类修复往返后二次序列化逐字节相同;重挂分支会产生重复 id
文件通道主进程 8 条通道,目录穿越防护主进程与渲染层 8 条一一对应

三条关键经验:

第一,把“可验证”当成架构目标而不是测试目标。引擎零依赖、不引用 DOM,这不是巧合而是设计选择;正因为它不碰环境,本文才能在纯 Node 里把 36 元素样例、12 元素布局、10 条校验、3 个生成文件、3 个导入类型全部跑一遍,而不是只能靠截图说话。反例是渲染层的 1460 行,同样重要但无法这样验证,只能靠静态比对。项目越早决定“哪些部分要被验证”,后面就越不需要靠人工点击去确认。

第二,model 与 view 分离不是理论教条,而是能直接减少一类 bug 的具体手段。因为类属于包、图只存引用,删除一个类只需要一处级联就能把所有图上的引用一并清掉;因为可见集与元素本体分开存,同一个类可以同时出现在多张类图上而不需要复制。反过来,凡是把“显示”和“存在”混在一起的设计,接下来必然要面对“删图会不会删元素”这个无解问题。

第三,凡是“双向”的功能,一定要回到输入端做一次闭环验证。本项目的生成与导入分别看都很像,各自的单元行为也都能解释得通,但把导入的输出再交给生成,枚举就坏了——这个缺陷不会在单向操作里暴露。同理,序列化的往返也只有在“写出去再读回来再写一遍”之后,才会发现容器重挂会产生重复 id。单向测试能证明它能跑,双向测试才能证明它是对的。

本轮的边界也写在这里:没有构建、没有安装、没有真机,没有改一行业务源码;上面的所有数字都能用同一份源码在 Node 里复现,但界面渲染与文件对话框只能等真正跑起来才能验证。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐