borm

🏎️ 更好的ORM库 (Better ORM library that is simple, fast and self-mockable for Go)

目标

易用：SQL-Like（一把梭：One-Line-CRUD）
KISS：保持小而美（不做大而全）
通用：支持struct，pb，map和基本类型
可测：支持自mock（因为参数作返回值，大部分mock框架不支持）
- 非测试向的library不是好library
As-Is：尽可能不作隐藏设定，防止误用
解决核心痛点：
- 手撸SQL难免有错，组装数据太花时间
- time.Time无法直接读写的问题
- SQL函数结果无法直接Scan
- db操作无法方便的Mock
- QueryRow的sql.ErrNoRows问题
- 直接替换系统自带Scanner，完整接管数据读取的类型转换
核心原则：
- 别像使用其他orm那样把一个表映射到一个model
- （在borm里可以用Fields过滤器做到）
- 尽量保持简单把一个操作映射一个model吧！
其他优点：
- 更自然的where条件（仅在需要加括号时添加，对比gorm）
- In操作接受各种类型slice，并且单元素时转成Equal操作
- 从其他orm库迁移无需修改历史代码，无侵入性修改

特性矩阵

下面是和一些主流orm库的对比（请不吝开issue勘误）

库		borm (me)	gorm	xorm	备注
易用性	无需指定类型	✅	❌	❌	borm在tag中无需低频的DDL
	无需指定model	✅	❌	❌	gorm/xorm改操作需提供“模版”
	无需指定主键	✅	❌	❌	gorm/xorm易误操作，如删/改全表
	学习成本低	✅	❌	❌	会SQL就会用borm
	可复用原生连接	✅	❌	❌	borm重构成本极小
	全类型转换	✅	maybe	❌	杜绝类型转换的抛错
	复用查询命令	✅	❌	❌	borm批量和单条使用同一个函数
可测试性	自mock	✅	❌	❌	borm非常便于单元测试
性能	较原生耗时	<=1x	2~3x	2~3x	xorm使用prepare模式会再慢2～3x
性能	反射	reflect2	reflect	reflect	borm零使用ValueOf

快速入门

引入包
```
import b "github.com/orca-zhang/borm"
```

定义Table对象

t := b.Table(d.DB, "t_usr")

t1 := b.Table(d.DB, "t_usr", ctx)

d.DB是支持Exec/Query/QueryRow的数据库连接对象
t_usr可以是表名，或者是嵌套查询语句
ctx是需要传递的Context对象，默认不传为context.Background()

（可选）定义model对象

// Info 默认未设置borm tag的字段不会取
type Info struct {
   ID   int64  `borm:"id"`
   Name string `borm:"name"`
   Tag  string `borm:"tag"`
}

// 调用t.UseNameWhenTagEmpty()，可以用未设置borm tag的字段名本身作为待获取的db字段

执行操作

CRUD接口返回值为 (影响的条数，错误)
类型V为map[string]interface{}的缩写形式，参考gin.H

插入

// o可以是对象/slice/ptr slice
n, err = t.Insert(&o)
n, err = t.InsertIgnore(&o)
n, err = t.ReplaceInto(&o)

// 只插入部分字段（其他使用缺省）
n, err = t.Insert(&o, b.Fields("name", "tag"))

// 解决主键冲突
n, err = t.Insert(&o, b.Fields("name", "tag"),
   b.OnDuplicateKeyUpdate(b.V{
      "name": "new_name",
      "age":  b.U("age+1"), // 使用b.U来处理非变量更新
   }))

查询

// o可以是对象/slice/ptr slice
n, err := t.Select(&o, 
   b.Where("name = ?", name), 
   b.GroupBy("id"), 
   b.Having(b.Gt("id", 0)), 
   b.OrderBy("id", "name"), 
   b.Limit(1))

// 使用基本类型+Fields获取条目数（n的值为1，因为结果只有1条）
var cnt int64
n, err = t.Select(&cnt, b.Fields("count(1)"), b.Where("name = ?", name))

// 还可以支持数组
var ids []int64
n, err = t.Select(&ids, b.Fields("id"), b.Where("name = ?", name))

// 可以强制索引
n, err = t.Select(&ids, b.Fields("id"), b.ForceIndex("idx_xxx"), b.Where("name = ?", name))

更新

// o可以是对象/slice/ptr slice
n, err = t.Update(&o, b.Where(b.Eq("id", id)))

// 使用map更新
n, err = t.Update(b.V{
      "name": "new_name",
      "tag":  "tag1,tag2,tag3",
      "age":  b.U("age+1"), // 使用b.U来处理非变量更新
   }, b.Where(b.Eq("id", id)), b.Limit(1))

// 使用map更新部分字段
n, err = t.Update(b.V{
      "name": "new_name",
      "tag":  "tag1,tag2,tag3",
   }, b.Fields("name"), b.Where(b.Eq("id", id)), b.Limit(1))

n, err = t.Update(&o, b.Fields("name"), b.Where(b.Eq("id", id)), b.Limit(1))

删除

// 根据条件删除
n, err = t.Delete(b.Where("name = ?", name))

// 根据条件删除部分条数
n, err = t.Delete(b.Where(b.Eq("id", id)), b.Limit(1))

可变条件

conds := []interface{}{b.Cond("1=1")} // 防止空where条件
if name != "" {
   conds = append(conds, b.Eq("name", name))
}
if id > 0 {
   conds = append(conds, b.Eq("id", id))
}
// 执行查询操作
n, err := t.Select(&o, b.Where(conds...))

联表查询(临时)

type Info struct {
   ID   int64  `borm:"t_usr.id"` // 字段定义加表名
   Name string `borm:"t_usr.name"`
   Tag  string `borm:"t_tag.tag"`
}

t := b.Table(d.DB, "t_usr join t_tag on t_usr.id=t_tag.id") // 表名用join语句

var o Info
n, err := t.Select(&o, b.Where(b.Eq("t_usr.id", id))) // 条件加上表名

获取插入的自增id

// 首先需要数据库有一个自增ID的字段
type Info struct {
   BormLastId int64 // 添加一个名为BormLastId的整型字段
   Name       string `borm:"name"`
   Age        string `borm:"age"`
}

o := Info{
   Name: "OrcaZ",
   Age:  30,
}
n, err = t.Insert(&o)

id := o.BormLastId // 获取到插入的id

正在使用其他orm框架（新的接口先切过来吧）

// [gorm] db是一个*gorm.DB
t := b.Table(db.DB(), "tbl")

// [xorm] db是一个*xorm.EngineGroup
t := b.Table(db.Master().DB().DB, "tbl")
// or
t := b.Table(db.Slave().DB().DB, "tbl")

其他细节

Table的选项

选项	说明
Debug	打印sql语句
Reuse	根据调用位置复用sql和存储方式
UseNameWhenTagEmpty	用未设置borm tag的字段名本身作为待获取的db字段
ToTimestamp	调用Insert时，使用时间戳，而非格式化字符串

选项使用示例：

n, err = t.Debug().Insert(&o)

n, err = t.ToTimestamp().Insert(&o)

Where

示例	说明
Where("id=? and name=?", id, name)	常规格式化版本
Where(Eq("id", id), Eq("name", name)...)	默认为and连接
Where(And(Eq("x", x), Eq("y", y), Or(Eq("x", x), Eq("y", y)...)...)	And & Or

预置Where条件

名称	示例	说明
逻辑与	And(...)	任意个参数，只接受下方的关系运算子
逻辑或	Or(...)	任意个参数，只接受下方的关系运算子
普通条件	Cond("id=?", id)	参数1为格式化字符串，后面跟占位参数
相等	Eq("id", id)	两个参数，id=?
不相等	Neq("id", id)	两个参数，id<>?
大于	Gt("id", id)	两个参数，id>?
大于等于	Gte("id", id)	两个参数，id>=?
小于	Lt("id", id)	两个参数，id<?
小于等于	Lte("id", id)	两个参数，id<=?
在...之间	Between("id", start, end)	三个参数，在start和end之间
近似	Like("name", "x%")	两个参数，name like "x%"
多值选择	In("id", ids)	两个参数，ids是基础类型的slice，slice只有1个元素会转化成Eq

GroupBy

示例	说明
GroupBy("id", "name"...)	-

Having

示例	说明
Having("id=? and name=?", id, name)	常规格式化版本
Having(Eq("id", id), Eq("name", name)...)	默认为and连接
Having(And(Eq("x", x), Eq("y", y), Or(Eq("x", x), Eq("y", y)...)...)	And & Or

OrderBy

示例	说明
OrderBy("id desc", "name asc"...)	-

Limit

示例	说明
Limit(1)	分页大小为1
Limit(0, 100)	偏移位置为0，分页大小为100

OnDuplicateKeyUpdate

示例	说明
OnDuplicateKeyUpdate(V{"name": "new"})	解决主键冲突的更新

ForceIndex

示例	说明
ForceIndex("idx_biz_id")	解决索引选择性差的问题

如何mock

mock步骤：

调用BormMock指定需要mock的操作
使用BormMockFinish检查是否命中mock

说明：

前五个参数分别为tbl, fun, caller, file, pkg

设置为空默认为匹配
支持通配符'?'和'*'，分别代表匹配一个字符和多个字符

不区分大小写

参数	名称	说明
tbl	表名	数据库的表名
fun	方法名	Select/Insert/Update/Delete
caller	调用方方法名	需要带包名
file	文件名	使用处所在文件路径
pkg	包名	使用处所在的包名

后三个参数分别为返回的数据，返回的影响条数和错误
只能在测试文件中使用

使用示例：

待测函数：

   package x

   func test(db *sql.DB) (X, int, error) {
      var o X
      tbl := b.Table(db, "tbl")
      n, err := tbl.Select(&o, b.Where("`id` >= ?", 1), b.Limit(100))
      return o, n, err
   }

在x.test方法中查询tbl的数据，我们需要mock数据库的操作

   // 必须在_test.go里面设置mock
   // 注意调用方方法名需要带包名
   b.BormMock("tbl", "Select", "*.test", "", "", &o, 1, nil)

   // 调用被测试函数
   o1, n1, err := test(db)

   So(err, ShouldBeNil)
   So(n1, ShouldEqual, 1)
   So(o1, ShouldResemble, o)

   // 检查是否全部命中
   err = b.BormMockFinish()
   So(err, ShouldBeNil)

待完成

Select存储到map
Insert从map读
Insert/Update支持非指针类型
Benchmark报告
事务相关支持
联合查询
匿名组合问题
连接池
读写分离

Name		Name	Last commit message	Last commit date
.semaphore		.semaphore
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
borm.go		borm.go
borm_test.go		borm_test.go

Navigation Menu

Repository files navigation

borm

目标

特性矩阵

下面是和一些主流orm库的对比（请不吝开issue勘误）

快速入门

其他细节

Table的选项

Where

预置Where条件

GroupBy

Having

OrderBy

Limit

OnDuplicateKeyUpdate

ForceIndex

如何mock

mock步骤：

说明：

使用示例：

待完成

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

borm

目标

特性矩阵

下面是和一些主流orm库的对比（请不吝开issue勘误）

快速入门

其他细节

Table的选项

Where

预置Where条件

GroupBy

Having

OrderBy

Limit

OnDuplicateKeyUpdate

ForceIndex

如何mock

mock步骤：

说明：

使用示例：

待完成

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages