ent orm筆記2---schema使用(上)

syncd發表於2020-08-27

在上一篇關於快速使用ent orm的筆記中，我們再最開始使用entc init User 建立schema，在ent orm 中的schema 其實就是資料庫模型，在schema中我們可以通過Fields 定義資料庫中表的欄位資訊；通過Edges 定義表之間的關係資訊；通過Index 定義欄位的索引資訊等等，這篇文章會整理一下關於ent orm 中如何使用這些。

備註：文章中的所有程式碼在github.com/peanut-cc/ent_orm_notes

Fileds

當我們執行 entc init User 之後，會在當前目錄下生成一個ent目錄，在該目錄下有一個schema目錄，預設情況下schema/user.go檔案如下：

package schema

import "github.com/facebook/ent"

// User holds the schema definition for the User entity.
type User struct {
	ent.Schema
}

// Fields of the User.
func (User) Fields() []ent.Field {
	return nil
}

// Edges of the User.
func (User) Edges() []ent.Edge {
	return nil
}

如果要對user 這表新增欄位，需要在Fileds方法中新增如下所示：

// Fields of the User.
func (User) Fields() []ent.Field {
	return []ent.Field{
		field.Int("age"),
		field.String("username").
			Unique(),
		field.Time("created_at").
			Default(time.Now),
		field.Float32("salary").
			Optional(),
	}
}

注意：預設情況下，所有欄位都是必填欄位，可以使用Optional方法將其設定為optional。

資料型別

下面的資料型別都是支援的：

All Go numeric types. Like int, uint8, float64, etc.
bool
string
time.Time
[]byte (only supported by SQL dialects).
JSON (only supported by SQL dialects).
Enum (only supported by SQL dialects).

// Fields of the User.
func (User) Fields() []ent.Field {
	return []ent.Field{
		field.Int("age"),
		field.String("username").
			Unique(),
		field.Time("created_at").
			Default(time.Now),
		field.Float32("salary").
			Optional(),
		field.Bool("active").
			Default(false),
		field.JSON("strings", []string{}).
			Optional(),
		field.Enum("state").
			Values("on", "off").
			Optional(),
	}
}

ID欄位

資料庫表的id欄位，預設是內建的，不需要單獨新增，其型別預設為int, 並在資料庫中自動遞增，

為了將id配置為在所有表中唯一，需要在schema migration的時候使用WithGlobalUniqueID

如果需要對id欄位進行其他配置，或者想要使用UUID格式存id，則需要覆蓋id的配置。

// Fields of the User.
func (User) Fields() []ent.Field {
	return []ent.Field{
		field.Int("id").
			StructTag(`json:"oid,omitempty"`),
	}
}

// Fields of the User.
func (User) Fields() []ent.Field {
	return []ent.Field{
		field.UUID("id", uuid.UUID{}),
	}
}

// Fields of the User.
func (User) Fields() []ent.Field {
	return []ent.Field{
		field.String("id").
			MaxLen(25).
			NotEmpty().
			Unique().
			Immutable(),
	}
}

資料庫型別

每個資料庫都有自己的從go的資料型別到資料庫型別的對映，例如，Mysql 在資料庫中將float64欄位建立為雙精度的。ent orm 有一個選項引數可以使用SchemaType 方法覆蓋預設行為

// Fields of the Card.
func (Card) Fields() []ent.Field {
	return []ent.Field{
		field.Float("amount").
			SchemaType(map[string]string{
				dialect.MySQL:    "decimal(6,2)", // Override MySQL.
				dialect.Postgres: "numeric",      // Override Postgres.
			}),
	}
}

GO Type

欄位的預設型別是基本的Go資料型別，例如，對於字串欄位，型別為string, 對於時間欄位，型別為time.Time

GoType 方法提供了一個選項，可以使用自定義型別替換預設的ent型別。但自定義型別必須是可以轉換為Go的基本型別的型別，或者實現了ValueScanner介面的型別

// Fields of the Card.
func (Card) Fields() []ent.Field {
	return []ent.Field{
		field.Float("amount").
			GoType(Amount(0)),
		field.String("name").
			Optional().
            // A ValueScanner type.
			GoType(&sql.NullString{}),
	}
}

Default Values 預設值

Non-unique 的欄位可以通過Default 和 UpdateDefault方法設定預設值

// Fields of the Group.
func (Group) Fields() []ent.Field {
	return []ent.Field{
		field.Time("created_at").
			Default(time.Now),
		field.Time("updated_at").
			Default(time.Now).
			UpdateDefault(time.Now),
	}
}

Validators

關於欄位的validator是通過 func(T) error 函式，該函式使用Validate方法在schema中定義，並在建立或更新schema的時候應用於欄位的校驗

欄位的validator支援的型別有string 和所有的數字型別

// Fields of the Group.
func (Group) Fields() []ent.Field {
	return []ent.Field{
		field.String("name").
			Match(regexp.MustCompile("[a-zA-Z_]+$")).
			Validate(func(s string) error {
				if strings.ToLower(s) == s {
					return errors.New("group name must begin with uppercase")
				}
				return nil
			}),
	}
}

內建的 Validators

ent orm 提供了一些內建的validators, 如下：

Numeric types:
Positive() - Positive adds a minimum value validator with the value of 1
Negative() - Negative adds a maximum value validator with the value of -1
NonNegative() - NonNegative adds a minimum value validator with the value of 0
Min(i) - Validate that the given value is > i.
Max(i) - Validate that the given value is < i.
Range(i, j) - Validate that the given value is within the range [i, j].
string:

MinLen(i)
MaxLen(i)
Match(regexp.Regexp)

Optional 可選欄位

可選欄位是在建立的時候不是必傳的欄位，並將在資料庫設定為可為空的欄位
預設情況下，欄位都是必填欄位

Nillable

有時候你可能希望區分欄位的零值和nil，如資料庫的某列包含0 或者NULL,Nillable選項正是為此而存在的.

如果有一個型別為T的欄位設定為Nillable ，在通過go generate 生成程式碼的時候的時候生成的struct 中改欄位的型別是*T, 如果資料庫中該欄位是NULL，那麼在ent orm的查詢結果中就是nil, 否則對於沒有設定Nillable的欄位，如果資料庫中欄位的值是NULl，返回的則是改欄位的零值

// Fields of the User.
func (User) Fields() []ent.Field {
	return []ent.Field{
		field.String("required_name"),
		field.String("optional_name").Optional(),
		field.String("nilable_name").Optional().Nillable(),
		field.String("nilable_name2").Optional().Nillable(),
		field.Int("age").Optional(),
		field.Int("age2").Optional().Nillable(),
	}
}

我們通過如下程式碼進行資料的建立和查詢，這裡分別建立了兩條資料，第一條資料的設定SetOptionalName，SetNilableName 的欄位都沒有設定內容，第二次的時候都設定了內容

package main

import (
	"context"
	"log"

	"github.com/peanut-cc/ent_orm_notes/schema_notes/ent/user"

	_ "github.com/go-sql-driver/mysql"
	"github.com/peanut-cc/ent_orm_notes/schema_notes/ent"
)

func main() {
	client, err := ent.Open("mysql", "root:123456@tcp(10.211.55.3:3306)/schema_notes?parseTime=True")
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
	ctx := context.Background()
	// run the auto migration tool
	if err := client.Schema.Create(ctx); err != nil {
		log.Fatalf("failed creating schema resources:%v", err)
	}
	client.User.Create().SetRequiredName("peanut").Save(ctx)
	client.User.Create().SetRequiredName("syncd").
		SetOptionalName("option_name").
		SetNilableName("nil_name").
		SetNilableName2("nil_name2").
		SetAge(18).
		SetAge2(20).
		SaveX(ctx)
	u := client.User.Query().Where(user.RequiredNameEQ("peanut")).OnlyX(ctx)
	log.Printf("required_name is:%v option_name is:%v nil_name is:%v nil_name2 is:%v age is :%v age2 is:%v\n", u.RequiredName,
		u.OptionalName, u.NilableName, u.NilableName2, u.Age, u.Age2)
	u2 := client.User.Query().Where(user.RequiredNameEQ("syncd")).OnlyX(ctx)
	log.Printf("required_name is:%v option_name is:%v nil_name is:%v nil_name2 is:%v age is :%v age2 is:%v\n", u2.RequiredName,
		u2.OptionalName, u2.NilableName, u2.NilableName2, u2.Age, u2.Age2)
}

下面是資料的列印結果：

2020/08/26 20:39:47 required_name is:peanut option_name is: nil_name is:<nil> nil_name2 is:<nil> age is :0 age2 is:<nil>
2020/08/26 20:39:47 required_name is:syncd option_name is:option_name nil_name is:0xc000200580 nil_name2 is:0xc000200590 age is :18 age2 is:0xc00020c4d8

Immutable 不可變欄位

不可變欄位，是隻能在建立的時候設定值

// Fields of the user.
func (User) Fields() []ent.Field {
    return []ent.Field{
        field.String("name"),
        field.Time("created_at").
            Default(time.Now).
            Immutable(),
    }
}

Uniqueness 唯一索引

可以使用Unique方法給欄位設定唯一索引。注意：唯一所以欄位不能具有預設值

// Fields of the user.
func (User) Fields() []ent.Field {
    return []ent.Field{
        field.String("name"),
        field.String("nickname").
            Unique(),
    }
}

Storage Key

可以使用StorageKey方法配置自定義儲存名稱。在SQL中對映為列名

// Fields of the user.
func (User) Fields() []ent.Field {
    return []ent.Field{
        field.String("name").
            StorageKey(`old_name"`),
    }
}

Indexes 索引

可以在多個欄位和一些關係表中建立索引

Struct Tags

可以使用StructTag方法將自定義struct tag新增到生成的實體中。
請注意，如果未提供此選項，或者提供的該選項不包含json標記，則預設json標記將與欄位名稱一起新增。

// Fields of the user.
func (User) Fields() []ent.Field {
    return []ent.Field{
        field.String("name").
            StructTag(`gqlgen:"gql_name"`),
    }
}

Sensitive Fields

可以使用Sensitive方法將字串欄位定義為Sensitive Fields。
Sensitive Fields不會被列印，並且在編碼時將被忽略。
請注意，Sensitive Fields不能具有struct標記。

// Fields of the user.
func (User) Fields() []ent.Field {
    return []ent.Field{
        field.String("password").
            Sensitive(),
    }
}

Annotations

在程式碼生成中，Annotations用於將任意後設資料附加到欄位物件。模板擴充套件可以檢索這個後設資料並在它們的模板中使用它。注意，後設資料物件必須可序列化為 JSON 原始值(例如，struct、 map 或 slice)。

// Fields of the user.
func (User) Fields() []ent.Field {
    return []ent.Field{
        field.Time("creation_date").
            Annotations(entgql.Annotation{
                OrderField: "CREATED_AT",
            }),
    }
}

Edges

快速使用

Edges 也理解為表之間的association,通常指的我們表之間的一對多，多對多關係等。

er-group-users

ent/schema/pet.go

package schema

import (
	"github.com/facebook/ent"
	"github.com/facebook/ent/schema/edge"
	"github.com/facebook/ent/schema/field"
)

// Pet holds the schema definition for the Pet entity.
type Pet struct {
	ent.Schema
}

// Fields of the Pet.
func (Pet) Fields() []ent.Field {
	return []ent.Field{
		field.String("name"),
	}
}

// Edges of the Pet.
func (Pet) Edges() []ent.Edge {
	return []ent.Edge{
		edge.From("owner", User.Type).
			Ref("pets").
			Unique(),
	}
}

ent/schema/user.go

package schema

import (
	"github.com/facebook/ent"
	"github.com/facebook/ent/schema/edge"
	"github.com/facebook/ent/schema/field"
)

// User holds the schema definition for the User entity.
type User struct {
	ent.Schema
}

// Fields of the User.
func (User) Fields() []ent.Field {
	return []ent.Field{
		field.String("name"),
		field.Int("age"),
	}
}

// Edges of the User.
func (User) Edges() []ent.Edge {
	return []ent.Edge{
		edge.To("pets", Pet.Type),
		edge.From("groups", Group.Type).Ref("users"),
	}
}

ent/schema/group.go

package schema

import (
	"github.com/facebook/ent"
	"github.com/facebook/ent/schema/edge"
	"github.com/facebook/ent/schema/field"
)

// Group holds the schema definition for the Group entity.
type Group struct {
	ent.Schema
}

// Fields of the Group.
func (Group) Fields() []ent.Field {
	return []ent.Field{
		field.String("name"),
	}
}

// Edges of the Group.
func (Group) Edges() []ent.Edge {
	return []ent.Edge{
		edge.To("users", User.Type),
	}
}

在上面的關係中，一個使用者可以有多個寵物，但是一個寵物只能屬於一個使用者。所以這裡對於寵物來說是一對一的關係，對於使用者來說是多對一關係。

我們檢視一下建立的pets表的資訊：

CREATE TABLE `pets` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT,
  `name` varchar(255) COLLATE utf8mb4_bin NOT NULL,
  `user_pets` bigint(20) DEFAULT NULL,
  PRIMARY KEY (`id`),
  KEY `pets_users_pets` (`user_pets`),
  CONSTRAINT `pets_users_pets` FOREIGN KEY (`user_pets`) REFERENCES `users` (`id`) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin

因為在上述關係中：使用者和寵物之間是一對多關係，所以這裡使用的edge.To;

而對寵物來說是一對一的關係，所以這裡使用edge.From的Ref

edge.To和edge.From 是建立表關係的兩個方法

一對一關係

er-user-card

在這個例子中，設定一個使用者只能有一張信用卡，而一個信用卡也只能屬於一個使用者。

ent/schema/user.go

package schema

import (
   "github.com/facebook/ent"
   "github.com/facebook/ent/schema/edge"
   "github.com/facebook/ent/schema/field"
)

// User holds the schema definition for the User entity.
type User struct {
   ent.Schema
}

// Fields of the User.
func (User) Fields() []ent.Field {
   return []ent.Field{
      field.String("name"),
      field.Int("age"),
   }
}

// Edges of the User.
func (User) Edges() []ent.Edge {
   return []ent.Edge{
      edge.To("card", Card.Type).Unique(),
   }
}

ent/schema/card.go

package schema

import (
   "github.com/facebook/ent"
   "github.com/facebook/ent/schema/edge"
   "github.com/facebook/ent/schema/field"
)

// Card holds the schema definition for the Card entity.
type Card struct {
   ent.Schema
}

// Fields of the Card.
func (Card) Fields() []ent.Field {
   return []ent.Field{
      field.String("number"),
      field.Time("expired"),
   }
}

// Edges of the Card.
func (Card) Edges() []ent.Edge {
   return []ent.Edge{
      edge.From("owner", User.Type).
         Ref("card").
         Unique().
         // We add the "Required" method to the builder
         // to make this edge required on entity creation.
         // i.e. Card cannot be created without its owner.
         Required(),
   }
}

一對多關係

er-user-pets

在這個例子中使用者和寵物之間是一對多關係，每個使用者可以有多個寵物，一個寵物只有一個主人

ent/schema/user.go

package schema

import (
   "github.com/facebook/ent"
   "github.com/facebook/ent/schema/edge"
   "github.com/facebook/ent/schema/field"
)

// User holds the schema definition for the User entity.
type User struct {
   ent.Schema
}

// Fields of the User.
func (User) Fields() []ent.Field {
   return []ent.Field{
      field.String("name"),
   }
}

// Edges of the User.
func (User) Edges() []ent.Edge {
   return []ent.Edge{
      edge.To("pets", Pet.Type),
   }
}

ent/schema/pet.go

package schema

import (
   "github.com/facebook/ent"
   "github.com/facebook/ent/schema/edge"
   "github.com/facebook/ent/schema/field"
)

// Pet holds the schema definition for the Pet entity.
type Pet struct {
   ent.Schema
}

// Fields of the Pet.
func (Pet) Fields() []ent.Field {
   return []ent.Field{
      field.String("name"),
   }
}

// Edges of the Pet.
func (Pet) Edges() []ent.Edge {
   return []ent.Edge{
      edge.From("owner", User.Type).
         Ref("pets").
         Unique(),
   }
}

相關的查詢如下程式碼：

package main

import (
   "context"
   "fmt"
   "log"

   _ "github.com/go-sql-driver/mysql"

   "github.com/peanut-cc/ent_orm_notes/one_to_many/ent"
)

func main() {
   client, err := ent.Open("mysql", "root:123456@tcp(192.168.1.100:3306)/one_to_one?parseTime=True")
   if err != nil {
      log.Fatal(err)
   }
   defer client.Close()
   ctx := context.Background()
   // run the auto migration tool
   if err := client.Schema.Create(ctx); err != nil {
      log.Fatalf("failed creating schema resources:%v", err)
   }
   Do(ctx, client)
}

func Do(ctx context.Context, client *ent.Client) error {
   // Create the 2 pets.
   pedro, err := client.Pet.
      Create().
      SetName("pedro").
      Save(ctx)
   if err != nil {
      return fmt.Errorf("creating pet: %v", err)
   }
   lola, err := client.Pet.
      Create().
      SetName("lola").
      Save(ctx)
   if err != nil {
      return fmt.Errorf("creating pet: %v", err)
   }
   // Create the user, and add its pets on the creation.
   // 建立使用者，並新增使用者和寵物的關係
   a8m, err := client.User.
      Create().
      SetName("a8m").
      AddPets(pedro, lola).
      Save(ctx)
   if err != nil {
      return fmt.Errorf("creating user: %v", err)
   }
   fmt.Println("User created:", a8m)shell
   // Output: User(id=1, age=30, name=a8m)

   // Query the owner. Unlike `Only`, `OnlyX` panics if an error occurs.
   // 根據寵物反向查詢所屬的使用者
   owner := pedro.QueryOwner().OnlyX(ctx)
   fmt.Println(owner.Name)
   // Output: a8m

   // Traverse the sub-graph. Unlike `Count`, `CountX` panics if an error occurs.
   // 根據寵物反向查詢使用者，並查詢該使用者有多少寵物
   count := pedro.
      QueryOwner(). // a8m
      QueryPets().  // pedro, lola
      CountX(ctx)   // count
   fmt.Println(count)
   // Output: 2
   return nil
}

多對多關係

er-user-groups

在這個例子中，使用者和組之間是多對多關係，每個組有多個使用者，每個使用者也可以加入多個組

ent/schema/group.go

package schema

import (
   "github.com/facebook/ent"
   "github.com/facebook/ent/schema/edge"
   "github.com/facebook/ent/schema/field"
)

// Group holds the schema definition for the Group entity.
type Group struct {
   ent.Schema
}

// Fields of the Group.
func (Group) Fields() []ent.Field {
   return []ent.Field{
      field.String("name"),
   }
}

// Edges of the Group.
func (Group) Edges() []ent.Edge {
   return []ent.Edge{
      edge.To("users", User.Type),
   }
}

ent/schema/user.go

package schema

import (
   "github.com/facebook/ent"
   "github.com/facebook/ent/schema/edge"
   "github.com/facebook/ent/schema/field"
)

// User holds the schema definition for the User entity.
type User struct {
   ent.Schema
}

// Fields of the User.
func (User) Fields() []ent.Field {
   return []ent.Field{
      field.String("name"),
   }
}

// Edges of the User.
func (User) Edges() []ent.Edge {
   return []ent.Edge{
      edge.From("groups", Group.Type).Ref("users"),
   }
}

這個時候，會生成第三張表，group_users表，檢視錶的資訊如下：

CREATE TABLE `group_users` (
  `group_id` bigint(20) NOT NULL,
  `user_id` bigint(20) NOT NULL,
  PRIMARY KEY (`group_id`,`user_id`),
  KEY `group_users_user_id` (`user_id`),
  CONSTRAINT `group_users_group_id` FOREIGN KEY (`group_id`) REFERENCES `groups` (`id`) ON DELETE CASCADE,
  CONSTRAINT `group_users_user_id` FOREIGN KEY (`user_id`) REFERENCES `users` (`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin

常用的查詢方法：

package schema

import (
   "github.com/facebook/ent"
   "github.com/facebook/ent/schema/edge"
   "github.com/facebook/ent/schema/field"
)

// User holds the schema definition for the User entity.
type User struct {
   ent.Schema
}

// Fields of the User.
func (User) Fields() []ent.Field {
   return []ent.Field{
      field.String("name"),
   }
}

// Edges of the User.
func (User) Edges() []ent.Edge {
   return []ent.Edge{
      edge.From("groups", Group.Type).Ref("users"),
   }
}

多對多（單張表）

er-following-followers

這種關係其實也挺常見的，如我們微博賬戶，不同賬戶之間可以相關關注

package schema

import (
   "github.com/facebook/ent"
   "github.com/facebook/ent/schema/edge"
   "github.com/facebook/ent/schema/field"
)

// User holds the schema definition for the User entity.
type User struct {
   ent.Schema
}

// Fields of the User.
func (User) Fields() []ent.package schema

import (
	"github.com/facebook/ent"
	"github.com/facebook/ent/schema/edge"
	"github.com/facebook/ent/schema/field"
)

// User holds the schema definition for the User entity.
type User struct {
	ent.Schema
}

// Fields of the User.
func (User) Fields() []ent.Field {
	return []ent.Field{
		field.String("name"),
	}
}

// Edges of the User.
func (User) Edges() []ent.Edge {
	return []ent.Edge{
		edge.To("following", User.Type).
			From("followers"),
	}
}
Field {
   return []ent.Field{
      field.String("name"),
   }
}

// Edges of the User.
func (User) Edges() []ent.Edge {
   return []ent.Edge{
      edge.To("following", User.Type).
         From("followers"),
   }
}

這樣會生成一個user_following表，表資訊為：

CREATE TABLE `user_following` (
  `user_id` bigint(20) NOT NULL,
  `follower_id` bigint(20) NOT NULL,
  PRIMARY KEY (`user_id`,`follower_id`),
  KEY `user_following_follower_id` (`follower_id`),
  CONSTRAINT `user_following_follower_id` FOREIGN KEY (`follower_id`) REFERENCES `users` (`id`) ON DELETE CASCADE,
  CONSTRAINT `user_following_user_id` FOREIGN KEY (`user_id`) REFERENCES `users` (`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin

其他

在這裡和在Fields中同樣也有Required StorageKey Indexes Annotations 用法基本一樣，這裡不再說明

ent orm筆記2---schema使用(上)

Fileds

資料型別

ID欄位

資料庫型別

GO Type

Default Values 預設值

Validators

內建的 Validators

Optional 可選欄位

Nillable

Immutable 不可變欄位

Uniqueness 唯一索引

Storage Key

Indexes 索引

Struct Tags

Sensitive Fields

Annotations

Edges

快速使用

一對一關係

一對多關係

多對多關係

多對多（單張表）

其他

延伸閱讀

相關文章