企业官网建设流程全解析

Encore Flow 架构图：基于 Encore 自动生成实时微服务架构可视化

【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore

Encore Flow 是 Encore 内置的可视化工具，能够基于应用元数据自动生成整个系统"鸟瞰图"，让开发者随时掌握微服务之间的依赖关系与协作方式。无论是本地开发还是云端环境，Flow 都会随着代码变更与部署实时刷新，帮助你定位瓶颈、加速新人上手、发现热路径。读完本文，你将掌握 Flow 的图表语义（服务框、依赖箭头、Pub/Sub 虚线）、依赖高亮交互，以及它与源码级元数据（meta.proto）之间的对应关系。

什么是 Encore Flow

Flow 是一个可视化工具，为你提供始终保持最新的整个系统视图，帮助你思考微服务架构、识别哪些服务互相依赖以及它们如何协同工作。它不是一个静态的架构图生成器，而是随代码演进、随部署刷新的"活"架构图。

Flow 解决的核心痛点是：架构图一旦由人工维护，就必然滞后于代码。Encore 的编译器在解析应用时会把服务、API、数据库、Pub/Sub 主题等声明收集成一份结构化元数据（即meta.Data），Flow 直接从这份元数据渲染图形，因此图上展示的内容与真实代码始终一致。

从当前仓库的 meta.proto 可以看到，Encore 为每个应用版本生成的元数据（Data）包含：

• svcs（Service）—— 所有服务及其 RPC、数据库、对象存储用量；
• pubsub_topics（PubSubTopic）—— 应用声明的所有 Pub/Sub 主题，含发布者（Publisher）与订阅者（Subscription）信息；
• sql_databases（SQLDatabase）—— 服务连接的数据库；
• auth_handler、cron_jobs、middleware、cache_clusters、metrics、buckets等。

Flow 渲染图就是这份元数据的图形化表达：每个服务是一个框，每个 Pub/Sub 主题也是一个框，箭头表示依赖。在下面的示例中，login服务依赖user和authentication两个服务：

Encore Flow 架构总览：login 依赖 user 与 authentication，payment 发布 payment-made，email 订阅该主题

鸟瞰视角（Birds-eye view）

能够对系统进行"缩放后退"式的全景观察，在整个开发周期的几乎所有环节都极具价值。Flow 可以帮助你：

• 在瓶颈发展成大问题之前定位它们。依赖集中在某一个服务上、某个服务被大量调用等模式，在鸟瞰图中一目了然；
• 让新团队成员更快上手。一张准确、实时的架构图，比阅读上百个文件更直观地传达"这个系统长什么样"；
• 定位系统中的热路径（hot paths）。流量密集、可能更需要额外关注的服务会从图中浮现出来。

服务和 Pub/Sub 主题用方框表示，箭头表示依赖关系。在上面的示例中，login服务对user和authentication服务存在依赖；虚线箭头表示对某个主题的发布（publication）或订阅（subscription）。这里payment服务向payment-made主题发布消息，email服务订阅了该主题。

图表语义与元数据的对应

Flow 中的每一类图形元素，都能在当前仓库的元数据定义中找到对应结构：

从源码结构看，Encore 的解析器会为每个Package记录其调用的全部 RPC（rpc_calls），这是 Flow 绘制服务间依赖箭头的关键数据：只要代码中出现跨服务的apiCall，解析器就会记录这次调用，Flow 随即在图中画出对应箭头。类似地，PubSubTopic中的Publisher（发布者所在服务）和Subscription（订阅者所在服务）直接决定了哪些服务与主题之间应该绘制虚线箭头。正因如此，Flow 图中的依赖关系不是由人工维护的，而是源码中真实调用关系的投影。

高亮依赖关系

将鼠标悬停在某个服务或 Pub/Sub 主题上，即可瞬间揭示其依赖的性质与规模。这在分析"某个服务到底依赖了什么"时非常高效：

Encore Flow 依赖高亮：login 查询数据库、调用 user 的两个端点与 authentication 的一个端点

在上面的示例中，login服务及其依赖被高亮显示。我们可以看出login：

• 对数据库发起查询；
• 调用user服务的两个端点（发起两个请求）；
• 调用authentication服务的一个端点。

悬停交互把鸟瞰图从"整体结构图"升级为"依赖分析器"——你不需要逐个翻阅代码，就能快速回答"这个服务会影响到谁、又受谁影响"这样的问题。

依赖高亮的源码依据

这种粒度的高亮信息，来自元数据对 RPC 的完整刻画。在 meta.proto 中，每个RPC都携带了：

• service_name—— 该端点所属的服务；
• name—— 端点名称；
• access_type（PRIVATE / PUBLIC / AUTH）—— 端点的访问方式；
• path与http_methods—— 端点的路由与 HTTP 方法；
• request_schema/response_schema—— 请求与响应的类型结构。

结合Package.rpc_calls（某个包调用了哪些 RPC），Flow 就能把"login 调用了 user 的哪个端点"这类关系精确还原到图上，并在悬停时展示出来。此外，pubsub.md 中定义的new Topic声明会被解析进PubSubTopic结构，其Subscription记录了订阅所在的服务，因此悬停一个主题时，Flow 同样能展示完整的发布者/订阅者清单。

实时更新

Flow 可以在两个位置访问：

• 本地开发：在 本地开发仪表盘（Local Development Dashboard） 中访问；
• 云端环境：在 Encore Cloud 仪表盘中访问（针对部署到云端的应用）。

本地开发：随代码变更实时刷新

本地开发时，Flow 会在你修改代码的同时自动实时更新，以反映最新的架构。这让你时刻留意重要的依赖关系，并且在引入新依赖时立刻感知到——新增一个apiCall、新增一个 Pub/Sub 订阅，图表都会立即变化。

下面视频演示了在user服务中先引入、再移除payment-made主题上一个新订阅时，Flow 图表的自动更新过程（视频资源位于仓库 docs 资产目录：assets/docs/flow-auto-update.mp4）。

本地 Flow 的实时性，根植于 Encore 本地运行机制的"实时重载"能力。在 cli/daemon/dash/dash.go 中可以看到，Dashboard 服务器实现了run.EventListener接口：当本地进程发生编译、重载、停止等事件时，会通过process/reload、process/compile-start、process/stop等 JSON-RPC 通知推送最新状态给前端；而应用元数据（meta.Data）由 resolveAppMeta 优先从正在运行的实例获取、否则回退到最近一次缓存的解析结果。换言之，每次代码变更触发重新解析后，新的元数据就绪，Flow 便能基于它重绘整个架构图。

启动本地开发环境并打开仪表盘的方式如下（来自 dev-dash.md）：

$ encore run API Base URL: http://localhost:4000 Dev Dashboard URL: http://localhost:9400/hello-world-cgu2

运行encore run后，仪表盘通常会自动在浏览器中打开，也可以跟随终端输出的 Dev Dashboard URL 手动访问。仪表盘中的 Service Catalog、分布式追踪 等特性与 Flow 一样，都会随代码变更实时更新。

云端环境：每次部署自动刷新

对于云端环境，Flow 会在每次部署后自动更新。由于 Encore Cloud 会在部署时重新生成并保存应用元数据，Flow 图中的服务、端点、Pub/Sub 拓扑会与最新部署的版本保持一致，无需任何手工同步操作。

一个可复现的示例：事件驱动架构在 Flow 中的呈现

为了直观理解 Flow 的图表语义，可以参照仓库自带的 TypeScript 示例应用（e2e-tests/testdata/tsapp）。该应用包含service1与service2两个服务，每个服务目录下都有：

• encore.service.ts—— 通过new Service(...)声明服务；
• api.ts—— 定义该服务的 API 端点；
• api.test.ts—— 端点测试。

运行encore run后，Flow 会把这两个服务渲染为两个方框；只要service1的代码中调用了service2的端点，图中就会出现一条从service1指向service2的实线箭头。如果再声明一个new Topic并让某服务发布、另一服务订阅（参考 pubsub.md 的signups.publish与订阅示例），主题就会以独立方框出现在图中，并以虚线连接发布者与订阅者。

这正对应 meta.proto 中Package.rpc_calls与 meta.proto 中PubSubTopic.publishers/subscriptions的语义：图上画什么，取决于代码里声明与调用了什么。

最佳实践与注意事项

• 把 Flow 当作日常开发工具，而非事后归档：本地开发时实时留意 Flow 图，新增依赖、引入新的主题订阅时，确认它们符合你的架构预期；
• 在团队 onboarding 中直接使用 Flow：用鸟瞰图替代冗长的架构文档宣讲，配合悬停高亮讲解依赖关系，能让新人更快建立系统心智模型；
• 关注热路径与瓶颈：高亮某个服务时，留意其依赖数量与规模，集中承载大量依赖的服务往往是性能优化或拆分（可参考 break-up-monolith.md 中的思路）的首选对象；
• 理解"图上内容=元数据"这一事实：Flow 只呈现 Encore 解析器从源码中收集到的信息，因此正确的文档注释与清晰的命名，会让 Flow 图对团队更有价值；
• 云端 Flow 以部署为单位更新：需要查看最新架构时，请确保已触发一次新的部署，而非依赖本地未提交的代码。

小结

Encore Flow 用一张实时、交互的架构图，把"系统长什么样、谁依赖谁"这一贯穿整个开发生命周期的问题变得一目了然。它以 Encore 编译器生成的元数据（meta.proto）为唯一事实来源，因此永远不会与代码脱节：本地开发时随每一次代码变更即时重绘，云端部署时随每一次部署自动刷新。结合悬停高亮的依赖分析，Flow 在瓶颈定位、新人上手、热路径识别等场景中都能发挥直接价值，是 Encore 可观测性体系中不可缺失的一环。

如需进一步了解 Flow 所处的完整可观测性生态，可以继续阅读 dev-dash.md（本地开发仪表盘）、tracing.md（分布式追踪）与 service-catalog.md（服务目录与自动 API 文档）。

【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore