TSQL API使用简介

代码地址：trantor-example-sql

DS作为业务模块的数据访问代理层（调用路径为：业务模块 —> DS —> DB），在提供GQL API访问数据库的基础上，增加了TrantorSQL（简称TSQL） API访问数据库的能力。

TSQL API（TrantorSqlDAO、TrantorLowLevelSqlDAO）与GQL API（TrantorDAO）两者互补，可以并存。

1 TSQL定义

• TSQL与MySQL 5.7的语法类似，主要差异如下：
  • TSQL中的表名为模型Key，字段名为模型字段名，比如：select name from test_TestCompany where id > 1000，其中test_TestCompany是模型Key，id和name是模型字段名
  • TSQL可通过点号（.）引用关联模型字段名，比如：select items.name from test_TestOrder where items.amount = 1，其中items是test_TestOrder的直接关联模型
  • TSQL中若出现别名，则所有字段名都通过别名引用，比如：select c.name from test_TestCompany as c where c.id > 1000，其中c是别名
• TSQL可以手写，但推荐使用开源软件jOOQ的DSL进行构建（Trantor提供了 SqlDSL、InsertSqlDSL、UpdateSqlDSL、DeleteSqlDSL、SelectSqlDSL 等工具类来帮助构建TSQL）
• DS不会直接将TSQL传入DB中进行执行，而是在解析TSQL后会自动转换为一到多条SQL再执行

1.1 直接关联模型和间接关联模型

• 假如Model1中定义了对Model2的关联关系，Model2中定义了对Model3的关联关系，则称Model2为Model1的直接关联模型，Model3为Model1的间接关联模型

2 TSQL API vs GQL API

2.1 功能差异

	GQL API	TSQL API
仅创建主模型	支持	支持
同时创建主模型和关联模型	支持	不支持
仅修改主模型	支持	支持
同时修改主模型和关联模型	支持	不支持
仅删除主模型	支持	支持
同时删除主模型和关联模型	不支持	不支持
仅查询主模型	支持	支持
同时查询主模型和多级关联模型	支持	支持

TSQL API对于单模型CRUD支持较好，基本上各种SQL都支持，但是相对于GQL API来说，对关联模型的支持较弱：

1、不支持在创建或修改主模型时，同时创建或修改关联模型

2、不支持查询关联模型时，对关联模型分页

2.1.1 不支持同时创建关联模型

--GQL
mutation {
  createManytest_center_Model3(
    data: [
      {
        stringField: "2李四2"
        intField: 12
        oneToOneField: {
            create:
              {
                booleanField: true
                stringField: "1string1"
                partitionKeyField: "1"
              }
          }
        oneToManyField: {
            create:[
              {
                dateTimeField: "2020-04-28 11:11:11"
                partitionKeyField: "1"
              }
            ]
          }
        manyToManyField: {
            create:[
              {
                stringField: "1string1"
                partitionKeyField: "1"
              }
            ]
          }
      }
    ]
  ) {
    _COUNT
  }
}

--TSQL 不支持

2.1.2 不支持关联模型分页查询

--GQL
query {
  partner_center_Partners(
    where: { id: 1 }
    orderBy: updatedAt_DESC
    skip: 0
    first: 10
  ) {
    id
    name
    labels(skip: 10, first: 20) {
      id
      name
    }
  }
}

--TSQL 不支持：jooq的DSL不能构建如下SQL
select
    `id`,
    `name`,
    `labels`.(`id`, `name`) limit 10,20
from
    `partner_center__partner`
limit
    0, 10

select
    `id`,
    `name`,
    `labels`.`id`,
    `labels`.`name`
from
    `partner_center__partner`
limit
    (0, 10),lables(10,20)

2.1.3 不支持select from多张表

不支持SQL

select
    u.id as uid,
    u.name as uname,
    c.id as cid,
    c.createdAt as ccreatedAt
from
    base_User u,
    base_Company c
where
    u.`name` = c.`name`
limit
    2;

但是可以换成Join写法来实现完全相同的功能

select
    u.id as uid,
    u.name as uname,
    c.id as cid,
    c.createdAt as ccreatedAt
from
    base_User u
    left join base_Company c on u.`name` = c.`name`
limit
    2;

2.1.4 Join

TSQL支持Join语法，支持inner join、cross join、left join、right join、straight join

select
    u.id as uid,
    u.name as uname,
    c.id as cid,
    c.createdAt as ccreatedAt
from
    base_User u
    left join base_Company c on u.`name` = c.`name`
limit
    2;

限制项：

1. 必须指定表别名以及字段别名：举例select id,name from base_User u left join base_Company on xxx，原因是无法知道select的字段属于哪个模型
2. 不允许select *：举例select * from base_User u left join base_Company on xxx，请显示声明需要查询的字段
3. 如果显示使用Join语法，则不可以同时使用关联模型查询

2.2 语法差异

2.2.1 Create

--GQL:
mutation {
  createManytest_TestCompany(
    data: [
      {
        f1: 1.01
        f2: "abc"
      }
      {
        f1: 2.01
        f2: "adf"
      }
      {
        f1: 3.01
        f2: "bbb"
      }
    ]
  ) {
    id
  }
}

--TSQL:
insert into `test_TestCompany`(`f1`,`f2`) values(1.01,'abc'),(2.01,'adf'),(3.01,'bbb')

2.2.2 Update

--GQL:
mutation {
  updateManytest_TestCompany(
    data: {
        f1: false
        f2: "hhh"
        f3: 10
    }
    where: { id_in: [1,2,3,4] }
  ) {
    _COUNT
  }
}

--TSQL:
update `test_TestCompany` set `f1`=false, `f2`='hhh', `f3`=10 where `id` in (1,2,3,4)

2.2.3 Delete

--GQL:
mutation {
  deleteManytest_center_Model3(
    where: { id_gt: 3 }
  ) {
    _COUNT
  }
}

--TSQL:
delete from `test_TestCompany` where `id`>3

2.2.4 Retrieve

--GQL:
query {test_TestCompanies(where: { id: 1 }) {_ALL}}

--TSQL:
select * from `test_TestCompany` where `id`=1

3 业务代码使用

3.1 不绑定业务模型

适用于多模型联表查询场景，比如：

select a.`f1`, b.`f2` from test_Model1 a left join test_Model2 b on a.`f3`= b.`f4` where b.`f5` > 5 limit 10
select a.`f1`, b.`f2` from test_Model1 a left join test_Model2 b on a.`f3`= b.`f4` where b.`f5` > :f5Value limit :pageSize

3.1.1 TrantorLowLevelSqlDAO使用

用户直接使用@Autowired注入TrantorLowLevelSqlDAO直接使用

@Autowired
private TrantorLowLevelSqlDAO trantorLowLevelSqlDAO;

TrantorLowLevelSqlDAO定义如下，方法主要包括批量查询，详情见：LowLevelSelectSqlDAO开发文档

@Component
@NoArgsConstructor
final public class TrantorLowLevelSqlDAO implements ApplicationContextAware, LowLevelSelectSqlDAO {
  ...实现代码
}

3.2 绑定业务模型

适用于单个模型CURD，涉及多模型联表查询时，请使用TrantorLowLevelSqlDAO。

3.2.1 TrantorSqlDAO 使用

TrantorSqlDAO使用如下，方法主要包括增删改查，详情见：TrantorSqlDAO开发文档

@Repository
public class StudentSqlDao extends TrantorSqlDAO<Student, Long> {

}

4. 常见问题

4.1 create api报 Integer cannot be cast to Long

请确认trantor sdk版本是否为0.13.0-SNAPSHOT及以上版本

<dependency>
  <groupId>io.terminus.trantor</groupId>
  <artifactId>sdk</artifactId>
  <version>0.13.0-SNAPSHOT</version>
</dependency>

如果是0.13.0-SNAPSHOT，则确认下当前项目中依赖的jar包打包日期是否早于11月12号，如果早于这个时间点，请重新import最新jar包。

4.2 select api部分字段查不到数据

如果查不到数据的字段都通过dbColumnName属性指定了dbName

@TModelField(dbColumnName = "db_field")
private String dbField;

请检查本地运行的datastore镜像tag是否为5.1.0.39之前的，如果是请升级到5.1.0.39。