goframe-v2

重要慣例

專案開發標準

• 對於完整專案（HTTP/微服務），請安裝 GoFrame CLI 並使用 gf init 建立專案骨架。詳情請參閱 專案建立 - init。
• 自動生成的程式碼檔案（dao、do、entity）不得手動建立或修改，遵循 GoFrame 慣例。
• 除非明確要求，否則請勿使用 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 會自動忽略：

  // 正確 - 使用 DO 物件
  dao.Users.Ctx(ctx).Where(cols.Id, id).Data(do.User{Uid: uid}).Update()
  
  // 正確 - 條件式欄位，未設定的欄位為 nil 且被忽略
  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()
  
  // 正確 - 使用 gdb.Raw 明確將欄位設為 NULL
  dao.Instances.Ctx(ctx).Where(cols.Id, id).Data(do.Instance{IdleSince: gdb.Raw("NULL")}).Update()
  
  // 錯誤 - 絕不應使用 g.Map 進行資料庫操作
  dao.Users.Ctx(ctx).Data(g.Map{cols.Uid: uid}).Update()
  

程式碼風格標準

• 變數宣告：定義多個變數時，使用 var 區塊將它們分組，以獲得更好的對齊和可讀性：

  // 正確 - 整齊且清晰
  var (
      authSvc       *auth.Service
      bizCtxSvc     *bizctx.Service
      k8sSvc        *svcK8s.Service
      notebookSvc   *notebook.Service
      middlewareSvc *middleware.Service
  )
  
  // 避免 - 分散的宣告
  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 會自動處理：

// 錯誤 - 多餘的手動時間設定
dao.User.Ctx(ctx).Data(do.User{
    Name:      "john",
    CreatedAt: gtime.Now(),  // 多餘！框架會處理
    UpdatedAt: gtime.Now(),  // 多餘！框架會處理
}).Insert()

// 正確 - 讓框架處理時間欄位
dao.User.Ctx(ctx).Data(do.User{
    Name: "john",
}).Insert()

2. 絕不手動加入 WhereNull(cols.DeletedAt) - GoFrame 會自動加入軟刪除過濾：

// 錯誤 - 多餘的軟刪除條件
dao.User.Ctx(ctx).
    Where(do.User{Status: 1}).
    WhereNull(cols.DeletedAt).  // 多餘！框架會自動加入
    Scan(&list)

// 正確 - 框架會自動加入 deleted_at IS NULL
dao.User.Ctx(ctx).
    Where(do.User{Status: 1}).
    Scan(&list)

3. 使用 Delete() 進行軟刪除 - 框架會轉換為 UPDATE SET deleted_at = NOW()：

// 正確 - 使用 Delete()，框架處理軟刪除
dao.User.Ctx(ctx).Where(do.User{Id: id}).Delete()
// 實際 SQL：UPDATE `sys_user` SET `deleted_at`=NOW() WHERE `id`=?

// 錯誤 - 手動 Update 設定 deleted_at
dao.User.Ctx(ctx).
    Where(do.User{Id: id}).
    Data(do.User{DeletedAt: gtime.Now()}).  // 多餘！
    Update()

欄位類型支援

deleted_at 欄位支援多種類型：

• DateTime/Timestamp：預設，儲存刪除時間
• Integer：儲存 Unix 時間戳（秒）
• Boolean：儲存 0/1 表示刪除狀態

設定（可選）

時間欄位名稱可在 config.yaml 中自訂：

database:
  default:
    createdAt: "created_at"   # 自訂欄位名稱
    updatedAt: "updated_at"
    deletedAt: "deleted_at"
    timeMaintainDisabled: false  # 設為 true 可停用此功能

GoFrame 文件

完整的 GoFrame 開發資源，涵蓋元件設計、使用、最佳實踐和注意事項：GoFrame 文件

GoFrame 程式碼範例

豐富的實用程式碼範例，涵蓋 HTTP 服務、gRPC 服務和各種專案類型：GoFrame 範例