goframe-v2

重要约定

项目开发规范

• 对于完整项目（HTTP／微服务），请安装 GoFrame CLI，并使用 gf init 创建项目脚手架。详情请参阅项目创建 - init。
• 按照 GoFrame 约定，自动生成的代码文件（dao、do、entity）不得手动创建或修改。
• 除非明确要求，否则不要使用 logic/ 目录处理业务逻辑。请直接在 service/ 目录中实现业务逻辑。
• 完整项目示例参考：
  • HTTP 服务最佳实践：user-http-service
  • gRPC 服务最佳实践：user-grpc-service

组件使用规范

• 创建新方法或变量前，先检查其他位置是否已有相应实现，并复用现有实现。
• 所有错误处理都使用 gerror 组件，以确保完整的堆栈跟踪，便于追溯。
• 探索新组件时，优先使用 GoFrame 内置组件，并参考示例中的最佳实践代码。
• 数据库操作必须使用 DO 对象（internal/model/do/），不得使用 g.Map 或 map[string]interface{}。DO 结构体字段类型为 interface{}；未设置的字段保持 nil，ORM 会自动忽略：

  // Good - use DO object
  dao.Users.Ctx(ctx).Where(cols.Id, id).Data(do.User{Uid: uid}).Update()
  
  // Good - conditional fields, unset fields are nil and ignored
  data := do.User{}
  if password != "" { data.PasswordHash = hash }
  if isAdmin != nil { data.IsAdmin = *isAdmin }
  dao.Users.Ctx(ctx).Where(cols.Id, id).Data(data).Update()
  
  // Good - explicitly set a column to NULL using gdb.Raw
  dao.Instances.Ctx(ctx).Where(cols.Id, id).Data(do.Instance{IdleSince: gdb.Raw("NULL")}).Update()
  
  // Bad - never use g.Map for database operations
  dao.Users.Ctx(ctx).Data(g.Map{cols.Uid: uid}).Update()
  

代码风格规范

• 变量声明：定义多个变量时，使用 var 块进行分组，以提高对齐性和可读性：

  // Good - aligned and clean
  var (
      authSvc       *auth.Service
      bizCtxSvc     *bizctx.Service
      k8sSvc        *svcK8s.Service
      notebookSvc   *notebook.Service
      middlewareSvc *middleware.Service
  )
  
  // Avoid - scattered declarations
  authSvc := auth.New()
  bizCtxSvc := bizctx.New()
  k8sSvc := svcK8s.New()
  

• 同一作用域中有 3 个或更多相关变量声明时，使用此模式。

软删除与时间维护

GoFrame 提供自动软删除和时间维护功能。表中包含 created_at、updated_at 或 deleted_at 字段时，ORM 会自动处理这些字段。

自动时间字段

字段	自动行为
created_at	在 Insert/InsertAndGetId 时自动写入，之后不会再修改
updated_at	在 Insert/Update/Save 时自动写入
deleted_at	在 Delete 时自动写入（软删除），查询时自动过滤

重要规则

1. 切勿手动设置时间字段——GoFrame 会自动处理：

// WRONG - redundant manual time setting
dao.User.Ctx(ctx).Data(do.User{
    Name:      "john",
    CreatedAt: gtime.Now(),  // REDUNDANT! Framework handles this
    UpdatedAt: gtime.Now(),  // REDUNDANT! Framework handles this
}).Insert()

// CORRECT - let framework handle time fields
dao.User.Ctx(ctx).Data(do.User{
    Name: "john",
}).Insert()

2. 切勿手动添加 WhereNull(cols.DeletedAt)——GoFrame 会自动添加软删除过滤条件：

// WRONG - redundant soft delete condition
dao.User.Ctx(ctx).
    Where(do.User{Status: 1}).
    WhereNull(cols.DeletedAt).  // REDUNDANT! Framework auto-adds this
    Scan(&list)

// CORRECT - framework auto-adds deleted_at IS NULL
dao.User.Ctx(ctx).
    Where(do.User{Status: 1}).
    Scan(&list)

3. 使用 Delete() 进行软删除——框架会将其转换为 UPDATE SET deleted_at = NOW()：

// CORRECT - use Delete(), framework handles soft delete
dao.User.Ctx(ctx).Where(do.User{Id: id}).Delete()
// Actual SQL: UPDATE `sys_user` SET `deleted_at`=NOW() WHERE `id`=?

// WRONG - manual Update with deleted_at
dao.User.Ctx(ctx).
    Where(do.User{Id: id}).
    Data(do.User{DeletedAt: gtime.Now()}).  // REDUNDANT!
    Update()

字段类型支持

deleted_at 字段支持多种类型：

• DateTime/Timestamp：默认类型，用于存储删除时间
• Integer：存储 Unix 时间戳（秒）
• Boolean：使用 0/1 表示删除状态

配置（可选）

可在 config.yaml 中自定义时间字段名称：

database:
  default:
    createdAt: "created_at"   # Custom field name
    updatedAt: "updated_at"
    deletedAt: "deleted_at"
    timeMaintainDisabled: false  # Set true to disable this feature

GoFrame 文档

涵盖组件设计、使用方法、最佳实践和注意事项的完整 GoFrame 开发资源：GoFrame 文档

GoFrame 代码示例

涵盖 HTTP 服务、gRPC 服务和各种项目类型的丰富实用代码示例：GoFrame 示例