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 の例