使用Golang创建RESTful API的最佳实践案例

以下创建一个 REST API 应用的最佳实践

库包：

Gin for HTTP
gorm for ORM
viper for configuration
zap for logging
testify for testing
go2hal for HAL
problem for problem JSON
validator for validation
sqlmock for SQL mocking

模型
使用ORM模型，在本例中，gorm使用该模型将结构转换为 SQL 语句。例如：

type Workspace struct {
  ID        uuid.UUID      `gorm:"type:uuid;default:uuid_generate_v4()" json:"id"`
  Name      string         `gorm:"not null,type:text" json:"name"`
  CreatedAt time.Time      `gorm:"autoCreateTime" json:"created_at"`
  UpdatedAt time.Time      `gorm:"autoUpdateTime" json:"updated_at"`
  DeletedAt gorm.DeletedAt `gorm:"index,->" json:"-"`
}

ID用作主键，使用随机 UUID 而不是自增整数。
name是模型的一个属性，它可以是任何名称下的任何有限数量的东西。
创建模型时的CreatedAt由 gorm 自动处理。
UpdatedAt模型更新时，由 gorm 自动处理。
DeletedAt这是 gorm 处理软删除的方式。它需要是 gorm.DeletedAt 的类型

存储库
存储库是一种设计模式，可以帮助我们进行CRUD操作。

我们先定义一个接口：

type Repository interface {
  Configure(*gorm.DB)
  List(after time.Time, limit int) (any, error)
  Get(id any) (any, error)
  Create(entity any) (any, error)
  Update(id any, entity any) (bool, error)
  Delete(id any) (bool, error)
}

然后他们使用 gorm 作为 ORM 的实现：

func (repository *WorkspaceRepository) List(after time.Time, limit int) (any, error) {
  var wc model.WorkspaceCollection
  order := "created_at"
  err := r.db.Limit(limit).Order(order).Where(fmt.Sprintf("%v > ?", order), after).Limit(limit).Find(&wc).Error

  return wc, err
}

func (repository *WorkspaceRepository) Get(id any) (any, error) {
  var w *model.Workspace

  err := r.db.Where("id = ?", id).First(&w).Error

  return w, err
}

func (repository *WorkspaceRepository) Create(entity any) (any, error) {
  w := entity.(*model.Workspace)

  err := r.db.Create(w).Error

  return w, err
}

func (repository *WorkspaceRepository) Update(id any, entity any) (bool, error) {
  w := entity.(*model.Workspace)

  if err := r.db.Model(w).Where("id = ?", id).Updates(w).Error; err != nil {
    return false, err
  }

  return true, nil
}

func (repository *WorkspaceRepository) Delete(id any) (bool, error) {
  if err := r.db.Delete(&model.Workspace{}, "id = ?", id).Error; err != nil {
    return false, err
  }

  return true, nil
}

路由
为了处理 HTTP 路由，我们需要创建一些称为控制器的函数，在这个例子中，使用了Gin。

func (server *Server) registerRoutes() {
  var router = server.router

  workspaces := router.Group("/workspaces")
  {
    workspaces.GET("", GetWorkspaces)
    workspaces.POST("", CreateWorkspace)
    workspaces.GET("/:uuid", GetWorkspace)
    workspaces.PATCH("/:uuid", UpdateWorkspace)
    workspaces.DELETE("/:uuid", DeleteWorkspace)
  }
}

控制器
控制器负责处理 HTTP 调用并返回有用的信息，这些信息可以是带有来自 ORM 的对象的 JSON 或错误。让我们实现所有的 CRUD 操作：

func GetWorkspaceRepository(ctx *gin.Context) repository.Repository {
  return ctx.MustGet("RepositoryRegistry").(*repository.RepositoryRegistry).MustRepository("WorkspaceRepository")
}

func GetWorkspaces(ctx *gin.Context) {
  var q = query{}

  if err := ctx.ShouldBindQuery(&q); err != nil {
    HandleError(err, ctx)
    return
  }

  entities, err := GetWorkspaceRepository(ctx).List(q.After, q.Limit)
  if err != nil {
    HandleError(err, ctx)
    return
  }

  WriteHAL(ctx, http.StatusOK, entities.(model.WorkspaceCollection).ToHAL(ctx.Request.URL.Path, ctx.Request.URL.Query()))
}

func GetWorkspace(ctx *gin.Context) {
  p := params{}

  ctx.ShouldBindUri(&p)

  if err := validate.Struct(p); err != nil {
    HandleError(err, ctx)
    return
  }

  entity, err := GetWorkspaceRepository(ctx).Get(p.ID)
  if err != nil {
    HandleError(err, ctx)
    return
  }

  WriteHAL(ctx, http.StatusOK, entity.(*model.Workspace).ToHAL(ctx.Request.URL.Path))
}

func CreateWorkspace(ctx *gin.Context) {
  body := model.Workspace{}

  if err := ctx.BindJSON(&body); err != nil {
    HandleError(err, ctx)
    return
  }

  entity, err := GetWorkspaceRepository(ctx).Create(&body)
  if err != nil {
    HandleError(err, ctx)
    return
  }

  workspace := entity.(*model.Workspace)
  selfHref, _ := url.JoinPath(ctx.Request.URL.Path, workspace.ID.String())
  WriteHAL(ctx, http.StatusCreated, workspace.ToHAL(selfHref))
}

func UpdateWorkspace(ctx *gin.Context) {
  p := params{}

  ctx.ShouldBindUri(&p)

  if err := validate.Struct(p); err != nil {
    HandleError(err, ctx)
    return
  }

  body := model.Workspace{}

  if err := ctx.BindJSON(&body); err != nil {
    HandleError(err, ctx)
    return
  }

  repository := GetWorkspaceRepository(ctx)

  _, err := repository.Update(p.ID, &body)
  if err != nil {
    HandleError(err, ctx)
    return
  }

  entity, err := repository.Get(p.ID)
  if err != nil {
    HandleError(err, ctx)
    return
  }

  WriteHAL(ctx, http.StatusOK, entity.(*model.Workspace).ToHAL(ctx.Request.URL.Path))
}

func DeleteWorkspace(ctx *gin.Context) {
  p := params{}

  ctx.ShouldBindUri(&p)

  if err := validate.Struct(p); err != nil {
    HandleError(err, ctx)
    return
  }

  _, err := GetWorkspaceRepository(ctx).Delete(p.ID)
  if err != nil {
    HandleError(err, ctx)
    return
  }

  WriteNoContent(ctx)
}

HAL 链接
API 是永恒的。一旦将 API 集成到生产应用程序中，就很难进行可能破坏现有集成的重大更改
Web API 设计原则：使用 API 和微服务交付价值
在实践中，很难打破 API 契约，因为 API 使用者会生你的气。新版本的 API 不实用；没有人会转移到另一个 API。
考虑到这一点，正式名称为 JSON 超文本应用程序语言的HAL Links尝试以一种没有痛苦的方式解决 API 迁移。API 应该在self字段中返回资源的表示，而不是对资源使用硬编码的位置。

{
  "_links": {
    "self": "/workspaces/6424f2b7-8094-48de-a68c-24bbb7de1faa"
  }
}

...

实现非常简单：

func (model *Workspace) ToHAL(selfHref string) (root hal.Resource) {
  root = hal.NewResourceObject()
  root.AddData(model)

  selfRel := hal.NewSelfLinkRelation()
  selfLink := &hal.LinkObject{Href: selfHref}
  selfRel.SetLink(selfLink)
  root.AddLink(selfRel)

  return
}

问题
你可能已经注意到每个错误都会调用HandleError函数，这个函数负责通过返回application/problem+json将错误变成更有意义的东西。

func HandleError(err error, ctx *gin.Context) {
  var p *problem.Problem

  switch {
  case errors.Is(err, gorm.ErrRecordNotFound):
    p = problem.New(
      problem.Title("Record Not Found"),
      problem.Type("errors:database/record-not-found"),
      problem.Detail(err.Error()),
      problem.Status(http.StatusNotFound),
    )
    break
  default:
    p = problem.New(
      problem.Title("Bad Request"),
      problem.Type("errors:http/bad-request"),
      problem.Detail(err.Error()),
      problem.Status(http.StatusBadRequest),
    )
    break
  }

  p.WriteTo(ctx.Writer)
}

例如，如果after参数不是RFC 3339的格式。它将返回一个错误

$ http localhost:8000/workspaces?after=0
HTTP/1.1 400 Bad Request
Content-Length: 164
Content-Type: application/problem+json
Date: Sat, 30 Jul 2022 18:23:54 GMT
{
    "detail": "parsing time \Ŕ\" as \񓟶-01-02T15:04:05Z07:00\": cannot parse \Ŕ\" as \񓟶\"",
    "status": 400,
    "title": "Bad Request",
    "type": "errors:http/bad-request"
}

注意Content-Type，它是HTTP APIs的问题细节的mimetype，正文中有一个详细的错误。

Full example