From 0efb0340eff26b2245525f051e184e6fd9e05a02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BC=80=E6=BA=90=E6=B5=B7=E5=93=A5?= Date: Sun, 5 Mar 2023 16:28:56 +0800 Subject: [PATCH] update docs --- docs/zh/{row_and_db.md => db_row.md} | 0 readme_zh.md | 185 +++++++++++++++------------ 2 files changed, 102 insertions(+), 83 deletions(-) rename docs/zh/{row_and_db.md => db_row.md} (100%) diff --git a/docs/zh/row_and_db.md b/docs/zh/db_row.md similarity index 100% rename from docs/zh/row_and_db.md rename to docs/zh/db_row.md diff --git a/readme_zh.md b/readme_zh.md index ee20b692..a3539d9f 100644 --- a/readme_zh.md +++ b/readme_zh.md @@ -1,4 +1,3 @@ - # Mybatis-Flex 一个优雅的 Mybatis 增强框架 ## 特征 @@ -19,18 +18,17 @@ ![](./docs/assets/images/qq_group.png) - ## 开始 - [Maven 依赖](./docs/zh/maven.md) - [示例项目](./mybatis-flex-test) - ## hello world **第一步：编写 Entity 实体类** ```java + @Table("tb_account") public class Account { @@ -55,6 +53,7 @@ public interface AccountMapper extends BaseMapper { **第三步：开始查询数据** 示例 1：查询 1 条数据 + ```java class HelloWorld { public static void main(String... args) { @@ -83,7 +82,7 @@ class HelloWorld { ```java //示例2：通过 QueryWrapper 构建条件查询数据列表 -QueryWrapper query = QueryWrapper.create() +QueryWrapper query=QueryWrapper.create() .select() .from(ACCOUNT) .where(ACCOUNT.ID.ge(100)) @@ -93,17 +92,18 @@ QueryWrapper query = QueryWrapper.create() // ELECT * FROM `tb_account` // WHERE `tb_account`.`id` >= 100 // AND (`tb_account`.`user_name` LIKE '%张%' OR `tb_account`.`user_name` LIKE '%李%' ) -List accounts = MybatisFlexBootstrap.getInstance() - .execute(AccountMapper.class, mapper -> - mapper.selectListByQuery(query) + List accounts=MybatisFlexBootstrap.getInstance() + .execute(AccountMapper.class,mapper-> + mapper.selectListByQuery(query) ); ``` 示例3：分页查询 + ```java // 示例3：分页查询 // 查询第 5 页，每页 10 条数据，通过 QueryWrapper 构建条件查询 -QueryWrapper query = QueryWrapper.create() +QueryWrapper query=QueryWrapper.create() .select() .from(ACCOUNT) .where(ACCOUNT.ID.ge(100)) @@ -116,9 +116,9 @@ QueryWrapper query = QueryWrapper.create() // AND (`user_name` LIKE '%张%' OR `user_name` LIKE '%李%' ) // ORDER BY `id` DESC // LIMIT 40,10 -Page accounts = MybatisFlexBootstrap.getInstance() - .execute(AccountMapper.class, mapper -> - mapper.paginate(5, 10, query) + Page accounts=MybatisFlexBootstrap.getInstance() + .execute(AccountMapper.class,mapper-> + mapper.paginate(5,10,query) ); ``` @@ -127,8 +127,8 @@ Page accounts = MybatisFlexBootstrap.getInstance() ### select * ```java -QueryWrapper query = new QueryWrapper(); -query.select().from(ACCOUNT) +QueryWrapper query=new QueryWrapper(); + query.select().from(ACCOUNT) // SQL: // SELECT * FROM tb_account @@ -137,8 +137,8 @@ query.select().from(ACCOUNT) ### select columns ```java -QueryWrapper query = new QueryWrapper(); -query.select(ACCOUNT.ID,ACCOUNT.USER_NAME).from(ACCOUNT) +QueryWrapper query=new QueryWrapper(); + query.select(ACCOUNT.ID,ACCOUNT.USER_NAME).from(ACCOUNT) // SQL: // SELECT id, user_name @@ -147,7 +147,7 @@ query.select(ACCOUNT.ID,ACCOUNT.USER_NAME).from(ACCOUNT) ```java QueryWrapper query=new QueryWrapper(); -query.select(ACCOUNT.ALL_COLUMNS).from(ACCOUNT) + query.select(ACCOUNT.ALL_COLUMNS).from(ACCOUNT) // SQL: // SELECT id, user_name, birthday, sex, is_normal @@ -159,10 +159,10 @@ query.select(ACCOUNT.ALL_COLUMNS).from(ACCOUNT) ```java QueryWrapper query=new QueryWrapper() .select( - ACCOUNT.ID, - ACCOUNT.USER_NAME, - max(ACCOUNT.BIRTHDAY), - avg(ACCOUNT.SEX).as("sex_avg") + ACCOUNT.ID, + ACCOUNT.USER_NAME, + max(ACCOUNT.BIRTHDAY), + avg(ACCOUNT.SEX).as("sex_avg") ).from(ACCOUNT); // SQL: @@ -176,10 +176,10 @@ query.select(ACCOUNT.ALL_COLUMNS).from(ACCOUNT) ```java QueryWrapper queryWrapper=QueryWrapper.create() - .select() - .from(ACCOUNT) - .where(ACCOUNT.ID.ge(100)) - .and(ACCOUNT.USER_NAME.like("michael")); + .select() + .from(ACCOUNT) + .where(ACCOUNT.ID.ge(100)) + .and(ACCOUNT.USER_NAME.like("michael")); // SQL: // SELECT * FROM tb_account @@ -191,14 +191,14 @@ QueryWrapper queryWrapper=QueryWrapper.create() ```java QueryWrapper queryWrapper=QueryWrapper.create() - .select() - .from(ACCOUNT) - .where(ACCOUNT.ID.ge(100)) - .and( + .select() + .from(ACCOUNT) + .where(ACCOUNT.ID.ge(100)) + .and( exist( - selectOne().from(ARTICLE).where(ARTICLE.ID.ge(100)) + selectOne().from(ARTICLE).where(ARTICLE.ID.ge(100)) ) - ); + ); // SQL: // SELECT * FROM tb_account @@ -212,11 +212,11 @@ QueryWrapper queryWrapper=QueryWrapper.create() ```java QueryWrapper queryWrapper=QueryWrapper.create() - .select() - .from(ACCOUNT) - .where(ACCOUNT.ID.ge(100)) - .and(ACCOUNT.SEX.eq(1).or(ACCOUNT.SEX.eq(2))) - .or(ACCOUNT.AGE.in(18,19,20).and(ACCOUNT.USER_NAME.like("michael"))); + .select() + .from(ACCOUNT) + .where(ACCOUNT.ID.ge(100)) + .and(ACCOUNT.SEX.eq(1).or(ACCOUNT.SEX.eq(2))) + .or(ACCOUNT.AGE.in(18,19,20).and(ACCOUNT.USER_NAME.like("michael"))); // SQL: // SELECT * FROM tb_account @@ -229,9 +229,9 @@ QueryWrapper queryWrapper=QueryWrapper.create() ```java QueryWrapper queryWrapper=QueryWrapper.create() - .select() - .from(ACCOUNT) - .groupBy(ACCOUNT.USER_NAME); + .select() + .from(ACCOUNT) + .groupBy(ACCOUNT.USER_NAME); // SQL: // SELECT * FROM tb_account @@ -242,10 +242,10 @@ QueryWrapper queryWrapper=QueryWrapper.create() ```java QueryWrapper queryWrapper=QueryWrapper.create() - .select() - .from(ACCOUNT) - .groupBy(ACCOUNT.USER_NAME) - .having(ACCOUNT.AGE.between(18,25)); + .select() + .from(ACCOUNT) + .groupBy(ACCOUNT.USER_NAME) + .having(ACCOUNT.AGE.between(18,25)); // SQL: // SELECT * FROM tb_account @@ -254,13 +254,14 @@ QueryWrapper queryWrapper=QueryWrapper.create() ``` ### join + ```java -QueryWrapper queryWrapper = QueryWrapper.create() - .select() - .from(ACCOUNT) - .leftJoin(ARTICLE).on(ACCOUNT.ID.eq(ARTICLE.ACCOUNT_ID)) - .innerJoin(ARTICLE).on(ACCOUNT.ID.eq(ARTICLE.ACCOUNT_ID)) - .where(ACCOUNT.AGE.ge(10)); +QueryWrapper queryWrapper=QueryWrapper.create() + .select() + .from(ACCOUNT) + .leftJoin(ARTICLE).on(ACCOUNT.ID.eq(ARTICLE.ACCOUNT_ID)) + .innerJoin(ARTICLE).on(ACCOUNT.ID.eq(ARTICLE.ACCOUNT_ID)) + .where(ACCOUNT.AGE.ge(10)); // SQL: // SELECT * FROM tb_account @@ -277,8 +278,8 @@ QueryWrapper queryWrapper = QueryWrapper.create() **疑问 2：如何通过实体类 Account.java 生成 QueryWrapper 所需要的 "ACCOUNT" 类 ?** -答：Mybatis-Flex 使用了 APT（Annotation Processing Tool）技术，在项目编译的时候，会自动根据 Entity 类定义的字段帮你生成 "ACCOUNT" 类， -通过开发工具构建项目（如下图），或者执行 maven 编译命令: `mvn clean package` 都可以自动生成。这个原理和 lombok 一致。 +答：Mybatis-Flex 使用了 APT（Annotation Processing Tool）技术，在项目编译的时候，会自动根据 Entity 类定义的字段帮你生成 "ACCOUNT" 类， 通过开发工具构建项目（如下图），或者执行 +maven 编译命令: `mvn clean package` 都可以自动生成。这个原理和 lombok 一致。 ![](./docs/assets/images/build_idea.png) @@ -286,72 +287,77 @@ QueryWrapper queryWrapper = QueryWrapper.create() ## Db + Row 工具类 -Db + Row 工具类，提供了在 Entity 实体类之外的数据库操作能力。使用 Db + Row 时，无需对数据库表进行映射， -Row 是一个 HashMap 的子类，相当于一个通用的 Entity。以下为 Db + Row 的一些示例： +Db + Row 工具类，提供了在 Entity 实体类之外的数据库操作能力。使用 Db + Row 时，无需对数据库表进行映射， Row 是一个 HashMap 的子类，相当于一个通用的 Entity。以下为 Db + Row +的一些示例： ```java //使用原生 SQL 插入数据 -String sql = "insert into tb_account(id,name) value (?, ?)"; -Db.insertBySql(sql,1,"michael"); +String sql="insert into tb_account(id,name) value (?, ?)"; + Db.insertBySql(sql,1,"michael"); //使用 Row 插入数据 -Row account = new Row(); -account.set("id",100); -account.set("name","Michael"); -Db.insertRow("tb_account",account); + Row account=new Row(); + account.set("id",100); + account.set("name","Michael"); + Db.insertRow("tb_account",account); //根据主键查询数据 -Row row = Db.selectOneById("tb_account","id",1); + Row row=Db.selectOneById("tb_account","id",1); //Row 可以直接转换为 Entity 实体类，且性能极高 -Account account = row.toEntity(Account.class); + Account account=row.toEntity(Account.class); //查询所有大于 18 岁的用户 -String listsql = "select * from tb_account where age > ?" -List rows = Db.selectListBySql(sql,18); + String listsql="select * from tb_account where age > ?" + List rows=Db.selectListBySql(sql,18); //分页查询：每页 10 条数据，查询第 3 页的年龄大于 18 的用户 -QueryWrapper query = QueryWrapper.create() + QueryWrapper query=QueryWrapper.create() .where(ACCOUNT.AGE.ge(18)); -Page rowPage = Db.paginate("tb_account",3,10,query); + Page rowPage=Db.paginate("tb_account",3,10,query); ``` + > Db 工具类还提供了更多 增、删、改、查和分页查询等方法。 -> +> > 具体参考： [Db.java](./mybatis-flex-core/src/main/java/com/mybatisflex/core/row/Db.java) 。 -> -> 更多关于 Row 插入时的**主键生成机制**、以及Db 的**事务管理**等，请点击 [这里](./docs/zh/row_and_db.md) 。 +> +> 更多关于 Row 插入时的**主键生成机制**、以及Db 的**事务管理**等，请点击 [这里](./docs/zh/db_row.md) 。 ## Entity 部分字段更新 相比市面上的其他框架，这部分的功能应该也算是 MyBatis-Flex 的亮点之一。在 BaseMapper 中，Mybatis-Flex 提供了如下的方法： ```java -update(T entity, boolean ignoreNulls) +update(T entity,boolean ignoreNulls) ``` + - 第一个参数是 entity 的对象。 - 第二个参数是是否忽略 null 值。 有些场景下，我们可能希望只更新 几个 字段，而其中个别字段需要更新为 null。此时需要用到 `UpdateEntity` 工具类，以下是示例代码： ```java -Account account = UpdateEntity.of(Account.class); -account.setId(1); -account.setUserName(null); -account.setSex(1); +Account account=UpdateEntity.of(Account.class); + account.setId(1); + account.setUserName(null); + account.setSex(1); -accountMapper.update(account,false); + accountMapper.update(account,false); ``` + 以上的示例中，会把 id 为 1 这条数据中的 user_name 字段更新为 null，sex 字段更新为 1，其他字段不会被更新。也就是说，通过 `UpdateEntity` 创建的对象，只会更新调用了 setter 方法的字段，若不调用 setter 方法，不管这个对象里的属性的值是什么，都不会更新到数据库。 其生成的 sql 内容如下： ```sql -update tb_account set user_name = ? ,sex = ? where id = ? -#params: null,1,1 +update tb_account +set user_name = ?, + sex = ? +where id = ? #params: null,1,1 ``` ## 多主键 @@ -359,18 +365,20 @@ update tb_account set user_name = ? ,sex = ? where id = ? Mybatis-Flex 多主键就是在 Entity 类里有多个 `@Id` 注解标识而已，比如： ```java + @Table("tb_account") public class Account { - @Id(keyType=KeyType.Auto) + @Id(keyType = KeyType.Auto) private Long id; - - @Id(keyType=KeyType.Generator, value="uuid") + + @Id(keyType = KeyType.Generator, value = "uuid") private String otherId; //getter setter } ``` + 当我们保存数据的时候，Account 的 id 主键为自增，而 otherId 主键则通过 uuid 生成。 ### 自定义主键生成器 @@ -390,16 +398,17 @@ public class UUIDKeyGenerator implements IKeyGenerator { 第 2 步：注册 UUIDKeyGenerator ```java -KeyGeneratorFactory.register("myUUID", new UUIDKeyGenerator()); +KeyGeneratorFactory.register("myUUID",new UUIDKeyGenerator()); ``` 第 3 步：在 Entity 里使用 "myUUID" 生成器： ```java + @Table("tb_account") public class Account { - - @Id(keyType=KeyType.Generator, value="myUUID") + + @Id(keyType = KeyType.Generator, value = "myUUID") private String otherId; //getter setter @@ -409,17 +418,27 @@ public class Account { ### 使用数据库 Sequence 生成 ```java + @Table("tb_account") public class Account { - @Id(keyType=KeyType.Sequence, value="select SEQ_USER_ID.nextval as id from dual") + @Id(keyType = KeyType.Sequence, value = "select SEQ_USER_ID.nextval as id from dual") private Long id; - + } ``` > 更多关于主键的配置，请点击 [这里](./docs/zh/id.md) +## 更多文档 + +- [Maven依赖](./docs/zh/maven.md) +- [主键设置](./docs/zh/id.md) +- [列的设置](./docs/zh/column.md) +- [逻辑删除](./docs/zh/logic_delete.md) +- [乐观锁](./docs/zh/version.md) +- [Db + Row](./docs/zh/db_row.md) +- [APT](./docs/zh/apt.md) ## 更多示例