跳到主要内容

09. API 与 Frontend：编辑器如何成为运行时控制台

9.1 前后端共享的是契约，不是实现​

@n8n/api-types 提供前后端共同使用的 request/response 类型；后端 controller 位于 packages/cli/src/controllers 和各业务模块，前端 API client 与 stores 位于 packages/frontend/editor-ui/src。

9.2 Workflow Document store​

编辑器把一个工作流拆成多个可观察状态：节点、连接、描述、设置、项目、凭证引用、发布状态、校验问题、viewport、pin data、execution 状态等。workflowDocument 下的 composable/store 负责从服务端数据派生出编辑器模型，避免一个巨型 store 同时承担所有状态变化。

重点路径：

9.3 保存与执行是两条链​

点击保存时，前端提交 workflow document；点击运行时，前端提交 manual execution 请求并订阅 execution 更新。两条链不能混为一谈：

编辑状态 → save workflow → version/publication state
执行状态 → manual run → execution id → push events → run data

执行中的节点高亮、错误气泡、部分执行和 pin data 都依赖第二条链。后端通过 push WebSocket/SSE 或轮询向前端传递状态，前端 store 再把事件映射为节点级视图。

9.4 Canvas 和 workflow graph 的双向映射​

前端画布需要 node position、handles、connection type、节点版本和显示问题；后端执行器需要相同节点的参数和连接。编辑器可以添加临时节点、草稿连接和 pin data，这些不一定直接等于已发布 workflow。因此保存、加载、导入、发布和执行都要有明确的版本边界。

9.5 REST controller 的分层​

典型请求是：

HTTP middleware / auth
  → controller 参数和 scope 校验
  → service 业务规则
  → repository / runner / event bus
  → response DTO

controller 不应直接调用 WorkflowExecute 细节；手动执行通常经过 manual-execution.service.ts、workflow-execution.service.ts 或 WorkflowRunner，这样 API、UI 和测试可以复用同一套执行编排。

9.6 设计取舍​

前端按领域拆 store降低单个状态容器的耦合；代价是同一个动作可能同时更新 workflow document、execution state、projects 和 notifications，需要明确事件顺序。

实时 push + REST兼顾初始快照和增量更新；代价是断线重连必须知道最后 event 或 execution 状态，不能只依赖内存中的 UI 状态。

共享 api-types减少 DTO 漂移；代价是接口变更会同时影响前后端和大量测试，版本演进要通过兼容字段或迁移完成。