使用 Encore 将单体（Monolith）拆分为微服务：完整实战指南-开发者社区

使用 Encore 将单体（Monolith）拆分为微服务：完整实战指南

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

本指南基于 Encore Go 应用模型，讲解如何在不重写代码的前提下，把一个单体后端中的某个功能拆分成独立服务（service）。你将学会：如何通过"新建 Go 包 + 移动 API 端点"完成服务拆分、拆分后 Service Catalog 与 Flow 架构图如何自动更新、以及拆分时数据库共享策略该如何取舍。读完即可在自己的 Encore 应用中安全地逐步演进架构。

为什么要拆分单体

随着业务增长，把单体后端中的特定功能拆分为独立服务是很常见的诉求。驱动拆分的典型原因包括：

独立扩缩容：某个功能（如通知、报表）的流量峰值与其他模块差异巨大，希望单独部署、单独扩容；
代码库结构优化：把不同业务域切成更小的代码单元，让团队边界与模块边界对齐；
故障隔离：让部分功能在依赖异常时仍能独立存活（可配合独立数据库实现更优雅的部分降级）。

Encore 的核心设计目标之一，就是让系统架构可以随业务自然演进：应用模型（Application Model）由代码声明式地推导而来，部署方式可以随环境变化而改变，却不需要改动业务代码。这意味着拆分服务主要是一个"移动代码"的动作，剩下的编排工作由 Encore 编译器自动完成。

如何从单体中拆出一个服务

以文档中的示例为例，假设我们有一个单体应用hello，包含两个公共 API 端点H1和H2：

package hello import ( "context" ) //encore:api public path=/hello/:name func H1(ctx context.Context, name string) (*Response, error) { msg := "Hello, " + name + "!" return &Response{Message: msg}, nil } //encore:api public path=/yo/:name func H2(ctx context.Context, name string) (*Response, error) { msg := "Yo, " + name + "!" return &Response{Message: msg}, nil } type Response struct { Message string }

现在要把H2拆到独立的yo服务中。在 Encore 中，拆分的全部操作就是：新建一个 Go 包（package），并把H2端点移进去。

新建yo/yo.go：

package yo import ( "context" ) //encore:api public path=/yo/:name func H2(ctx context.Context, name string) (*Response, error) { msg := "Yo, " + name + "!" return &Response{Message: msg}, nil } type Response struct { Message string }

磁盘上的目录结构变为：

/my-app ├── encore.app // ... and other top-level project files │ ├── hello // hello service (a Go package) │ └── hello.go // hello service code │ └── yo // yo service (a Go package) └── yo.go // yo service code

为什么"新建包"就等价于"新建服务"

这背后是 Encore 对服务（service）的定义方式：在 Encore Go 中，服务就是一个包含 API 定义的普通 Go 包，包名即服务名。这一点在定义服务文档中有明确说明：只要在一个普通 Go 包内通过//encore:api注解定义了至少一个 API，Encore 就会把这个包识别为一个服务。

也就是说，hello与yo从"一个包里的两个函数"变成"两个各自包含 API 的包"的那一刻，Encore 的应用模型就已经把它们视为两个独立服务了——不需要任何注册表、配置文件或额外声明。从源码结构看，v2/app/service.go 等解析层逻辑正是围绕"包 = 服务"这一模型来组织服务发现与资源归属的。

端点路由注意点

拆分后H2的路径/yo/:name保持不变，这得益于 Encore 使用声明式的路径参数（:name）语法，路由与具体的包位置解耦。因此在拆分过程中：

对外 API 路径无需修改，客户端调用不感知；
服务间调用则从"同包函数调用"变为"跨服务 API 调用"，需要把原来的直接调用改为通过 Encore 生成的客户端进行调用（可参考定义类型安全 API 中关于 public/private 访问控制的说明，跨服务调用通常应使用//encore:api private）。

架构可视化自动更新：Service Catalog 与 Flow

拆分完成后，Encore 会自动感知架构变化，无需手动维护任何图表或文档：

Service Catalog（服务目录）：Encore 基于应用模型自动生成服务目录与全部 API 文档，且永远与代码保持同步。运行你的应用（本地开发或云端部署）后，在本地开发控制台即可看到hello与yo两个服务分别列出，各自的端点文档也已就绪。详见 Service Catalog。
Flow 架构图：Flow 是实时更新的交互式架构可视化工具，服务以方框表示、箭头表示依赖关系。本地开发时它会随代码变更实时刷新，云端环境则随每次部署自动更新。拆分后你可以在 Flow 中立刻看到hello与yo两个独立服务节点。详见 Flow 架构图。

借助这两个工具，拆分服务的风险可以被即时可视化地确认：依赖关系是否正确、是否引入了意外的循环依赖、每个服务的资源（数据库、Pub/Sub 主题等）归属是否如预期。

拆分时的数据库策略：共享还是独立

服务拆分后，紧接着要面对的核心问题是数据库如何处理。Encore 对两者都支持，选择取决于你的具体场景，详见在服务间共享数据库。

默认行为：每服务独立数据库

默认情况下，Encore 中每个服务拥有自己的数据库，其收益包括：

数据库的归属与连接方式对其他服务完全抽象，服务间不耦合数据层；
数据库变更范围更小、更安全（schema 演进只在单一服务内生效）；
服务独立性更强，整体可靠性更高——即使某个数据库暂时过载或离线，其他服务仍能更优雅地处理部分故障。

何时选择共享数据库

有些情况下共享数据库反而更简单可靠，例如报表类服务需要直接读取业务库的数据。Encore 的共享方式非常轻量：每个数据库归属于定义它的服务（服务名即数据库名），其他服务通过sqldb.Named("dbname")建立数据库引用即可。

以文档中的todo/report示例为例，report服务直接访问todo服务的数据库：

todo/migrations/1_create_table.up.sql

CREATE TABLE todo_item ( id BIGSERIAL PRIMARY KEY, title TEXT NOT NULL, done BOOLEAN NOT NULL DEFAULT FALSE );

report/report.go

package report import ( "context" "encore.dev/storage/sqldb" ) // todoDB connects to the "todo" service's database. var todoDB = sqldb.Named("todo") type ReportResponse struct { Total int } // CountCompletedTodos generates a report with the number of completed todo items. //encore:api method=GET path=/report/todo func CountCompletedTodos(ctx context.Context) (*ReportResponse, error) { var report ReportResponse err := todoDB.QueryRow(ctx,` SELECT COUNT(*) FROM todo_item WHERE completed = TRUE `).Scan(&report.Total) return &report, err }

一旦这样声明，Encore 就理解report服务依赖todo服务的数据库，并自动编排好所需连接——本地开发与云端运行行为完全一致。

拆分实践中的数据库决策建议

拆分初期：如果拆分出的服务只是消费同一份业务数据做只读计算（如报表、聚合、导出），共享数据库可以显著降低迁移成本；
需要独立演化时：如果被拆出的服务将来会独立演进 schema 或独立部署扩缩容，尽早迁移为独立数据库收益更大；
边界清晰：无论选择哪种方式，都应让数据库归属关系与服务的业务边界一致，避免出现多个服务交叉读写同一张表、schema 归属混乱的情况。

从单体到微服务的渐进式路线图

结合本文的拆分方法与 Encore 的应用结构能力（详见应用结构），推荐的分步演进路线是：

保持单体：初期所有代码放在一个包里，快速验证业务；
按需拆分服务：当某个功能需要独立扩缩容、独立故障域或独立团队维护时，按本文步骤拆出新包；
数据库策略同步决策：拆分时一并决定是共享还是独立数据库；
用可视化验证：每次拆分后通过 Service Catalog 与 Flow 检查依赖关系是否符合预期；
部署形态灵活调整：Encore 允许在云环境（AWS/GCP）中按需配置多个服务是合并到同一进程还是分开部署，这一决策可以在不改代码的情况下于环境配置层面完成（见应用结构中关于进程分配的说明）。

这套路线图的核心价值在于：架构演进是代码目录结构的演进，而不是基础设施重构。你可以在需要时才拆分，也可以随时调整部署形态，而业务代码始终保持稳定。