本文介绍在真实世界 go web 项目中如何合理分离路由定义、http 处理器、核心业务逻辑及第三方服务（如邮件、推送）接口，强调接口抽象、依赖注入与测试友好性，避免过早分包或过度设计。
本文介绍在真实世界 go web 项目中如何合理分离路由定义、http 处理器、核心业务逻辑及第三方服务（如邮件、推送）接口，强调接口抽象、依赖注入与测试友好性，避免过早分包或过度设计。
在构建可维护、可测试且易于演进的 Go REST API 时，结构混乱是比性能瓶颈更常见的“技术债源头”。许多开发者初期将所有代码塞入 main 包——路由、中间件、数据库操作、邮件发送混杂一处，导致单元测试困难、逻辑复用受限、第三方服务替换成本高昂。本文提供一套经过生产验证的分层实践，不追求教条式“Clean Architecture”图谱，而聚焦务实、轻量、可立即落地的组织方式。
核心原则：分层 ≠ 过度分包，接口先行，依赖倒置
Go 的哲学强调“少即是多”，项目结构应服务于可读性与可维护性，而非机械遵循某套范式。关键不在于包数量多少，而在于职责边界是否清晰、依赖方向是否合理、测试是否无需 HTTP 层即可运行。
- ✅ 推荐做法：将业务逻辑封装为独立函数或方法，定义明确输入输出，*不依赖 http.Request、`gin.Context` 或具体第三方 SDK**；
- ❌ 应避免：在 handler 中直接调用 ses.SendEmail(...) 或 sns.Publish(...)；也不应在 model 层硬编码邮件模板路径。
以下是一个典型但精简的目录结构示例（基于你描述的 /auth 和 /resources 场景）：
myapp/
├── cmd/
│ └── server/ # 唯一 main.go 入口，仅负责初始化与启动
├── internal/
│ ├── auth/ # 认证业务逻辑（JWT 生成/校验/黑名单管理）
│ │ ├── service.go # AuthService 接口及核心实现
│ │ └── blacklist.go # 黑名单存储抽象（如 Redis 实现）
│ ├── resource/ # 资源管理业务逻辑
│ │ ├── service.go # ResourceService 接口 + Create() / List()
│ │ └── notifier.go # 通知触发逻辑（不关心邮件/推送具体实现）
│ ├── mailer/ # 邮件能力抽象层（接口定义）
│ │ ├── interface.go # Mailer 接口：Send(to, template, data)
│ │ └── ses/ # AWS SES 具体实现（仅在此处 import github.com/aws/aws-sdk-go）
│ └── notification/ # 推送能力抽象层（同上）
│ ├── interface.go # Notifier 接口
│ └── sns/ # SNS 实现
└── api/ # 纯 HTTP 层：路由 + handler + middleware
├── router.go # gin/chi 路由注册（无业务逻辑）
├── auth_handler.go # 仅解析参数、调用 auth.Service、写响应
├── resource_handler.go
└── auth_middleware.go # JWT 解析与校验，调用 auth.Service.ValidateToken()
关键实践详解
1. 业务逻辑独立于传输层
internal/auth/service.go 应提供纯函数式接口：
// internal/auth/service.go
type Service interface {
SignIn(ctx context.Context, username, password string) (string, error) // 返回 JWT token
SignOut(ctx context.Context, token string) error
ValidateToken(ctx context.Context, token string) (*User, error)
}
type service struct {
store BlacklistStore // 依赖抽象存储，非具体 Redis 客户端
}
func NewService(store BlacklistStore) Service { ... }
Handler 中仅做粘合：
// api/auth_handler.go
func (h *AuthHandler) SignIn(c *gin.Context) {
var req struct{ Username, Password string }
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(400, gin.H{"error": "invalid input"})
return
}
token, err := h.authSvc.SignIn(c.Request.Context(), req.Username, req.Password)
if err != nil {
c.JSON(401, gin.H{"error": "auth failed"})
return
}
c.JSON(200, gin.H{"token": token})
}
✅ 优势：auth.Service 可被单元测试（mock BlacklistStore），也可被 CLI 工具或定时任务复用。
2. 第三方服务必须通过接口抽象
internal/mailer/interface.go 定义契约：
package mailer
type Mailer interface {
Send(ctx context.Context, to string, templateName string, data any) error
}
internal/mailer/ses/ses.go 实现它：
package ses
import "github.com/aws/aws-sdk-go/service/ses"
type SESMailer struct {
client *ses.SES
}
func (m *SESMailer) Send(ctx context.Context, to, tmpl string, data any) error {
// 使用 AWS SDK 发送，此处才 import ses
}
cmd/server/main.go 中完成依赖注入：
func main() {
sesClient := ses.New(session.Must(session.NewSession())))
mailer := ses.NewSESMailer(sesClient)
authSvc := auth.NewService(redisStore)
resourceSvc := resource.NewService(mailer, notifier) // 传入抽象接口
r := gin.Default()
api.RegisterRoutes(r, authSvc, resourceSvc)
r.Run(":8080")
}
✅ 优势：切换邮件服务商只需新增 mailer/sendgrid/ 包并注入新实例；测试时可传入 &mockMailer{}。
3. 路由与中间件归属 HTTP 层，不跨层污染
- api/router.go：只调用 r.POST("/auth/sign-in", h.SignIn)，不包含任何业务判断；
- api/auth_middleware.go：解析 Authorization: Bearer xxx，调用 authSvc.ValidateToken()，将用户信息存入 c.Set("user", u) —— 中间件本身不处理错误响应格式，交由统一错误处理中间件或 handler 自行决定。
4. 关于包划分的务实建议
- internal/ 下按业务域（auth, resource）而非技术层（handler, service, repo）建包，更符合 Go 的“面向包设计”思想；
- 避免 util、common、helpers 等泛化包——功能明确的工具应归属其使用方所在包，或提升为独立开源库（如 github.com/yourorg/goemail）；
- cmd/ 下每个子目录对应一个可执行命令（server, migrate, seed），确保 main 函数极简。
总结：三句口诀
? Handler 是胶水，不是大脑 —— 它只负责 HTTP 协议转换与错误映射；
? 业务逻辑是核心资产，必须可脱离 HTTP 独立测试与复用；
? 第三方依赖必须被接口围栏隔离，注入点唯一且显式。
这种结构不会让你第一天就写出“完美架构”，但它能确保第 100 次迭代时，你依然能快速定位问题、安全替换组件、并自信地为每个业务函数编写覆盖率 >90% 的测试。
