功能说明 | TLWB云开发平台文档(v4.0.0)

# 功能说明

用于前端通过http向服务器端发送查询请求格式，并获得后端传回的json数据。
后端传回的json数据格式见下一节后端数据返回格式(response)
主要功能有:
(1) 按指定模块\表\数据源编号\视图对指定的数据库类型进行查询
(2) 查询并导出为excel文件(可指定导出列的标题)
(3) 查询权限并获得权限按钮
(4) 对查询结果进行分页/分组/排序处理
(5) 查询指定的字段
(6) 自定义SQL查询(后端需开启支持前端自定义SQL选项)(sql选项)
(7) 对多表进行联合查询(merge选项)
(8) 设置各种查询条件(filter选项)
(9) 设置字典让服务器端进行字典翻译(dict选项)

# 组成部分

本格式为JSON结构体，由 head 和 option 两个部分构成。

{
    head: { },  /* 必配，如果走通用接口则必须配置 */
    option: { } /* 必配，选项 */
}

1
2
3
4

# 选项一览表

{
    head: {
        dbType:'mongodb'    //选配, 数据库类型,支持关系数据库和非关系数据库,默认为关系数据库, 非关系数据库目前只支持mongodb
        module: 'sys_position', //模块编号,在sys_module表中找
        source: 'sysPositionList_01', //sql语句编号,在sys_data_sql表中找
        view: '',   //视图名称,在数据库视图名称中找
        table: '',     //表名称,在sys_module表中maintable字段和subtable字段中找
    },
    option: {
        att:{}, //前端传给后端的只用于head中配置了source的情况，格式为字段名称和字段值,例如：{name: '张三'}
        onlyField:false //是否只那查询结果字段,不拿数据,true:只拿字段,不拿数据 false:数据与字段都要拿,默认为false
        isPrivilege: true,  //对模块子表是否进行权限判断,默认为true
        export: false,      //是否导出数据
        titles:[]   //导出字段的标题
        keyField: false,     //是否需要回传主键字段名字
        privilege:           //是否需要权限按钮按钮列表,可设置类型:Boolean, String, Array
        load: true,         //是否装载数据
        order: '',         //选配, 排序字段
        group:'id, name',   //选配,查询结果分组

        fields: "",     //选配, 回传的字段名称,为空或者*表示所有字段
        page: 1,        //选配, 如果有分页,拿第几页
        size: 10,       //选配, 如果有分页,每页数据行数
        lastId:'',      //选配, 当前页的最后一条数据的_id值,作用为针对MongoDB的分页查询优化
        sql: ''     //自定义sql(后端服务器要开启允许自定义sql)，如果采用此项，merge\filter\fields选项都无效
        merge: '',    //选配,多表查询
        filter: [ //选配, 查询条件,变量采用 #{} 方式,旧值采用old. ,新值采用new. 注意:AND或OR后面必须是数组,如果中括号前不写AND或OR，则默认为AND
            {AND:[{'rid':{'=':'#{rid}'}}]},  ==>{'rid':{'=':'#{rid}'}}  => {'rid':'#{rid}'} //简写方式,操作符默认为=
            {OR:[{'rid':{'=':'#{rid}'}},     ==>{'rid':{'=':'#{rid}'}}  => {'rid':'#{rid}'} //简写方式
                 {OR:[{'rid':{'=':'#{rid}'}}]},
                 {AND:[{'rid':{'=':'#{rid}'}}]}
                ]
            }
            [{'rid':'#{rid}'},{'rid':{'=':'#{rid}'}}] //AND的简写方式
            [{'rid':'#{rid}'},{OR:{'rid':'#{rid}'}},{OR:{'rid':'#{rid}'}}] //OR的简写方式
        ],
        dict: { //选配,字典翻译
            字段名: {           //必配,要翻译的字段名
                appendField: ''    //选配, 翻译后要增加到结果集中的字段名称，如果翻译后不增加字段则不配置本项，系统将翻译后的字段替换源字段值
                fix: {1:'男',0:'女'}  //选配, 固定值翻译
                table: {    //选配, 数据库查询后翻译
                    name: '',    //必配, 表名字
                    field: '',   //必配, 要拿值的字段名称
                    where: "字段名=?"  //选配, 查询条件，如果不配置此项，则查询条件默认为翻译的字段名称(当2个表的字段名称相同时可以不配置)
                }
            }
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

# head 选项

# 选项格式

说明：head 结构体为 JSON 格式。如果不使用自定义接口，则必须配置头部参数

{
    head: {
        dbType:'mongodb'    //选配, 数据库类型,支持关系数据库和非关系数据库,默认为关系数据库, 非关系数据库目前支持mongodb/elasticsearch
        module: 'sys_position', //模块编号,在sys_module表中找
        source: 'sysPositionList_01', //sql语句编号,在sys_data_sql表中找
        view: '',   //视图名称,在数据库视图名称中找
        table: '',     //表名称,在sys_module表中maintable字段和subtable字段中找
    }
}

1
2
3
4
5
6
7
8
9

# 选项说明

说明：head 结构体为 JSON 格式。

参数	必填	数据类型	可选值	说明
dbType	否	String	mongodb	数据库类型,除非指明是非关系数据库mongodb，其余都为关系数据库
module	否	String		说明本组件所属模块编号,建议设置,用于数据操作时的权限判断以及获取该模块的主表
source	否	String		说明本组件操作的sql语句编号（需事先设置sql语句并编号）
view	否	String		说明本组件操作的视图编号（需事先在数据库中设置视图），使用本项必须设置module值
table	否	String		说明本组件操作的表名，使用本项必须设置module值，只有在该module下有子表并且使用子表时才设置

# option 选项

# 选项格式

说明：option 结构体为选配，结构体格式为：

option: {
        att:{}, //前端传给后端的只用于head中配置了source的情况，格式为字段名称和字段值,例如：{name: '张三'}
        onlyField:false, //是否只那查询结果字段,不拿数据,true:只拿字段,不拿数据 false:数据与字段都要拿,默认为false
        subTable: 0, //是否将关联平行表或子表的数据传回,0:不传,1:传第1级子表,2:传第1级和第2级,以此类推
        isPrivilege: true,  //对模块子表是否进行权限判断,默认为true
        export: false,      //是否导出数据
        titles:[]   //导出字段的标题
        keyField: false,     //是否需要回传主键字段名字
        privilege:           //是否需要权限按钮按钮列表,可设置类型:Boolean, String, Array
        load: true,         //是否装载数据
        order: '',         //选配, 排序字段
        group:'id, name',   //选配,查询结果分组

        fields: "",     //选配, 回传的字段名称,为空或者*表示所有字段
        page: 1,        //选配, 如果有分页,拿第几页
        size: 10,       //选配, 如果有分页,每页数据行数
        lastId:'',      //选配, 当前页的最后一条数据的_id值,作用为针对MongoDB的分页查询优化
        sql: ''     //自定义sql(后端服务器要开启允许自定义sql)，如果采用此项，merge\filter\fields选项都无效
        merge: 'INNER JOIN sys_module_action on sys_module.mid = sys_module_action.mid'    //选配,多表联合查询, 第一张表与后续表间的关系,内连接(inner join)，左连接(left join)，右连接(right join)
        filter: [ //选配, 查询条件,变量采用 #{} 方式,旧值采用old. ,新值采用new. 注意:AND或OR后面必须是数组,如果中括号前不写AND或OR，则默认为AND
            {AND:[{'rid':{'=':'#{rid}'}}]},  ==>{'rid':{'=':'#{rid}'}}  => {'rid':'#{rid}'} //简写方式,操作符默认为=
            {OR:[{'rid':{'=':'#{rid}'}},     ==>{'rid':{'=':'#{rid}'}}  => {'rid':'#{rid}'} //简写方式
                 {OR:[{'rid':{'=':'#{rid}'}}]},
                 {AND:[{'rid':{'=':'#{rid}'}}]}
                ]
            }
            [{'rid':'#{rid}'},{'rid':{'=':'#{rid}'}}] //AND的简写方式
            [{'rid':'#{rid}'},{OR:{'rid':'#{rid}'}},{OR:{'rid':'#{rid}'}}] //OR的简写方式
        ],
        dict: { //选配,字典翻译
            字段名: {           //必配,要翻译的字段名
                appendField: ''    //选配, 翻译后要增加到结果集中的字段名称，如果翻译后不增加字段则不配置本项，系统将翻译后的字段替换源字段值
                fix: {1:'男',0:'女'}  //选配, 固定值翻译
                table: {    //选配, 数据库查询后翻译
                    name: '',    //必配, 表名字
                    field: '',   //必配, 要拿值的字段名称
                    where: "字段名=?"  //选配, 查询条件，如果不配置此项，则查询条件默认为翻译的字段名称(当2个表的字段名称相同时可以不配置)
                }
            }
        }
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# 选项说明

参数	必填	数据类型	默认值	可选值	说明
att	否	JSON			前端传给后端的只用于head中配置了source的情况，格式为字段名称和字段值,例如：{name: '张三'}
onlyField	否	Boolean	false	true false	是否只拿查询结果字段名称,不拿数据,true:只拿字段,不拿字段数据 false:数据与字段都要拿
isPrivilege	否	Boolean	true	true false	对模块子表是否进行权限判断
export	否	Boolean	true	true false	导出数据时是否从数据库字典表拿字段名称和标题
titles	否	Array			导出字段的标题
keyField	否	Boolean	false	true false	是否需要回传主键字段名字
privilege	否	Boolean String Array	false		是否加载后立即从服务器拿按钮操作权限,默认为false,可设置类型:Boolean, String, Array
load	否	Boolean	true	true false	是否加载后就立即查询,默认为true,只有设置为false时初始化加载后才不拿数据
order	否	String			服务器查询时排序,例如按姓名升序排序: 'name asc'
group	否	String			查询结果分组字段多个字段逗号分隔，例如对name,id字段进行分组则设置为: 'id,name'
fields	否	String			查询的字段名称,为空或者*表示所有字段
page	否	Number	1		如果有分页,拿第几页
size	否	Number	10		如果有分页,每页数据条数
lastId	否	String			当前页的最后一条数据的_id值,只针对MongoDB的分页查询优化有效
sql	否	String			自定义sql(后端服务器要开启允许自定义sql)，如果采用此项，merge\filter\fields选项都无效
merge	否	JSON			多表联合查询，例如3张表联合查询格式为`INNER JOIN sys_module on sys_privilege.mid = sys_module.mid INNER JOIN sys_module_action on sys_module.mid = sys_module_action.mid and sys_privilege.action = sys_module_action.action`
filter	否	JSON			查询条件,变量采用 #{} 方式,旧值采用old. ,新值采用new. 注意:AND或OR后面必须是数组,如果中括号前不写AND或OR，则默认为AND
dict	否	JSON			服务器端字典翻译

# 其中filter查询条件选项

规则：每个条件为一个json，多个条件为一个数组。

filter: [
    {字段1: 值}, //条件1:例如 id=1 写为: {id: 1}
    {字段2: 值}, //AND连接条件2:例如 number>1 写为: {number: {>: 1}}
    {OR: [{字段3: 值}]}, //OR连接条件3
    [{字段4: 值}, {OR: [{字段5: 值}]}] //条件4与条件5之间OR连接
]

1
2
3
4
5
6

简写方式：原始写法：{AND:[{rid: {'=': 1}}]} 简单写法1：{rid: {'=': 1}} //此时系统默认与前面条件为AND连接简单写法2：{rid: 1} //此时系统默认操作符为等号，即：=

# 其中dict字典翻译选项

说明：dict用于告诉后端需要进行字段翻译，结构体格式为：

dict: {
        字段名: {           //必配,要翻译的字段名
            appendField: ''    //选配, 翻译后要增加到结果集中的字段名称，如果翻译后不增加字段则不配置本项，系统将翻译后的字段替换源字段值
            fix: {1:'男',0:'女'}  //选配, 固定值翻译
            table: {    //选配, 数据库查询后翻译
                name: '',    //必配, 表名字
                field: '',   //必配, 要拿值的字段名称
                where: "字段名=?"  //选配, 查询条件，如果不配置此项，则查询条件默认为翻译的字段名称(当2个表的字段名称相同时可以不配置)
            }
        }
    }

1
2
3
4
5
6
7
8
9
10
11

# 例1: 配置head

# 例1.1: 配置模块

配置模块后，系统会检查该模块是否存在，如果存在并且该模块设置了主表，则使用该模块下的主表进行操作。例如访问user模块下的主表，则配置的head结构体为：

    head:{
        module: 'user'       /* user模块编号 */
    }

1
2
3

TIP

说明：由于默认访问关系数据库，因此省略dbType参数，由于只操作user模块的主表因此省略source、view和table。

# 例1.2: 配置表

如果访问模块下的主表，则不用配置table，如果该模块还有多个子表，可指明访问该模块下的哪个子表，例如访问user模块下的 member表，则配置的head结构体为：

    head:{
        module: 'user'       /* user模块编号 */
        table: 'member'     /* user模块下的子表名 */
    }

1
2
3
4

TIP

说明：由于默认访问关系数据库，因此省略dbType参数。

# 例1.3: 配置自定义SQL数据源

针对自定义的SQL语句，系统支持对自定义SQL设置编号，在此配置自定义SQL的编号

    head:{
        source: 'sql_user'       /* 使用后端定义的编号为sql_user的数据源 */
    }

1
2
3

TIP

说明：由于默认访问关系数据库，因此省略dbType参数。

# 例2: 配置多表联合查询

# 例2.1 配置2张表联合查询

例如查询sys_module模块下的sys_module表与sys_module模块下的sys_module_action表，2张表的连接条件为sys_module的mid字段值等同于sys_module_action表的mid字段值，要返回的字段是将sys_module表的name改名为midname，sys_module_action表的name字段改名为actionname。查询条件是sysid字段的值为sys并且action字段的值为add。
SQL语句为:

SELECT sys_module.name as midname,sys_module_action.name as actionname
  FROM sys_module, sys_module_action
  WHERE sys_module.mid = sys_module_action.mid;

1
2
3

等同于：

SELECT sys_module.name as midname,sys_module_action.name as actionname 
  FROM sys_module
  INNER JOIN sys_module_action on sys_module.mid = sys_module_action.mid;

1
2
3

等同于：

merge: 'INNER JOIN sys_module_action on sys_module.mid = sys_module_action.mid' //第一张表与第二张表采用内连接(inner join)方式，内联字段为mid

# 例2.2 配置3张表联合查询

例如查询sys_privilege模块下sys_privilege表与sys_module模块下的sys_module表与sys_module模块下的sys_module_action表，2张表的连接条件为sys_module的mid字段值等同于sys_module_action表的mid字段值，要返回的字段是将sys_module表的name改名为midname，sys_module_action表的name字段改名为actionname。查询条件是sysid字段的值为sys并且action字段的值为add。 SQL语句为:

SELECT sys_privilege, sys_module.name as midname, sys_module_action.name as actionname  
   FROM sys_privilege, sys_module, sys_module_action  
   WHERE sys_privilege.mid = sys_module.mid AND sys_module.mid = sys_module_action.mid;

1
2
3

等同于：

SELECT sys_module.name as midname,sys_module_action.name as actionname  
  FROM sys_privilege 
  INNER JOIN sys_module on sys_privilege.mid = sys_module.mid 
  INNER JOIN sys_module_action on sys_module.mid = sys_module_action.mid;

1
2
3
4

等同于：

merge: 'INNER JOIN sys_module on sys_privilege.mid = sys_module.mid 
        INNER JOIN sys_module_action on sys_module.mid = sys_module_action.mid', //第一张表与第二张表采用内连接(inner join)方式，内联字段为mid

1
2
3

# 例3: 配置查询条件

# 例子3.1: AND查询1

SQL条件:

(id=1) and (name='zs')

等同于：

filter: [
    {id: 1},
    {name: 'zs'}
]

1
2
3
4

# 例子3.2: AND查询2

SQL条件:

(id>1) and (name like '%zs')

等同于：

filter: [
    {id: {'>': 1}},
    {name: {like: '%zs'}}
]

1
2
3
4

# 例子3.3: OR查询1

SQL条件:

(id=1) or (name='zs')

等同于：

filter: [
    {id: 1},
    {or: [{name: 'zs'}]}
]

1
2
3
4

# 例子3.4: OR查询2

SQL条件:

(id=1) or (name='zs' and job=2)

等同于：

filter: [
    {id: 1},
    {or: [{name: 'zs'}, {jon: 2}]}
]

1
2
3
4

# 例子3.5: AND与OR联合查询

SQL条件:

(id=1 or make>1) or (name='zs' and job=2)

等同于：

filter: [
    [{id: 1},{or: [{make: {'>': 1}}]}],
    {or: [{name: 'zs'}, {jon: 2}]}
]

1
2
3
4

← 开发步骤 2.后端返回格式(response) →