Skip to content

张磊 / FileStorageBeego

Go to a project
Toggle navigation
Toggle navigation pinning
37f8c6a0 by slene
Options

zh docs update

1 parent 46668b81
Inline Side-by-side
Showing 5 changed files with 231 additions and 57 deletions
orm/docs/zh/Models.md
...@@ -105,11 +105,8 @@ func NewComment() *Comment { ...@@ -105,11 +105,8 @@ func NewComment() *Comment {
105 105
106 func init() { 106 func init() {
107 // 需要在init中注册定义的model 107 // 需要在init中注册定义的model
108 orm.RegisterModel(new(User)) 108 orm.RegisterModel(new(User), new(Profile))
109 orm.RegisterModel(new(Profile)) 109 orm.RegisterModel(new(Post), new(Tag), new(Comment))
110 orm.RegisterModel(new(Post))
111 orm.RegisterModel(new(Tag))
112 orm.RegisterModel(new(Comment))
113 } 110 }
114 ``` 111 ```
115 112
......
orm/docs/zh/Object.md
...@@ -12,7 +12,7 @@ fmt.Println(o.Insert(user)) ...@@ -12,7 +12,7 @@ fmt.Println(o.Insert(user))
12 12
13 user.UserName = "Your" 13 user.UserName = "Your"
14 fmt.Println(o.Update(user)) 14 fmt.Println(o.Update(user))
15 15 fmt.Println(o.Read(user))
16 fmt.Println(o.Delete(user)) 16 fmt.Println(o.Delete(user))
17 ``` 17 ```
18 ### Read 18 ### Read
...@@ -36,7 +36,7 @@ o := orm.NewOrm() ...@@ -36,7 +36,7 @@ o := orm.NewOrm()
36 var user User 36 var user User
37 user.UserName = "slene" 37 user.UserName = "slene"
38 user.Password = "password" 38 user.Password = "password"
39 user.Email = "vslene@gmail.com" 39 user.Email = "vslene@gmail.com"[]()
40 user.IsActive = true 40 user.IsActive = true
41 41
42 fmt.Println(o.Insert(&user)) 42 fmt.Println(o.Insert(&user))
......
orm/docs/zh/Orm.md
1 ## Orm 1 ## Orm
2 2
3 beego/orm 的使用方法 3 beego/orm 的使用例子
4 ```go 4 ```go
5 package main 5 package main
6 6
...@@ -11,21 +11,12 @@ import ( ...@@ -11,21 +11,12 @@ import (
11 ) 11 )
12 12
13 func init() { 13 func init() {
14 // 这个用来设置 driverName 对应的数据库类型
15 // mysql / sqlite3 / postgres 这三种是默认已经注册过的，所以可以无需设置
16 orm.RegisterDriver("mysql", orm.DR_MySQL) 14 orm.RegisterDriver("mysql", orm.DR_MySQL)
17 15
18 // 参数1 自定义的数据库名称，用来在orm中切换数据库使用
19 // 参数2 driverName
20 // 参数3 对应的链接字符串
21 // 参数4 设置最大的空闲连接数，使用 golang 自己的连接池
22 orm.RegisterDataBase("default", "mysql", "root:root@/orm_test?charset=utf8", 30) 16 orm.RegisterDataBase("default", "mysql", "root:root@/orm_test?charset=utf8", 30)
23 } 17 }
24 18
25 func main() { 19 func main() {
26 // 请确保在所有 RegisterModel 之前执行
27 orm.BootStrap() // 强制在 main 函数里调用，检查 Model 关系，检测数据库参数，调用 orm 提供的 Command
28
29 o := orm.NewOrm() 20 o := orm.NewOrm()
30 o.Using("default") // 默认使用 default，你可以指定为其他数据库 21 o.Using("default") // 默认使用 default，你可以指定为其他数据库
31 22
...@@ -42,25 +33,134 @@ func main() { ...@@ -42,25 +33,134 @@ func main() {
42 33
43 fmt.Println(o.Insert(profile)) 34 fmt.Println(o.Insert(profile))
44 fmt.Println(o.Insert(user)) 35 fmt.Println(o.Insert(user))
36 }
37 ```
38
39 #### RegisterDriver
40
41 三种数据库类型
42
43 ```go
44 orm.DR_MySQL
45 orm.DR_Sqlite
46 orm.DR_Postgres
47 ```
48
49 ```go
50 // 参数1 driverName
51 // 参数2 数据库类型
52 // 这个用来设置 driverName 对应的数据库类型
53 // mysql / sqlite3 / postgres 这三种是默认已经注册过的，所以可以无需设置
54 orm.RegisterDriver("mysql", orm.DR_MySQL)
55 ```
56
57 #### RegisterDataBase
58
59 orm 必须注册一个名称为 `default` 的数据库，用以作为默认使用。
60
61 ```go
62 // 参数1 自定义数据库名称，用来在orm中切换数据库使用
63 // 参数2 driverName
64 // 参数3 对应的链接字符串
65 // 参数4 设置最大的空闲连接数，使用 golang 自己的连接池
66 orm.RegisterDataBase("default", "mysql", "root:root@/orm_test?charset=utf8", 30)
67 ```
68
69 ## Ormer
70
71 ```go
72 var o Ormer
73 o = orm.NewOrm() // 创建一个 Ormer
74 // NewOrm 的同时会执行一次 orm.BootStrap，用以验证模型之间的定义并缓存。
75 ```
76
77 * type Ormer interface {
78 * [Read(Modeler) error](Object.md#Read)
79 * [Insert(Modeler) (int64, error)](Object.md#Insert)
80 * [Update(Modeler) (int64, error)](Object.md#Update)
81 * [Delete(Modeler) (int64, error)](Object.md#Delete)
82 * [M2mAdd(Modeler, string, ...interface{}) (int64, error)](Object.md#M2mAdd)
83 * [M2mDel(Modeler, string, ...interface{}) (int64, error)](Object.md#M2mDel)
84 * [LoadRel(Modeler, string) (int64, error)](Object.md#LoadRel)
85 * [QueryTable(interface{}) QuerySeter](#QueryTable)
86 * [Using(string) error](#Using)
87 * [Begin() error](Transaction.md#Begin)
88 * [Commit() error](Transaction.md#Commit)
89 * [Rollback() error](Transaction.md#Rollback)
90 * [Raw(string, ...interface{}) RawSeter](#Raw)
91 * [Driver() Driver](#Driver)
92 * }
93
94
95 #### QueryTable
96
97 传入表名，或者 Modeler 对象，返回一个 [QuerySeter](Query.md#QuerySeter)
98
99 ```go
100 o := orm.NewOrm()
101 var qs QuerySeter
102 qs = o.QueryTable("user")
103 // 如果表没有定义过，会立刻 panic
104 ```
105
106 #### Using
45 107
46 var params []orm.Params 108 切换为其他数据库
47 if cnt, err := o.QueryTable("user").RelatedSel().Limit(3).OrderBy("-id").Values(&params); err != nil { 109
48 fmt.Println(err) 110 ```go
49 } else { 111 orm.RegisterDataBase("db1", "mysql", "root:root@/orm_db2?charset=utf8", 30)
50 fmt.Println(cnt) 112 orm.RegisterDataBase("db2", "sqlite3", "data.db", 30)
51 for _, p := range params { 113
52 fmt.Println(p) 114 o1 := orm.NewOrm()
53 } 115 o1.Using("db1")
54 } 116
55 117 o2 := orm.NewOrm()
56 var users []*User 118 o2.Using("db2")
57 if cnt, err := o.QueryTable("user").RelatedSel().Limit(3).OrderBy("-id").All(&users); err != nil { 119
58 fmt.Println(err) 120 // 切换为其他数据库以后
59 } else { 121 // 这个 Ormer 对象的其下的 api 调用都将使用这个数据库
60 fmt.Println(cnt) 122
61 for _, u := range users { 123 ```
62 fmt.Println(u.Id, u.Profile) 124
63 } 125 默认使用 `default` 数据库，无需调用 Using
64 } 126
127 #### Raw
128
129 使用 sql 语句直接进行操作
130
131 Raw 函数，返回一个 [RawSeter](Raw.md) 用以对设置的 sql 语句和参数进行操作
132
133 ```go
134 o := NewOrm()
135 var r RawSeter
136 r = o.Raw("UPDATE user SET user_name = ? WHERE user_name = ?", "testing", "slene")
137 ```
138
139 #### Driver
140
141 返回当前 orm 使用的 db 信息
142
143 ```go
144 type Driver interface {
145 Name() string
146 Type() DriverType
65 } 147 }
66 ```
...\ No newline at end of file ...\ No newline at end of file
148 ```
149
150 ```go
151 orm.RegisterDataBase("db1", "mysql", "root:root@/orm_db2?charset=utf8", 30)
152 orm.RegisterDataBase("db2", "sqlite3", "data.db", 30)
153
154 o1 := orm.NewOrm()
155 o1.Using("db1")
156 dr := o1.Driver()
157 fmt.Println(dr.Name() == "db1") // true
158 fmt.Println(dr.Type() == orm.DR_MySQL) // true
159
160 o2 := orm.NewOrm()
161 o2.Using("db2")
162 dr = o2.Driver()
163 fmt.Println(dr.Name() == "db2") // true
164 fmt.Println(dr.Type() == orm.DR_Sqlite) // true
165
166 ```
......
orm/docs/zh/Query.md
...@@ -13,7 +13,7 @@ qs := o.QueryTable("user") ...@@ -13,7 +13,7 @@ qs := o.QueryTable("user")
13 user := NewUser() 13 user := NewUser()
14 qs = o.QueryTable(user) // 返回 QuerySeter 14 qs = o.QueryTable(user) // 返回 QuerySeter
15 ``` 15 ```
16 ### expr 16 ## expr
17 17
18 QuerySeter 中用于描述字段和 sql 操作符使用简单的 expr 查询方法 18 QuerySeter 中用于描述字段和 sql 操作符使用简单的 expr 查询方法
19 19
...@@ -32,9 +32,20 @@ qs.Filter("profile__age__in", 18, 20) // WHERE profile.age IN (18, 20) ...@@ -32,9 +32,20 @@ qs.Filter("profile__age__in", 18, 20) // WHERE profile.age IN (18, 20)
32 qs.Filter("profile__age__in", 18, 20).Exclude("profile__money__lt", 1000) 32 qs.Filter("profile__age__in", 18, 20).Exclude("profile__money__lt", 1000)
33 // WHERE profile.age IN (18, 20) AND NOT profile.money < 1000 33 // WHERE profile.age IN (18, 20) AND NOT profile.money < 1000
34 ``` 34 ```
35 ### Operators 35 ## Operators
36 36
37 当前支持的操作符号 37 当前支持的操作符号：
38
39 * [exact](#exact) / [iexact](#iexact) 等于
40 * [contains](#contains) / [icontains](#icontains) 包含
41 * [gt / gte](#gt / gte) 大于 / 大于等于
42 * [lt / lte](#lt / lte) 小于 / 小于等于
43 * [startswith](#startswith) / [istartswith](#istartswith) 以...起始
44 * [endswith](#endswith) / [iendswith](#iendswith) 以...结束
45 * [in](#in)
46 * [isnull](#isnull)
47
48 后面以 `i` 开头的表示：大小写不敏感
38 49
39 #### exact 50 #### exact
40 51
...@@ -119,6 +130,29 @@ qs.Filter("profile__isnull", false) ...@@ -119,6 +130,29 @@ qs.Filter("profile__isnull", false)
119 ``` 130 ```
120 ## QuerySeter 131 ## QuerySeter
121 132
133 QuerySeter 当前支持的方法
134
135 * type QuerySeter interface {
136 * [Filter(string, ...interface{}) QuerySeter](#Filter)
137 * [Exclude(string, ...interface{}) QuerySeter](#Exclude)
138 * [SetCond(*Condition) QuerySeter](#SetCond)
139 * [Limit(int, ...int64) QuerySeter](#Limit)
140 * [Offset(int64) QuerySeter](#Offset)
141 * [OrderBy(...string) QuerySeter](#OrderBy)
142 * [RelatedSel(...interface{}) QuerySeter](#RelatedSel)
143 * [Count() (int64, error)](#Count)
144 * [Update(Params) (int64, error)](#Update)
145 * [Delete() (int64, error)](#Delete)
146 * [PrepareInsert() (Inserter, error)](#PrepareInsert)
147 * [All(interface{}) (int64, error)](#All)
148 * [One(Modeler) error](#One)
149 * [Values(*[]Params, ...string) (int64, error)](#Values)
150 * [ValuesList(*[]ParamsList, ...string) (int64, error)](#ValuesList)
151 * [ValuesFlat(*ParamsList, string) (int64, error)](#ValuesFlat)
152 * }
153
154 每个返回 QuerySeter 的 api 调用时都会新建一个 QuerySeter，不影响之前创建的。
155
122 #### Filter 156 #### Filter
123 157
124 多个 Filter 之间使用 `AND` 连接 158 多个 Filter 之间使用 `AND` 连接
...@@ -139,6 +173,21 @@ qs.Exclude("profile__isnull", true).Filter("user_name", "slene") ...@@ -139,6 +173,21 @@ qs.Exclude("profile__isnull", true).Filter("user_name", "slene")
139 173
140 #### SetCond 174 #### SetCond
141 175
176 自定义条件表达式
177
178 ```go
179 cond := NewCondition()
180 cond1 := cond.And("profile__isnull", false).AndNot("status__in", 1).Or("profile__age__gt", 2000)
181
182 qs := orm.QueryTable("user")
183 qs = qs.SetCond(cond1)
184 // WHERE ... AND ... AND NOT ... OR ...
185
186 cond2 := cond.AndCond(cond1).OrCond(cond.And("user_name", "slene"))
187 qs = qs.SetCond(cond2).Count()
188 // WHERE (... AND ... AND NOT ... OR ...) OR ( ... )
189 ```
190
142 #### Limit 191 #### Limit
143 192
144 限制最大返回数据行数，第二个参数可以设置 `Offset` 193 限制最大返回数据行数，第二个参数可以设置 `Offset`
...@@ -166,7 +215,7 @@ qs.Limit(-1, 100) ...@@ -166,7 +215,7 @@ qs.Limit(-1, 100)
166 215
167 设置 偏移行数 216 设置 偏移行数
168 ```go 217 ```go
169 qs.OFFSET(20) 218 qs.Offset(20)
170 // LIMIT 1000 OFFSET 20 219 // LIMIT 1000 OFFSET 20
171 ``` 220 ```
172 221
...@@ -226,6 +275,28 @@ fmt.Printf("Affected Num: %s, %s", num, err) ...@@ -226,6 +275,28 @@ fmt.Printf("Affected Num: %s, %s", num, err)
226 // DELETE FROM user WHERE user_name = "slene" 275 // DELETE FROM user WHERE user_name = "slene"
227 ``` 276 ```
228 277
278 #### PrepareInsert
279
280 用于一次 prepare 多次 insert 插入，以提高批量插入的速度。
281
282 ```go
283 var users []*User
284 ...
285 qs := dORM.QueryTable("user")
286 i, _ := qs.PrepareInsert()
287 for _, user := range users {
288 id, err := i.Insert(user)
289 if err != nil {
290 ...
291 }
292 }
293 // PREPARE INSERT INTO user (`user_name`, ...) VALUES (?, ...)
294 // EXECUTE INSERT INTO user (`user_name`, ...) VALUES ("slene", ...)
295 // EXECUTE ...
296 // ...
297 i.Close() // 别忘记关闭 statement
298 ```
299
229 #### All 300 #### All
230 返回对应的结果集对象 301 返回对应的结果集对象
231 ```go 302 ```go
...@@ -235,13 +306,20 @@ fmt.Printf("Returned Rows Num: %s, %s", num, err) ...@@ -235,13 +306,20 @@ fmt.Printf("Returned Rows Num: %s, %s", num, err)
235 ``` 306 ```
236 307
237 #### One 308 #### One
238 尝试返回单个对象 309
310 尝试返回单条记录
311
239 ```go 312 ```go
240 var user *User 313 var user *User
241 err := o.QueryTable("user").Filter("user_name", "slene").One(&user) 314 err := o.QueryTable("user").Filter("user_name", "slene").One(&user)
242 if err == orm.ErrMultiRows { 315 if err == orm.ErrMultiRows {
316 // 多条的时候报错
243 fmt.Printf("Returned Multi Rows Not One") 317 fmt.Printf("Returned Multi Rows Not One")
244 } 318 }
319 if err == orm.ErrNoRows {
320 // 没有找到记录
321 fmt.Printf("Not row found")
322 }
245 ``` 323 ```
246 324
247 #### Values 325 #### Values
...@@ -323,10 +401,5 @@ if err != nil { ...@@ -323,10 +401,5 @@ if err != nil {
323 } 401 }
324 ``` 402 ```
325 403
326 #### PrepareInsert
327
328 用于批量插入 prepare -> insert -> insert
329
330
331 404
332 405
......
orm/docs/zh/README.md
...@@ -27,8 +27,6 @@ func init() { ...@@ -27,8 +27,6 @@ func init() {
27 } 27 }
28 28
29 func main() { 29 func main() {
30 orm.BootStrap() // 确保在所有 RegisterModel 之后执行
31
32 o := orm.NewOrm() 30 o := orm.NewOrm()
33 31
34 user := User{Name: "slene"} 32 user := User{Name: "slene"}
...@@ -55,12 +53,18 @@ func main() { ...@@ -55,12 +53,18 @@ func main() {
55 53
56 ## 详细文档 54 ## 详细文档
57 55
58 1. [Model Definition](Models.md) 56 1. [模型定义](Models.md)
57 - [支持的 Field 类型](Models.md#Field Type)
58 - [Field 设置参数](Models.md#Field Options)
59 - [关系型 Field 设置](Models.md#Relation Field Options)
59 2. Custom Fields 60 2. Custom Fields
60 3. [Orm](Orm.md) 61 3. [Orm 使用方法](Orm.md)
61 4. [Object](Object.md) 62 - [Ormer 接口](Orm.md#Ormer)
62 5. [Query](Query.md) 63 4. [对象操作](Object.md)
63 6. Condition 64 5. [复杂查询](Query.md)
64 7. Raw 65 - [查询使用的表达式语法](Query.md#expr)
65 8. Transaction 66 - [查询支持的操作符号](Query.md#Operators)
66 9. Faq 67 - [QuerySeter 接口](Query.md#QuerySeter)
68 6. Raw
69 7. Transaction
70 8. Faq
......
Styling with Markdown is supported
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!