Golang 框架开发中的代码重构技巧与最佳范例

先说几个核心判断：代码重构这事儿，在 Go 框架开发里，真不是为了“看着更高级”或者“代码更花哨”。它就是解决几个真实到不能再真实的痛点——handler 里塞满了业务逻辑、service 层和 repository 层职责模糊不清、错误处理散落一地、测试时为了隔离依赖得折腾半天。重构有没有效果，核心就看三件事：cmd/ 是不是更薄了、internal/domain/ 是不是更稳了、api/ 是不是更纯粹了。

按业务域组织包结构，而非技术分层

把所有的 handler 都塞进 handlers/、所有 model 都丢进 models/，这是 Go 项目早期最常见的结构陷阱，几乎每个人都踩过。它带来的问题很直接：跨模块引用变得随意、职责边界越改越模糊，最后迁移成本高到想放弃重来。

一个更合理的做法是让每个业务模块（比如 user、order）自包含。具体来说，每个模块内部要包含接口定义（interface.go）、HTTP handler（只依赖本模块的接口）、核心 service（不直接 import db 或 http 包）、repository 接口（repository.go），以及配套的单元测试。

这里有一个必须遵守的规则：禁止跨模块直接引用实现。举个例子，user/internal/service.go 绝对不能 import order/internal/repository。如果两个模块需要协作，那就在 user/interface.go 里定义回调函数或者事件接口作为通信介质，而不是直接硬依赖。

至于公共基础能力，比如日志、配置、HTTP 工具，统一收口到 internal/pkg/ 下，并且显式导入。千万别用 _ 空导入或者全局变量初始化来搞，那是给自己埋坑。

用小接口解耦依赖，拒绝“大而全”的 service 接口

定义一个 UserService 接口，里面塞进 Create、Update、Delete、SendEmail、ExportCSV——这种接口看着功能挺全，但实际用起来才发现，难实现、难 mock、难测试，而且严重违背 Go 推崇的“小接口哲学”。

更好的做法是按调用方的视角来拆分。举个例子，HTTP handler 通常只需要 UserCreator 和 UserFinder；后台任务可能只需要 UserExporter。接口名应该体现用途而不是实体，比如写成 type UserNotifier interface { Notify(user *User, msg string) error }，而不是套一个 UserService 的模板。

实现的时候，可以把多个小接口组合起来：type userSvc struct{ creator UserCreator; finder UserFinder; notifier UserNotifier }。这样既灵活，又避免了继承一个巨接口带来的所有问题。

提取校验与转换逻辑为独立函数，避免 handler 胀大

在 Gin handler 里写 c.ShouldBindJSON(&req) + 一堆 if req.X == "" + strings.TrimSpace + time.Parse，这是一种典型的坏味道。它让 handler 一口气承担了协议解析、数据校验、格式转换、业务路由四重职责，想不乱都难。

一个更清晰的思路是：为每个 API 请求体定义专属的 DTO，放在 api/v1/ 目录下，并配套一个 Validate() 方法（返回 error，不 panic）。校验失败的时候统一用 c.Error(errors.New("invalid request")) 或者封装成 ErrorResponse，千万别在 handler 内部直接写 return c.JSON(400, ...)。

至于时间、金额、ID 这类格式转换逻辑，抽成私有函数，比如 parseOrderTime(s string) (time.Time, error)。这样做不仅能复用，还方便单独写测试。

重构前必须补全测试，否则就是在赌运气

没有测试覆盖的重构，本质上就是在生产环境改 SQL 语句却不跑 explain，风险极高。特别是对于 Gin handler 和 service 层，测试的缺失意味着你根本无法确认“外部行为不变”这个前提是否成立。

具体的测试策略可以参考：handler 测试用 gin.CreateTestContext + httptest.NewRequest，验证状态码、响应体、错误类型，但不要验证具体的 JSON 字段值——那是 DTO 层的职责。service 测试用接口 mock（比如 gomock 或者手写的 fake），重点覆盖分支路径，比如用户不存在、库存不足、支付超时这些典型场景。

重构开始前，先跑一遍 go test -v -race ./internal/domain/user/...，确认原有测试全部通过。重构完成后，再全量跑一次，并且新增覆盖率不低于 85%。

最容易忽略的一点是错误类型的稳定性。像 errors.Is(err, ErrUserNotFound) 这种判断，如果在重构过程中被改成了 fmt.Errorf("user %d not found", id)，那上游所有依赖错误分类的逻辑就全废了。接口契约一旦被破坏，整个错误处理体系都会跟着崩。这一点，必须警惕。