Go项目中“大顶层结构体”本质是职责过载，应按能力域拆分为DB、Cache、HTTP等独立类型并组合，App仅负责组装启动，确保可测试、可替换、编译快。
Go 项目里出现“大顶层结构体”不是设计问题，而是结构体承载了太多职责——它本不该是入口、配置、服务、状态管理的聚合点。拆分不是为了拆而拆，而是让每个部分能独立测试、替换、演进。
为什么不能把所有字段塞进一个 App 结构体
常见现象：启动时 new 出一个巨无霸结构体，比如 App，里面塞了 *sql.DB、Config、Logger、HTTPServer、GRPCServer、CacheClient、甚至 ShutdownChan。编译慢、测试难、改一处要重跑全部单元测试，且无法 mock 某个依赖单独验证逻辑。
根本原因在于违背了 Go 的组合哲学：结构体应表达“是什么”，而不是“做什么”。App 不是一个实体，而是一组协作组件的装配器。
- 字段超过 10 个，基本可判定职责过载；
- 任意字段修改导致
go test ./...中大量测试失败，说明耦合已失控； -
App方法里频繁调用a.db.QueryRow、a.logger.Info、a.cache.Get—— 这不是业务逻辑，是胶水代码。
按职责边界拆成小结构体，再组合
不是删字段，而是把“能独立存在、有明确生命周期、可被复用”的能力提取为独立类型。例如：
立即学习“go语言免费学习笔记（深入）”；
type DB struct {
*sql.DB
}
func NewDB(cfg Config) (*DB, error) {
// 初始化逻辑
}
type Cache struct {
client *redis.Client
}
func NewCache(cfg Config) (*Cache, error) {
// 初始化逻辑
}
type App struct {
db *DB
cache *Cache
srv *http.Server
}
关键点：
- 每个小结构体自包含初始化逻辑（
NewXXX），不依赖外部传入一堆参数； -
App只保留组装和启动职责，不处理 SQL 查询或缓存 key 拼接； - 测试
DB时，直接mock sql.DB；测试Cache时，用redis.NewMockClient()；两者互不影响。
internal/ 下如何组织这些结构体
结构体不是按“技术层”（如 service/、repo/）放，而是按“能力域”组织。例如：
internal/ ├── db/ // DB 类型 + migration + driver 封装 ├── cache/ // Cache 类型 + key 策略 + fallback 逻辑 ├── http/ // HTTP server 封装 + middleware 注册 + health check ├── auth/ // JWT 解析、role 校验、token 刷新等 └── app/ // 最终组合：new App(db, cache, http, auth)
这样做的好处：
-
app/包只 import 自己真正需要的依赖，不会因cache/修改而触发db/重新编译； -
auth/可被http/和未来grpc/共用，无需复制粘贴校验逻辑； -
go list -f '{{.Deps}}' ./internal/app能清晰看到它依赖哪些子系统，便于做依赖分析。
编译加速：避免 internal/app 成为高频变更热点
如果每次改个路由都要重编 app/，说明它承担了不该有的职责。真正该常变的是 handler 或 service 层，而 app/ 应该稳定。
- 把路由注册逻辑下沉到
internal/http/router.go，app.Run()只调http.Serve()； - 业务 handler 放在
internal/user/handler.go，由http.Router注册，app完全不知晓； - 使用函数选项模式注入依赖：
http.NewServer(http.WithDB(db), http.WithCache(cache))，而非把所有依赖塞进结构体字段。
最易被忽略的一点：结构体字段顺序影响 GC 压力。把指针字段（*DB、*Cache）集中放在结构体前部，能让 runtime 更快扫描存活对象——这点在高并发长生命周期服务中会体现出来。
