8.0
热点
AI SCORE
编程提效2026-08-30 01:27
架构图箭头质量检测：15条可编程检查规则
dev.to · AI#架构图#工具#工程实践
Editor brief · 编辑速览
作者编写了程序化检查器，对52张已发布架构图进行评分，79%未通过。规则涵盖正交布线、无交叉、无穿 shape 违规等，可直接用于工程实践。
我编写了一个程序化的检查器，用 15 条质量规则对架构图箭头进行评分，然后对我站点上发布的 52 张图逐一运行检查。
不是"边缘情况"。就是失败。线条交叉、斜线段、线条穿入形状、出口点挤在一起。这个检查器是机械化的，而且应用在我自己已发布的产物上，所以这不是一项研究，而是一次自我审计：在我已交付的图中，约 79% 存在路由问题——而这些问题人眼会自动略过。
以下 15 条规则即检查器强制执行的标准。自审计之后发布的所有图均通过全部规则。
专业架构图要求边必须是纯正交的、零交叉、零线条穿入形状、出口点均匀分布、与形状保持 20px 净空、路径点严格对齐网格。这些不是风格偏好——而是可程序化检查的几何约束。大多数自动路由的图至少违反这 15 条规则中的 3 条。
这三条规则零容忍。违反其中任何一条，无论其他方面做得多好，图表看起来都是业余的。
每条边的每个线段必须完全水平或完全垂直。禁止斜线。禁止曲线。禁止"差不多就行"。
测试方法：取一条边路径上任意两个相邻的点。如果它们的 X 坐标相同（垂直段）或 Y 坐标相同（水平段），则线段合法。如果两者都不同，该线段就是斜线。
重要性：斜线看起来是无意为之。它暗示工具自动路由了这条边，没有人复核。即使整体干净的图中出现一段斜线，也会破坏视觉一致性。
修复方法：在拐点插入一个路径点，将斜线拆分为两条正交线段。选择 L 形（先水平或先垂直），使与其他边的交叉更少。
任意两条边在路径的任意位置上都不允许相交。
测试方法：将每条边分解为水平段和垂直段。对于每对边，检查所有 H-V 段组合。当水平段的 Y 值落在垂直段的 Y 端点之间 且 垂直段的 X 值落在水平段的 X 端点之间时，即发生交叉。
重要性：交叉的边迫使读者追溯每条线的走向。交叉超过两个，图表就变成了谜题而非沟通工具。
修复方法：通过添加绕开交叉点的路径点来重新路由较短的边。使用"高速公路"模式——将边路由到主图区域之外，再折返。
任何边段都不允许穿过非该边起点或终点的形状边界框。
测试方法：对于每条边段，检查其与每个非起点、非终点的形状是否相交。Y=100、从 x=50 到 x=300 的水平段，若形状位于 (120, 80, 160, 60)，则该段穿入了形状，因为段 Y 落在形状垂直边界内，且段 X 范围与形状水平边界重叠。
重要性：这是最严重的违规。穿过方框的箭头看起来是破损的。这是任何人都第一个注意到的问题。它无声宣告："没人审核过这张图。"
修复方法：添加两个路径点，将边绕过形状，并保持至少 20px 净空。可以从下方（shape.bottom + 20）、上方（shape.top - 20）或侧面绕行。
这些规则影响路由看起来是否专业。这是"可接受"与"精致"之间的差距。
每条边应使用连接目标所需的最少弯折数，不得违反规则 1-3。额外的弯折增加视觉噪音。
测试方法：对于有 N 个路径点的边，模拟移除每个中间路径点。如果移除后路径仍然合法，则该路径点多余。
当多条边从同一侧面离开形状时，它们必须均匀分布。不能全部挤在中心。
公式：对于从同一侧面出来的 N 条边，将每条边定位在 (i + 1) / (N + 1) 处。三条边从右侧出来，应分别位于 Y 位置的 0.25、0.50 和 0.75。不是 0.33、0.50、0.67。更不能全部在 0.50。
重要性：挤在一起的出口点会在形状附近产生重叠的边段。每条边开头的几个像素看起来像一条粗线，而非独立的路径。
当一个源连接多个目标时，路由模式必须围绕中心轴视觉上对称。
模式：所有边从源头的均匀分布点出发。所有边行进到一条共享的"高速公路"线（垂直或水平引导线）。每条边在高速公路上转向其目标。结果：零交叉、完全对称。
与规则 6 相同但方向相反。多个源汇聚到一个目标时，必须从均匀分布的点进入，并保持对称路由。
这些控制边周围的留白。边紧贴形状的紧凑图表看起来拥挤且难以阅读。
每条边段必须与任何非起点、非终点形状边界保持至少 20px 的距离。
测试方法：对于每条边段，找到距离其最近的形状边界（除该边起点和终点外）。如果距离小于 20px，则该边过近。
重要性：紧凑的净空让边的连接对象变得模糊——它究竟连接到这个形状，还是只是路过。20px 的留白消除了这种歧义。
两条不同的边不得共享同一路径段。同一线上的平行边看起来像一条粗边。
修复方法：将平行边垂直于共享段方向偏移 10px。两条在 y=100 的水平边变成一条在 y=95、一条在 y=105。
每条边的标签必须位于该边最长线段的中心，不与任何形状重叠，且有白色背景，使标签在穿过边线时仍然可读。
这些是点睛之笔。它们区分"好"与"可发布"。
主流动方向必须一致。如果图表从左到右流动，超过 70% 的边应遵循该方向。反馈循环和次要关系是例外。
连接相同形状列的平行边必须保持其垂直顺序。如果边 A 的起点在边 B 起点的上方，则边 A 的路径应在每一点都保持在边 B 上方。
每个弯折必须是精确的 90 度。这由规则 1 保证——如果所有线段都是正交的，所有弯折都是直角。
每条边的第一个路径点必须与源形状上计算的出口点完全匹配。不允许浮点漂移。形状在 x=100、宽度=200 上 exitX=0.5，意味着边从 x=200 开始。精确无误。
所有路径点必须在 10px 网格上。将每个坐标取整：x = Math.round(x / 10) * 10。
我编写了一个 TypeScript 引擎，解析 .drawio XML，提取所有顶点和边，将边路径分解为线段，并将每条规则作为几何检查来运行。
// Rule 2: Zero Crossings
// Check every pair of edges for H-V segment intersections
for (const segA of edgeA.segments) {
for (const segB of edgeB.segments) {
if (segA.direction === 'H' && segB.direction === 'V') {
if (segA.y > segB.minY && segA.y < segB.maxY &&
segB.x > segA.minX && segB.x < segA.maxX) {
violations.push('CROSSING');
}
}
}
}
评分标准：规则 1-3（关键）30 分，规则 4-7（路由）25 分，规则 8-10（间距）25 分，规则 11-15（精修）20 分。通过门槛：95 分。不是 70 分。不是 80 分。专业图表中出现一条交叉箭头就是一条过多。
检查器对发布时站点上的全部 52 张图进行了评分。结果分布如下：
得 100 分的图全部是简单的从左到右水平流向。路由简单。没有扇出。没有反馈循环。一旦图中有超过一个流动方向，自动路由器就开始产生违规。
每个不合格图的修复方法都相同：为每条边添加显式路径点，而不是依赖自动路由器。当指定了精确路径，路径就是精确的。
从规则 1-3 开始。如果你的图没有斜线段、没有交叉、没有边穿入形状，它们就已经比野外 90% 的架构图更好了。
然后加上规则 5（出口分布）和规则 8（净空）。这两条规则解释了大多数"总觉得哪里不对但说不清为什么"的感觉。
最后，执行规则 15（网格对齐）。当每个路径点都对齐到 10px 网格时，整个图会感觉有序——即使你无法解释原因。
其余规则是精修。它们对发布重要。它们对白板草图不重要。
以上 15 条规则通过了机械审查。手动应用它们，或将它们接入你的图表工具链，让坏的箭头从一开始就不会被画出来。
关于这些图背后的技术流水线，请参阅 Architecture Diagrams with Draw.io MCP and Claude。
本文最初发表于 az365.ai。我是 Alex Pechenizkiy，微软 Azure 和 Power Platform 解决方案架构师，撰写诚实、厂商中立的微软 AI 栈分析。更多内容见 az365.ai。