Skip to content

Commit 5950b48

Browse files
fix markdown style
1 parent a2a7729 commit 5950b48

File tree

5 files changed

+15
-15
lines changed

5 files changed

+15
-15
lines changed

source/zh-cn/entities-and-column-binding.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -103,9 +103,9 @@ object Employees : Table<Employee>("t_employee") {
103103

104104
Ktorm 提供以下几种不同的绑定类型:
105105

106-
1. **简单绑定**使用 `bindTo` 函数将列绑定到一个简单的属性上,如 `c.bindTo { it.name }`
107-
2. **嵌套绑定**使用 `bindTo` 函数将列绑定到多层嵌套的某个属性上,如 `c.bindTo { it.manager.department.id }`;这样,从数据库中获取该列时,它的值会被填充到 `employee.manager.department.id` 中;把修改更新到数据库时,只要嵌套的属性中的任何一级发生变化,都会将新的值同步更新到所绑定的这个列。简单绑定其实也是嵌套绑定的一种特例,只不过嵌套的属性只有一层。
108-
3. **引用绑定**使用 `references` 函数将列绑定到另一个表,如 `c.references(Departments) { it.department }`,相当于数据库中的外键引用。使用引用绑定的列,在通过实体查询函数从数据库中获取当前实体对象的时候,会自动递归地 left join 其关联表,并将关联的实体对象也一并获取。
106+
1. **简单绑定**使用 `bindTo` 函数将列绑定到一个简单的属性上,如 `c.bindTo { it.name }`
107+
2. **嵌套绑定**使用 `bindTo` 函数将列绑定到多层嵌套的某个属性上,如 `c.bindTo { it.manager.department.id }`;这样,从数据库中获取该列时,它的值会被填充到 `employee.manager.department.id` 中;把修改更新到数据库时,只要嵌套的属性中的任何一级发生变化,都会将新的值同步更新到所绑定的这个列。简单绑定其实也是嵌套绑定的一种特例,只不过嵌套的属性只有一层。
108+
3. **引用绑定**使用 `references` 函数将列绑定到另一个表,如 `c.references(Departments) { it.department }`,相当于数据库中的外键引用。使用引用绑定的列,在通过实体查询函数从数据库中获取当前实体对象的时候,会自动递归地 left join 其关联表,并将关联的实体对象也一并获取。
109109

110110
另外,Ktorm 2.6 及以上版本还支持了多重绑定的功能,我们可以通过连续调用 `bindTo``references` 函数把一个列绑定到多个属性上。这样,当通过查询从数据库中获取实体对象的时候,这个列的值就会同时填充到它绑定的每一个属性上去。
111111

source/zh-cn/entity-sequence.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -93,8 +93,8 @@ data class EntitySequence<E : Any, T : BaseTable<E>>(
9393

9494
Ktorm 的实体序列 API,大部分都是以扩展函数的方式提供的,这些扩展函数大致可以分为两类:
9595

96-
- **中间操作**这类函数并不会执行序列中的查询,而是修改并创建一个新的序列对象,比如 `filter` 函数会使用指定的筛选条件创建一个新的序列对象。中间函数的返回值类型通常都是 `EntitySequence`,以便我们继续链式调用其他序列函数。
97-
- **终止操作**这类函数的返回值通常是一个集合或者是某个计算的结果,他们会马上执行一个查询,然后获取它的结果并执行一定的运算,比如 `toList``reduce` 等。
96+
- **中间操作**这类函数并不会执行序列中的查询,而是修改并创建一个新的序列对象,比如 `filter` 函数会使用指定的筛选条件创建一个新的序列对象。中间函数的返回值类型通常都是 `EntitySequence`,以便我们继续链式调用其他序列函数。
97+
- **终止操作**这类函数的返回值通常是一个集合或者是某个计算的结果,他们会马上执行一个查询,然后获取它的结果并执行一定的运算,比如 `toList``reduce` 等。
9898

9999
## 中间操作
100100

source/zh-cn/operators.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -44,15 +44,15 @@ Ktorm 的每个运算符实际上都是一个返回 `SqlExpression` 的 Kotlin
4444

4545
这些运算符按照实现方式大概可以分为两类:
4646

47-
**使用 operator 关键字重载的 Kotlin 内置运算符**这类运算符一般用于实现加减乘除等基本的运算,由于重载了 Kotlin 的内置运算符,它们使用起来就像是真的执行了运算一样,比如 `Employees.salary + 1000`。但实际上并没有,它们只是创建了一个 SQL 表达式,这个表达式会被 `SqlFormatter` 翻译为 SQL 中的对应符号。下面是加号运算符的代码实现,可以看到,它只是创建了一个 `BinaryExpression<T>` 而已:
47+
**使用 operator 关键字重载的 Kotlin 内置运算符**这类运算符一般用于实现加减乘除等基本的运算,由于重载了 Kotlin 的内置运算符,它们使用起来就像是真的执行了运算一样,比如 `Employees.salary + 1000`。但实际上并没有,它们只是创建了一个 SQL 表达式,这个表达式会被 `SqlFormatter` 翻译为 SQL 中的对应符号。下面是加号运算符的代码实现,可以看到,它只是创建了一个 `BinaryExpression<T>` 而已:
4848

4949
```kotlin
5050
infix operator fun <T : Number> ColumnDeclaring<T>.plus(expr: ColumnDeclaring<T>): BinaryExpression<T> {
5151
return BinaryExpression(BinaryExpressionType.PLUS, asExpression(), expr.asExpression(), sqlType)
5252
}
5353
```
5454

55-
**普通的运算符函数**然而,Kotlin 重载运算符还有许多限制,比如 `equals` 方法要求必须返回 `Boolean`,然而 Ktorm 的运算符需要返回 SQL 表达式,因此,Ktorm 提供了另外一个 `eq` 函数用于相等比较。除此之外,还有许多 SQL 中的运算符在 Kotlin 中并不存在,比如 like,Ktorm 就提供了一个 `like` 函数用于字符串匹配。下面是 `like` 函数的实现,这类函数一般都具有 infix 关键字修饰:
55+
**普通的运算符函数**然而,Kotlin 重载运算符还有许多限制,比如 `equals` 方法要求必须返回 `Boolean`,然而 Ktorm 的运算符需要返回 SQL 表达式,因此,Ktorm 提供了另外一个 `eq` 函数用于相等比较。除此之外,还有许多 SQL 中的运算符在 Kotlin 中并不存在,比如 like,Ktorm 就提供了一个 `like` 函数用于字符串匹配。下面是 `like` 函数的实现,这类函数一般都具有 infix 关键字修饰:
5656

5757
```kotlin
5858
infix fun ColumnDeclaring<*>.like(argument: String): BinaryExpression<Boolean> {
@@ -73,7 +73,7 @@ infix fun ColumnDeclaring<*>.like(argument: String): BinaryExpression<Boolean> {
7373

7474
对于重载的 Kotlin 内置运算符,其优先级遵循 Kotlin 语言自己的规范。例如表达式 `Employees.salary + 1000 * 2`,由于乘号的优先级较高,最终翻译出来的 SQL 是 `t_employee.salary + 2000`
7575

76-
**但是对于普通的运算符函数,却并没有优先级一说**在 Kotlin 语言的层面,它们实际上都只是普通的函数调用,因此只需要遵循从前往后结合的原则,尽管这有时可能会违反我们的直觉。比如 `a or b and c`,这里的 `or``and` 都是运算符函数,直觉上,`and` 的优先级应该比 `or` 高,因此应该优先结合,但实际上,它们只是普通的 Kotlin 函数而已。如果对这一点没有清楚的认识,可能导致一些意料之外的 bug,为了解决这个问题,我们可以在需要的地方使用括号,比如 `a or (b and c)`
76+
**但是对于普通的运算符函数,却并没有优先级一说**在 Kotlin 语言的层面,它们实际上都只是普通的函数调用,因此只需要遵循从前往后结合的原则,尽管这有时可能会违反我们的直觉。比如 `a or b and c`,这里的 `or``and` 都是运算符函数,直觉上,`and` 的优先级应该比 `or` 高,因此应该优先结合,但实际上,它们只是普通的 Kotlin 函数而已。如果对这一点没有清楚的认识,可能导致一些意料之外的 bug,为了解决这个问题,我们可以在需要的地方使用括号,比如 `a or (b and c)`
7777

7878
关于表达式优先级的具体顺序,请参考 [Kotlin 语言规范](https://kotlinlang.org/docs/reference/grammar.html#expressions)中的相关规定。
7979

source/zh-cn/query.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -55,9 +55,9 @@ query
5555
5656
`Query` 类中还有一些有用的属性:
5757

58-
- **sql**返回该查询生成的 SQL 字符串,可以在调试程序的时候确认生成的 SQL 是否符合预期。
59-
- **rowSet**返回该查询的结果集对象,此字段懒初始化,在第一次获取时,执行 SQL 语句,从数据库中获取结果。
60-
- **totalRecords**如果该查询没有使用 offset, limit 进行分页,此字段返回结果集的总行数;如果使用了分页,返回去除 offset, limit 限制后的符合条件的总记录数。Ktorm 使用此字段来支持页码计算,你可以使用 totalRecords 除以你的每页大小来计算总页数。
58+
- **sql**返回该查询生成的 SQL 字符串,可以在调试程序的时候确认生成的 SQL 是否符合预期。
59+
- **rowSet**返回该查询的结果集对象,此字段懒初始化,在第一次获取时,执行 SQL 语句,从数据库中获取结果。
60+
- **totalRecords**如果该查询没有使用 offset, limit 进行分页,此字段返回结果集的总行数;如果使用了分页,返回去除 offset, limit 限制后的符合条件的总记录数。Ktorm 使用此字段来支持页码计算,你可以使用 totalRecords 除以你的每页大小来计算总页数。
6161

6262
## 获取查询结果
6363

@@ -67,8 +67,8 @@ query
6767

6868
你可能已经发现,`Query.rowSet` 返回的结果集并不是普通的 `ResultSet`,而是 `QueryRowSet`。这是 Ktorm 提供的特殊的 `ResultSet` 的实现,与普通的 `ResultSet` 不同,它增加了如下特性:
6969

70-
- **离线可用**它不依赖于数据库连接,当连接关闭后,仍然可以正常使用,使用完毕也不需要调用 `close` 方法。`QueryRowSet` 在创建时,已经完整取出了结果集中的所有数据保存在内存中,因此只需要等待 GC 自动回收即可。
71-
- **索引访问运算符**`QueryRowSet` 重载了[索引访问运算符](https://kotlinlang.org/docs/reference/operator-overloading.html#indexed),因此你可以使用方括号语法 `[]` ,通过传入指定的 `Column` 对象来获取这个列的数据,这种方法得益于编译器的静态检查,不易出错。不过,你仍然可以使用 `ResultSet` 中的 `getXxx` 方法,通过传入列的序号或名称字符串来获取。
70+
- **离线可用**它不依赖于数据库连接,当连接关闭后,仍然可以正常使用,使用完毕也不需要调用 `close` 方法。`QueryRowSet` 在创建时,已经完整取出了结果集中的所有数据保存在内存中,因此只需要等待 GC 自动回收即可。
71+
- **索引访问运算符**`QueryRowSet` 重载了[索引访问运算符](https://kotlinlang.org/docs/reference/operator-overloading.html#indexed),因此你可以使用方括号语法 `[]` ,通过传入指定的 `Column` 对象来获取这个列的数据,这种方法得益于编译器的静态检查,不易出错。不过,你仍然可以使用 `ResultSet` 中的 `getXxx` 方法,通过传入列的序号或名称字符串来获取。
7272

7373
使用索引访问运算符获取列的方法如下:
7474

source/zh-cn/spring-support.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -83,8 +83,8 @@ class SpringManagedTransactionManager(val dataSource: DataSource) : TransactionM
8383

8484
除了事务管理,Spring JDBC 还提供了异常转换的功能,它能将 JDBC 中抛出的 `SQLException` 统一转换为 [DataAccessException](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/dao/DataAccessException.html) 重新抛出,这个功能有两条好处:
8585

86-
- **使用 unchecked 异常**JDBC 抛出的 `SQLException` 是 checked 异常,对于 Java 用户,这意味着我们需要在许多地方被迫地捕获一些没用的异常。Spring JDBC 统一将他们转换为 `RuntimeException`,有利于代码的整洁。不过 Kotlin 中不存在此问题,因此从这个角度看,此功能意义不大。
87-
- **统一数据访问层的异常体系**在 JDBC 中,使用不同的驱动,其底层抛出的异常类型都不同(虽然它们都是 `SQLException` 的子类),而且 JDBC 中定义的异常体系语义模糊。Spring JDBC 定义了一套成体系的清晰简洁的异常类型,能帮助我们更好地选择感兴趣的异常进行处理,并且屏蔽了不同数据库之间的异常差异。
86+
- **使用 unchecked 异常**JDBC 抛出的 `SQLException` 是 checked 异常,对于 Java 用户,这意味着我们需要在许多地方被迫地捕获一些没用的异常。Spring JDBC 统一将他们转换为 `RuntimeException`,有利于代码的整洁。不过 Kotlin 中不存在此问题,因此从这个角度看,此功能意义不大。
87+
- **统一数据访问层的异常体系**在 JDBC 中,使用不同的驱动,其底层抛出的异常类型都不同(虽然它们都是 `SQLException` 的子类),而且 JDBC 中定义的异常体系语义模糊。Spring JDBC 定义了一套成体系的清晰简洁的异常类型,能帮助我们更好地选择感兴趣的异常进行处理,并且屏蔽了不同数据库之间的异常差异。
8888

8989
使用 `Database.connectWithSpringSupport` 方法创建的 `Database` 对象默认启用了 Spring JDBC 的异常转换功能,因此我们可以写出这样的代码:
9090

0 commit comments

Comments
 (0)