Gin 是个好框架，这不是客气话。路由快，API 简洁，中间件好用，写一个 CRUD 服务从零到能跑可能只要半小时。
但我最近盘了一下自己和周围团队的 Go 项目，发现一个规律：大多数项目的痛点不在框架，在架构。 Gin 把 HTTP 层的事情做得很好。路由、参数绑定、中间件链、JSON 序列化——这些大概覆盖了 Web 开发 80% 的需求。
剩下的 20% 呢？依赖注入、错误处理分层、测试隔离、数据访问抽象——Gin 不管这些。它也不该管，因为这些是架构层的事。
问题是，很多项目在 Gin “够用"的 80% 里待了太久，直到有一天发现改个数据源要动好几个文件、写个单测要启动真实数据库——这时候才意识到，该在 Gin 之上多搭一层了。
顺便说一句，Go 1.22 增强了标准库 net/http.ServeMux 的路由能力（支持方法匹配和路径通配符），框架在路由层的价值正在缩小。但路由从来不是痛点——“handler 该不该直接调数据库"“error 该在哪一层处理"“测试该怎么隔离”，这些问题不会因为路由变好了就消失。
这就是我说的 80% 够用陷阱：框架够用，但你的项目可能已经长大了。
接下来我用一个用户管理服务的例子，走一遍从"Gin 裸写"到"接口驱动分层"的过程。所有代码都是实际结构，你可以直接对比每一步的改动成本。
1. 从一个 Gin 裸写项目开始
先看一个典型的 Gin 项目长什么样。一个用户 CRUD，5 个 API，一个 main.go 搞定：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
|
var db *sql.DB // 全局变量，整个项目共享
func createUser(c *gin.Context) {
var req struct {
Name string `json:"name"`
Email string `json:"email"`
}
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": "参数格式错误"})
return
}
// 业务校验也在这里
if req.Name == "" || req.Email == "" {
c.JSON(http.StatusBadRequest, gin.H{"error": "姓名和邮箱不能为空"})
return
}
// 数据库操作直接写在 handler 里
result, err := db.Exec(
"INSERT INTO users (name, email) VALUES (?, ?)",
req.Name, req.Email,
)
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": "创建失败"})
log.Printf("创建用户失败: %v", err)
return
}
id, _ := result.LastInsertId()
c.JSON(http.StatusCreated, gin.H{"id": id})
}
|
这样写能跑吗？能。跑得还挺快。
1 个文件，190 行，5 个 CRUD 处理函数全在里面。项目小的时候，这是最高效的写法——没有任何多余的抽象，打开一个文件就能看全。
那问题在哪？
2. 第一个需求变更来了
问题藏在第一个需求变更里——产品说：“加个 Redis 缓存吧，用户信息读得太频繁了。”
在 Gin 裸写版里，这意味着什么？db.Query 和 db.Exec 散落在 5 个处理函数里。读相关的函数要加缓存逻辑，写相关的函数要加缓存失效——5 个函数里至少 3-4 个要改。
现在看分层版。同样的需求，你只需要做一件事：写一个新的 CachedUserRepo，实现同一个 UserRepository 接口：
1
2
3
4
5
6
7
8
|
// 接口定义——所有数据访问层的"合同"
type UserRepository interface {
List(ctx context.Context) ([]model.User, error)
GetByID(ctx context.Context, id int64) (model.User, error)
Create(ctx context.Context, user *model.User) error
Update(ctx context.Context, user *model.User) error
Delete(ctx context.Context, id int64) error
}
|
然后在 main.go 里把注入换一行——这其实是装饰器模式，新实现包装已有实现，接口不变：
1
2
|
mysqlRepo := repository.NewMySQLUserRepo(db)
repo := repository.NewCachedUserRepo(redisClient, mysqlRepo)
|
改动量对比：
| 维度 |
无分层版 |
分层版 |
| 涉及文件 |
3-4 个函数要改 |
新增 1 个文件 + main.go 改 1 行 |
| 改动风险 |
改一个漏一个 |
接口不变，上游零改动 |
| 回滚方案 |
逐行还原 |
main.go 换回一行注入 |
多出来的代码量是 71%（190 行 → 325 行）。但换来的是：改一个数据源从"改 3-4 个函数"变成"改 1 个文件”。
3. 线上告警响了
凌晨两点，你收到一条 500 告警：某个用户查询接口挂了。
打开 Gin 裸写版的代码，你得翻遍所有处理函数才能定位问题。每个函数的错误处理风格都不一样：
1
2
3
4
5
6
7
8
|
// 函数 A：返回 "error" 字段
c.JSON(500, gin.H{"error": "查询失败"})
// 函数 B：返回 "msg" 字段
c.JSON(500, gin.H{"msg": "查询失败", "code": -1})
// 函数 C：直接把原始错误丢出去
c.JSON(500, gin.H{"error": err.Error()})
|
前端不知道该解析哪个字段，排查问题时 grep 不到统一的日志模式，有人甚至把数据库错误信息直接返回给了客户端。
分层版怎么做？定义一个 AppError 类型，加一个错误处理中间件：
1
2
3
4
5
6
7
8
9
10
|
type AppError struct {
Code string // 业务错误码
Message string // 用户可见信息
Status int // HTTP 状态码
Err error // 原始错误（只进日志，不给客户端）
}
func (e *AppError) Error() string {
return fmt.Sprintf("[%s] %s", e.Code, e.Message)
}
|
中间件负责统一拦截和格式化：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
func ErrorHandler() gin.HandlerFunc {
return func(c *gin.Context) {
c.Next()
if len(c.Errors) == 0 {
return
}
err := c.Errors.Last().Err
var appErr *AppError
if errors.As(err, &appErr) {
if appErr.Err != nil {
log.Printf("[%s] %s | 原因: %v", appErr.Code, appErr.Message, appErr.Err)
}
c.JSON(appErr.Status, gin.H{"code": appErr.Code, "message": appErr.Message})
} else {
log.Printf("[UNKNOWN] %v", err)
c.JSON(500, gin.H{"code": "INTERNAL_ERROR", "message": "服务器内部错误"})
}
}
}
|
handler 变得很干净：
1
2
3
4
5
6
7
8
9
10
11
12
13
|
func getUser(c *gin.Context) {
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
if err != nil {
_ = c.Error(ErrBadRequest("无效的用户ID"))
return
}
user, err := userService.GetByID(c.Request.Context(), id)
if err != nil {
_ = c.Error(err) // 直接往上抛，中间件统一处理
return
}
c.JSON(http.StatusOK, user)
}
|
handler 只管业务逻辑，不管错误格式。所有错误的格式化、日志记录、敏感信息过滤，都在中间件里统一处理。
排查那个凌晨的 500？在中间件的日志里一查就行——所有错误都经过同一个出口。
4. 测试写不动了
你想给 createUser 写个单元测试。
在无分层版里，createUser 直接调用全局变量 db。要测它，你有两条路：
- 启动一个测试数据库——MySQL 环境下通常秒级，SQLite 内存模式快一些但也要数百毫秒
- 用 go-sqlmock——mock SQL 层，大约 40-60 行代码搞定一个测试用例。但你 mock 的是 SQL 语句，不是业务逻辑
分层版呢？service 依赖的是 UserRepository 接口，手写一个 mock 就行：
1
2
3
4
5
6
7
8
9
10
|
type mockUserRepo struct {
users []model.User
}
func (m *mockUserRepo) Create(ctx context.Context, user *model.User) error {
user.ID = int64(len(m.users) + 1)
m.users = append(m.users, *user)
return nil
}
// ...其他方法类似
|
测试代码：
1
2
3
4
5
6
7
8
9
|
func TestCreateUser(t *testing.T) {
repo := &mockUserRepo{}
svc := service.NewUserService(repo)
user := &model.User{Name: "张三", Email: "zhangsan@test.com"}
err := svc.Create(context.Background(), user)
assert.NoError(t, err)
assert.Equal(t, 1, len(repo.users))
}
|
15 行，零外部依赖，纯内存操作，毫秒级完成。写测试的门槛不在意愿——启动真库、mock SQL、清理数据，这些成本才是拦路虎。分层之后，拦路虎没了。
5. 渐进式演进——不需要推翻重来
看到这里你可能想：道理我都懂，但我的项目已经是 Gin 裸写了，总不能推翻重来吧？
不需要。分层是可以一步步加的。
先抽 service 层——把处理函数里的业务逻辑（校验、组合、转换）移到 service 包。处理函数只做"接收请求 → 调 service → 返回响应”。这一步不涉及接口，纯粹是把代码挪个位置。
稳定之后，定义 repository 接口。把 service 里的数据库操作抽成接口，写一个 MySQL 实现。service 不再直接引用 sql.DB，而是依赖 UserRepository 接口。这一步之后，mock 测试就可以写了。
等项目到了十几个 service 的规模，手动在 main.go 里 new 依赖开始痛苦了，再考虑 wire 或 fx。关于 DI 工具的选型和演进时机，我之前写过《从手动到框架：Go DI 演进的三个拐点》，这里不展开。
当然，分层不是免费的。多 71% 的代码量是真实成本，接口跳转不如直接调用直观，三个 API 的小工具硬搞三层也是过度设计。关键不是"要不要分层”，是"什么时候分层"。
6. 什么时候该"毕业"
不是所有项目都需要分层。一个内部工具、一个 demo、一个只有 3 个 API 的微服务——Gin 裸写完全够用。
但当你发现这些迹象，该考虑加一层了：改数据源动多文件、测试要启真库、error 逻辑到处复制——前面三章已经展开聊过。除此之外还有一个容易忽视的信号：新人上手需要通读整个 main.go 才能理解业务流程。 当一个文件承载了路由、校验、数据访问、错误处理全部职责，新人的认知负担会随代码量线性增长。
Gin 很好。当你的项目给出了这些信号，下一步不是换框架，是给架构加一层该有的结构。事务传递、链路追踪这些更深层的架构问题，留给下一篇再聊。