全部产品
云市场

JDBC数据服务使用

更新时间:2019-10-09 21:16:50

JDBC数据服务是通过 JDBC 将后端数据库访问能力以 RESTful 方式发布为 CSB 服务。

目前支持单表和多表查询,后续根据需要会提供插入、修改和删除库表数据的能力。

服务发布

使用前提条件

  • 已申请或授权使用指定 CSB 实例,参见CSB实例管理
  • 需要您已掌握 CSB 的基本使用,包含 RESTful 服务发布和调用等,参见CSB 服务发布
  • 需要您具有 SQL 和 MyBatis 基本使用基础知识。

数据源管理

CSB 目前支持 MySQL 兼容的数据库,包括 RDS、DRDS 和 MySQL。

CSB 默认使用的 MySQL JDBC 驱动版本为 5.1.40 (兼容此版本之前的驱动),如需使用特定版本的 MySQL 驱动,请联系 CSB 技术支持人员。

每个 CSB 实例可以配置多个数据源,多个服务可以共享一个数据源:

实例数据源

数据源列表

服务管理

发布服务的过程与普通服务发布一样,只是在接入协议配置界面有所不同。

单表查询

  • 查询配置

    单表查询的接入协议配置如下:

    单表查询

  • 配置项说明:

    • 数据源:选择CSB实例上已配置好的数据源,或直接点“数据源管理”进行当前CSB实例数据源的新增、修改和删除。
    • 返回记录数上限:一次查询服务请求最多允许返回多少条记录。
    • SQL 模板:以 MyBatis 语法进行查询 SQL 语句模板表达,只写“FROM 表名 WHERE 条件 ORDER/GROUP”子句,CSB自动根据接入协议的出参配置进行“SELECT 结果字段列表”子句的生成。示例SQL模板如下:
      1. FROM tableName
      2. WHERE field1 > #{参数1} and field2 in (#{参数21}, #{参数22}) and field3 like concat('%',#{参数3},'%')
      3. ORDER BY field4 asc, field5 desc
    • 生成的SQL模板:显示根据当前出参和SQL模板最终生成的查询SQL示意。
    • 生成的统计SQL模板:显示根据当前配置和SQL模板最终生成的查询记录数统计SQL示意。
    • 高级选项:“COUNT扫描总记录数保护”是通过设置“COUNT扫描总记录数上限”,对SQL语句进行封装,限定统计SQL扫描记录数量的上限,避免COUNT命令对数据库造成的压力。
  • 入参配置

    CSB自动生成单表查询的入参模板字段,并根据入参配置自动将请求参数传递给MyBatis语法的SQL模板,以便执行数据查询。服务入参界面如下:

    单表查询入参

    各入参字段说明如下:

    • requireTotalCount:是否返回总记录数,CSB客户端传“true”时,CSB会使用“统计SQL模板”进行总记录数统计。可以删除此模板字段入参,删除后不允许此服务进行总记录统计。
    • offset:从第n条查询结果记录开始返回,含义与MySQL的此关键字一致。可以删除此模板字段入参,删除后不允许此服务进行offset操作。
    • limit:限定本次服务请求返回的记录数,含义与MySQL的此关键字一致。可以删除此模板字段入参,删除后不允许此服务进行limit操作。
    • queryValues:所有查询参数的结构体,每个子结点的“SQL模板参数”对应一个SQL模板的MyBatis参数,“发布入参名”对应客户端发起请求时传入的参数名。此结构体入参结点不可删除。
  • 出参配置

    CSB根据出参配置自动生成SQL模板的“SELECT 字段列表”子名。服务出参界面如下:

    单表查询出参

    CSB自动生成单表查询的出参模板字段:

    • resultCode:查询服务返回码,参见 CSB错误代码,此出参不可删除。
    • resultMsg:查询服务执行结果消息,此出参不可删除。
    • tatalCount:符合查询条件的总记录数,此出参不可删除。
    • count:本次查询请求返回的记录数,此出参不可删除。
    • result:本次查询结果记录集结构体,CSB根据此结构体子结点自动生成“SELECT 字段列表”子句,此出参不可删除。
    • __csbRecordError:如果记录的某个字段解析错误,则此字段保存错误信息。比如出参定义某个字段为Long型,但数据表中对应字段的某条记录为字符值,则在试图解析到此记录的字段值并转换为Long型时会抛出异常,导致此条记录生成失败,此时定义的业务结果字段为空,而此字段则会表达出生成记录的错误信息。此出参不可删除。

多表查询

与单表查询类似,只是在特定配置项和字段要求略有不同。

  • 查询配置

    多表查询的接入协议配置如下:

    多表查询

    配置项说明:

    • 数据表名和表别名列表:以英文逗号分隔的多个数据库表和别名,如table1 as t1, table2 t2
    • SQL模板:与单表查询不同之处在于需要明确写各表的别名,以及各字段归属表的别名,示例sql模板如下:
      1. FROM table1 alias1, table2 alias2
      2. WHERE alias1.id=alias2.id1 and alias1.field1 > #{参数1} and alias2.field2 in (#{参数21}, #{参数22}) and alias2.field3 like concat('%',#{参数3},'%')
      3. ORDER BY alias1.field4 desc, alias2.field5 desc
  • 入参配置

    入参配置与单表查询配置完全一样。

  • 出参配置

    出参配置与单表查询配置一样,只是需要明确字段的归属表别名,如下图所示:

    多表查询出参

服务订购

与普通服务的订购完全一样。

服务审批

与普通服务的订购审批完全一样。

服务访问

JDBC 数据服务对外目前只支持 RESTful 协议,客户端访问时与普通 CSB 的 RESTful 服务调用方式完全一样。参见CSB SDK 使用

CLI 方式下进行 JDBC 数据服务调用示例:

  1. java -jar http-sdk-1.1.4.jar -method post -url "http://CSB服务地址:8086/CSB" \
  2. -api "JDBC数据服务名" -version "服务版本号" -ak "凭证ak" -sk "凭证sk" \
  3. -cbJSON "{'requireTotalCount':true,'offset':跳过n条记录,'limit':返回记录数上限,'queryValues':{'查询条件字段1':'查询条件字段值1', '查询条件字段2':'查询条件字段值2'}}"

说明:CSB 服务地址即部署 CSB Broker 的 ECS 实例的 IP 地址。如果 Broker 部署了多个 ECS 实例,并绑定了 SLB,则 CSB 服务地址为 SLB 的地址。

FAQ

SQL 模板里可以使用 MyBatis 的所有语法吗?

是的,SQL 模板安全兼容 MyBatis 语法。

查询结果字段可以支持逻辑运算结果吗?

支持。

  • 单表查询:可以将查询结果的“数据表字段”直接配置为需要的字段逻辑运算表达式。如(score1+score2)/2
  • 多表查询:可以将查询结果的“表别名.字段名”直接配置为需要的字段逻辑运算表达式,如(t1.score1 + t2.score2)/2。与单表查询的区别在于各字段都需要明确归属表的别名。

多表查询支持 left join 吗?

支持。按数据源类型支持的标准 left join 语法写法 SQL 模板即可。