liangc/shaozhangmenBack @ e2a9957ccb75d24bac3053b894dfa44b6b61c533

BeetlSQL中文文档

作者: 闲大赋,Gavin.King,Sue,Zhoupan,woate

社区 http://ibeetl.com

qq群 219324263

当前版本 2.7.3 , 另外还需要beetl(http://git.oschina.net/xiandafu/beetl2.0/attach_files) 包

1. BeetlSQL 特点

BeetSql是一个全功能DAO工具，同时具有Hibernate 优点 & Mybatis优点功能，适用于承认以SQL为中心，同时又需求工具能自动能生成大量常用的SQL的应用。

开发效率
- 无需注解，自动使用大量内置SQL，轻易完成增删改查功能，节省50%的开发工作量
- 数据模型支持Pojo，也支持Map/List这种快速模型，也支持混合模型
- SQL 模板基于Beetl实现，更容易写和调试，以及扩展
- 可以针对单个表(或者视图）代码生成pojo类和sql模版，甚至是整个数据库。能减少代码编写工作量
维护性
- SQL 以更简洁的方式，Markdown方式集中管理，同时方便程序开发和数据库SQL调试。
- 可以自动将sql文件映射为dao接口类
- 灵活直观的支持支持一对一，一对多，多对多关系映射而不引入复杂的OR Mapping概念和技术。
- 具备Interceptor功能，可以调试，性能诊断SQL，以及扩展其他功能
其他
- 内置支持主从数据库支持的开源工具
- 支持跨数据库平台，开发者所需工作减少到最小，目前跨数据库支持mysql,postgres,oracle,sqlserver,h2,sqllite.

2. 5分钟例子

2.1. 安装

maven 方式:

<dependency>
	<groupId>com.ibeetl</groupId>
	<artifactId>beetlsql</artifactId>
	<version>2.7.3</version>
</dependency>

或者依次下载beetlsql，beetl 最新版本包放到classpath里

2.2. 准备工作

为了快速尝试BeetlSQL，需要准备一个Mysql数据库或者其他任何beetlsql支持的数据库，然后执行如下sql脚本

CREATE TABLE `user` (
	  `id` int(11) NOT NULL AUTO_INCREMENT,
	  `name` varchar(64) DEFAULT NULL,
	  `age` int(4) DEFAULT NULL,
	  `userName` varchar(64) DEFAULT NULL COMMENT '用户名称',
	  `roleId` int(11) DEFAULT NULL COMMENT '用户角色',
	  `date` datetime NULL DEFAULT NULL,
	  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

编写一个Pojo类，与数据库表对应（或者可以通过SQLManager的gen方法生成此类，参考一下节）

import java.math.*;
import java.util.Date;

/*
*
* gen by beetlsql 2016-01-06
*/
public class User  {
	private Integer id ;
	private Integer age ;
	//用户角色
	private Integer roleId ;
	private String name ;
	//用户名称
	private String userName ;
	private Date date ;

}

2.3. 代码例子

写一个java的Main方法，内容如下

ConnectionSource source = ConnectionSourceHelper.getSimple(driver, url, "", userName, password);
DBStyle mysql = new MySqlStyle();
// sql语句放在classpagth的/sql 目录下
SQLLoader loader = new ClasspathLoader("/sql");
// 数据库命名跟java命名一样，所以采用DefaultNameConversion，还有一个是UnderlinedNameConversion，下划线风格的
所以采用DefaultNameConversion nc = new  所以采用DefaultNameConversion();
// 最后，创建一个SQLManager,DebugInterceptor 不是必须的，但可以通过它查看sql执行情况
SQLManager sqlManager = new SQLManager(mysql,loader,source,nc,new Interceptor[]{new DebugInterceptor()});


//使用内置的生成的sql 新增用户，如果需要获取主键，可以传入KeyHolder
User user = new User();
user.setAge(19);
user.setName("xiandafu");
sqlManager.insert(user);

//使用内置sql查询用户
int id = 1;
user = sqlManager.unique(User.class,id);

//模板更新,仅仅根据id更新值不为null的列
User newUser = new User();
newUser.setId(1);
newUser.setAge(20);
sqlManager.updateTemplateById(newUser);

//模板查询
User query = new User();
query.setName("xiandafu");
List<User> list = sqlManager.template(query);


//使用user.md 文件里的select语句，参考下一节。
User query2 = new User();
query.setName("xiandafu");
List<User> list2 = sqlManager.select("user.select",User.class,query2);

2.4. SQL文件例子

通常一个项目还是有少量复杂sql，可能只有5，6行，也可能有上百行，放在单独的sql文件里更容易编写和维护，为了能执行上例的user.select,需要在classpath里建立一个sql目录（ClasspathLoader 配置成sql目录，参考上一节ClasspathLoader初始化的代码）以及下面的user.md 文件，内容如下

select
===
select * from user where 1=1
@if(!isEmpty(age)){
and age = #age#
@}
@if(!isEmpty(name)){
and name = #name#
@}

关于如何写sql模板，会稍后章节说明，如下是一些简单说明。

采用md格式，===上面是sql语句在本文件里的唯一标示，下面则是sql语句。
@ 和回车符号是定界符号，可以在里面写beetl语句。
"#" 是站位符号，生成sql语句得时候，将输出？，如果你想输出表达式值，需要用text函数，或者任何以db开头的函数，引擎则认为是直接输出文本。
isEmpty是beetl的一个函数，用来判断变量是否为空或者是否不存在.
文件名约定为类名，首字母小写。

sql模板采用beetl原因是因为beetl 语法类似js，且对模板渲染做了特定优化，相比于mybatis，更加容易掌握和功能强大，可读性更好，也容易在java和数据库之间迁移sql语句

2.5. 代码&sql生成

User类并非需要自己写，好的实践是可以在项目中专门写个类用来辅助生成pojo和sql片段，代码如下

public static void main(String[] args){
	SqlManager sqlManager  = ...... //同上面的例子
	sqlManager.genPojoCodeToConsole("user");
	sqlManager.genSQLTemplateToConsole("user");
}

注意:我经常在我的项目里写一个这样的辅助类，用来根据表或者视图生成各种代码和sql片段，以快速开发.

genPojoCodeToConsole 方法可以根据数据库表生成相应的Pojo代码，输出到控制台，开发者可以根据这些代码创建相应的类，如上例子，控制台将输出

package com.test;
import java.math.*;
import java.util.Date;
import java.sql.Timestamp;

/*
*
* gen by beetlsql 2016-01-06
*/
public class user  {
	private Integer id ;
	private Integer age ;
	//用户角色
	private Integer roleId ;
	private String name ;
	//用户名称
	private String userName ;
	private Date date ;

}

上述生成的代码有些瑕疵，比如包名总是com.test，类名是小写开头（因为用了DefaultNameConversion)，你需要修改成你要的包名和正常的类名，pojo类也没有生成getter，setter方法，你需要用ide自带的工具再次生成一下。

#### 注意

生成属性的时候，id总是在前面，后面依次是类型为Integer的类型，最后面是日期类型，剩下的按照字母排序放到中间。

一旦有了User 类，如果你需要些sql语句，那么genSQLTemplateToConsole 将是个很好的辅助方法，可以输出一系列sql语句片段，你同样可以赋值粘贴到代码或者sql模板文件里（user.md),如上例所述，当调用genSQLTemplateToConsole的时候，生成如下

sample
===
* 注释

	select #use("cols")# from user where #use("condition")#

cols
===

	id,name,age,userName,roleId,date

updateSample
===

	`id`=#id#,`name`=#name#,`age`=#age#,`userName`=#userName#,`roleId`=#roleId#,`date`=#date#

condition
===

	1 = 1
	@if(!isEmpty(name)){
	 and `name`=#name#
	@}
	@if(!isEmpty(age)){
	 and `age`=#age#
	@}

beetlsql生成了用于查询，更新，条件的sql片段和一个简单例子。你可以按照你的需要copy到sql模板文件里.实际上，如果你熟悉gen方法，你可以直接gen代码和sql到你的工程里，甚至是整个数据库都可以调用genAll来一次生成

#### 注意

sql 片段的生成顺序按照数据库表定义的顺序显示

3. BeetlSQL 说明

3.1. 获得SQLManager

SQLManager 是系统的核心，他提供了所有的dao方法。获得SQLManager，可以直接构造SQLManager.并通过过单例获取如：

ConnectionSource source = ConnectionSourceHelper.getSimple(driver, url, "", userName, password);
DBStyle mysql = new MySqlStyle();
// sql语句放在classpagth的/sql 目录下
SQLLoader loader = new ClasspathLoader("/sql");
// 数据库命名跟java命名一样，所以采用DefaultNameConversion，还有一个是UnderlinedNameConversion，下划线风格的
UnderlinedNameConversion nc = new  UnderlinedNameConversion();
// 最后，创建一个SQLManager,DebugInterceptor 不是必须的，但可以通过它查看sql执行情况
SQLManager sqlManager = new SQLManager(mysql,loader,source,nc,new Interceptor[]{new DebugInterceptor()});

更常见的是，已经有了DataSource，创建ConnectionSource 可以采用如下代码

ConnectionSource source = ConnectionSourceHelper.single(datasource);

如果是主从Datasource

ConnectionSource source = ConnectionSourceHelper.getMasterSlave(master,slaves)

3.2. 查询API

3.2.1. 模板类查询（自动生成sql）

public List all(Class clazz) 查询出所有结果集
public List all(Class clazz, int start, int size) 翻页
public int allCount(Class<?> clazz) 总数
public List template(T t) 根据模板查询，返回所有符合这个模板的数据库同上，mapper可以提供额外的映射，如处理一对多，一对一
public List template(T t,int start,int size) 同上，可以翻页
public long templateCount(T t) 获取符合条件的个数

翻页的start，系统默认位从1开始，为了兼容各个数据库系统，会自动翻译成数据库习俗，比如start为1，会认为mysql，postgres从0开始（从start－1开始），oralce从1开始（start－0）开始。

然而，如果你只用特定数据库，可以按照特定数据库习俗来，比如，你只用mysql，start为0代表起始纪录，需要配置

OFFSET_START_ZERO = true

这样，翻页参数start传入0即可。

注意:根据模板查询并不包含时间字段，也不包含排序，然而，可以通过在pojo class上使用@TableTemplate() 或者日期字段的getter方法上使用@DateTemplate()来定制，如下:

@TableTemplate("order by id desc ")
public class User  {
	private Integer id ;
	private Integer age ;
	// ...
	@DateTemplate(accept="minDate,maxDate")
	public Date getDate() {
		return date;
	}
}

这样，模板查询将添加order by id desc ,以及date字段将按照日期范围来查询。具体参考annotation一章

3.2.2. 通过sqlid查询,sql语句在md文件里

public List select(String sqlId, Class clazz, Map paras) 根据sqlid来查询，参数是个map
public List select(String sqlId, Class clazz, Object paras) 根据sqlid来查询，参数是个pojo
public List select(String sqlId, Class clazz, Map paras, int start, int size)，增加翻页
public List select(String sqlId, Class clazz, Object paras, int start, int size) ，增加翻页
public T selectSingle(String id,Object paras, Class target) 根据sqlid查询，输入是Pojo，将对应的唯一值映射成指定的taget对象，如果未找到，则返回空。需要注意的时候，有时候结果集本生是空，这时候建议使用unique
public T selectSingle(String id,Map paras, Class target) 根据sqlid查询，输入是Map，将对应的唯一值映射成指定的taget对象，如果未找到，则返回空。需要注意的时候，有时候结果集本生是空，这时候建议使用unique
public T selectUnique(String id,Object paras, Class target) 根据sqlid查询，输入是Pojo或者Map，将对应的唯一值映射成指定的taget对象,如果未找到，则抛出异常
public T selectUnique(String id,Map paras, Class target) 根据sqlid查询，输入是Pojo或者Map，将对应的唯一值映射成指定的taget对象,如果未找到，则抛出异常
public Integer intValue(String id,Object paras) 查询结果映射成Integer，如果找不到，返回null，输入是object
public Integer intValue(String id,Map paras) 查询结果映射成Integer，如果找不到，返回null，输入是map，其他还有 longValue，bigDecimalValue
public T unique(Class clazz,Object pk) 根据主键查询，如果未找到，抛出异常.
3.3. 翻页查询API
- public void pageQuery(String sqlId,Class clazz,PageQuery query)
  BeetlSQL 提供一个PageQUery对象,用于web应用的翻页查询,BeetlSql假定有sqlId 和sqlId$count,俩个sqlId,并用这来个来翻页和查询结果总数.如:
```
queryNewUser
===
select * from user order by id desc ;

queryNewUser$count
===
select count(1) from user
```
  对于俩个相似的sql语句,你可以使用use函数,把公共部分提炼出来.
  
  大部分情况下,都不需要2个sql来完成,一个sql也可以,要求使用page函数或者pageTag标签,这样才能同时获得查询结果集总数和当前查询的结果
```
queryNewUser
===
select
@pageTag(){
a.*,b.name role_name
@}
from user a left join b ...
```
  如上sql,会在查询的时候转为俩条sql语句
```
select count(1) from user a left join b...
select a.*,b.name role_name  from user a left join b...
```
  如果字段较多,为了输出方便,也可以使用pageTag,字段较少,用page函数也可以. ,具体参考pageTag和page函数说明.翻页代码如下
```
//从第一页开始查询,无参数
PageQuery query = new PageQuery();
sql.pageQuery("user.queryNewUser", User.class,query);
System.out.println(query.getTotalPage());
System.out.println(query.getTotalRow());
System.out.println(query.getPageNumber());
List<User> list = query.getList();
```
  PageQuery 对象也提供了 orderBy属性，用于数据库排序，如 "id desc"
  
  #### 跨数据库支持
  
  如果你打算使用PageQuery做翻页,且只想提供一个sql语句+page函数,那考虑到垮数据库,应该不要在这个sql语句里包含排序,因为大部分数据库都不支持. page函数生成的查询总数sql语句,因为包含了oder by,在大部分数据库都是会报错的的,比如:select count(1) form user order by name,在sqlserver,mysql,postgres都会出错,oracle允许这种情况, 因此,如果你要使用一条sql语句+page函数,建议排序用PageQuery对象里有排序属性oderBy,可用于排序,而不是放在sql语句里.
  
  如果你不打算使用PageQuery+一条sql的方式,而是用俩条sql来分别翻页查询和统计总数,那无所谓
  
  或者你直接使用select 带有起始和读取总数的接口,也没有关系,可以在sql语句里包含排序
  
  3.4. 更新API
  
  3.4.1. 自动生成sql
  - public void insert(Class<?> clazz,Object paras) 插入paras到paras关联的表
  - public void insert(Class<?> clazz,Object paras,KeyHolder holder)，插入paras到paras关联的表，如果需要主键，可以通过holder的getKey来获取
  - public int insert(Class clazz,Object paras,boolean autoAssignKey) 插入paras，并且指定是否自动将数据库主键赋值到paras里
  - public int updateById(Object obj) 根据主键更新，主键通过annotation表示，如果没有，则认为属性id是主键，所有值参与更新
  - public int updateTemplateById(Object obj) 根据主键更新，组件通过annotation表示，如果没有，则认为属性id是主键,属性为null的不会更新
  - public int updateTemplateById(Class<?> clazz，Map paras) 根据主键更新，组件通过clazz的annotation表示，如果没有，则认为属性id是主键,属性为null的不会更新。
  - public int[] updateByIdBatch(List<?> list) 批量更新
  - public void insertBatch(Class clazz,List<?> list) 批量插入数据
  3.4.2. 通过sqlid更新
  - public int insert(String sqlId,Object paras,KeyHolder holder) 根据sqlId 插入，并返回主键，主键id由paras对象所指定
  - public int insert(String sqlId,Object paras,KeyHolder holder,String keyName) 同上，主键由keyName指定
  - public int insert(String sqlId,Map paras,KeyHolder holder,String keyName)，同上，参数通过map提供
  - public int update(String sqlId, Object obj) 根据sqlid更新
  - public int update(String sqlId, Map paras) 根据sqlid更新，输出参数是map
  - public int[] updateBatch(String sqlId,List<?> list) 批量更新
  - public int[] updateBatch(String sqlId,Map[] maps) 批量更新，参数是个数组，元素类型是map

beetlsql.md 67 KB Histórico Raw

BeetlSQL中文文档

1. BeetlSQL 特点

2. 5分钟例子

2.1. 安装

2.2. 准备工作

2.3. 代码例子

2.4. SQL文件例子

2.5. 代码&sql生成

3. BeetlSQL 说明

3.1. 获得SQLManager

3.2. 查询API

3.2.1. 模板类查询（自动生成sql）

3.2.2. 通过sqlid查询,sql语句在md文件里

3.3. 翻页查询API

3.4. 更新API

3.4.1. 自动生成sql

3.4.2. 通过sqlid更新

3.5. 直接执行SQL

3.5.1. 直接执行sql模板语句

3.5.2. 直接执行JDBC sql语句

3.6. 其他

3.6.1. 强制使用主或者从

3.6.2. 生成Pojo代码和SQ片段

4. 命名转化，表和列名映射

5. 复合主键

6. 使用Mapper

7. BeetlSQL Annotation

7.1. @AutoID 和 @AssignID ，@SeqID

7.2. @Tail

7.3. @ColumnIgnore

7.4. @EnumMapping

7.5. @Table

7.6. @TableTemplate

7.7. Mapper相关注解

7.8. ORMQuery

8. BeetlSQL 数据模型

9. Markdown方式管理

10. SQL 注释

11. (重要) 配置beetlsql

11.1. 开发模式和产品模式

11.2. NameConversion

11.3. 模板字符集

11.4. 翻页起始参数是0还是1

11.5. 自定义方法和标签函数

12. SQL 模板基于Beetl实现

13. Beetl 入门

13.1. 定界符号

13.2. 变量

13.3. 算数表达式

13.4. 逻辑表达式

13.5. 控制语句

13.6. 访问变量属性

13.7. 判断对象非空空

13.8. 调用方法

13.9. 自定义方法

13.10. 内置方法

13.11. 标签功能

14. Debug功能

15. 缓存功能

16. Interceptor功能

17. 内置支持主从数据库

18. 可以支持更复杂的分库分表逻辑

19. 跨数据库平台

20. 代码生成

20.1. 生成pojo 和 md文件

20.2. 生成更多的代码

21. 直接使用SQLResult

22. Hibernate,MyBatis,MySQL 对比

23. ORM

23.1. sql语句里的ORM查询

23.2. ORM 注解

24. 集成和Demo

24.1. Spring集成和Demo

参考

24.2. SpringBoot集成

24.3. JFinal集成和Demo

beetlsql.md 67 KB

Histórico Raw