From 5ccdaeb09e399c027ec7cc1b21166531a8a3cb51 Mon Sep 17 00:00:00 2001 From: slene Date: Thu, 1 Aug 2013 09:23:44 +0800 Subject: [PATCH] zh docs update --- orm/docs/zh/Models.md | 353 +++++++++++++++++++++--------------------- orm/docs/zh/Object.md | 90 +++++------ orm/docs/zh/Orm.md | 118 +++++++------- orm/docs/zh/Query.md | 268 ++++++++++++++++---------------- orm/docs/zh/README.md | 79 +++++++++- 5 files changed, 497 insertions(+), 411 deletions(-) diff --git a/orm/docs/zh/Models.md b/orm/docs/zh/Models.md index 284f40d2..83ef76f5 100644 --- a/orm/docs/zh/Models.md +++ b/orm/docs/zh/Models.md @@ -8,108 +8,110 @@ 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)) - } +```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 @@ -140,8 +142,9 @@ note: 根据文档的更新，随时都可能更新这个 Model * RelReverseMany ## Field Options - - `orm:"null;rel(fk)"` +```go +orm:"null;rel(fk)" +``` 通常每个 Field 的 StructTag 里包含两种类型的设置，类似 null 的 bool 型设置，还有 类似 rel(fk) 的指定值设置，bool 型默认为 false，指定以后即表示为 true @@ -174,40 +177,40 @@ note: 根据文档的更新，随时都可能更新这个 Model #### column 为字段设置 db 字段的名称 - - UserName `orm:"column(db_user_name)"` - +```go +UserName `orm:"column(db_user_name)"` +``` #### default 为字段设置默认值，类型必须符合 - - Status int `orm:"default(1)"` - +```go +Status int `orm:"default(1)"` +``` #### choices 为字段设置一组可选的值，类型必须符合。其他值 clean 会返回错误 - - Status int `orm:"choices(1,2,3,4)"` - +```go +Status int `orm:"choices(1,2,3,4)"` +``` #### size (string) string 类型字段设置 size 以后，db type 将使用 varchar - - Title string `orm:"size(60)"` - +```go +Title string `orm:"size(60)"` +``` #### digits / decimals 设置 float32, float64 类型的浮点精度 - - Money float64 `orm:"digits(12);decimals(4)"` - +```go +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` - +```go +Created time.Time `auto_now_add` +Updated time.Time `auto_now` +``` * auto_now 每次 model 保存时都会对时间自动更新 * auto_now_add 第一次保存时才设置时间 @@ -216,49 +219,49 @@ string 类型字段设置 size 以后，db type 将使用 varchar #### type 设置为 date, time.Time 字段的对应 db 类型使用 date - - Created time.Time `orm:"auto_now_add;type(date)"` - +```go +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:"-"` - +**RelOneToOne**: +```go +type User struct { + ... + Profile *Profile `orm:"null;rel(one);on_delete(set_null)"` +``` +对应的反向关系 **RelReverseOne**: +```go +type Profile struct { + ... + User *User `orm:"reverse(one)" json:"-"` +``` +**RelForeignKey**: +```go +type Post struct { + ... + User*User `orm:"rel(fk)"` // RelForeignKey relation +``` +对应的反向关系 **RelReverseMany**: +```go +type User struct { + ... + Posts []*Post `orm:"reverse(many)" json:"-"` // fk 的反向关系 +``` +**RelManyToMany**: +```go +type Post struct { + ... + Tags []*Tag `orm:"rel(m2m)"` // ManyToMany relation +``` +对应的反向关系 **RelReverseMany**: +```go +type Tag struct { + ... + Posts []*Post `orm:"reverse(many)" json:"-"` +``` #### rel_table / rel_through 此设置针对 `orm:"rel(m2m)"` 的关系字段 @@ -275,17 +278,19 @@ RelManyToMany: 设置对应的 rel 关系删除时，如何处理关系字段。 - cascade 级联删除(默认值) - set_null 设置为 NULL，需要设置 null = true - set_default 设置为默认值，需要设置 default 值 - do_nothing 什么也不做，忽略 +```go +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 User struct { ... - type Profile struct { - ... - User *User `orm:"reverse(one)" json:"-"` - - 删除 Profile 时将设置 User.Profile 的数据库字段为 NULL \ No newline at end of file + Profile *Profile `orm:"null;rel(one);on_delete(set_null)"` +... +type Profile struct { + ... + User *User `orm:"reverse(one)" json:"-"` + +// 删除 Profile 时将设置 User.Profile 的数据库字段为 NULL +``` \ No newline at end of file diff --git a/orm/docs/zh/Object.md b/orm/docs/zh/Object.md index 3d0ce14d..4dcd2184 100644 --- a/orm/docs/zh/Object.md +++ b/orm/docs/zh/Object.md @@ -1,59 +1,59 @@ ## Object 对 object 操作的三个方法 Insert / Update / Delete - - o := orm.NewOrm() - user := NewUser() - user.UserName = "slene" - user.Password = "password" - user.Email = "vslene@gmail.com" - obj := o.Object(user) - fmt.Println(obj.Insert()) - user.UserName = "Your" - fmt.Println(obj.Update()) - fmt.Println(obj.Delete()) - +```go +o := orm.NewOrm() +user := NewUser() +user.UserName = "slene" +user.Password = "password" +user.Email = "vslene@gmail.com" +obj := o.Object(user) +fmt.Println(obj.Insert()) +user.UserName = "Your" +fmt.Println(obj.Update()) +fmt.Println(obj.Delete()) +``` ### Read - - var user User - err := o.QueryTable("user").Filter("id", 1).One(&user) - if err != orm.ErrMultiRows { - fmt.Println(user.UserName) - } - +```go +var user User +err := o.QueryTable("user").Filter("id", 1).One(&user) +if err != orm.ErrMultiRows { + fmt.Println(user.UserName) +} +``` ### Create +```go +profile := NewProfile() +profile.Age = 30 +profile.Money = 9.8 - profile := NewProfile() - profile.Age = 30 - profile.Money = 9.8 +user := NewUser() +user.Profile = profile +user.UserName = "slene" +user.Password = "password" +user.Email = "vslene@gmail.com" +user.IsActive = true - user := NewUser() - user.Profile = profile - user.UserName = "slene" - user.Password = "password" - user.Email = "vslene@gmail.com" - user.IsActive = true - - fmt.Println(o.Object(profile).Insert()) - fmt.Println(o.Object(user).Insert()) - fmt.Println(user.Id) - +fmt.Println(o.Object(profile).Insert()) +fmt.Println(o.Object(user).Insert()) +fmt.Println(user.Id) +``` 创建后会自动对 auto 的 field 赋值 ### Update - - var user User - err := o.QueryTable("user").Filter("id", 1).One(&user) - if err != orm.ErrMultiRows { - fmt.Println(user.UserName) - } - user.UserName = "MyName" - o.Object(&user).Update() - +```go +var user User +err := o.QueryTable("user").Filter("id", 1).One(&user) +if err != orm.ErrMultiRows { + fmt.Println(user.UserName) +} +user.UserName = "MyName" +o.Object(&user).Update() +``` ### Delete - - o.Object(user).Delete() - +```go +o.Object(user).Delete() +``` Delete 操作会对反向关系进行操作，此例中 Post 拥有一个到 User 的外键。删除 User 的时候。如果 on_delete 设置为默认的级联操作，将删除对应的 Post 删除以后会清除 auto field 的值 diff --git a/orm/docs/zh/Orm.md b/orm/docs/zh/Orm.md index f96e3966..4b9a2350 100644 --- a/orm/docs/zh/Orm.md +++ b/orm/docs/zh/Orm.md @@ -1,64 +1,66 @@ ## Orm beego/orm 的使用方法 +```go +package main - package main - - import ( - "fmt" - "github.com/astaxie/beego/orm" - _ "github.com/go-sql-driver/mysql" - ) - - func init() { - // 这个用来设置 driverName 对应的数据库类型 - // mysql / sqlite3 / postgres 这三种是默认已经注册过的，所以可以无需设置 - orm.RegisterDriver("mysql", orm.DR_MySQL) - - // 参数1 自定义的数据库名称，用来在orm中切换数据库使用 - // 参数2 driverName - // 参数3 对应的链接字符串 - // 参数4 设置最大的空闲连接数，使用 golang 自己的连接池 - orm.RegisterDataBase("default", "mysql", "root:root@/orm_test?charset=utf8", 30) - } - - func main() { - orm.BootStrap() // 强制在 main 函数里调用，检查 Model 关系，检测数据库参数，调用 orm 提供的 Command - - o := orm.NewOrm() - o.Using("default") // 默认使用 default，你可以指定为其他数据库 - - profile := NewProfile() - profile.Age = 30 - profile.Money = 9.8 - - user := NewUser() - user.Profile = profile - user.UserName = "slene" - user.Password = "password" - user.Email = "vslene@gmail.com" - user.IsActive = true - - fmt.Println(o.Object(profile).Insert()) - fmt.Println(o.Object(user).Insert()) - - var params []orm.Params - if cnt, err := o.QueryTable("user").RelatedSel().Limit(3).OrderBy("-id").Values(¶ms); err != nil { - fmt.Println(err) - } else { - fmt.Println(cnt) - for _, p := range params { - fmt.Println(p) - } - } - - var users []*User - if cnt, err := o.QueryTable("user").RelatedSel().Limit(3).OrderBy("-id").All(&users); err != nil { - fmt.Println(err) - } else { - fmt.Println(cnt) - for _, u := range users { - fmt.Println(u.Id, u.Profile) - } +import ( + "fmt" + "github.com/astaxie/beego/orm" + _ "github.com/go-sql-driver/mysql" +) + +func init() { + // 这个用来设置 driverName 对应的数据库类型 + // mysql / sqlite3 / postgres 这三种是默认已经注册过的，所以可以无需设置 + orm.RegisterDriver("mysql", orm.DR_MySQL) + + // 参数1 自定义的数据库名称，用来在orm中切换数据库使用 + // 参数2 driverName + // 参数3 对应的链接字符串 + // 参数4 设置最大的空闲连接数，使用 golang 自己的连接池 + orm.RegisterDataBase("default", "mysql", "root:root@/orm_test?charset=utf8", 30) +} + +func main() { + // 请确保在所有 RegisterModel 之前执行 + orm.BootStrap() // 强制在 main 函数里调用，检查 Model 关系，检测数据库参数，调用 orm 提供的 Command + + o := orm.NewOrm() + o.Using("default") // 默认使用 default，你可以指定为其他数据库 + + profile := NewProfile() + profile.Age = 30 + profile.Money = 9.8 + + user := NewUser() + user.Profile = profile + user.UserName = "slene" + user.Password = "password" + user.Email = "vslene@gmail.com" + user.IsActive = true + + fmt.Println(o.Object(profile).Insert()) + fmt.Println(o.Object(user).Insert()) + + var params []orm.Params + if cnt, err := o.QueryTable("user").RelatedSel().Limit(3).OrderBy("-id").Values(¶ms); err != nil { + fmt.Println(err) + } else { + fmt.Println(cnt) + for _, p := range params { + fmt.Println(p) } } + + var users []*User + if cnt, err := o.QueryTable("user").RelatedSel().Limit(3).OrderBy("-id").All(&users); err != nil { + fmt.Println(err) + } else { + fmt.Println(cnt) + for _, u := range users { + fmt.Println(u.Id, u.Profile) + } + } +} +``` \ No newline at end of file diff --git a/orm/docs/zh/Query.md b/orm/docs/zh/Query.md index 91786743..9d5e41dd 100644 --- a/orm/docs/zh/Query.md +++ b/orm/docs/zh/Query.md @@ -3,16 +3,16 @@ orm 以 **QuerySeter** 来组织查询，每个返回 **QuerySeter** 的方法都会获得一个新的 **QuerySeter** 对象。 基本使用方法: +```go +o := orm.NewOrm() - o := orm.NewOrm() - - // 获取 QuerySeter 对象，user 为表名 - qs := o.QueryTable("user") - - // 也可以直接使用对象作为表名 - user := NewUser() - qs = o.QueryTable(user) // 返回 QuerySeter +// 获取 QuerySeter 对象，user 为表名 +qs := o.QueryTable("user") +// 也可以直接使用对象作为表名 +user := NewUser() +qs = o.QueryTable(user) // 返回 QuerySeter +``` ### expr QuerySeter 中用于描述字段和 sql 操作符使用简单的 expr 查询方法 @@ -20,18 +20,18 @@ QuerySeter 中用于描述字段和 sql 操作符使用简单的 expr 查询方 字段组合的前后顺序依照表的关系，比如 User 表拥有 Profile 的外键，那么对 User 表查询对应的 Profile.Age 为条件，则使用 `Profile__Age` 注意，字段的分隔符号使用双下划线 `__`，除了描述字段， expr 的尾部可以增加操作符以执行对应的 sql 操作。比如 `Profile__Age__gt` 代表 Profile.Age > 18 的条件查询。 注释后面将描述对应的 sql 语句，仅仅是描述 expr 的类似结果，并不代表实际生成的语句。 +```go +qs.Filter("id", 1) // WHERE id = 1 +qs.Filter("profile__age", 18) // WHERE profile.age = 18 +qs.Filter("Profile__Age", 18) // 使用字段名和Field名都是允许的 +qs.Filter("profile__age", 18) // WHERE profile.age = 18 +qs.Filter("profile__age__gt", 18) // WHERE profile.age > 18 +qs.Filter("profile__age__gte", 18) // WHERE profile.age >= 18 +qs.Filter("profile__age__in", 18, 20) // WHERE profile.age IN (18, 20) - qs.Filter("id", 1) // WHERE id = 1 - qs.Filter("profile__age", 18) // WHERE profile.age = 18 - qs.Filter("Profile__Age", 18) // 使用字段名和Field名都是允许的 - qs.Filter("profile__age", 18) // WHERE profile.age = 18 - qs.Filter("profile__age__gt", 18) // WHERE profile.age > 18 - qs.Filter("profile__age__gte", 18) // WHERE profile.age >= 18 - qs.Filter("profile__age__in", 18, 20) // WHERE profile.age IN (18, 20) - - qs.Filter("profile__age__in", 18, 20).Exclude("profile__money__lt", 1000) - // WHERE profile.age IN (18, 20) AND NOT profile.money < 1000 - +qs.Filter("profile__age__in", 18, 20).Exclude("profile__money__lt", 1000) +// WHERE profile.age IN (18, 20) AND NOT profile.money < 1000 +``` ### Operators 当前支持的操作符号 @@ -39,162 +39,166 @@ QuerySeter 中用于描述字段和 sql 操作符使用简单的 expr 查询方 #### exact Filter / Exclude / Condition expr 的默认值 - - qs.Filter("user_name", "slene") // WHERE user_name = 'slene' - qs.Filter("user_name__exact", "slene") // WHERE user_name = 'slene' - qs.Filter("profile", nil) // WHERE profile_id IS NULL - +```go +qs.Filter("user_name", "slene") // WHERE user_name = 'slene' +qs.Filter("user_name__exact", "slene") // WHERE user_name = 'slene' +// 使用 = 匹配，大小写是否敏感取决于数据表使用的 collation +qs.Filter("profile", nil) // WHERE profile_id IS NULL +``` #### iexact - - qs.Filter("user_name__iexact", "slene") - // WHERE user_name LIKE 'slene' - // 大小写不敏感，匹配任意 'Slene' 'sLENE' - +```go +qs.Filter("user_name__iexact", "slene") +// WHERE user_name LIKE 'slene' +// 大小写不敏感，匹配任意 'Slene' 'sLENE' +``` #### contains - - qs.Filter("user_name__contains", "slene") - // WHERE user_name LIKE BINARY '%slene%' - // 大小写敏感, 匹配包含 slene 的字符 - +```go +qs.Filter("user_name__contains", "slene") +// WHERE user_name LIKE BINARY '%slene%' +// 大小写敏感, 匹配包含 slene 的字符 +``` #### icontains - - qs.Filter("user_name__icontains", "slene") - // WHERE user_name LIKE '%slene%' - // 大小写不敏感, 匹配任意 'im Slene', 'im sLENE' - +```go +qs.Filter("user_name__icontains", "slene") +// WHERE user_name LIKE '%slene%' +// 大小写不敏感, 匹配任意 'im Slene', 'im sLENE' +``` #### in - - qs.Filter("profile__age__in", 17, 18, 19, 20) - // WHERE profile.age IN (17, 18, 19, 20) - +```go +qs.Filter("profile__age__in", 17, 18, 19, 20) +// WHERE profile.age IN (17, 18, 19, 20) +``` #### gt / gte +```go +qs.Filter("profile__age__gt", 17) +// WHERE profile.age > 17 - qs.Filter("profile__age__gt", 17) - // WHERE profile.age > 17 - - qs.Filter("profile__age__gte", 18) - // WHERE profile.age >= 18 - +qs.Filter("profile__age__gte", 18) +// WHERE profile.age >= 18 +``` #### lt / lte +```go +qs.Filter("profile__age__lt", 17) +// WHERE profile.age < 17 - qs.Filter("profile__age__lt", 17) - // WHERE profile.age < 17 - - qs.Filter("profile__age__lte", 18) - // WHERE profile.age <= 18 - +qs.Filter("profile__age__lte", 18) +// WHERE profile.age <= 18 +``` #### startswith - - qs.Filter("user_name__startswith", "slene") - // WHERE user_name LIKE BINARY 'slene%' - // 大小写敏感, 匹配以 'slene' 起始的字符串 - +```go +qs.Filter("user_name__startswith", "slene") +// WHERE user_name LIKE BINARY 'slene%' +// 大小写敏感, 匹配以 'slene' 起始的字符串 +``` #### istartswith - - qs.Filter("user_name__istartswith", "slene") - // WHERE user_name LIKE 'slene%' - // 大小写不敏感, 匹配任意以 'slene', 'Slene' 起始的字符串 - - +```go +qs.Filter("user_name__istartswith", "slene") +// WHERE user_name LIKE 'slene%' +// 大小写不敏感, 匹配任意以 'slene', 'Slene' 起始的字符串 +``` #### endswith - - qs.Filter("user_name__endswith", "slene") - // WHERE user_name LIKE BINARY '%slene' - // 大小写敏感, 匹配以 'slene' 结束的字符串 - +```go +qs.Filter("user_name__endswith", "slene") +// WHERE user_name LIKE BINARY '%slene' +// 大小写敏感, 匹配以 'slene' 结束的字符串 +``` #### iendswith - - qs.Filter("user_name__startswith", "slene") - // WHERE user_name LIKE '%slene' - // 大小写不敏感, 匹配任意以 'slene', 'Slene' 结束的字符串 - +```go +qs.Filter("user_name__startswith", "slene") +// WHERE user_name LIKE '%slene' +// 大小写不敏感, 匹配任意以 'slene', 'Slene' 结束的字符串 +``` #### isnull +```go +qs.Filter("profile__isnull", true) +qs.Filter("profile_id__isnull", true) +// WHERE profile_id IS NULL - qs.Filter("profile__isnull", true) - qs.Filter("profile_id__isnull", true) - // WHERE profile_id IS NULL - - qs.Filter("profile__isnull", false) - // WHERE profile_id IS NOT NULL - +qs.Filter("profile__isnull", false) +// WHERE profile_id IS NOT NULL +``` ## QuerySeter #### Filter 多个 Filter 之间使用 `AND` 连接 - - qs.Filter("profile__isnull", true).Filter("user_name", "slene") - // WHERE profile_id IS NULL AND user_name = 'slene' - +```go +qs.Filter("profile__isnull", true).Filter("user_name", "slene") +// WHERE profile_id IS NULL AND user_name = 'slene' +``` #### Exclude 使用 `NOT` 排除条件 多个 Exclude 之间使用 `AND` 连接 - - qs.Exclude("profile__isnull", true).Filter("user_name", "slene") - // WHERE NOT profile_id IS NULL AND user_name = 'slene' - +```go +qs.Exclude("profile__isnull", true).Filter("user_name", "slene") +// WHERE NOT profile_id IS NULL AND user_name = 'slene' +``` #### Limit 限制最大返回数据行数，第二个参数可以设置 `Offset` +```go +var DefaultRowsLimit = 1000 // orm 默认的 limit 值为 1000 - var DefaultRowsLimit = 1000 // orm 默认的 limit 值为 1000 - - // 默认情况下 select 查询的最大行数为 1000 - // LIMIT 1000 - - qs.Limit(10) - // LIMIT 10 - - qs.Limit(10, 20) - // LIMIT 10 OFFSET 20 - - qs.Limit(-1) - // no limit - - qs.Limit(-1, 100) - // LIMIT 18446744073709551615 OFFSET 100 - // 18446744073709551615 是 1<<64 - 1 用来指定无 limit 限制 但有 offset 偏移的情况 +// 默认情况下 select 查询的最大行数为 1000 +// LIMIT 1000 +qs.Limit(10) +// LIMIT 10 + +qs.Limit(10, 20) +// LIMIT 10 OFFSET 20 + +qs.Limit(-1) +// no limit + +qs.Limit(-1, 100) +// LIMIT 18446744073709551615 OFFSET 100 +// 18446744073709551615 是 1<<64 - 1 用来指定无 limit 限制 但有 offset 偏移的情况 +``` #### Offset 设置 偏移行数 - - qs.OFFSET(20) - // LIMIT 1000 OFFSET 20 - +```go +qs.OFFSET(20) +// LIMIT 1000 OFFSET 20 +``` #### OrderBy 参数使用 **expr** 在 expr 前使用减号 `-` 表示 `DESC` 的排列 +```go +qs.OrderBy("id", "-profile__age") +// ORDER BY id ASC, profile.age DESC - qs.OrderBy("id", "-profile__age") - // ORDER BY id ASC, profile.age DESC - - qs.OrderBy("-profile__money", "profile") - // ORDER BY profile.money DESC, profile_id ASC - +qs.OrderBy("-profile__money", "profile") +// ORDER BY profile.money DESC, profile_id ASC +``` #### RelatedSel 关系查询，参数使用 **expr** +```go +var DefaultRelsDepth = 5 // 默认情况下直接调用 RelatedSel 将进行最大 5 层的关系查询 - var DefaultRelsDepth = 5 // 默认情况下直接调用 RelatedSel 将进行最大 5 层的关系查询 - - qs := o.QueryTable("post") - - qs.RelateSel() - // INNER JOIN user ... LEFT OUTER JOIN profile ... - - qs.RelateSel("user") - // INNER JOIN user ... - // 设置 expr 只对设置的字段进行关系查询 - - // 对设置 null 属性的 Field 将使用 LEFT OUTER JOIN - - +qs := o.QueryTable("post") +qs.RelateSel() +// INNER JOIN user ... LEFT OUTER JOIN profile ... + +qs.RelateSel("user") +// INNER JOIN user ... +// 设置 expr 只对设置的字段进行关系查询 + +// 对设置 null 属性的 Field 将使用 LEFT OUTER JOIN +``` +#### Count + +查询当前条件下的行数 +```go +o.QueryTable("user").Count() // SELECT COUNT(*) FROM USER +``` diff --git a/orm/docs/zh/README.md b/orm/docs/zh/README.md index 789d6504..67fab17d 100644 --- a/orm/docs/zh/README.md +++ b/orm/docs/zh/README.md @@ -1,7 +1,83 @@ ## beego orm 介绍 +## 快速入门 -## 指南 +```go +package main + +import ( + "fmt" + "github.com/astaxie/beego/orm" + _ "github.com/go-sql-driver/mysql" +) + +// 最简单的两个表的定义 +type User struct { + Id int `orm:"auto"` + Name string `orm:"size(100)"` + orm.Manager +} + +type Post struct { + Id int `orm:"auto"` + User *User `orm:"rel(fk)"` + Title string `orm:"size(100)"` + Content string + orm.Manager +} + +func init() { + // 将表定义注册到 orm 里 + orm.RegisterModel(new(User)) + orm.RegisterModel(new(Post)) + + // 链接参数设置 + orm.RegisterDataBase("default", "mysql", "root:root@/my_db?charset=utf8", 30) +} + +func main() { + orm.BootStrap() // 确保在所有 RegisterModel 之后执行 + + o := orm.NewOrm() + + var user User + obj := o.Object(&user) + + // 创建 + user.Name = "slene" + id, err := obj.Insert() + fmt.Println(id, err) + + // 更新 + user.Name = "astaxie" + num, err := obj.Update() + fmt.Println(num, err) + + // 查询单个 + var u User + err = o.QueryTable("user").Filter("id", &user).One(&u) + fmt.Println(u.Id, u.Name, err) + + // 创建 post + var post Post + post.Title = "beego orm" + post.Content = "powerful amazing" + post.User = &u + id, err = o.Object(&post).Insert() + fmt.Println(id, err) + + // 当然，以 map[string]interface{} 形式的数据返回也是允许的 + var maps []orm.Params + num, err = o.QueryTable("user").Filter("id", &u).Values(&maps) + fmt.Println(num, err, maps[0]) + + // 删除 + num, err = obj.Delete() // 默认，级联删除 user 以及关系存在的 post + fmt.Println(num, err) +} +``` + +## 详细文档 1. [Model Definition](Models.md) 2. Custom Fields @@ -12,4 +88,3 @@ 7. Raw 8. Transaction 9. Faq -