From 37f8c6a04a20caaf06192beae7d0e920477aa760 Mon Sep 17 00:00:00 2001 From: slene Date: Wed, 7 Aug 2013 19:11:57 +0800 Subject: [PATCH] zh docs update --- orm/docs/zh/Models.md | 7 +- orm/docs/zh/Object.md | 4 +- orm/docs/zh/Orm.md | 162 ++++++++++++++++++++++++++++++++++-------- orm/docs/zh/Query.md | 93 +++++++++++++++++++++--- orm/docs/zh/README.md | 24 ++++--- 5 files changed, 232 insertions(+), 58 deletions(-) diff --git a/orm/docs/zh/Models.md b/orm/docs/zh/Models.md index f071730b..76f8c345 100644 --- a/orm/docs/zh/Models.md +++ b/orm/docs/zh/Models.md @@ -105,11 +105,8 @@ func NewComment() *Comment { func init() { // 需要在init中注册定义的model - orm.RegisterModel(new(User)) - orm.RegisterModel(new(Profile)) - orm.RegisterModel(new(Post)) - orm.RegisterModel(new(Tag)) - orm.RegisterModel(new(Comment)) + orm.RegisterModel(new(User), new(Profile)) + orm.RegisterModel(new(Post), new(Tag), new(Comment)) } ``` diff --git a/orm/docs/zh/Object.md b/orm/docs/zh/Object.md index f18c8c58..684f6067 100644 --- a/orm/docs/zh/Object.md +++ b/orm/docs/zh/Object.md @@ -12,7 +12,7 @@ fmt.Println(o.Insert(user)) user.UserName = "Your" fmt.Println(o.Update(user)) - +fmt.Println(o.Read(user)) fmt.Println(o.Delete(user)) ``` ### Read @@ -36,7 +36,7 @@ o := orm.NewOrm() var user User user.UserName = "slene" user.Password = "password" -user.Email = "vslene@gmail.com" +user.Email = "vslene@gmail.com"[]() user.IsActive = true fmt.Println(o.Insert(&user)) diff --git a/orm/docs/zh/Orm.md b/orm/docs/zh/Orm.md index 148f4d5b..84c2e96c 100644 --- a/orm/docs/zh/Orm.md +++ b/orm/docs/zh/Orm.md @@ -1,6 +1,6 @@ ## Orm -beego/orm 的使用方法 +beego/orm 的使用例子 ```go package main @@ -11,21 +11,12 @@ import ( ) 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，你可以指定为其他数据库 @@ -42,25 +33,134 @@ func main() { fmt.Println(o.Insert(profile)) fmt.Println(o.Insert(user)) - - 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 +``` + +#### RegisterDriver + +三种数据库类型 + +```go +orm.DR_MySQL +orm.DR_Sqlite +orm.DR_Postgres +``` + +```go +// 参数1 driverName +// 参数2 数据库类型 +// 这个用来设置 driverName 对应的数据库类型 +// mysql / sqlite3 / postgres 这三种是默认已经注册过的，所以可以无需设置 +orm.RegisterDriver("mysql", orm.DR_MySQL) +``` + +#### RegisterDataBase + +orm 必须注册一个名称为 `default` 的数据库，用以作为默认使用。 + +```go +// 参数1 自定义数据库名称，用来在orm中切换数据库使用 +// 参数2 driverName +// 参数3 对应的链接字符串 +// 参数4 设置最大的空闲连接数，使用 golang 自己的连接池 +orm.RegisterDataBase("default", "mysql", "root:root@/orm_test?charset=utf8", 30) +``` + +## Ormer + +```go +var o Ormer +o = orm.NewOrm() // 创建一个 Ormer +// NewOrm 的同时会执行一次 orm.BootStrap，用以验证模型之间的定义并缓存。 +``` + +* type Ormer interface { + * [Read(Modeler) error](Object.md#Read) + * [Insert(Modeler) (int64, error)](Object.md#Insert) + * [Update(Modeler) (int64, error)](Object.md#Update) + * [Delete(Modeler) (int64, error)](Object.md#Delete) + * [M2mAdd(Modeler, string, ...interface{}) (int64, error)](Object.md#M2mAdd) + * [M2mDel(Modeler, string, ...interface{}) (int64, error)](Object.md#M2mDel) + * [LoadRel(Modeler, string) (int64, error)](Object.md#LoadRel) + * [QueryTable(interface{}) QuerySeter](#QueryTable) + * [Using(string) error](#Using) + * [Begin() error](Transaction.md#Begin) + * [Commit() error](Transaction.md#Commit) + * [Rollback() error](Transaction.md#Rollback) + * [Raw(string, ...interface{}) RawSeter](#Raw) + * [Driver() Driver](#Driver) +* } + + +#### QueryTable + +传入表名，或者 Modeler 对象，返回一个 [QuerySeter](Query.md#QuerySeter) + +```go +o := orm.NewOrm() +var qs QuerySeter +qs = o.QueryTable("user") +// 如果表没有定义过，会立刻 panic +``` + +#### Using + +切换为其他数据库 + +```go +orm.RegisterDataBase("db1", "mysql", "root:root@/orm_db2?charset=utf8", 30) +orm.RegisterDataBase("db2", "sqlite3", "data.db", 30) + +o1 := orm.NewOrm() +o1.Using("db1") + +o2 := orm.NewOrm() +o2.Using("db2") + +// 切换为其他数据库以后 +// 这个 Ormer 对象的其下的 api 调用都将使用这个数据库 + +``` + +默认使用 `default` 数据库，无需调用 Using + +#### Raw + +使用 sql 语句直接进行操作 + +Raw 函数，返回一个 [RawSeter](Raw.md) 用以对设置的 sql 语句和参数进行操作 + +```go +o := NewOrm() +var r RawSeter +r = o.Raw("UPDATE user SET user_name = ? WHERE user_name = ?", "testing", "slene") +``` + +#### Driver + +返回当前 orm 使用的 db 信息 + +```go +type Driver interface { + Name() string + Type() DriverType +} +``` + +```go +orm.RegisterDataBase("db1", "mysql", "root:root@/orm_db2?charset=utf8", 30) +orm.RegisterDataBase("db2", "sqlite3", "data.db", 30) + +o1 := orm.NewOrm() +o1.Using("db1") +dr := o1.Driver() +fmt.Println(dr.Name() == "db1") // true +fmt.Println(dr.Type() == orm.DR_MySQL) // true + +o2 := orm.NewOrm() +o2.Using("db2") +dr = o2.Driver() +fmt.Println(dr.Name() == "db2") // true +fmt.Println(dr.Type() == orm.DR_Sqlite) // true + +``` diff --git a/orm/docs/zh/Query.md b/orm/docs/zh/Query.md index 7bd55e7a..f6c51ece 100644 --- a/orm/docs/zh/Query.md +++ b/orm/docs/zh/Query.md @@ -13,7 +13,7 @@ qs := o.QueryTable("user") user := NewUser() qs = o.QueryTable(user) // 返回 QuerySeter ``` -### expr +## expr QuerySeter 中用于描述字段和 sql 操作符使用简单的 expr 查询方法 @@ -32,9 +32,20 @@ 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 ``` -### Operators +## Operators -当前支持的操作符号 +当前支持的操作符号： + +* [exact](#exact) / [iexact](#iexact) 等于 +* [contains](#contains) / [icontains](#icontains) 包含 +* [gt / gte](#gt / gte) 大于 / 大于等于 +* [lt / lte](#lt / lte) 小于 / 小于等于 +* [startswith](#startswith) / [istartswith](#istartswith) 以...起始 +* [endswith](#endswith) / [iendswith](#iendswith) 以...结束 +* [in](#in) +* [isnull](#isnull) + +后面以 `i` 开头的表示：大小写不敏感 #### exact @@ -119,6 +130,29 @@ qs.Filter("profile__isnull", false) ``` ## QuerySeter +QuerySeter 当前支持的方法 + +* type QuerySeter interface { + * [Filter(string, ...interface{}) QuerySeter](#Filter) + * [Exclude(string, ...interface{}) QuerySeter](#Exclude) + * [SetCond(*Condition) QuerySeter](#SetCond) + * [Limit(int, ...int64) QuerySeter](#Limit) + * [Offset(int64) QuerySeter](#Offset) + * [OrderBy(...string) QuerySeter](#OrderBy) + * [RelatedSel(...interface{}) QuerySeter](#RelatedSel) + * [Count() (int64, error)](#Count) + * [Update(Params) (int64, error)](#Update) + * [Delete() (int64, error)](#Delete) + * [PrepareInsert() (Inserter, error)](#PrepareInsert) + * [All(interface{}) (int64, error)](#All) + * [One(Modeler) error](#One) + * [Values(*[]Params, ...string) (int64, error)](#Values) + * [ValuesList(*[]ParamsList, ...string) (int64, error)](#ValuesList) + * [ValuesFlat(*ParamsList, string) (int64, error)](#ValuesFlat) +* } + +每个返回 QuerySeter 的 api 调用时都会新建一个 QuerySeter，不影响之前创建的。 + #### Filter 多个 Filter 之间使用 `AND` 连接 @@ -139,6 +173,21 @@ qs.Exclude("profile__isnull", true).Filter("user_name", "slene") #### SetCond +自定义条件表达式 + +```go +cond := NewCondition() +cond1 := cond.And("profile__isnull", false).AndNot("status__in", 1).Or("profile__age__gt", 2000) + +qs := orm.QueryTable("user") +qs = qs.SetCond(cond1) +// WHERE ... AND ... AND NOT ... OR ... + +cond2 := cond.AndCond(cond1).OrCond(cond.And("user_name", "slene")) +qs = qs.SetCond(cond2).Count() +// WHERE (... AND ... AND NOT ... OR ...) OR ( ... ) +``` + #### Limit 限制最大返回数据行数，第二个参数可以设置 `Offset` @@ -166,7 +215,7 @@ qs.Limit(-1, 100) 设置 偏移行数 ```go -qs.OFFSET(20) +qs.Offset(20) // LIMIT 1000 OFFSET 20 ``` @@ -226,6 +275,28 @@ fmt.Printf("Affected Num: %s, %s", num, err) // DELETE FROM user WHERE user_name = "slene" ``` +#### PrepareInsert + +用于一次 prepare 多次 insert 插入，以提高批量插入的速度。 + +```go +var users []*User +... +qs := dORM.QueryTable("user") +i, _ := qs.PrepareInsert() +for _, user := range users { + id, err := i.Insert(user) + if err != nil { + ... + } +} +// PREPARE INSERT INTO user (`user_name`, ...) VALUES (?, ...) +// EXECUTE INSERT INTO user (`user_name`, ...) VALUES ("slene", ...) +// EXECUTE ... +// ... +i.Close() // 别忘记关闭 statement +``` + #### All 返回对应的结果集对象 ```go @@ -235,13 +306,20 @@ fmt.Printf("Returned Rows Num: %s, %s", num, err) ``` #### One -尝试返回单个对象 + +尝试返回单条记录 + ```go var user *User err := o.QueryTable("user").Filter("user_name", "slene").One(&user) if err == orm.ErrMultiRows { + // 多条的时候报错 fmt.Printf("Returned Multi Rows Not One") } +if err == orm.ErrNoRows { + // 没有找到记录 + fmt.Printf("Not row found") +} ``` #### Values @@ -323,10 +401,5 @@ if err != nil { } ``` -#### PrepareInsert - -用于批量插入 prepare -> insert -> insert - - diff --git a/orm/docs/zh/README.md b/orm/docs/zh/README.md index 5d3ea23a..73a68055 100644 --- a/orm/docs/zh/README.md +++ b/orm/docs/zh/README.md @@ -27,8 +27,6 @@ func init() { } func main() { - orm.BootStrap() // 确保在所有 RegisterModel 之后执行 - o := orm.NewOrm() user := User{Name: "slene"} @@ -55,12 +53,18 @@ func main() { ## 详细文档 -1. [Model Definition](Models.md) +1. [模型定义](Models.md) + - [支持的 Field 类型](Models.md#Field Type) + - [Field 设置参数](Models.md#Field Options) + - [关系型 Field 设置](Models.md#Relation Field Options) 2. Custom Fields -3. [Orm](Orm.md) -4. [Object](Object.md) -5. [Query](Query.md) -6. Condition -7. Raw -8. Transaction -9. Faq +3. [Orm 使用方法](Orm.md) + - [Ormer 接口](Orm.md#Ormer) +4. [对象操作](Object.md) +5. [复杂查询](Query.md) + - [查询使用的表达式语法](Query.md#expr) + - [查询支持的操作符号](Query.md#Operators) + - [QuerySeter 接口](Query.md#QuerySeter) +6. Raw +7. Transaction +8. Faq