update

README.md

@@ -15,10 +15,11 @@ xorm是一个简单而强大的Go语言ORM库. 通过它可以使数据库操作
 * 同时支持原始SQL语句和ORM操作的混合执行
 * 支持类ibatis方式配置SQL语句（支持xml配置文件和pongo2模板2种方式）
 * 支持动态SQL功能
-* 支持一次批量混合执行CRUD操作，并返回多个结果集
+* 支持一次批量混合执行多个CRUD操作，并返回多个结果集
 * 使用连写来简化调用
 * 支持使用Id, In, Where, Limit, Join, Having, Table, Sql, Cols等函数和结构体等方式作为条件
 * 支持级联加载Struct
+* 支持数据库查询结果直接返回Json字符串和xml字符串
 * 支持缓存
 * 支持根据数据库自动生成xorm的结构体
 * 支持记录版本（即乐观锁）
@@ -123,23 +124,34 @@ results, err := engine.Query(sql_1)
  * 第2种方式：返回的结果类型为 []map[string]interface{}
 -------------------------------------------------------------------------------------*/
 sql_2_1 := "select * from user"
-results, err := engine.Sql(sql_2_1).Query().GetResults()
+results, err := engine.Sql(sql_2_1).Query().List()
 
 sql_2_2 := "select * from user where id = ? and age = ?"
-results, err := engine.Sql(sql_2_2, 7, 17).Query().GetResults()
+results, err := engine.Sql(sql_2_2, 7, 17).Query().List()
+
+//此Query()方法返回对象还支持ListPage()方法和Count()方法，这两个方法都是针对数据库查询出来后的结果集进行操作
+//此Query()方法返回对象还支持Xml()方法、XmlIndent()方法和Json()方法，相关内容请阅读之后的章节
+//ListPage()方法并非数据库分页方法，只是针对数据库查询出来后的结果集[]map[string]interface{}对象取部分切片
+//例如以下例子，是取结果集的第1条到第50条记录
+results, err := engine.Sql(sql_2_2, 7, 17).Query().ListPage(1,50)
+//例如以下例子，是取结果集的第13条到第28条记录
+results, err := engine.Sql(sql_2_2, 7, 17).Query().ListPage(13,28)
+//此Count()方法也并非使用数据库count函数查询数据库某条件下的记录数，只是针对Sql语句对数据库查询出来后的结果集[]map[string]interface{}对象的数量
+//此Count()方法也并非Engine对象和Session对象下的Count()方法，使用时请区分场景
+count, err := engine.Sql(sql_2_2, 7, 17).Query().Count()
 
 /*-------------------------------------------------------------------------------------
   第3种方式：执行SqlMap配置文件中的Sql语句，返回的结果类型为 []map[string]interface{}
 -------------------------------------------------------------------------------------*/
 sql_id_3_1 := "sql_3_1" //配置文件中sql标签的id属性,SqlMap的key
-results, err := engine.SqlMapClient(sql_3_1).Query().GetResults()
+results, err := engine.SqlMapClient(sql_3_1).Query().List()
 
 sql_id_3_2 := "sql_3_2"
-results, err := engine.SqlMapClient(sql_id_3_2, 7, 17).Query().GetResults()
+results, err := engine.SqlMapClient(sql_id_3_2, 7, 17).Query().List()
 
 sql_id_3_3 := "sql_3_3"
 paramMap_3_3 := map[string]interface{}{"id": 7, "name": "xormplus"}
-results1, err := engine.SqlMapClient(sql_id_3_3, &paramMap_3_3).Query().GetResults()
+results1, err := engine.SqlMapClient(sql_id_3_3, &paramMap_3_3).Query().List()
 
 /*-------------------------------------------------------------------------------------
  * 第4种方式：执行SqlTemplate配置文件中的Sql语句，返回的结果类型为 []map[string]interface{}
@@ -149,12 +161,12 @@ sql_key_4_1 := "select.example.stpl" //配置文件名,SqlTemplate的key
 //执行的 sql：select * from user where id=7
 //如部分参数未使用，请记得使用对应类型0值，如此处name参数值为空字符串，模板使用指南请详见pongo2
 paramMap_4_1 := map[string]interface{}{"count": 1, "id": 7, "name": ""}
-results, err := engine.SqlTemplateClient(sql_key_4_1, &paramMap_4_1).Query().GetResults()
+results, err := engine.SqlTemplateClient(sql_key_4_1, &paramMap_4_1).Query().List()
 
 //执行的 sql：select * from user where name='xormplus'
 //如部分参数未使用，请记得使用对应类型0值，如此处id参数值为0，模板使用指南请详见pongo2
 paramMap_4_2 := map[string]interface{}{"id": 0, "count": 2, "name": "xormplus"}
-results, err := engine.SqlTemplateClient(sql_key_4_1, &paramMap_4_2).Query().GetResults()
+results, err := engine.SqlTemplateClient(sql_key_4_1, &paramMap_4_2).Query().List()
 
 /*-------------------------------------------------------------------------------------
  * 第5种方式：返回的结果类型为对应的[]interface{}
@@ -296,7 +308,7 @@ id := engine.SqlMapClient(key, &paramMap).Query().Results[0]["id"] //返回查
 id := engine.SqlTemplateClient(key, &paramMap).Query().Results[0]["id"] //返回查询结果的第一条数据的id列的值
 ```
 
-* 事务处理，当使用事务处理时，需要创建Session对象，另外当使用Sql()、SqlMapClient()、SqlTemplateClient()方法进行操作时也推荐手工创建Session对象方式管理Session。在进行事物处理时，可以混用ORM方法和RAW方法，如下代码所示：
+* 事务处理，当使用事务处理时，需要创建Session对象，另外当使用Sql()、SqlMapClient()、SqlTemplateClient()方法进行操作时也推荐手工创建Session对象方式管理Session。在进行事物处理时，可以混用ORM方法和RAW方法。注意如果您使用的是mysql，数据库引擎为innodb事务才有效，myisam引擎是不支持事务的。示例代码如下：
 
 ```go
 session := engine.NewSession()
@@ -423,8 +435,107 @@ engine.GetSqlMap(...key)
 engine.GetSqlTemplates(...key)
 ```
 <a name="ROP_ARM"/>
-# 一次批量混合执行CRUD操作，并返回批量结果集
+# 批量SQL操作
+* 批量SQL操作API
 
+```Go
+//第一种方式，可以从Engine对象轻松进行使用，该方式自动管理事务，注意如果您使用的是mysql，数据库引擎为innodb事务才有效，myisam引擎是不支持事务的。
+engine.Sqls(sqls, parmas...).Execute()
+engine.SqlMapsClient(sqlkeys, parmas...).Execute()
+engine.SqlTemplatesClient(sqlkeys, parmas...).Execute()
+
+//第2种方式，手动创建Session对象进行调用，该方式需要您手动管理事务
+session := engine.NewSession()
+defer session.Close()
+// add Begin() before any action
+err := session.Begin()
+
+
+_, err = session.Exec("delete from userinfo where username = ?", user2.Username)
+if err != nil {
+    session.Rollback()
+    return
+}
+
+results, _, err = session.Sqls(sqls, parmas...).Execute()
+
+_, results, err = session.SqlMapsClient(sqlkeys, parmas...).Execute()
+
+results, _, err = session.SqlTemplatesClient(sqlkeys, parmas...).Execute()
+
+if err != nil {
+    session.Rollback()
+    return
+}
+
+// add Commit() after all actions
+err = session.Commit()
+if err != nil {
+    return
+}
+
+```
+
+* Sqls(sqls, parmas...)方法说明：
+  1. sqls参数
+    * sqls参数数据类型为interface{}类型，但实际参数类型检查时，只支持string，[]string和map[string]string三中类型，使用其他类型均会返回参数类型错误。
+    * 使用string类型则为执行单条Sql执行单元（传送门：[Sql执行单元定义](#SQL)），Execute()方法返回的结果集数据类型为[][]map[string]interface{}，只有1个元素。
+    * 使用[]string则Execute()方法为有序执行多条Sql执行单元，Execute()方法返回的结果集数据类型为[][]map[string]interface{}类型，结果集元素个数与sqls参数的元素个数相同，每个元素索引与返回结果集的索引一一对应。
+    * 使用map[string]string类型则Execute()方法为无序执行多条Sql执行单元，Execute()方法返回的结果集数据类型为map[string][]map[string]interface{}，结果集map的key与返回结果集的key一一对应。
+  2. parmas...参数
+	* 可以接收0个参数或则1个参数，当所有执行单元都无需执行参数时候，可以不传此参数
+	* parmas参数数据类型为interface{}，但实际参数类型检查时，只支持map[string]interface{}，[]map[string]interface{}和map[string]map[string]interface{}三种类型，使用其他类型均会返回参数类型错误。
+	* 使用map[string]interface{}类型时候，sqls参数类型必须为string类型，即map[string]interface{}类型为单条Sql执行单元的参数。
+	* 使用[]map[string]interface{}类型时候，sqls参数类型可以为string类型，此时只有第一个元素[0]map[string]interface{}会被提取，之后的元素将不起任何作用。同时，sqls参数类型也可以为[]string类型，这种参数组合是最常用的组合形式之一，sqls参数的索引和parmas参数的索引一一对应。当某个索引所对应的Sql执行单元是无参数的时候，请将此索引的值设为nil，即parmas[i] = nil
+	* 使用map[string]map[string]interface{}类型时，sqls参数类型必须为map[string]string类型，这种参数组合是最常用的组合形式之一，sqls参数的key和parmas参数的key一一对应。当某个key所对应的Sql执行单元是无参数的时候，请将此key的值设为nil，即parmas[key] = nil
+
+* SqlMapsClient(sqlkeys, parmas...)方法说明：
+  1. sqlkeys参数
+    * sqlkeys参数数据类型为interface{}类型，但实际参数类型检查时，只支持string，[]string和map[string]string三中类型，使用其他类型均会返回参数类型错误。
+    * 使用string类型则为执行单条Sql执行单元（Sql执行单元定义），即在xorm种缓存的SqlMap中的key所对应的配置项，Execute()方法返回的结果集数据类型为[][]map[string]interface{}，只有1个元素。
+    * 使用[]string则Execute()方法为有序执行多条Sql执行单元，Execute()方法返回的结果集数据类型为[][]map[string]interface{}类型，结果集元素个数与sqls参数的元素个数相同，sqlkeys的索引与返回结果集的索引一一对应，sqlkeys存储的是每个元素的值是xorm缓存的SqlMap的key
+    * 使用map[string]string类型则Execute()方法为无序执行多条Sql执行单元，Execute()方法返回的结果集数据类型为map[string][]map[string]interface{}，sqlkeys的key与返回结果集的key一一对应，sqlkeys存储的是每个键值对的值是xorm缓存的SqlMap的key
+  2. parmas...参数
+	* 可以接收0个参数或则1个参数，当所有执行单元都无需执行参数时候，可以不传此参数
+	* parmas参数数据类型为interface{}，但实际参数类型检查时，只支持map[string]interface{}，[]map[string]interface{}和map[string]map[string]interface{}三种类型，使用其他类型均会返回参数类型错误。
+	* 使用map[string]interface{}类型时候，sqlkeys参数类型必须为string类型，即map[string]interface{}类型为单条Sql执行单元的参数。效果等同SqlMapClient()方法（请注意本方法名为SqlMapsClient）。
+	* 使用[]map[string]interface{}类型时候，sqlkeys参数类型支持两种：
+		* 第1种为string类型，此时只有第一个元素[0]map[string]interface{}会被提取，之后的元素将不起任何作用。
+		* 第2种为[]string类型，这种参数组合是最常用的组合形式之一，sqlkeys参数的索引和parmas参数的索引一一对应。当某个索引所对应的Sql执行单元是无参数的时候，请将此索引的值设为nil，即parmas[i] = nil
+	* 使用map[string]map[string]interface{}类型时，sqlkeys参数类型必须为map[string]string类型，这种参数组合是最常用的组合形式之一，sqlkeys参数的key和parmas参数的key一一对应。当某个key所对应的Sql执行单元是无参数的时候，请将此key的值设为nil，即parmas[key] = nil
+
+* SqlTemplatesClient(sqlkeys, parmas...)方法说明：
+  1. sqlkeys参数
+    * sqlkeys参数数据类型为interface{}类型，但实际参数类型检查时，只支持string，[]string和map[string]string三中类型，使用其他类型均会返回参数类型错误。
+    * 使用string类型则为执行单条Sql执行单元（Sql执行单元定义），即在xorm缓存的SqlTemplate中的key所对应的模板，Execute()方法返回的结果集数据类型为[][]map[string]interface{}，只有1个元素。
+    * 使用[]string则Execute()方法为有序执行多条Sql执行单元，Execute()方法返回的结果集数据类型为[][]map[string]interface{}类型，结果集元素个数与sqls参数的元素个数相同，sqlkeys的索引与返回结果集的索引一一对应，sqlkeys存储的是每个元素的值是xorm缓存的SqlTemplate的key
+    * 使用map[string]string类型则Execute()方法为无序执行多条Sql执行单元，Execute()方法返回的结果集数据类型为map[string][]map[string]interface{}，sqlkeys的key与返回结果集的key一一对应，sqlkeys存储的是每个键值对的值是xorm缓存的SqlTemplate的key
+  2. parmas...参数
+	* 可以接收0个参数或则1个参数，当所有执行单元都无需执行参数时候，可以不传此参数
+	* parmas参数数据类型为interface{}，但实际参数类型检查时，只支持map[string]interface{}，[]map[string]interface{}和map[string]map[string]interface{}三种类型，使用其他类型均会返回参数类型错误。
+	* 使用map[string]interface{}类型时候，sqlkeys参数类型必须为string类型，即map[string]interface{}类型为单条Sql执行单元的参数。效果等同SqlMapClient()方法（请注意本方法名为SqlMapsClient）。
+	* 使用[]map[string]interface{}类型时候，sqlkeys参数类型支持两种：
+		* 第1种为string类型，此时只有第一个元素[0]map[string]interface{}会被提取，之后的元素将不起任何作用；
+		* 第2种为[]string类型，这种参数组合是最常用的组合形式之一，sqlkeys参数的索引和parmas参数的索引一一对应。当某个索引所对应的Sql执行单元是无参数的时候，请将此索引的值设为nil，即parmas[i] = nil
+	* 使用map[string]map[string]interface{}类型时，sqlkeys参数类型必须为map[string]string类型，这种参数组合是最常用的组合形式之一，sqlkeys参数的key和parmas参数的key一一对应。当某个key所对应的Sql执行单元是无参数的时候，请将此key的值设为nil，即parmas[key] = nil
+
+* Execute()方法说明：
+	* 一共3个返回值，([][]map[string]interface{}, map[string][]map[string]interface{}, error)
+	* 当以上3个方法的sqls或sqlkeys参数为string或[]string时，返回结果集为第一个返回值，第二返回值为nil
+	* 当以上3个方法的sqls或sqlkeys参数为map[string]string时，返回结果集为第二个返回值，第一个返回值为nil
+	* 当以上3个方法执行中出现错误，则第三个返回值有值，前2个返回值均为nil
+
+<a name="SQL"></a>
+* Sql执行单元定义
+	* 当sqls为string时候，则Sql执行单元为该字符串的内容
+	* 当sqlkeys为string时，则Sql执行单元为所对应的SqlMap配置项或SqlTemplate模板
+	* 当sqls为[]string或map[string]string时候，则Sql执行单元为相关元素的字符串内容
+	* 当sqlkeys为[]string或map[string]string时候，则Sql执行单元为以相关元素为key所对应的SqlMap配置项或SqlTemplate模板
+	* Sql执行单元的具体内容，必须以"select", "insert", "delete", "update", "create", "drop"为起始内容,但后续内容不会继续做检查，请合理定义Sql执行单元内容
+	* Sql执行单元并非单条Sql语句，当执行insert，delete，update，create，drop操作时候，可以为多条Sql语句，这里需要对应的数据库的SQL语法支持。如在一个执行单元批量执行多条Sql，返回结果集作为一组所有执行单元的大结果集中的一个元素，这个结果集的数据类型为map[string]interface{}，只有2个键值对，一个键值对的key为LastInsertId，一个键值对的key为RowsAffected，请控制好执行粒度。另外不是所有数据库都支持返回LastInsertId，目前还在设计通用API能支持此功能。
+	* 当执行select操作时候，执行单元的Sql语句必须为一条，返回结果集作为一组所有执行单元的大结果集中的一个元素
+	* insert，delete，update，create，drop操作不能和select操作混合定义在同一个执行单元中
+	* 最后，Sql执行单元基于以上约定，请合理组织
 
 # ORM方式操作数据库
 * ORM方式插入一条或者多条记录