优化文档

Author: shigebeyond

README.md

@@ -593,9 +593,10 @@ gradle :jkmvc-example:build -x test
 14. [relation](doc/orm/relation.md)
 15. [validation](doc/orm/validation.md)
 16. [using](doc/orm/using.md)
+17. [relation using callback](doc/orm/cbrelation.md)
 
 ## other
-17. [deploy](doc/deploy.md)
+18. [deploy](doc/deploy.md)
 
 # 中文文档
 
@@ -620,7 +621,8 @@ gradle :jkmvc-example:build -x test
 14. [关联关系](doc/orm/relation.cn.md)
 15. [校验](doc/orm/validation.cn.md)
 16. [使用](doc/orm/using.cn.md)
+17. [基于回调的关联关系](doc/orm/cbrelation.cn.md)
 
 ## 其他
-17. [部署](doc/deploy.cn.md)
-18. [changelog](doc/changelog.md)
+18. [部署](doc/deploy.cn.md)
+19. [changelog](doc/changelog.md)

doc/orm/cbrelation.cn.md

@@ -0,0 +1,63 @@
+# 基于回调的关联关系
+
+基于db实现的关联关系, 是通过拼接主键外键条件的联查sql, 来查询关联对象的
+
+而基于回调实现的关联关系, 是使用回调来查询关联对象的.
+
+Jkmvc的ORM模块，支持2种回调实现的关联关系：`hasMany`, `hasOne`
+
+## 1 hasMany 有多个的关系
+
+`hasMany`关系，如 `Post` 模型从属于`User`模型（就是一个文章从属于一个用户）。从用户角度，`User` 模型有多个`Post`模型（就是一个用户有多个文章），我们可以这样定义`hasMany`关系：
+
+```
+hasMany("posts" /* 关系名 */, UserModel::id /* 主模型的主键的getter */, PostModel::userId /* 从对象的外键的getter */){ // 批量获取关联对象的回调
+    PostModel.queryBuilder().where("user_id", "IN", it).findModels<PostModel>()
+}
+```
+让我们来看看方法定义： 
+
+```
+fun <M:IOrm, K, R> IOrmMeta.cbHasMany(name: String, pkGetter: (M)->K, fkGetter: (R)->K, relatedSupplier:(List<K>) -> List<R>): IOrmMeta
+```
+
+接上面的例子，`User`模型的的关系定义如下
+
+```
+hasMany("posts", UserModel::id, PostModel::userId){
+     // 自定义的查询, 可以是rpc
+     PostModel.queryBuilder().where("user_id", "IN", it).findModels<PostModel>()
+}
+```
+
+以后，你就可以通过`user["posts"]`来访问`Post`模型（就是某用户的文章啦）
+
+## 2 hasOne 有一个的关系
+
+`hasOne`关系基本等同于`hasMany`关系。只是`hasOne`关系是一对一的，而`hasMany`是一对多。如果一个用户只有一个文章，则我们的代码是这样的：
+
+```
+hasOne("story", UserModel::id, PostModel::userId){
+     // 自定义的查询, 可以是rpc
+     PostModel.queryBuilder().where("user_id", "IN", it).findModels<PostModel>()
+}
+```
+
+# 关联对象查询
+
+使用 `OrmQueryBuilder.with()` 来联查关联对象
+
+```
+// 联查一对一关联对象
+val post = PostModel.queryBuilder()
+    .with("author")
+    .where("id", "=", 20)
+    .findModel<PostModel>();
+
+// -------------------------------
+// 联查一对多关联对象
+val user = UserModel.queryBuilder()
+    .with("posts")
+    .where("id", "=", 20)
+    .findModel<UserModel>();
+```

doc/orm/cbrelation.md

@@ -0,0 +1,62 @@
+# Relations using callback
+
+Relations using db query related objects with sql
+
+Relations using callback query related objects using callback
+
+Jkmvc ORM supports 2 types of callback relations: `hasMany`, `hasOne`.
+
+## 1 hasMany
+
+The standard `hasMany` relation, eg: a post belongs to a user.  From the user's perspective, a user has many posts. A hasMany relation is defined below:
+
+```
+hasMany("posts" /* relation name */, UserModel::id /* this model's primary key getter */, PostModel::userId /* related model's foreign key getter */){ // callback to query related objects
+    PostModel.queryBuilder().where("user_id", "IN", it).findModels<PostModel>()
+}
+```
+Let's have a look at the method definition 
+
+```
+fun <M:IOrm, K, R> IOrmMeta.cbHasMany(name: String, pkGetter: (M)->K, fkGetter: (R)->K, relatedSupplier:(List<K>) -> List<R>): IOrmMeta
+```
+Again, for our user and post example, this would look like the following in the user model:
+
+```
+hasMany("posts", UserModel::id, PostModel::userId){
+    // you can also call rpc
+    PostModel.queryBuilder().where("user_id", "IN", it).findModels<PostModel>()
+}
+```
+
+Using the above, the posts could be access using `user["posts"]`.
+
+## 2 hasOne
+
+A `hasOne` relation is almost identical to a `hasMany` relation.  In a `hasOne` relation, there can be 1 and only 1 relation (rather than 1 or more in a hasMany). If a user can only have one post or story, rather than many then the code would look like this:
+
+```
+hasOne("story", UserModel::id, PostModel::userId){
+    // you can also call rpc
+    PostModel.queryBuilder().where("user_id", "IN", it).findModels<PostModel>()
+}
+```
+
+# Query related object
+
+use `OrmQueryBuilder.with()` to query related object
+
+```
+// Query 1:1 related object, it will merge into 1 sql
+val post = PostModel.queryBuilder()
+    .with("author")
+    .where("id", "=", 20)
+    .findModel<PostModel>();
+
+// -------------------------------
+// Query 1:N related objects, it will split into 2 sql
+val user = UserModel.queryBuilder()
+    .with("posts")
+    .where("id", "=", 20)
+    .findModel<UserModel>();
+```

doc/orm/relation.cn.md

@@ -156,7 +156,7 @@ post.removeRelation('categories', category);
 
 # 关联对象查询
 
-使用 `OrmQueryBuilder.with()` 来联查关联对象
+使用 `OrmQueryBuilder.with()` 来联查关联对象, 框架会自动帮你解决联查放大问题
 
 ```
 // 联查一对一关联对象, 合并为1条sql查询

doc/orm/validation.cn.md

@@ -8,15 +8,15 @@ Orm模型与[Validation](../common/validation/validation.cn.md)库紧密集成
 
 每个规则是`net.jkcode.jkmvc.orm.RuleValidator`对象，它有2个属性：
 1. `label`：字段中文名
-2. `rule`：验证表达式
+2. `rule`：验证表达式, 可包含多个, 用空格分割
 
 有两种方法来定义规则
 1.重写`OrmMeta :: rules`属性
 
 ```
 public override val rules: MutableMap<String, IValidator> = hashMapOf(
 	"userId" to RuleValidator("用户", "notEmpty"),
-	"age" to RuleValidator( "年龄", "between(1,120)")
+	"age" to RuleValidator( "年龄", "digit() between(1,120)")
 )
 ```
 
@@ -25,7 +25,7 @@ public override val rules: MutableMap<String, IValidator> = hashMapOf(
 ```
 // 添加标签 + 规则
 addRule("name", "姓名", "notEmpty");
-addRule("age", "年龄", "between(1,120)");
+addRule("age", "年龄", "digit() between(1,120)");
 ```
 
 ## 2执行验证

doc/orm/validation.md

@@ -8,15 +8,15 @@ Validation rules are defined in the `OrmMeta::rules` property. This property is
 
 Each rule is `net.jkcode.jkmvc.orm.RuleValidator` object, which has 2 properties:
 1. `label`: A label is a human-readable version of the field name.
-2. `rule`: A validation expression
+2. `rule`: A validation expressions, split by space
 
 There are 2 way to define rules
 1. override `OrmMeta::rules` property
 
 ```
 public override val rules: MutableMap<String, IValidator> = hashMapOf(
 	"userId" to RuleValidator("Id label", "notEmpty"),
-	"age" to RuleValidator( "Age label", "between(1,120)")
+	"age" to RuleValidator( "Age label", "digit() between(1,120)")
 )
 ```
 
@@ -25,7 +25,7 @@ public override val rules: MutableMap<String, IValidator> = hashMapOf(
 ```
 // add label and rule for field
 addRule("name", "Name label", "notEmpty");
-addRule("age", "Age label", "between(1,120)");
+addRule("age", "Age label", "digit() between(1,120)");
 ```
 
 ## 2 Execute validation