github.com/insionng/yougam@v0.0.0-20170714101924-2bc18d833463/libraries/go-xorm/xorm/README_CN.md (about)

     1  # xorm
     2  
     3  [English](https://github.com/go-xorm/xorm/blob/master/README.md)
     4  
     5  xorm是一个简单而强大的Go语言ORM库. 通过它可以使数据库操作非常简便。
     6  
     7  [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/go-xorm/xorm?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
     8  
     9  [![Build Status](https://drone.io/github.com/go-xorm/tests/status.png)](https://drone.io/github.com/go-xorm/tests/latest)  [![Go Walker](http://gowalker.org/api/v1/badge)](http://gowalker.org/github.com/go-xorm/xorm)
    10  
    11  # 注意
    12  
    13  最新的版本有不兼容的更新，您必须使用 `engine.ShowSQL()` 和 `engine.Logger().SetLevel()` 来替代 `engine.ShowSQL = `, `engine.ShowInfo = ` 等等。
    14  
    15  ## 特性
    16  
    17  * 支持Struct和数据库表之间的灵活映射，并支持自动同步
    18  
    19  * 事务支持
    20  
    21  * 同时支持原始SQL语句和ORM操作的混合执行
    22  
    23  * 使用连写来简化调用
    24  
    25  * 支持使用Id, In, Where, Limit, Join, Having, Table, Sql, Cols等函数和结构体等方式作为条件
    26  
    27  * 支持级联加载Struct
    28  
    29  * 支持缓存
    30  
    31  * 支持根据数据库自动生成xorm的结构体
    32  
    33  * 支持记录版本（即乐观锁）
    34  
    35  * 内置SQL Builder支持
    36  
    37  ## 驱动支持
    38  
    39  目前支持的Go数据库驱动和对应的数据库如下：
    40  
    41  * Mysql: [github.com/go-sql-driver/mysql](https://github.com/go-sql-driver/mysql)
    42  
    43  * MyMysql: [github.com/ziutek/mymysql/godrv](https://github.com/ziutek/mymysql/godrv)
    44  
    45  * Postgres: [github.com/lib/pq](https://github.com/lib/pq)
    46  
    47  * Tidb: [github.com/pingcap/tidb](https://github.com/pingcap/tidb)
    48  
    49  * SQLite: [github.com/mattn/go-sqlite3](https://github.com/mattn/go-sqlite3)
    50  
    51  * MsSql: [github.com/denisenkom/go-mssqldb](https://github.com/denisenkom/go-mssqldb)
    52  
    53  * MsSql: [github.com/lunny/godbc](https://github.com/lunny/godbc)
    54  
    55  * Oracle: [github.com/mattn/go-oci8](https://github.com/mattn/go-oci8) (试验性支持)
    56  
    57  ## 更新日志
    58  
    59  * **v0.6.0**
    60      * 去除对 ql 的支持
    61      * 新增条件查询分析器 [github.com/go-xorm/builder](https://github.com/go-xorm/builder), 从因此 `Where, And, Or` 函数
    62  将可以用 `builder.Cond` 作为条件组合
    63      * 新增 Sum, SumInt, SumInt64 和 NotIn 函数
    64      * Bug修正
    65  
    66  * **v0.5.0**
    67      * logging接口进行不兼容改变
    68      * Bug修正
    69  
    70  * **v0.4.5**
    71      * bug修正
    72      * extends 支持无限级
    73      * Delete Limit 支持
    74  
    75  * **v0.4.4**
    76      * Tidb 数据库支持
    77      * QL 试验性支持
    78      * sql.NullString支持
    79      * ForUpdate 支持
    80      * bug修正
    81  
    82  [更多更新日志...](https://github.com/go-xorm/manual-zh-CN/tree/master/chapter-16)
    83  
    84  ## 安装
    85  
    86  推荐使用 [gopm](https://github.com/gpmgo/gopm) 进行安装：
    87  
    88  	gopm get github.com/go-xorm/xorm
    89  
    90  或者您也可以使用go工具进行安装：
    91  
    92  	go get github.com/go-xorm/xorm
    93  
    94  ## 文档
    95  
    96  * [操作指南](http://xorm.io/docs)
    97  
    98  * [GoWalker代码文档](http://gowalker.org/github.com/go-xorm/xorm)
    99  
   100  * [Godoc代码文档](http://godoc.org/github.com/go-xorm/xorm)
   101  
   102  # 快速开始
   103  
   104  * 第一步创建引擎，driverName, dataSourceName和database/sql接口相同
   105  
   106  ```Go
   107  engine, err := xorm.NewEngine(driverName, dataSourceName)
   108  ```
   109  
   110  * 定义一个和表同步的结构体，并且自动同步结构体到数据库
   111  
   112  ```Go
   113  type User struct {
   114      Id int64
   115      Name string
   116      Salt string
   117      Age int
   118      Passwd string `xorm:"varchar(200)"`
   119      Created time.Time `xorm:"created"`
   120      Updated time.Time `xorm:"updated"`
   121  }
   122  
   123  err := engine.Sync2(new(User))
   124  ```
   125  
   126  * 最原始的也支持SQL语句查询，返回的结果类型为 []map[string][]byte
   127  
   128  ```Go
   129  results, err := engine.Query("select * from user")
   130  ```
   131  
   132  * 执行一个SQL语句
   133  
   134  ```Go
   135  affected, err := engine.Exec("update user set age = ? where name = ?", age, name)
   136  ```
   137  
   138  * 插入一条或者多条记录
   139  
   140  ```Go
   141  affected, err := engine.Insert(&user)
   142  // INSERT INTO struct () values ()
   143  affected, err := engine.Insert(&user1, &user2)
   144  // INSERT INTO struct1 () values ()
   145  // INSERT INTO struct2 () values ()
   146  affected, err := engine.Insert(&users)
   147  // INSERT INTO struct () values (),(),()
   148  affected, err := engine.Insert(&user1, &users)
   149  // INSERT INTO struct1 () values ()
   150  // INSERT INTO struct2 () values (),(),()
   151  ```
   152  
   153  * 查询单条记录
   154  
   155  ```Go
   156  has, err := engine.Get(&user)
   157  // SELECT * FROM user LIMIT 1
   158  has, err := engine.Where("name = ?", name).Desc("id").Get(&user)
   159  // SELECT * FROM user WHERE name = ? ORDER BY id DESC LIMIT 1
   160  ```
   161  
   162  * 查询多条记录，当然可以使用Join和extends来组合使用
   163  
   164  ```Go
   165  var users []User
   166  err := engine.Where("name = ?", name).And("age > 10").Limit(10, 0).Find(&users)
   167  // SELECT * FROM user WHERE name = ? AND age > 10 limit 0 offset 10
   168  
   169  type Detail struct {
   170      Id int64
   171      UserId int64 `xorm:"index"`
   172  }
   173  
   174  type UserDetail struct {
   175      User `xorm:"extends"`
   176      Detail `xorm:"extends"`
   177  }
   178  
   179  var users []UserDetail
   180  err := engine.Table("user").Select("user.*, detail.*")
   181      Join("INNER", "detail", "detail.user_id = user.id").
   182      Where("user.name = ?", name).Limit(10, 0).
   183      Find(&users)
   184  // SELECT user.*, detail.* FROM user INNER JOIN detail WHERE user.name = ? limit 0 offset 10
   185  ```
   186  
   187  * 根据条件遍历数据库，可以有两种方式: Iterate and Rows
   188  
   189  ```Go
   190  err := engine.Iterate(&User{Name:name}, func(idx int, bean interface{}) error {
   191      user := bean.(*User)
   192      return nil
   193  })
   194  // SELECT * FROM user
   195  
   196  rows, err := engine.Rows(&User{Name:name})
   197  // SELECT * FROM user
   198  defer rows.Close()
   199  bean := new(Struct)
   200  for rows.Next() {
   201      err = rows.Scan(bean)
   202  }
   203  ```
   204  
   205  * 更新数据，除非使用Cols,AllCols函数指明，默认只更新非空和非0的字段
   206  
   207  ```Go
   208  affected, err := engine.Id(1).Update(&user)
   209  // UPDATE user SET ... Where id = ?
   210  
   211  affected, err := engine.Update(&user, &User{Name:name})
   212  // UPDATE user SET ... Where name = ?
   213  
   214  var ids = []int64{1, 2, 3}
   215  affected, err := engine.In(ids).Update(&user)
   216  // UPDATE user SET ... Where id IN (?, ?, ?)
   217  
   218  // force update indicated columns by Cols
   219  affected, err := engine.Id(1).Cols("age").Update(&User{Name:name, Age: 12})
   220  // UPDATE user SET age = ?, updated=? Where id = ?
   221  
   222  // force NOT update indicated columns by Omit
   223  affected, err := engine.Id(1).Omit("name").Update(&User{Name:name, Age: 12})
   224  // UPDATE user SET age = ?, updated=? Where id = ?
   225  
   226  affected, err := engine.Id(1).AllCols().Update(&user)
   227  // UPDATE user SET name=?,age=?,salt=?,passwd=?,updated=? Where id = ?
   228  ```
   229  
   230  * 删除记录，需要注意，删除必须至少有一个条件，否则会报错。要清空数据库可以用EmptyTable
   231  
   232  ```Go
   233  affected, err := engine.Where(...).Delete(&user)
   234  // DELETE FROM user Where ...
   235  ```
   236  
   237  * 获取记录条数
   238  
   239  ```Go
   240  counts, err := engine.Count(&user)
   241  // SELECT count(*) AS total FROM user
   242  ```
   243  
   244  * 条件编辑器
   245  
   246  ```Go
   247  err := engine.Where(builder.NotIn("a", 1, 2).And(builder.In("b", "c", "d", "e"))).Find(&users)
   248  // SELECT id, name ... FROM user WHERE a NOT IN (?, ?) AND b IN (?, ?, ?)
   249  ```
   250  
   251  # 案例
   252  
   253  * [github.com/m3ng9i/qreader](https://github.com/m3ng9i/qreader)
   254  
   255  * [Wego](http://github.com/go-tango/wego)
   256  
   257  * [Docker.cn](https://docker.cn/)
   258  
   259  * [Gogs](http://try.gogits.org) - [github.com/gogits/gogs](http://github.com/gogits/gogs)
   260  
   261  * [Gowalker](http://gowalker.org) - [github.com/Unknwon/gowalker](http://github.com/Unknwon/gowalker)
   262  
   263  * [Gobuild.io](http://gobuild.io) - [github.com/shxsun/gobuild](http://github.com/shxsun/gobuild)
   264  
   265  * [Sudo China](http://sudochina.com) - [github.com/insionng/toropress](http://github.com/insionng/toropress)
   266  
   267  * [Godaily](http://godaily.org) - [github.com/govc/godaily](http://github.com/govc/godaily)
   268  
   269  * [YouGam](http://www.yougam.com/)
   270  
   271  * [GoCMS - github.com/zzboy/GoCMS](https://github.com/zzdboy/GoCMS)
   272  
   273  * [GoBBS - gobbs.domolo.com](http://gobbs.domolo.com/)
   274  
   275  * [go-blog](http://wangcheng.me) - [github.com/easykoo/go-blog](https://github.com/easykoo/go-blog)
   276  
   277  ## 讨论
   278  
   279  请加入QQ群：280360085 进行讨论。
   280  
   281  ## 贡献
   282  
   283  如果您也想为Xorm贡献您的力量，请查看 [CONTRIBUTING](https://github.com/go-xorm/xorm/blob/master/CONTRIBUTING.md)
   284  
   285  ## LICENSE
   286  
   287  BSD License
   288  [http://creativecommons.org/licenses/BSD/](http://creativecommons.org/licenses/BSD/)