本文详解如何在真实 go web 项目中合理分层——将 http 路由、请求处理器、核心业务逻辑及第三方服务（如邮件、推送）解耦，兼顾可测试性、可维护性与演进弹性。
本文详解如何在真实 go web 项目中合理分层——将 http 路由、请求处理器、核心业务逻辑及第三方服务（如邮件、推送）解耦，兼顾可测试性、可维护性与演进弹性。
在构建生产级 Go REST API 时，结构混乱是技术债的温床：main.go 膨胀成“上帝文件”，业务逻辑与 HTTP 细节混杂，第三方 SDK 调用四处散落，导致单元测试困难、替换依赖成本高昂、新成员上手缓慢。真正的工程化并非追求教条式分层（如强行套用 MVC），而是围绕关注点分离与可替代性设计边界。以下是一套经实战验证的轻量但稳健的架构方案。
一、核心原则：以“内部 API”为中心，而非框架或模式
Go 应用的本质是集成系统——它协调数据库、缓存、邮件、通知等外部能力，完成业务目标。因此，架构重心应放在定义清晰、无框架依赖的内部业务接口（Internal API） 上，而非围绕 HTTP 或 MVC 组织代码。
- ✅ 推荐做法：所有核心业务逻辑封装为纯函数或结构体方法，接收领域对象（如 *models.Resource）、返回标准错误，不感知 HTTP 请求/响应、中间件、JSON 编解码。
- ❌ 避免做法：在 handler 中直接调用 mailer.Send(...) 或拼接 SQL；或将 JWT 验证逻辑硬编码在 auth-handler.go 内部。
例如，资源创建的业务逻辑应独立于 HTTP：
// internal/service/resource_service.go
package service
import (
"context"
"myapp/internal/models"
"myapp/internal/ports"
)
type ResourceService struct {
repo ports.ResourceRepository
notifier ports.Notifier
mailer ports.Mailer
}
func (s *ResourceService) Create(ctx context.Context, input models.ResourceInput) (*models.Resource, error) {
// 1. 核心业务校验与创建
res, err := s.repo.Create(ctx, input)
if err != nil {
return nil, err
}
// 2. 触发副作用（解耦且可 mock）
go func() {
_ = s.notifier.NotifyNewResource(ctx, res)
_ = s.mailer.SendResourceCreatedEmail(ctx, res)
}()
return res, nil
}
该 ResourceService 完全不依赖 net/http，可被 CLI 命令、定时任务或 gRPC 服务复用，且能通过接口注入模拟依赖进行完整单元测试。
二、分层实践：四层职责明确，按需拆包
| 层级 | 目录示例 | 职责 | 关键约束 |
|---|---|---|---|
| Handlers (cmd/api/handler) | auth_handler.go, resource_handler.go | 解析 HTTP 请求、调用 Internal API、构造 HTTP 响应 | 仅含 5–15 行胶水代码；禁止业务逻辑、第三方调用 |
| Internal API (internal/service) | auth_service.go, resource_service.go | 实现核心业务规则、事务协调、副作用触发 | 依赖抽象端口（interfaces），不依赖具体实现 |
| Ports & Adapters (internal/ports, pkg/mailer, pkg/notifier) | mailer.go（接口定义）, pkg/mailer/mandrill.go（实现） | 定义第三方交互契约（接口），并提供具体适配器 | 接口定义在 internal/ports，实现放在 pkg/ 下独立子包 |
| Routes & Middleware (cmd/api) | main.go, router.go | 注册路由、挂载中间件（如 JWT 验证）、初始化依赖树 | 中间件与路由同包；依赖注入在此完成 |
✨ 第三方服务接口化示例
将 Mandrill 邮件服务封装为可替换的端口：
// internal/ports/mailer.go
package ports
type Mailer interface {
Send(ctx context.Context, to, subject string, body []byte) error
}
// pkg/mailer/mandrill.go
package mandrill
import "myapp/internal/ports"
type MandrillMailer struct {
client *mandrill.Client // 第三方 SDK
}
func (m *MandrillMailer) Send(ctx context.Context, to, subject string, body []byte) error {
// 调用 Mandrill SDK 实现
return m.client.MessagesSend(...)
}
// cmd/api/main.go —— 依赖注入点
func main() {
mandrillClient := mandrill.NewClient("API_KEY")
mailer := mandrill.NewMandrillMailer(mandrillClient)
svc := service.NewResourceService(
repo,
notifier,
mailer, // 注入具体实现
)
handler := handler.NewResourceHandler(svc)
router := chi.NewRouter()
router.Post("/resources", handler.Create)
}
? 关键优势：未来切换至 AWS SES 只需新增 pkg/mailer/ses.go 实现同一接口，并在 main.go 中替换注入，业务层零修改。
三、包组织策略：克制拆分，优先内聚
- 拒绝“util”包：pkg/util 是反模式。通用工具应沉淀为独立模块（如 github.com/yourorg/go-tools/uuid），按功能原子化发布。
- 应用层包宜扁平：cmd/api（入口）、internal/service（业务）、internal/ports（契约）已足够清晰；过早拆分为 internal/service/auth/internal/service/resource 易增加导航成本，除非规模超 10k 行。
- 第三方适配器独立成包：pkg/mailer/mandrill、pkg/notifier/aws_sns 等，便于跨项目复用或开源。
四、注意事项与总结
- 中间件归属：JWT 验证、日志、限流等中间件应与路由同包（如 cmd/api/middleware.go），因其强绑定 HTTP 生命周期，无需抽象为端口。
- 模型位置：internal/models 存放领域实体（如 User, Resource），避免在 handler 或 pkg/ 中重复定义。
- 测试友好性：internal/service 层可通过 mock 包模拟 ports.Mailer 等接口，实现 100% 业务逻辑覆盖，无需启动 HTTP 服务器。
- 演进提示：当 internal/service 某个模块（如认证）复杂度显著升高，再考虑拆为独立微服务——先做好的单体，再拆服务。
最终架构不是静态图纸，而是随业务生长的活体。从 main.go 中剥离业务逻辑、为第三方依赖定义接口、让 handler 仅剩几行调用——这三个动作，足以让您的 Go 项目迈出工程化的坚实第一步。
