encore-architecture

Encore 应用架构

在选择目录和声明之前，先设计应用的逻辑架构。对 Encore.ts 和 Encore.go 应用相同的架构思路；语言特定的实现请使用 encore-service 或 encore-go-service。

了解应用

检查现有代码，并在可用时了解 Encore 应用模型。识别：

• 用户和系统操作
• API、定时任务和 Pub/Sub 处理程序
• 数据模型及其变更代码
• 基础设施资源及使用这些资源的服务
• 现有的同步调用和事件流
• 故障、扩缩容、部署和安全要求

除非所请求的更改要求重新定义现有应用概念，否则应予以保留。

区分服务与进程

将 Encore 服务视为代码和 API 边界，而不是固定的部署单元。Encore 平台可以在一个进程中运行所有服务，也可以将每个服务放在单独的进程中；可按环境配置，无需更改代码。

使用服务边界来表达应用职责。使用进程分配来调整隔离和扩缩容，而无需重新设计这些职责。

尽可能将后端保留在一个 Encore 应用中，使应用模型涵盖其服务、资源、IAM、追踪和 Flow 图。

选择服务边界

新应用先从一个服务开始，除非已有明确且稳定的边界。在其中使用模块、目录或 Go 子包来组织代码。

如果某项业务能力职责明确，且拥有自己的操作和数据，可以考虑将其拆分为独立服务。故障隔离、独立扩缩容或部署、更小的安全接口，或与现有外部系统的接缝，都可以成为拆分的理由。

权衡拆分的成本：网络故障、跨服务协调、分布式一致性，以及双方都必须维护的接口。如果大多数更改都会同时影响双方，或者双方都无法独立完成有用的工作，就应将行为放在一起。

避免创建代表技术层的服务，例如处理程序、业务逻辑或数据库访问。应暴露 ReserveInventory 这样的能力操作，而不是对其他服务表的通用访问。

如果发现跨越同一边界的连续调用反复出现，或存在很长的转发服务链，这可能说明拟议的服务划分过细。

分配数据职责

为每个数据模型、其业务规则和架构变更指定一个负责服务。当其他服务需要所属服务执行这些规则时，优先使用调用或事件。

Encore 支持通过 TypeScript 中的 SQLDatabase.named 和 Go 中的 sqldb.Named 共享数据库访问。对于报表、渐进式迁移，或其他服务接口带来的复杂性大于其所减少的复杂性的情况，可以有意识地使用此方式。共享数据库前，应明确迁移责任和写入权限。

不要将每个服务必须使用一个数据库作为 Encore 的要求。应评估共享架构访问所产生的耦合，并与新增服务接口所产生的耦合进行比较。

选择通信方式

如果调用方需要先获得结果才能继续、操作必须报告成功或失败，或某个服务拥有所请求的能力，请使用类型化服务 API。

如果调用方无需等待、多个消费者需要独立响应，或消费者重试不应重复发起请求，请使用 Pub/Sub。应考虑最终一致性；如果重复投递会影响正确性，应确保处理程序具有幂等性。

保持即时请求/响应工作流同步。让事件消费者彼此独立，避免通过按顺序触发事件重新构建同步调用链。

如果数据库变更和事件发布必须保持一致，应针对两者之间可能发生的故障进行设计。Encore.go 提供事务性 Pub/Sub outbox；其他情况则需要应用特定的一致性机制。

定义接口和授权

将操作划分为公开、需认证或私有。除非外部客户端需要，否则应将内部能力操作设为私有。

在网关配置身份验证和跨域策略。有关特定能力或记录的授权决策，应由拥有该能力或记录的服务负责。

组织和演进

Encore 服务不能嵌套。将大量相关服务归入系统目录；系统用于组织源代码，不属于 Encore 资源或部署单元。

拆分服务时，先确定需要一同迁移的操作和数据，添加新服务，用 API 或事件替换直接调用，并在迁移期间明确数据所有权。在 Encore Flow 中检查生成的模型，并测试现在跨越服务边界的调用。

提出架构方案时，应列出拟议的服务、各自的职责、拥有的资源以及通信路径。说明每次服务拆分的具体原因，并指出重要的一致性或故障权衡。优先选择满足既定需求的最简架构。

完整指南和特定语言的示例，请参阅 应用结构。