一、为什么 Go 项目结构值得专门聊#

写 Go 项目，最头疼的事情不是语法，语法一天就能上手。真正让人纠结的是「代码往哪放」。Go 官方不像 Rails 或 Django 那样给你规定目录结构。搜「Go project layout」能搜出一堆方案，golang-standards/project-layout、clean architecture、hexagonal architecture，每个都有道理，但每个都不能直接拿来就用。

我也纠结过一阵。最早写 Go 就一个 main.go 打天下，后来项目大了开始拆文件夹，拆的过程中踩了不少坑：层太多了写起来烦，层太少了改起来痛。折腾了几个项目之后，慢慢沉淀出一套自己用着顺手的结构。不敢说这是最优解，但至少是在实际项目里磨合过的。

这套结构的背景是 Go + Gin + PostgreSQL + Redis 的中小型后端服务，APP 端占大头。现在很多微服务架构也采用类似的分层方案。这篇聊聊这套结构长什么样，以及每个设计决策背后的想法。

二、整体目录结构#

先把全貌亮出来，后面的章节再逐个拆解每个部分：

四个顶层目录各有定位：

migrations/ 单独拎出来不放 internal 里，是因为迁移工具需要直接读取这些 SQL 文件，放 internal 反而碍事。

这不是照搬 golang-standards/project-layout。那个仓库里有些目录我觉得没必要，比如 api/、third_party/；有些是我后来根据实际需要加的，比如拆了三个 cmd。项目结构这种东西，合适比「标准」重要。

三、三个入口：API / Worker / Migrate#

最早我只有一个 cmd/main.go，API 服务、数据库迁移、异步任务全塞在一起。能跑是能跑，但问题很快就来了：

• 部署时只想跑 API，但启动时 Worker 的依赖也得初始化，Redis 没配好整个服务就起不来
• 想单独跑数据库迁移，得把整个 API 服务的依赖都拉起来
• API 和 Worker 需要的环境变量不一样，混在一起 .env 文件越来越乱

所以拆成三个入口，各管各的依赖。这三个入口不是一开始就设计好的，是被上面这些部署时的实际问题逼出来的。

cmd/api/ 是 HTTP 服务，最核心的入口，可以多实例水平部署。cmd/worker/ 是 Asynq 队列消费者加定时调度，跟 API 共享 service、repository 层的代码，但各自独立初始化依赖：Worker 不需要启动 HTTP server，API 不需要启动 Asynq server。cmd/migrate/ 是数据库迁移，独立进程，只连数据库执行 SQL，不依赖 Redis、不依赖 JWT，启动快、依赖少。CI/CD 里先跑 migrate 再起 API，职责清晰。

每个 main.go 的职责很简单：加载配置、初始化依赖、启动服务、处理信号优雅关闭。不在 main 里写任何业务逻辑。下面是 API 入口的精简版：

1
// cmd/api/main.go（精简版）
2
func main() {
3
    // 1. 加载配置
4
    cfg := config.Load()
5

6
    // 2. 初始化基础依赖
7
    registry, cleanup, err := config.InitAPI(cfg)
8
    if err != nil {
9
        log.Fatal("init failed", zap.Error(err))
10
    }
11
    defer cleanup()
12

13
    // 3. 创建并启动 HTTP 服务
14
    srv := internal.NewServer(registry)
15

16
    go func() {
17
        if err := srv.Start(); err != nil {
18
            log.Error("server stopped", zap.Error(err))
19
        }
20
    }()
21

22
    // 4. 等待信号，优雅关闭
23
    quit := make(chan os.Signal, 1)
24
    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
25
    <-quit
26

27
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
28
    defer cancel()
29
    srv.Shutdown(ctx)
30
}

代码不多，但结构很清楚。收到 SIGINT 或 SIGTERM 后，给 HTTP server 10 秒的优雅关闭窗口，等正在处理的请求结束，再释放资源退出。cleanup 函数由 InitAPI 返回，负责关闭数据库连接、Redis 连接这些基础依赖，用 defer 保证一定会执行。

四、分层设计：handler → service → repository#

这是整个项目结构的核心。调用链是一条单向路径：

每一层有明确的职责边界，不能越级。下面逐层看。

handler 是 HTTP 协议适配层，做三件事：绑定参数、调用 service、格式化响应，不写任何业务逻辑。

1
type ArticleHandler struct {
2
    svc *service.ArticleService
3
}
4

5
func (h *ArticleHandler) Create(c *gin.Context) {
6
    var req struct {
7
        Title   string   `json:"title" binding:"required,max=200"`
8
        Content string   `json:"content" binding:"required"`
9
        Tags    []string `json:"tags"`
10
    }
11
    if err := c.ShouldBindJSON(&req); err != nil {
12
        response.ParamError(c, err)
13
        return
14
    }
15

16
    article, err := h.svc.CreateArticle(c.Request.Context(), req.Title, req.Content, req.Tags)
17
    if err != nil {
18
        response.Error(c, err)
19
        return
20
    }
21
    response.Success(c, article)
22
}

service 是业务逻辑层，接收普通参数，返回业务数据或错误码。注意它接收的是 context.Context，不是 *gin.Context，这一步很关键，后面会展开说。

1
type ArticleService struct {
2
    repo *repository.ArticleRepository
3
}
4

5
func (s *ArticleService) CreateArticle(ctx context.Context, title, content string, tags []string) (*model.Article, error) {
6
    // 业务规则校验
7
    if len(tags) > 10 {
8
        return nil, errcode.ErrTooManyTags
9
    }
10

11
    article := &model.Article{
12
        Title:   title,
13
        Content: content,
14
        Tags:    tags,
15
    }
16
    if err := s.repo.Create(ctx, article); err != nil {
17
        return nil, errcode.ErrDatabase
18
    }
19
    return article, nil
20
}

service 接收 context.Context 而不是 *gin.Context，是为了跟 HTTP 协议解耦。同样的 service 可以被 handler 调用，也可以被 worker 调用，不用改一行代码。service 返回的错误是 errcode 包里定义的业务错误码，不是直接返回「数据库错误」这种字符串。handler 拿到错误码之后，通过统一的 response.Error() 转成 JSON 响应，这块后面详细说。

repository 是数据访问层，整个项目里唯一允许写 GORM 或原生 SQL 的地方。

1
type ArticleRepository struct {
2
    db *gorm.DB
3
}
4

5
func (r *ArticleRepository) Create(ctx context.Context, article *model.Article) error {
6
    return r.db.WithContext(ctx).Create(article).Error
7
}
8

9
func (r *ArticleRepository) FindByID(ctx context.Context, id uint) (*model.Article, error) {
10
    var article model.Article
11
    err := r.db.WithContext(ctx).First(&article, id).Error
12
    if err != nil {
13
        return nil, err
14
    }
15
    return &article, nil
16
}

model 是 GORM 数据模型，纯数据结构，不包含任何方法：

1
type Article struct {
2
    ID        uint      `gorm:"primarykey" json:"id"`
3
    Title     string    `gorm:"size:200;not null" json:"title"`
4
    Content   string    `gorm:"type:text;not null" json:"content"`
5
    Tags      []string  `gorm:"type:text[];default:'{}'" json:"tags"`
6
    CreatedAt time.Time `json:"created_at"`
7
    UpdatedAt time.Time `json:"updated_at"`
8
}

五、手写依赖注入：Registry 模式#

依赖注入（DI）的核心目的只有一个：让每一层只声明自己需要什么，由上层把依赖传进来，自己不 new 别人。Go 社区有几个流行的 DI 方案：Google 的 Wire（编译期代码生成）、Uber 的 Dig 和 Fx（运行时反射注入）。

我试过 Wire，用了一阵之后放弃了，原因有几个：

• 多一个代码生成步骤（wire gen），每次改依赖都要重新跑，CI 也得加这步
• 生成的代码是个黑盒，出了问题排查不直观
• 对于中小型项目，手写 DI 的代码量其实没有想象中大

Dig 和 Fx 用运行时反射注入，出错信息更不友好。而且 Go 社区整体偏好「编译期能发现的问题就别留到运行时」，反射注入跟这个哲学有点冲突。所以最终选了手写。

核心是一个 Registry 模式，把所有基础依赖集中放在一个结构体里：

1
type Registry struct {
2
    DB          *gorm.DB
3
    Cache       *redis.Client
4
    JWT         *auth.JWTManager
5
    QueueClient *asynq.Client
6
    I18n        *i18n.Bundle
7
    // 其他基础依赖
8
}

config 包负责初始化这些基础依赖，组装成 Registry，同时返回一个 cleanup 函数用于资源释放：

1
func InitAPI(cfg *Config) (*Registry, func(), error) {
2
    db, err := database.Open(cfg.DatabaseURL)
3
    if err != nil {
4
        return nil, nil, err
5
    }
6

7
    cache := cache.NewClient(cfg.RedisAddr, cfg.RedisPassword, cfg.RedisDB)
8
    jwt := auth.NewJWTManager(cfg.JWTSecret, cfg.JWTExpiresAt)
9

10
    registry := &Registry{
11
        DB:    db,
12
        Cache: cache,
13
        JWT:   jwt,
14
    }
15

16
    cleanup := func() {
17
        cache.Close()
18
        sqlDB, _ := db.DB()
19
        sqlDB.Close()
20
    }
21

22
    return registry, cleanup, nil
23
}

然后 internal/server.go 从 Registry 装配完整的调用链：

1
func NewServer(reg *config.Registry) *Server {
2
    // 装配调用链：repo → service → handler
3
    articleRepo := repository.NewArticleRepository(reg.DB)
4
    articleSvc := service.NewArticleService(articleRepo)
5
    articleHandler := handler.NewArticleHandler(articleSvc)
6

7
    // 装配路由
8
    engine := gin.New()
9
    router.RegisterRoutes(engine, router.Dependencies{
10
        Article: articleHandler,
11
        Auth:    middleware.JWTAuth(reg.JWT, reg.Cache),
12
    })
13

14
    return &Server{
15
        engine: engine,
16
        addr:   reg.Config.ServerPort,
17
    }
18
}

所有的依赖装配集中在 server.go 这一个地方。handler、service、repository 自己不 new 任何其他业务对象，它们只声明自己需要什么，由上层传进来。这样做的好处是：打开 server.go，整个应用的依赖关系一目了然，谁依赖谁、什么时候创建什么时候销毁，全在这一个文件里。IDE 可以直接跳转到每个构造函数，不需要理解任何 DI 框架的「魔法」。

代码多吗？确实比 Wire 生成的要多一些。但这点「啰嗦」换来的是完全透明的依赖关系，我觉得值。

六、路由设计#

router 包只干一件事：注册 URL 和 handler 的映射关系。不构造依赖，不初始化服务。

1
type Dependencies struct {
2
    Article *handler.ArticleHandler
3
    User    *handler.UserHandler
4
    Auth    gin.HandlerFunc
5
}
6

7
func RegisterRoutes(r *gin.Engine, deps Dependencies) {
8
    // 健康检查，不需要认证
9
    r.GET("/health", handler.Health)
10

11
    // API 路由组
12
    v1 := r.Group("/api/v1")
13

14
    registerArticleRoutes(v1, deps)
15
    registerUserRoutes(v1, deps)
16
}
17

18
func registerArticleRoutes(r *gin.RouterGroup, deps Dependencies) {
19
    articles := r.Group("/articles")
20
    articles.Use(deps.Auth)
21

22
    articles.GET("", deps.Article.List)
23
    articles.POST("", deps.Article.Create)
24
    articles.GET("/:id", deps.Article.Get)
25
}
26

27
func registerUserRoutes(r *gin.RouterGroup, deps Dependencies) {
28
    users := r.Group("/users")
29

30
    // 公开接口
31
    users.POST("/login", deps.User.Login)
32
    users.POST("/register", deps.User.Register)
33

34
    // 需要认证的接口
35
    authed := users.Group("")
36
    authed.Use(deps.Auth)
37
    authed.GET("/me", deps.User.Me)
38
}

这里有几个设计决策值得说。

第一，按模块拆私有函数。每个业务模块一个 registerXxxRoutes，模块内自己决定哪些接口公开、哪些需要认证。模块多了也不会让 router.go 变成一个几百行的大文件。

第二，Dependencies 由外部传入。router 不关心 handler 是怎么创建的，它只接收现成的、可以直接用的 handler。这就保证了路由注册和依赖装配的解耦：改装配逻辑不用动 router，改路由不用动装配。

第三，认证中间件作为依赖传入。Auth 中间件也是从外面传进来的，router 不知道具体的认证实现。以后换了认证方式（比如从 JWT 换成 OAuth），只改 server.go 里的装配代码就行。

七、统一响应协议和错误码#

这块是我纠结比较久才定下来的。

1
{
2
  "code": 0,
3
  "message": "success",
4
  "data": { "id": 1, "title": "..." }
5
}

1
{
2
  "code": 4001,
3
  "reason": "INVALID_PARAMS",
4
  "message": "标题不能为空",
5
  "metadata": {
6
    "trace_id": "550e8400-..."
7
  }
8
}

1
type AppError struct {
2
    Code    int    // 数字错误码
3
    Reason  string // 机器可读的错误标识
4
    Message string // 人类可读的错误信息
5
}
6

7
func (e *AppError) Error() string {
8
    return e.Message
9
}
10

11
// 通用错误
12
var (
13
    ErrInvalidParams = &AppError{Code: 4001, Reason: "INVALID_PARAMS", Message: "请求参数不合法"}
14
    ErrUnauthorized  = &AppError{Code: 4010, Reason: "UNAUTHORIZED", Message: "未登录或登录已过期"}
15
    ErrForbidden     = &AppError{Code: 4030, Reason: "FORBIDDEN", Message: "没有权限"}
16
    ErrNotFound      = &AppError{Code: 4040, Reason: "NOT_FOUND", Message: "资源不存在"}
17
    ErrDatabase      = &AppError{Code: 9002, Reason: "DATABASE_ERROR", Message: "系统繁忙，请稍后重试"}
18
)
19

20
// 业务错误
21
var (
22
    ErrTooManyTags    = &AppError{Code: 5001, Reason: "TOO_MANY_TAGS", Message: "标签数量超过限制"}
23
    ErrDuplicateTitle = &AppError{Code: 5002, Reason: "DUPLICATE_TITLE", Message: "标题已存在"}
24
)

1
func Success(c *gin.Context, data interface{}) {
2
    c.JSON(200, gin.H{
3
        "code":    0,
4
        "message": "success",
5
        "data":    data,
6
    })
7
}
8

9
func Error(c *gin.Context, err error) {
10
    var appErr *errcode.AppError
11
    if errors.As(err, &appErr) {
12
        c.JSON(200, gin.H{
13
            "code":    appErr.Code,
14
            "reason":  appErr.Reason,
15
            "message": appErr.Message,
16
            "metadata": gin.H{
17
                "trace_id": c.GetString("trace_id"),
18
            },
19
        })
20
        return
21
    }
22
    // 兜底：未知错误
23
    c.JSON(200, gin.H{
24
        "code":    9999,
25
        "reason":  "INTERNAL_ERROR",
26
        "message": "系统繁忙，请稍后重试",
27
    })
28
}

八、多语言（i18n）#

我做的项目基本都有多语言需求，所以从项目结构设计的时候就得把 i18n 考虑进去。很多框架虽然支持 i18n，但不会告诉你翻译文件该放哪、错误信息怎么跟多语言串起来。这块得自己规划。

1
{
2
  "INVALID_PARAMS": "请求参数不合法",
3
  "UNAUTHORIZED": "未登录或登录已过期",
4
  "TOO_MANY_TAGS": "标签数量超过限制",
5
  "DATABASE_ERROR": "系统繁忙，请稍后重试"
6
}

1
{
2
  "INVALID_PARAMS": "Invalid request parameters",
3
  "UNAUTHORIZED": "Not logged in or session expired",
4
  "TOO_MANY_TAGS": "Too many tags",
5
  "DATABASE_ERROR": "System busy, please try again later"
6
}

1
func Error(c *gin.Context, err error) {
2
    var appErr *errcode.AppError
3
    if errors.As(err, &appErr) {
4
        // 根据请求语言偏好翻译 message
5
        lang := c.GetHeader("Accept-Language")
6
        message := i18n.Translate(lang, appErr.Reason, appErr.Message)
7

8
        c.JSON(200, gin.H{
9
            "code":    appErr.Code,
10
            "reason":  appErr.Reason,
11
            "message": message,
12
            "metadata": gin.H{
13
                "trace_id": c.GetString("trace_id"),
14
            },
15
        })
16
        return
17
    }
18
    // ...
19
}

九、JWT 鉴权：三层校验#

JWT 鉴权不只是「验个签名」就完事了。我设计了三层校验链，每层解决不同的问题：

Layer 1 是标配，所有 JWT 库都做。签名验证确保 token 没被篡改，exp 确保 token 没过期，iss 校验确保 token 是我们自己签发的。

Layer 2 解决「主动登出」的问题。JWT 是无状态的，签发出去之后你没法「撤回」它，只要没过期它就有效。所以用户主动登出的时候，把这个 token 的 JTI（JWT ID，每个 token 的唯一标识）加到 Redis 黑名单里。中间件每次请求都查一下 Redis，命中黑名单就拒绝。黑名单的 TTL 设成跟 token 过期时间一样，过期了自然失效，不会无限膨胀。

Layer 3 解决「批量失效」的问题。用户改了密码、管理员踢人、账号被封，这些场景需要让某个用户的所有 token 都失效。一个个加黑名单不现实，你不知道用户一共有多少有效 token。所以 token 里带一个 token_version 字段，数据库或缓存里存着这个用户当前的版本号。改密码时把版本号加 1，所有旧 token 的版本号就对不上了，一次性全部失效：

1
// Token Claims 结构
2
type Claims struct {
3
    UserID       uint64 `json:"user_id"`
4
    TokenVersion uint64 `json:"token_version"`
5
    jwt.RegisteredClaims
6
}

Layer 3 是可选的，骨架里默认不启用。如果你的项目需要，实现一个 TokenVersionStore 接口注入进去就行：

1
type TokenVersionStore interface {
2
    GetTokenVersion(ctx context.Context, userID uint64) (uint64, error)
3
}

不需要这个功能的项目就不注入，中间件自动跳过 Layer 3 的检查。这样既不增加简单项目的复杂度，又给需要的项目留了扩展口。

十、异步队列#

不是所有操作都适合在 HTTP 请求里同步完成。发邮件、推送通知、生成报表这些耗时操作，应该扔到异步队列里处理。我用的是 Asynq，一个基于 Redis 的 Go 异步任务库。

选它的原因很简单：项目本来就用 Redis，不想再引入 RabbitMQ 或 Kafka 这种重依赖；纯 Go 实现，API 简洁，文档清晰；自带定时任务调度（Scheduler），不用再接 cron；有 Web UI（Asynqmon）可以看任务状态。

任务定义放在 internal/task/ 包里，只负责描述任务的类型和 payload，不包含处理逻辑：

1
const TypeSendEmail = "email:send"
2

3
type SendEmailPayload struct {
4
    To      string `json:"to"`
5
    Subject string `json:"subject"`
6
    Body    string `json:"body"`
7
}
8

9
func NewSendEmailTask(payload SendEmailPayload) (*asynq.Task, error) {
10
    data, err := json.Marshal(payload)
11
    if err != nil {
12
        return nil, err
13
    }
14
    return asynq.NewTask(TypeSendEmail, data), nil
15
}

API 端在 service 层投递任务：

1
// 在 service 层
2
func (s *UserService) Register(ctx context.Context, ...) error {
3
    // ... 创建用户 ...
4

5
    // 异步发送欢迎邮件
6
    t, _ := task.NewSendEmailTask(task.SendEmailPayload{
7
        To:      user.Email,
8
        Subject: "欢迎注册",
9
        Body:    "...",
10
    })
11
    s.queueClient.Enqueue(t)
12

13
    return nil
14
}

Worker 端消费任务：

1
// internal/worker/ 下面的 handler
2
func HandleSendEmail(ctx context.Context, t *asynq.Task) error {
3
    var payload task.SendEmailPayload
4
    json.Unmarshal(t.Payload(), &payload)
5
    return sendEmail(payload.To, payload.Subject, payload.Body)
6
}

Worker 和 API 共享 service、repository 层的代码。两者的区别只是入口不同：API 通过 HTTP handler 进入业务逻辑，Worker 通过 Asynq handler 进入。这就是为什么前面强调 service 层不依赖 *gin.Context 很重要，如果 service 层耦合了 HTTP 概念，Worker 就没法复用了。

十一、其他约定#

十二、不是银弹#

这套结构不是银弹。它是在特定场景下，Go + Gin + PostgreSQL + Redis 的中小型后端服务，经过几个项目打磨出来的方案。如果要提炼几个核心原则的话：

• 显式优于隐式：手写 DI、显式错误处理、每一层的职责都摆在明面上
• 职责边界清晰：每一层只干自己该干的事，不越级、不混搭
• 依赖关系单向：handler → service → repository，不反向依赖
• 为变化留余地：JWT 的三层校验可以按需开关，分层可以根据复杂度增减，Worker 和 API 可以独立部署

项目小的时候这套结构可能觉得有点「重」，就几个接口至于分这么多层吗？但项目一旦开始长大，你会庆幸一开始就把边界画好了。改一个 service 不用担心影响 handler 的逻辑，加一个新模块只需要加对应的 handler/service/repository 然后在 router 里注册一下。

当然，如果你的项目就是一个简单的内部工具或者原型验证，该 main.go 一把梭就一把梭，别被「最佳实践」束缚住了。结构是为项目服务的，不是反过来。

参考资料#

• Asynq - 基于 Redis 的 Go 异步任务库
• Wire - Google 的编译期依赖注入工具
• Dig - Uber 的运行时依赖注入容器
• Fx - 基于 Dig 的应用框架
• go-i18n - Go 国际化库
• golang-standards/project-layout - Go 项目目录结构参考
• arixbit/go-example - 本文结构的参考实现仓库