Beego/orm/docs/zh/Models.md

## Model Definition

比较全面的 Model 定义例子，后文所有的例子如无特殊说明都以这个为基础。

当前还没有完成自动创建表的功能，所以提供一个 [Models.sql](Models.sql) 测试

note: 根据文档的更新，随时都可能更新这个 Model

##### models.go:

	package main
	
	import (
		"github.com/astaxie/beego/orm"
		"time"
	)
	
	type User struct {
		Id          int        `orm:"auto"`            		 // 设置为auto主键
		UserName    string     `orm:"size(30);unique"` // 设置字段为unique
		Email       string     `orm:"size(100)"`       // 设置string字段长度时,会使用varchar类型
		Password    string     `orm:"size(100)"`
		Status      int16      `orm:"choices(0,1,2,3);defalut(0)"` // choices设置可选值
		IsStaff     bool       `orm:"default(false)"`              // default设置默认值
		IsActive    bool       `orm:"default(0)"`
		Created     time.Time  `orm:"auto_now_add;type(date)"`           // 创建时自动设置时间
		Updated     time.Time  `orm:"auto_now"`                          // 每次更新时自动设置时间
		Profile     *Profile   `orm:"null;rel(one);on_delete(set_null)"` // OneToOne relation, 级联删除时设置为NULL
		Posts       []*Post `orm:"reverse(many)" json:"-"` // fk 的反向关系
		orm.Manager `json:"-"` // 每个model都需要定义orm.Manager
	}
	
	// 定义NewModel进行orm.Manager的初始化(必须)
	func NewUser() *User {
		obj := new(User)
		obj.Manager.Init(obj)
		return obj
	}
	
	type Profile struct {
		Id          int     `orm:"auto"`
		Age         int16   ``
		Money       float64 ``
		User        *User   `orm:"reverse(one)" json:"-"` // 设置反向关系(字段可选)
		orm.Manager `json:"-"`
	}
	
	func (u *Profile) TableName() string {
		return "profile" // 自定义表名
	}
	
	func NewProfile() *Profile {
		obj := new(Profile)
		obj.Manager.Init(obj)
		return obj
	}
	
	type Post struct {
		Id          int       `orm:"auto"`
		User        *User     `orm:"rel(fk)"` // RelForeignKey relation
		Title       string    `orm:"size(60)"`
		Content     string    ``
		Created     time.Time ``
		Updated     time.Time ``
		Tags        []*Tag    `orm:"rel(m2m)"` // ManyToMany relation
		orm.Manager `json:"-"`
	}
	
	func NewPost() *Post {
		obj := new(Post)
		obj.Manager.Init(obj)
		return obj
	}
	
	type Tag struct {
		Id          int     `orm:"auto"`
		Name        string  `orm:"size(30)"`
		Status      int16   `orm:"choices(0,1,2);default(0)"`
		Posts       []*Post `orm:"reverse(many)" json:"-"`
		orm.Manager `json:"-"`
	}
	
	func NewTag() *Tag {
		obj := new(Tag)
		obj.Manager.Init(obj)
		return obj
	}
	
	type Comment struct {
		Id          int       `orm:"auto"`
		Post        *Post     `orm:"rel(fk)"`
		Content     string    ``
		Parent      *Comment  `orm:"null;rel(fk)"` // null设置allow NULL
		Status      int16     `orm:"choices(0,1,2);default(0)"`
		Created     time.Time `orm:"auto_now_add"`
		orm.Manager `json:"-"`
	}
	
	func NewComment() *Comment {
		obj := new(Comment)
		obj.Manager.Init(obj)
		return obj
	}
	
	func init() {
		// 需要在init中注册定义的model
		orm.RegisterModel(new(User))
		orm.RegisterModel(new(Profile))
		orm.RegisterModel(new(Post))
		orm.RegisterModel(new(Tag))
		orm.RegisterModel(new(Comment))
	}

## Field Type

现在 orm 支持下面的字段形式

| go type		   | field type  | mysql type
| :---   	   | :---        | :---
| bool | TypeBooleanField | tinyint
| string | TypeCharField | varchar
| string | TypeTextField | longtext
| time.Time | TypeDateField | date
| time.TIme | TypeDateTimeField | datetime
|  int16 |TypeSmallIntegerField | int(4)
|  int, int32 |TypeIntegerField | int(11)
|  int64 |TypeBigIntegerField | bigint(20)
|  uint, uint16 |TypePositiveSmallIntegerField | int(4) unsigned
|  uint32 |TypePositiveIntegerField | int(11) unsigned
|  uint64 |TypePositiveBigIntegerField | bigint(20) unsigned
| float32, float64 | TypeFloatField | double
| float32, float64 | TypeDecimalField | double(digits, decimals)

关系型的字段，其字段类型取决于对应的主键。

* RelForeignKey
* RelOneToOne
* RelManyToMany
* RelReverseOne
* RelReverseMany

## Field Options

    `orm:"null;rel(fk)"`
	
通常每个 Field 的 StructTag 里包含两种类型的设置，类似 null 的 bool 型设置，还有 类似 rel(fk) 的指定值设置，bool 型默认为 false，指定以后即表示为 true

多个设置间使用 `;` 分隔，设置的值如果是多个，使用 `,` 分隔。

#### auto

设置为 Autoincrement Primary Key

#### pk

设置为 Primary Key

#### null

数据库表默认为 `NOT NULL`，设置 null 代表 `ALLOW NULL`

#### blank

设置 string 类型的字段允许为空，否则 clean 会返回错误

#### index

为字段增加索引

#### unique

为字段增加 unique 键

#### column

为字段设置 db 字段的名称

	UserName `orm:"column(db_user_name)"`

#### default

为字段设置默认值，类型必须符合

	Status int `orm:"default(1)"`

#### choices

为字段设置一组可选的值，类型必须符合。其他值 clean 会返回错误

	Status int `orm:"choices(1,2,3,4)"`

#### size (string)

string 类型字段设置 size 以后，db type 将使用 varchar

	Title string `orm:"size(60)"`

#### digits / decimals

设置 float32, float64 类型的浮点精度

	Money float64 `orm:"digits(12);decimals(4)"`

总长度 12 小数点后 4 位 eg: `99999999.9999`

#### auto_now / auto_now_add

	Created     time.Time `auto_now_add`
	Updated     time.Time `auto_now`

* auto_now 每次 model 保存时都会对时间自动更新
* auto_now_add 第一次保存时才设置时间

对于批量的 update 此设置是不生效的

#### type

设置为 date, time.Time 字段的对应 db 类型使用 date

	Created time.Time `orm:"auto_now_add;type(date)"`

## Relation Field Options

#### rel / reverse

RelOneToOne:

	type User struct {
		...
		Profile *Profile `orm:"null;rel(one);on_delete(set_null)"`

对应的反向关系 RelReverseOne:

	type Profile struct {
		...
		User *User `orm:"reverse(one)" json:"-"`

RelForeignKey:

	type Post struct {
		...
		User*User `orm:"rel(fk)"` // RelForeignKey relation

对应的反向关系 RelReverseMany:

	type User struct {
		...
		Posts []*Post `orm:"reverse(many)" json:"-"` // fk 的反向关系

RelManyToMany:

	type Post struct {
		...
		Tags []*Tag `orm:"rel(m2m)"` // ManyToMany relation
   
对应的反向关系 RelReverseMany:

	type Tag struct {
		...
		Posts []*Post `orm:"reverse(many)" json:"-"`

#### rel_table / rel_through

此设置针对 `orm:"rel(m2m)"` 的关系字段

	rel_table       设置自动生成的 m2m 关系表的名称
	rel_through     如果要在 m2m 关系中使用自定义的 m2m 关系表
	                通过这个设置其名称，格式为 pkg.path.ModelName
	                eg: app.models.PostTagRel
	                PostTagRel 表需要有到 Post 和 Tag 的关系

当设置 rel_table 时会忽略 rel_through

#### on_delete

设置对应的 rel 关系删除时，如何处理关系字段。

	cascade        级联删除(默认值)
	set_null       设置为 NULL，需要设置 null = true
	set_default    设置为默认值，需要设置 default 值
	do_nothing     什么也不做，忽略

	type User struct {
		...
		Profile *Profile `orm:"null;rel(one);on_delete(set_null)"`
	...
	type Profile struct {
		...
		User *User `orm:"reverse(one)" json:"-"`
	
	删除 Profile 时将设置 User.Profile 的数据库字段为 NULL