TypeScript中如何定义支持流程图连线校验的节点端口数据类型

在搭建可视化流程编辑工具时，节点端口的数据建模直接决定了连线逻辑是否健壮。如果端口仅仅用普通字符串或者数字来标记，那么当画布上出现几十种节点、上百条连线时，开发者根本无法在编码阶段感知到某个输出口接到了错误类型的输入口。TypeScript作为带有静态类型能力的超集，完全可以把端口本身变成一种带有方向和载荷语义的类型，从而在类型层面约束连线的合法性。

端口基础类型的结构化定义

最直观的做法是把每一个端口看成包含唯一标识、方向以及承载数据类型的对象。方向可以用字面量类型source与target区分，而载荷类型则通过泛型参数传入。这样我们在声明节点时，就能明确写出某个输出端口只能吐出number，而某个输入端口只接受string。下面的代码展示了最基础的端口类型别名。

使用泛型可以让端口定义复用性更强。比如Port<T>中的T可以是原始类型，也可以是复杂的业务对象。配合判别联合，我们还能把不同类型的端口归到一个总类型下，方便在连线函数中做穷尽检查。这种结构比单纯用枚举更不容易出错，因为泛型把数据契约直接绑在了端口身上。

type PortDirection = 'source' | 'target';

interface Port<T = unknown> {
  id: string;
  direction: PortDirection;
  payloadType: T;
}

type NumberSourcePort = Port<number> & { direction: 'source' };
type StringTargetPort = Port<string> & { direction: 'target' };

const outPort: NumberSourcePort = {
  id: 'nodeA_out',
  direction: 'source',
  payloadType: 0
};

const inPort: StringTargetPort = {
  id: 'nodeB_in',
  direction: 'target',
  payloadType: ''
};

利用类型守卫实现运行期连线校验

虽然TypeScript能在编译期拦掉大部分错误，但流程图数据往往来自后端接口或者用户拖拽产生，属于运行期动态输入。此时我们需要类型守卫函数来确认两个端口是否允许相连。核心思路是检查双方方向互补，且payloadType对应的类型标签一致。这里把类型标签单独抽成字符串字面量，可以避免直接依赖泛型在运行期被擦除的问题。

下面的示例给出了一个canConnect函数以及对应的守卫。我们在端口上附加了typeTag字段，用于存储运行期可读取的类型名。这样即使用户从配置文件中读出了陌生结构，我们也能在连线前抛出明确错误，而不是等到执行节点逻辑时才崩溃。守卫函数返回的类型谓词还能让后续代码自动获得正确的类型收窄。

interface RuntimePort {
  id: string;
  direction: 'source' | 'target';
  typeTag: 'number' | 'string' | 'boolean';
}

function isCompatibleSource(p: RuntimePort): p is RuntimePort & { direction: 'source' } {
  return p.direction === 'source';
}

function canConnect(a: RuntimePort, b: RuntimePort): boolean {
  if (a.direction === b.direction) return false;
  if (a.typeTag !== b.typeTag) return false;
  return true;
}

const p1: RuntimePort = { id: 'a', direction: 'source', typeTag: 'number' };
const p2: RuntimePort = { id: 'b', direction: 'target', typeTag: 'number' };
console.log(canConnect(p1, p2));

实际项目中，端口可能还带有数量限制，比如一个target端口只能被连接一次。我们可以在守卫之外再叠加一层业务校验，但类型层面的匹配依然是第一道防线。把typeTag与编译期泛型保持映射同步，能显著降低维护成本。

基于邻接关系的流程图整体校验方案

当画布上不止一对端口，而是成百上千的节点时，我们需要从图的角度校验所有连线。可以定义一个Edge类型来描述一条从源端口到目标端口的关系，然后用函数遍历边集合，对每一条调用前面的canConnect逻辑。若发现不兼容的边，就收集起来反馈给上层UI高亮显示。

下面的代码演示了如何把节点、端口和边组合在一起，并用validateGraph做全量检查。这里我们故意把端口类型建模成判别联合，让TypeScript在写校验循环时如果漏掉某种typeTag就会报错。相比在页面上用弹窗挨个试错，这种集中校验能在一瞬间定位所有非法连线，特别适合低代码平台中的保存前拦截。

type Edge = { from: RuntimePort; to: RuntimePort };

function validateGraph(edges: Edge[]): Edge[] {
  const invalid: Edge[] = [];
  for (const e of edges) {
    if (!canConnect(e.from, e.to)) {
      invalid.push(e);
    }
  }
  return invalid;
}

const badEdge: Edge = {
  from: { id: 'x', direction: 'source', typeTag: 'number' },
  to: { id: 'y', direction: 'target', typeTag: 'string' }
};

console.log(validateGraph([badEdge]).length);

除了基础方向和新标类型，还可以把端口扩展为支持多泛型参数，例如描述一个既输出数字又携带元信息的复合端口。只要在RuntimePort里把typeTag改成数组，并在canConnect中做子集判断，就能支持更复杂的流程语义。整体来看，用TypeScript定义端口数据类型并不是单纯写几个接口，而是把连线规则提前编织进了类型系统与运行期守卫之中。

TypeScript流程图端口校验修改时间：2026-08-18 07:12:28