一、前言

hi，大家好，这里是白泽。今天给大家分享一个GitHub 🌟 3.5k 的 Go项目：go-backend-clean-arch

https://github.com/amitshekhariitbhu/go-backend-clean-architecture

这个项目是一位老外写的，通过一个 HTTP demo 介绍了一个优雅的项目结构。

我也在b站出了一期30多分钟的视频，讲解了这个仓库，欢迎你的关注 📺 B站：白泽talk，qq交流群：622383022。

🌟 当然，如果您是一位 Go 学习的新手，您可以在我开源的学习仓库：https://github.com/BaiZe1998/go-learning 中，找到我往期翻译的英文书籍，或者Go学习路线。

二、项目架构

三、目录详解

.
├── Dockerfile # 镜像文件
├── api
│   ├── controller # 接口
│   ├── middleware # 中间件（JWT鉴权）
│   └── route # 路由绑定
├── bootstrap
│   ├── app.go # 核心类
│   ├── database.go # 数据库
│   └── env.go # 配置类
├── cmd
│   └── main.go # 启动命令
├── docker-compose.yaml
├── domain # 实例层
├── go.mod
├── go.sum
├── internal # 内部工具
│   └── tokenutil
├── mongo # mongodb
│   └── mongo.go
├── repository # 仓储层
└── usecase # 业务层

3.1 参数配置 & 项目启动

./cmd/main.go

type Application struct {
    Env   *Env
    Mongo mongo.Client
}
​
type Env struct {
    AppEnv                 string `mapstructure:"APP_ENV"`
    ServerAddress          string `mapstructure:"SERVER_ADDRESS"`
    ContextTimeout         int    `mapstructure:"CONTEXT_TIMEOUT"`
    DBHost                 string `mapstructure:"DB_HOST"`
    DBPort                 string `mapstructure:"DB_PORT"`
    ...
}
​
func main() {
    // app 是整个应用的实例，管理生命周期中的重要资源
    app := bootstrap.App()
    // 配置变量
    env := app.Env
    // 数据库实例
    db := app.Mongo.Database(env.DBName)
    defer app.CloseDBConnection()
​
    timeout := time.Duration(env.ContextTimeout) * time.Second
    // gin 实例创建
    gin := gin.Default()
    // 路由绑定
    route.Setup(env, timeout, db, gin)
    // 运行服务
    gin.Run(env.ServerAddress)
}

🌟 接下来的讲解将以登陆逻辑为例，讲解三层架构。

3.2 接口层

./api/controller/login_controller.go

LoginController 持有配置类，以及 LoginUsecase 接口（定义了业务层的行为）

// 业务层接口
type SignupUsecase interface {
    Create(c context.Context, user *User) error
    GetUserByEmail(c context.Context, email string) (User, error)
    CreateAccessToken(user *User, secret string, expiry int) (accessToken string, err error)
    CreateRefreshToken(user *User, secret string, expiry int) (refreshToken string, err error)
}
​
type LoginController struct {
   LoginUsecase domain.LoginUsecase
   Env          *bootstrap.Env
}
​
func (lc *LoginController) Login(c *gin.Context) {
   var request domain.LoginRequest
​
   err := c.ShouldBind(&request)
   if err != nil {
      c.JSON(http.StatusBadRequest, domain.ErrorResponse{Message: err.Error()})
      return
   }
​
   user, err := lc.LoginUsecase.GetUserByEmail(c, request.Email)
   if err != nil {
      c.JSON(http.StatusNotFound, domain.ErrorResponse{Message: "User not found with the given email"})
      return
   }
​
   if bcrypt.CompareHashAndPassword([]byte(user.Password), []byte(request.Password)) != nil {
      c.JSON(http.StatusUnauthorized, domain.ErrorResponse{Message: "Invalid credentials"})
      return
   }
​
   accessToken, err := lc.LoginUsecase.CreateAccessToken(&user, lc.Env.AccessTokenSecret, lc.Env.AccessTokenExpiryHour)
   if err != nil {
      c.JSON(http.StatusInternalServerError, domain.ErrorResponse{Message: err.Error()})
      return
   }
​
   refreshToken, err := lc.LoginUsecase.CreateRefreshToken(&user, lc.Env.RefreshTokenSecret, lc.Env.RefreshTokenExpiryHour)
   if err != nil {
      c.JSON(http.StatusInternalServerError, domain.ErrorResponse{Message: err.Error()})
      return
   }
​
   loginResponse := domain.LoginResponse{
      AccessToken:  accessToken,
      RefreshToken: refreshToken,
   }
​
   c.JSON(http.StatusOK, loginResponse)
}

3.3 业务层

./usecase/login_usecase.go

loginUsecase 结构实现 LoginUsecase 接口，同时在 loginUsecase 结构中，持有了 UserRepository 接口（定义了仓储层的行为）。

// 数据防腐层接口
type UserRepository interface {
    Create(c context.Context, user *User) error
    Fetch(c context.Context) ([]User, error)
    GetByEmail(c context.Context, email string) (User, error)
    GetByID(c context.Context, id string) (User, error)
}
​
type loginUsecase struct {
   userRepository domain.UserRepository
   contextTimeout time.Duration
}
​
func NewLoginUsecase(userRepository domain.UserRepository, timeout time.Duration) domain.LoginUsecase {
   return &loginUsecase{
      userRepository: userRepository,
      contextTimeout: timeout,
   }
}
​
func (lu *loginUsecase) GetUserByEmail(c context.Context, email string) (domain.User, error) {
   ctx, cancel := context.WithTimeout(c, lu.contextTimeout)
   defer cancel()
   return lu.userRepository.GetByEmail(ctx, email)
}
​
func (lu *loginUsecase) CreateAccessToken(user *domain.User, secret string, expiry int) (accessToken string, err error) {
   return tokenutil.CreateAccessToken(user, secret, expiry)
}
​
func (lu *loginUsecase) CreateRefreshToken(user *domain.User, secret string, expiry int) (refreshToken string, err error) {
   return tokenutil.CreateRefreshToken(user, secret, expiry)
}

3.4 防腐层

./repository/user_repository.go

userRepository 结构实现了 UserRepository 接口，内部持有 mongo.Database 接口（定义数据层行为），以及 collection 实例的名称。

// 数据操作层接口
type Database interface {
    Collection(string) Collection
    Client() Client
}
​
type userRepository struct {
   database   mongo.Database
   collection string
}
​
func NewUserRepository(db mongo.Database, collection string) domain.UserRepository {
   return &userRepository{
      database:   db,
      collection: collection,
   }
}
​
func (ur *userRepository) Create(c context.Context, user *domain.User) error {
   collection := ur.database.Collection(ur.collection)
​
   _, err := collection.InsertOne(c, user)
​
   return err
}
​
func (ur *userRepository) Fetch(c context.Context) ([]domain.User, error) {
   collection := ur.database.Collection(ur.collection)
​
   opts := options.Find().SetProjection(bson.D{{Key: "password", Value: 0}})
   cursor, err := collection.Find(c, bson.D{}, opts)
​
   if err != nil {
      return nil, err
   }
​
   var users []domain.User
​
   err = cursor.All(c, &users)
   if users == nil {
      return []domain.User{}, err
   }
​
   return users, err
}
​
func (ur *userRepository) GetByEmail(c context.Context, email string) (domain.User, error) {
   collection := ur.database.Collection(ur.collection)
   var user domain.User
   err := collection.FindOne(c, bson.M{"email": email}).Decode(&user)
   return user, err
}
​
func (ur *userRepository) GetByID(c context.Context, id string) (domain.User, error) {
   collection := ur.database.Collection(ur.collection)
​
   var user domain.User
​
   idHex, err := primitive.ObjectIDFromHex(id)
   if err != nil {
      return user, err
   }
​
   err = collection.FindOne(c, bson.M{"_id": idHex}).Decode(&user)
   return user, err
}

3.5 数据层

./mongo/mongo.go

实现了 mongo.Database 接口，通过 mongoDatabase 结构体的两个方法可以获取对应的 Client 实例和 Collection 实例，从而操作数据库。

type mongoDatabase struct {
   db *mongo.Database
}
​
func (md *mongoDatabase) Collection(colName string) Collection {
    collection := md.db.Collection(colName)
    return &mongoCollection{coll: collection}
}
​
func (md *mongoDatabase) Client() Client {
    client := md.db.Client()
    return &mongoClient{cl: client}
}

四、单例与封装

查看 ./cmd/main.go 的路由绑定逻辑：route.Setup(env, timeout, db, gin)。

func Setup(env *bootstrap.Env, timeout time.Duration, db mongo.Database, gin *gin.Engine) {
   publicRouter := gin.Group("")
   // All Public APIs
   NewSignupRouter(env, timeout, db, publicRouter)
   NewLoginRouter(env, timeout, db, publicRouter)
   NewRefreshTokenRouter(env, timeout, db, publicRouter)
​
   protectedRouter := gin.Group("")
   // Middleware to verify AccessToken
   protectedRouter.Use(middleware.JwtAuthMiddleware(env.AccessTokenSecret))
   // All Private APIs
   NewProfileRouter(env, timeout, db, protectedRouter)
   NewTaskRouter(env, timeout, db, protectedRouter)
}

进一步查看 NewLoginRouter，会发现，在注册路由触发的 controller 方法的时候，已经将所需要的 db 创建出来，并且在数据层共享，同时防腐层、业务层、控制层的实例，在服务启动前创建，依次嵌套持有，因此所有的结构都是单例，且类似树形结构，依次串联。

func NewLoginRouter(env *bootstrap.Env, timeout time.Duration, db mongo.Database, group *gin.RouterGroup) {
   ur := repository.NewUserRepository(db, domain.CollectionUser)
   lc := &controller.LoginController{
      LoginUsecase: usecase.NewLoginUsecase(ur, timeout),
      Env:          env,
   }
   group.POST("/login", lc.Login)
}

通过这种方式，实现了资源的约束，使得开发者无法跨模块调用实例，导致循环依赖等安全问题。