註解語法

註解是介面方法中的註解，Gen 會剖析它們並為套用的結構產生查詢 API。

Gen 提供一些慣例，以支援動態條件式 SQL，讓我們從三個面向來介紹它們

傳回結果
範本佔位符
範本運算式

傳回結果

Gen 允許設定傳回結果類型，目前支援下列四種基本類型

選項	說明
gen.T	傳回結構
gen.M	傳回對應
gen.RowsAffected	傳回資料庫傳回的受影響列數 (類型：int64)
error	傳回任何錯誤 (如有)

例如

type Querier interface {
  // SELECT * FROM @@table WHERE id=@id
  GetByID(id int) (gen.T, error) // returns struct and error

  // SELECT * FROM @@table WHERE id=@id
  GetByID(id int) gen.T // returns data as struct

  // SELECT * FROM @@table WHERE id=@id
  GetByID(id int) (gen.M, error) // returns map and error

   // INSERT INTO @@table (name, age) VALUES (@name, @age)
  InsertValue(name string, age int) (gen.RowsAffected, error) // returns affected rows count and error
}

這些基本類型可以與其他符號結合使用，例如 *、[]，例如

type Querier interface {
  // SELECT * FROM @@table WHERE id=@id
  GetByID(id int) (*gen.T, error) // returns data as pointer and error

  // SELECT * FROM @@table WHERE id=@id
  GetByID(id int) (*[]gen.T, error) // returns data as pointer of slice and error

  // SELECT * FROM @@table WHERE id=@id
  GetByID(id int) ([]*gen.T, error) // returns data as slice of pointer and error

  // SELECT * FROM @@table WHERE id=@id
  GetByID(id int) ([]gen.M, error) // returns data as slice of map and error
}

範本佔位符

Gen 提供一些佔位符，以產生動態且安全的 SQL

名稱	說明
`@@table`	轉譯並加上引號的資料表名稱
`@@<name>`	從參數中轉譯並加上引號的資料表/欄位名稱
`@<name>`	從參數中取得 SQL 查詢參數

例如

type Filter interface {
  // SELECT * FROM @@table WHERE @@column=@value
  FilterWithColumn(column string, value string) (gen.T, error)
}

// Apply the `Filter` interface to `User`, `Company`
g.ApplyInterface(func(Filter) {}, model.User{}, model.Company{})

產生程式碼後，您可以在應用程式中像這樣使用它。

import "your_project/query"

func main() {
  user, err := query.User.FilterWithColumn("name", "jinzhu")
  // similar like db.Exec("SELECT * FROM `users` WHERE `name` = ?", "jinzhu")

  company, err := query.Company.FilterWithColumn("name", "tiktok")
  // similar like db.Exec("SELECT * FROM `companies` WHERE `name` = ?", "tiktok")
}

範本運算式

Gen 提供強大的運算式支援，以支援動態條件式 SQL，目前支援下列運算式

if/else
where
設定
迴圈

`if/else`

if/else 表達式允許將 golang 語法用作條件，它可以寫成

{{if cond1}}
  // do something here
{{else if cond2}}
  // do something here
{{else}}
  // do something here
{{end}}

例如

type Querier interface {
  // SELECT * FROM users WHERE
  //  {{if name !=""}}
  //      username=@name AND
  //  {{end}}
  //  role="admin"
  QueryWith(name string) (gen.T,error)
}

更複雜的案例

type Querier interface {
  // SELECT * FROM users
  //  {{if user != nil}}
  //      {{if user.ID > 0}}
  //          WHERE id=@user.ID
  //      {{else if user.Name != ""}}
  //          WHERE username=@user.Name
  //      {{end}}
  //  {{end}}
  QueryWith(user *gen.T) (gen.T, error)
}

如何使用

query.User.QueryWith(&User{Name: "zhangqiang"})
// SELECT * FROM users WHERE username="zhangqiang"

`where`

where 表達式讓您更容易為 SQL 查詢撰寫 WHERE 子句，以下是一個簡單的範例

type Querier interface {
  // SELECT * FROM @@table
  //  {{where}}
  //      id=@id
  //  {{end}}
  Query(id int) gen.T
}

使用產生的程式碼，您可以像這樣使用

query.User.Query(10)
// SELECT * FROM users WHERE id=10

以下是另一個複雜的案例，在這個案例中，您將學習 WHERE 子句只有在有任何子表達式相符時才會插入，並且它可以智慧地修剪 where 子句中的不必要的 and、or、xor、,。

type Querier interface {
  // SELECT * FROM @@table
  //  {{where}}
  //    {{if !start.IsZero()}}
  //      created_time > @start
  //    {{end}}
  //    {{if !end.IsZero()}}
  //      AND created_time < @end
  //    {{end}}
  //  {{end}}
  FilterWithTime(start, end time.Time) ([]gen.T, error)
}

產生的程式碼可以使用像這樣

var (
  since = time.Date(2022, 10, 1, 0, 0, 0, 0, time.UTC)
  end   = time.Date(2022, 10, 10, 0, 0, 0, 0, time.UTC)
  zero  = time.Time{}
)

query.User.FilterWithTime(since, end)
// SELECT * FROM `users` WHERE created_time > "2022-10-01" AND created_time < "2022-10-10"

query.User.FilterWithTime(since, zero)
// SELECT * FROM `users` WHERE created_time > "2022-10-01"

query.User.FilterWithTime(zero, end)
// SELECT * FROM `users` WHERE created_time < "2022-10-10"

query.User.FilterWithTime(zero, zero)
// SELECT * FROM `users`

`set`

set 表達式用於為 SQL 查詢產生 SET 子句，它會自動修剪不必要的 ,，例如

// UPDATE @@table
//  {{set}}
//    {{if user.Name != ""}} username=@user.Name, {{end}}
//    {{if user.Age > 0}} age=@user.Age, {{end}}
//    {{if user.Age >= 18}} is_adult=1 {{else}} is_adult=0 {{end}}
//  {{end}}
// WHERE id=@id
Update(user gen.T, id int) (gen.RowsAffected, error)