重要な慣例

プロジェクト開発標準

• 完全なプロジェクト(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`=?

// 誤り - deleted_at を使用した手動 Update
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 Documentation

GoFrame コード例

HTTP サービス、gRPC サービス、および様々なプロジェクトタイプをカバーする豊富な実用的なコード例: GoFrame Examples