A General-Purpose Monolithic Service Framework in Go
在 Go 服务端项目里，单体架构经常被简单理解为“先写在一起，以后再拆”。这个理解并不准确。真正有工程价值的单体，不是把所有代码堆在一个仓库里，而是在单进程、单代码库的前提下，仍然保持清晰的模块边界、稳定的依赖关系和可演进的部署方式。
本文给出一个通用 Go 单体架构服务框架的设计思路，目标有三个：
- 在项目早期降低系统复杂度，提升交付效率。
- 在代码规模增长后，仍然保持模块边界清晰。
- 为未来的独立部署甚至微服务拆分预留结构基础。
为什么单体服务框架很重要
1. 简化研发链路
对于大多数业务系统，真正稀缺的不是“服务数量”，而是交付效率。单体架构把开发、调试、联调、部署收敛到一个工程内，避免在项目早期就引入注册发现、服务治理、跨服务调用链路等额外复杂度。
如果框架层统一了配置、日志、错误处理、依赖注入、生命周期管理，团队在新增业务时只需要关注模块实现，而不需要重复搭建基础设施胶水代码。
2. 控制复杂度，而不是制造复杂度
单体不等于混乱。真正决定系统是否可维护的关键，在于模块边界是否明确。一个设计合理的单体框架，应当做到：
- 业务按服务维度组织，而不是按技术文件类型散落。
- 模块内部维护自己的
entity和业务规则。 - 模块之间通过 DTO 或接口交互，避免直接共享内部模型。
- 基础设施能力下沉到公共层，避免业务代码到处直连数据库和中间件。
做到这些之后，单体项目同样可以获得接近微服务的边界清晰度，只是运行时仍然保留单体的简单性。
3. 进程内调用带来更低成本的稳定性
单体架构最直接的收益，是把大量跨网络调用转化为进程内调用。这样可以减少序列化、网络延迟、超时重试、熔断降级等一系列分布式问题。
这并不是说单体天然更稳定，而是它把问题空间缩小了。只要在框架层统一处理日志、监控、panic recover、优雅退出和资源初始化，系统稳定性通常更容易保障。
4. 为未来拆分提供边界基础
很多团队最终会走向多应用部署，甚至局部微服务化。决定拆分成本的，不是今天是不是单体，而是今天有没有清晰边界。
如果服务层从一开始就避免跨模块共享内部对象，只通过明确的输入输出交互，那么未来把某个服务拆成独立进程时，改造成本会低很多。
框架分层设计
这个框架按职责从上到下分为四层：CMD、APP、Service、Infra。
1. CMD 启动层
CMD 层是程序入口，负责命令解析、配置加载、容器构建和应用启动。这里适合使用 cobra 组织命令结构，把启动参数和运行模式标准化。
它只做装配，不承载业务逻辑。
2. APP 应用层
APP 层负责把服务能力暴露为可运行的应用实例。一个 APP 可以是 HTTP Server、gRPC Server，也可以是 MQ Consumer。这里更关注协议适配、路由注册、中间件挂载、鉴权接入和生命周期控制。
技术栈上可以使用 gin 和 grpc。关键点不是框架选型，而是把“应用运行时”与“业务服务”分开。
3. Service 服务层
Service 层承载核心业务逻辑，是整个框架的中心。每个服务独立维护自己的 entity、领域规则和 use case；服务之间只通过 DTO 交互，不直接暴露内部结构。
这样做有两个价值：
- 降低模块耦合，避免形成隐式依赖。
- 为未来独立部署或微服务拆分保留边界。
另外，服务方法建议默认按“对外可调用”来设计，明确输入、输出、权限校验和错误语义，而不是仅服务于某一个上层调用点。
4. Infra 基础设施层
Infra 层负责提供数据库、缓存、消息队列、配置、日志、链路追踪等通用能力。它向上提供稳定抽象，但不承载业务决策。
业务代码依赖基础设施接口或封装后的组件，而不是把 SQL、Redis、MQ 细节散落在各个服务里。
关键实现方式
1. 使用 dig 做依赖注入
组件依赖统一交给 dig 管理。每个模块只声明自己提供什么、依赖什么，容器负责最终装配。这样可以减少大量手写初始化代码，并让依赖关系显式化。
在工程规模上来之后，这一点非常重要。没有依赖注入的单体，最终往往会变成初始化代码越来越重、模块耦合越来越深的“大 main.go”。
2. 单二进制，多 APP 启动
整个服务最终可以打包成单个二进制，通过命令参数启动不同 APP，例如：http app、grpc app、mq consumer app。这意味着代码仍然统一维护，但运行时入口可以按职责拆分。
3. 支持按 APP 独立部署
虽然整体是单体架构，但不同 APP 可以独立发布。例如 HTTP APP 和 MQ Consumer APP 分开部署，避免 Web 接口更新影响消息消费链路。
这种模式本质上是“单仓库 + 单框架 + 多运行单元”。它非常适合业务增长期：既保留单体的研发效率，又在部署层获得一定隔离能力。
总结
一个通用 Go 单体架构服务框架，不是为了和微服务对立，而是为了在系统早期用更低复杂度支撑业务增长，并通过清晰边界为未来演进打基础。
如果分层合理、依赖清晰、部署方式灵活，那么单体不是权宜之计，而是一种非常稳健的工程选择。