cj2sql 使用指南:仓颉宏驱动的类型安全 SQL 生成与增删改查实战
cj2sql 使用指南:仓颉宏驱动的类型安全 SQL 生成与增删改查实战
cj2sql 是一个基于仓颉(Cangjie)宏系统构建的 SQL 生成框架:在编译期通过 @cjSql 宏展开,将仓颉函数中的特定代码结构转换为 SQL 抽象语法树,最终生成可执行的 SQL 字符串与绑定参数。本指南以 doc/use.md 为主体,结合仓库源码与测试用例,系统讲解查询、更新、删除、插入四大 DML 操作的完整写法,覆盖 like/in/exists/between/case when 等关键字扩展、SQL 函数扩展、实体与表信息映射以及多数据库方言支持。读完本文,你将能够用纯仓颉语法声明式地编写任意增删改查逻辑,并获得带占位符与参数列表的 BoundSql 结果。
一、环境准备与依赖引入
在使用 cj2sql 之前,需要先配置仓颉编译器环境与项目依赖(详见 README.md):
- 设置 STDX 模块环境变量:cj2sql 依赖仓颉标准扩展库(STDX),需设置类似
CANGJIE_STDX_PATH=path\to\cangjie-stdx-windows-x64-x.x.x.x\windows_x86_64_llvm\dynamic\stdx的环境变量,否则编译会失败。 - 添加依赖配置:在项目
cjpm.toml中声明依赖:
[dependencies]
cj2sql = { git = "https://gitcode.com/Cangjie-SIG/cj2sql" }
- 运行单元测试:在工程根目录执行
cjpm test,可验证框架行为与当前环境是否匹配。
二、快速上手:导入与宏标注
2.1 导入宏和工具类
查询功能需要导入以下四类符号(见 src/sql/use.cj):
// 宏
import cj2sql.macros.cjSql
// 宏生成使用的统一工具类
import cj2sql.sql.ExprUtil
// 枚举(方便当前提供方法的提示)
import cj2sql.sql.ExtSql
// 查询
import cj2sql.sql.select
cjSql:核心编译期宏,负责把函数体内可识别的代码结构改写成 SQL 语法树构建代码;ExprUtil:表达式工具类,提供列、参数、二元操作、in、between、case when、exists 等表达式的构造方法;ExtSql/ExtFunc:关键字与函数枚举,仅用于在源码层面声明 SQL 关键字与函数,帮助编辑器提示与宏解析;select(以及insert、update、delete):创建 DML 语句对象的泛型工厂函数。
2.2 使用宏
所有包含 DML 代码的函数都必须标注 @cjSql,宏会在编译期解析方法体(入口实现见 src/macros/cjsql.cj):
@cjSql
public func useCjSql(userId: Int) {
// ... dml 代码
}
宏 cjSql 会基于 FunctionParser 遍历函数体,把 select、join、filter、set、values 等调用及其尾随闭包转换成 SQL 抽象语法树节点(接口设计详见 doc/design.md)。除 cjSql 外,还可使用 originSql 宏在列中嵌入原始 SQL 片段。
三、查询(Select)
3.1 创建操作对象与关联表
基于表实体创建查询对象,并支持 join 系列关联:
// 基于表实体, 创建查询
let user = select<User>()
// 目前支持 join, left join, right join, cross join
// 关联表, 并设置关联关系
let role = join<Role>() {t => t.id == user.roleId}
select<T>() 内部通过 DefaultDmlCreator.select<T>() 创建 Select 语句并绑定 From(TableHelper.getTableInfo<T>()),表名、列名由实体类元信息推导(见 src/sql/dml/default_dml_creator.cj)。join 类型由宏根据方法名区分:join 为普通 JOIN,另有 leftJoin、rightJoin、innerJoin、crossJoin,分别对应 DefaultDmlCreator 中 origin.left/right/inner/cross 标志位的设置。
3.2 设置筛选条件
规则:每一行为一个条件,多行自动使用 AND 连接;每行代码均需符合仓颉语法格式。
join on
通过 join 语句的 on 方法添加多表关联条件:
// 通过 join 语句的 on 方法添加多表关联条件
role.on {
user.roleId > role.id
}
// 简单使用
role.on(user.roleId > role.id)
where
let name = 'cangjie'
let list = [10, 20, 30]
user.filter {
user.id == 1
user.id >= 1
user.id > 1
role.id != 0
role.id <= 1
role.id < 1
(role.name == 'admin' && role.name == 'cangjie')
(role.name == 'admin' || role.name == 'cangjie')
if (name.size > 0) {
role.userName == name
}
// in 列表
inn(role.id, 1, 2, 3)
notIn(role.id, 1, 3, 5)
inn(role.id, list)
notIn(role.id, list)
// 左右模糊
likeAll(role.name, 'mi')
likeLeft(role.name, 'jie')
likeRight(role.name, 'cang')
// notLike, notLikeLeft, notLikeRight 同理
// 判空
user.id is null
user.id is notNull
}
// 简单筛选(复杂筛选使用尾随表达式)
user.filter(user.id == 1, role.id > 10)
要点说明:
- 动态参数:
user.id == 1中的字面量会编译为参数占位符?;而变量(如userId、list)会被自动解析为ParameterExpr动态参数,实际值收集进BoundSql.parameters(实现见 src/sql/expr/param.cj)。 - 动态 if:仓颉
if语句会在编译期按分支条件生成对应 SQL 片段,实现"代码 if 判断"动态拼接。 - 优先级:需要括号的复合条件请显式使用括号,如
(role.name == 'admin' && role.name == 'cangjie');生成 SQL 时嵌套条件会被SqlBuilder用圆括号包裹(见 src/sql/statement/sql_builder.cj)。 - 两种调用形式:尾随闭包形式
filter { ... }支持多行条件与复杂逻辑;普通参数形式filter(expr1, expr2)适合简单筛选。
having
user.having {
// having 条件同 where 条件一样
// 注意在严格模式下, 必须存在 group by 列
}
// 简单条件(使用方法同 where)
user.having()
having 与 where 语法完全一致,但语义上作用于分组结果;在严格模式下使用 having 必须同时存在 groupBy 列。
3.3 设置列
规则:每一行为一列,多行自动使用 , 连接(若写到一行,使用 ; 分割);每行代码均需符合仓颉语法格式。
select
user.select {
user.age
// 使用别名
user.id as uid
// 使用原始 SQL (内部展开宏)
@originSql("CAST(user.id AS varchar)") as cid
}
// 简单查询列
user.select(user.age, user.id as uid)
@originSql 由 src/macros/cjsql.cj 中的 originSql 宏处理,在编译期将括号内的字符串原样展开为 SQL 片段,适合嵌入数据库专有语法(如 CAST、函数表达式等)。
group by
user.groupBy {
// groupBy 列同 select 列一样
}
// 简单分组
user.groupBy() // 使用方法同 select 列一样
order by
user.orderBy {
// 默认 asc 排序
user.id
// 注意需要使用 is 关键字
user.roleId is desc
user.roleId is asc
}
// 简单排序(仅支持同为 asc)
user.orderBy(user.id)
排序方向通过 is asc / is desc 表达式声明(映射到 SqlOrderByItem),裸列默认 ASC;注意简单参数形式 orderBy(...) 仅支持同方向(asc)排序。
3.4 其他扩展方法
// 为查询表设置别名, 若不存在此方法, 则会自动报绑定变量名
user.tableAlias('u')
role.tableAlias('r')
// 将所有字段设置为查询列
user.addAllSelectItem(includeJoin: true)
// 添加 count(1) 列
user.addSelectCount()
// 设置 limit, offset
user.limitOffset(10, 20)
tableAlias:显式设置表别名。宏会自动为select/join生成默认别名(如u、r),若代码中直接使用实体变量名而非别名,编译期会提示绑定变量名错误。addAllSelectItem(includeJoin: true):将所有字段(含 join 表字段)加入查询列。addSelectCount():追加count(1)列。limitOffset(rowCount, offset):设置分页。
3.5 获取结果
// SQL 生成校验, 必须存在 select 列
// 对于存在 having 筛选, 必须存在 groupBy 列
user.validate()
// 生成 SQL 信息
let boundSql = user.toBoundSql()
let sql = boundSql.sql
// 获取 sql 中的所有参数
let params = boundSql.parameters
validate() 执行合法性校验:查询必须存在 select 列;若使用了 having 则必须存在 groupBy 列。toBoundSql() 返回 BoundSql 对象(接口定义见 src/sql/statement/sql_builder.cj),其中:
sql:最终 SQL 字符串,动态参数以?占位(由SqlBuilder.writeParameter统一写入并登记参数,见 src/sql/statement/sql_builder.cj);parameters:按出现顺序排列的参数数组,元素为ParameterExpr,其value属性可取出实际值。
四、更新(Update)
@cjSql
public func useCjSqlUpdate(userId: Int64, newUserId: Int64) {
// update 表, 创建 update 语句对象
let user = update<User>()
user.set {
// 设置赋值条件
user.id = newUserId
user.userName = 'cangjie'
}.filter {
// 设置更新条件
user.id == userId
}
// 简单筛选
user.filter(user.id == userId)
}
set { ... } 中的赋值语句会生成 SET col = ? 片段(字符串字面量直接内联),filter 生成 WHERE 条件。测试用例(见 src/use_update_test.cj)验证生成结果为:
UPDATE user_test SET id = ?, user_name = 'cangjie' WHERE id = ? AND user_name = 'abc'
五、删除(Delete)
@cjSql
public func useCjSqlDelete(userId: Int64) {
// delete 表, 创建 delete 语句对象
let user = delete<User>()
user.filter {
// 设置删除条件
user.id == userId
user.userName == 'abc'
}
// 简单筛选
user.filter(user.id == userId, user.userName == 'abc')
}
对应生成 SQL(见 src/use_delete_test.cj):
DELETE FROM user_test WHERE id = ? AND user_name = 'abc'
六、插入(Insert)
6.1 单条插入
@cjSql
public func useCjSqlInsert(userId: Int64) {
// insert 表, 创建 insert 语句对象
let user = insert<User>()
user.values {
// 设置插入值
user.id = userId
user.userName = 'abc'
}
}
6.2 批量插入
@cjSql
public static func useCjSqlInsertList(userIdList: Array<Int64>) {
// insert 表, 创建 insert 语句对象
let user = insert<UserTest>()
user.values {
// 批量插入
for (userId in userIdList) {
// 设置插入值
user.id = userId
user.userName = 'cangjie'
}
}
}
在 values 闭包中直接编写仓颉 for 循环即可声明批量插入;宏在编译期展开循环为多行 VALUES。测试用例(见 src/use_insert_test.cj)验证 3 个元素的列表生成:
INSERT INTO user_test(id, user_name) VALUES (?, 'cangjie'), (?, 'cangjie'), (?, 'cangjie')
七、SQL 关键字扩展(ExtSql)
导入枚举 ExtSql(import cj2sql.sql.ExtSql),其枚举值仅用于声明 SQL 关键字。使用规则:ExtSql.关键字(参数列表);在已导入的情况下,前缀 ExtSql. 可省略。完整枚举定义见 src/sql/use.cj。
7.1 like
规则:like(列, 字符串/字符变量),notLike 同 like。
// 左模糊
likeAll(user.id, 'abc') // ==> user.id LIKE '%abc'
// 右模糊
likeRight(user.id, 'abc') // ==> user.id LIKE 'abc%'
// 全模糊
likeAll(user.id, 'abc') // ==> user.id LIKE '%abc%'
// 原生 like (需要自行拼接模糊)
like(user.id, 'abc') // ==> user.id LIKE 'abc'
// notLike 同 like 一样
notLike(user.id, 'abc') // ==> user.id NOT LIKE 'abc'
扩展说明:枚举中还提供 likeLeft、notLikeLeft、notLikeRight、notLikeAll 等变体。当模糊参数来自变量时,宏会预先拼接 % 通配符并作为绑定参数传入(测试用例中 likeAll(user.userName, userName) 的参数值为 '%' + userName + '%',见 src/use_select_test.cj)。
7.2 in
规则:inn(列, 可迭代的值/子查询),notIn 同 inn。
// in 字面量
inn(user.id, 1, 2, 3)
// ==> user.id in (1, 2, 3)
// in 可迭代变量
let list = [1, 2, 3]
inn(user.id, list)
// ==> user.id in (?, ?, ?)
// in 子查询
inn(user.id, user.subQuery<RoleTest> {
r =>
r.select { r.id }.filter { r.id == 2}
})
// ==> user.id in (SELECT r.id FROM role_test r WHERE r.id = 2)
注意:in 字面量形式直接内联数值;可迭代变量形式会为每个元素生成 ? 占位参数;子查询形式通过 subQuery<T> 构建内联 SELECT。
7.3 exists
规则:exists(列, 子查询),notExists 同 exists。
// exists 子查询
exists(user.id, user.subQuery<RoleTest> {
r =>
r.select { r.id }.filter { r.id == 2}
})
// ==> EXISTS (SELECT r.id FROM role_test r WHERE r.id = 2)
底层通过 SqlExists 表达式生成 EXISTS (...) 前缀(见 src/sql/statement/sql_builder.cj),目前仅支持子查询。
7.4 between and
规则:between(列, 开始字面量/变量, 结束字面量/变量),notBetween 同 between。
// between and
let five = 5
between(user.id, 1, five)
// ==> user.id BETWEEN 1 AND ?
开始值若为字面量则内联,结束值若为变量则转为参数占位。
7.5 case when
规则:caseWhen(if/match表达式);可用于 select 列,但需要配合 as 使用。
caseWhen(if (user.id > 1) {
user.id
} else {
user.roleId
}) == 1
// ==> (CASE WHEN user.id > 1 THEN user.id ELSE user.role_id END) = 1
caseWhen 既支持 if/else 表达式,也支持 match 表达式改写。测试用例中的 match 形式(见 src/use_select_test.cj)生成:
CASE u.id WHEN 1 THEN u.user_name WHEN 2 THEN r.role_name ELSE 'unknown' END
7.6 null / notNull / asc / desc
逻辑表达式:
user.id is null // ==> user.id IS NULL
user.id is notNull // ==> user.id IS NOT NULL
排序列(用于 orderBy 闭包):
user.id is asc // ==> user.id ASC
user.id is desc // ==> user.id DESC
八、SQL 函数扩展(ExtFunc)
导入枚举 ExtFunc(import cj2sql.sql.ExtFunc),枚举值仅用于声明 SQL 函数。使用规则:ExtFunc.函数名(参数列表),前缀 ExtFunc. 可省略。当前支持函数:count、avg、min、max、sum、concat(定义见 src/sql/use.cj)。
concat(user.id, user.roleId) as newId
// ==> concat(user.id, user.role_id) newId
函数调用最终生成 SqlFunctionExpr(函数名(参数列表) 形式),可与 as 别名组合使用。测试用例(见 src/use_select_test.cj)展示了 count/min/avg/max/sum/concat 组合查询:
SELECT CAST( u.id AS varchar) cid, count(u.id), min(u.id), avg(u.id), max(u.id), sum(u.id), concat(u.id, u.role_id) newId FROM user_test u WHERE u.id IS NOT NULL
九、实体与表信息
9.1 默认规则
- 表名称:类名转下划线;
- 列名称:类属性转下划线(仅支持
public prop); - 实现类:
cj2sql.sql.meta.ClassTableInfo。
从源码看(src/sql/meta/class_table_info.cj),ClassTableInfo 通过反射读取类的 instanceProperties,并调用 StringUtil.nameUnderline 将驼峰命名转为下划线(如 userName → user_name、roleId → role_id);未找到属性时会抛出 InfoNotFoundException。因此编写实体类时应声明 public prop 属性:
class User {
public prop id: Int64
public prop userName: String
public prop roleId: Int64
}
9.2 动态扩展
当默认的类名/属性名映射不满足实际表结构时,可按三步自定义表信息:
- 表信息元数据:实现接口
cj2sql.sql.meta.TableInfo,提供databaseName、schemaName、tableName、propNames、getColumnName等能力(接口定义见 src/sql/meta/table_info.cj); - 表信息工厂:实现接口
cj2sql.sql.meta.TableFactory,负责getTableInfo/registerTableInfo(接口定义见 src/sql/meta/table_factory.cj); - 替换原表信息工厂:调用
cj2sql.sql.meta.TableHelper#replaceFactory注入自定义工厂(见 src/sql/meta/table_helper.cj)。
替换后,所有 select<T>() / insert<T>() 等操作都会通过新工厂获取表信息,从而实现 database/schema 前缀、自定义列名映射等能力(SqlBuilder.doVisitTableItem 支持输出 database.schema.table alias 结构,见 src/sql/statement/sql_builder.cj)。
十、方言支持
方言抽象接口为 cj2sql.sql.dialect.SqlDialect(定义见 src/sql/dialect/sql_dialect.cj):
public interface SqlDialect {
/**
* 方言名称
*/
prop name: String
/**
* 获取 SQL 和 参数
*/
func getBoundSql(statement: SqlStatement): BoundSql
}
方言名称常量位于 cj2sql.sql.dialect.SqlDialectName,当前支持四种方言:mysql、oracle、postgresql、sqlserver,对应源码目录 src/sql/dialect 下的 mysql、oracle、postgresql、sqlserver 四个子模块。
方言差异主要由各方言的 Builder 定制。例如分页(limit/offset):
LIMIT ?, ?
- Oracle(至少 12c,见 src/sql/dialect/oracle/oracle_sql_builder.cj):
OFFSET ? ROWS FETCH NEXT ? ROWS ONLY
PostgreSQL 与 SQL Server 同样通过各自 Builder(postgresql_builder.cj、sqlserver_builder.cj)定制方言差异点。由于 cj2sql 的 SQL 生成统一走 SqlStatementVisitor 遍历语法树(sql_builder.cj),换方言只需切换 SqlDialect 实现,业务代码无需改动。
十一、综合示例与验证
将以上能力组合,一个完整的联表查询(摘自 README.md 与 src/use_select_test.cj):
@cjSql
public func useCjSql(maxId: Int64, userName: String) {
// 数组参数
let list = ArrayList<Int>(5) {i => i + 1}
// from 表, 创建 select 语句对象
let u = select<User>()
// join 表, 创建 join 对象, 并根据主键 与 from 表关联
let r = u.join<Role>().on {t => t.id == u.roleId}
// 查询所有列(包含所有 join 表)
u.addAllSelectItem(includeJoin: true)
u.select {
u.id as uid
u.userName as uname
u.age as uage
r.id as rid
r.roleName
}
u.filter {
u.id < maxId
(u.roleId > 2 || u.age > 18)
if (userName != '') {
likeAll(u.userName, userName)
} else if (userName.size > 100) {
likeRight(u.userName, userName)
}
if (!list.isEmpty()) {
inn(u.id, list)
}
r.id < maxId
u.userName is notNull
r.roleName is null
}.groupBy {
u.id
u.age
}.having {
u.id > 1
}.orderBy {
u.id is desc
r.id
}
u.limitOffset(10, 20)
// 生成 SQL 字符串
println(u.toBoundSql().sql)
// 遍历参数列表
for (param in u.getParameters()) {
if (let Some(str) <- param.value as ToString) {
println(str.toString())
}
}
}
生成 SQL:
SELECT
u.id,
u.user_name,
u.age,
u.role_id,
r.id,
r.role_name,
u.id uid,
u.user_name uname,
u.age uage,
r.id rid,
r.role_name
FROM user u
JOIN role r ON r.id = u.role_id
WHERE
u.id < ?
AND (u.role_id > 2 OR u.age > 18)
AND u.user_name LIKE ?
AND u.id IN (?, ?, ?, ?, ?)
AND r.id < ?
AND u.user_name IS NOT NULL
AND r.role_name IS NULL
GROUP BY
u.id,
u.age
HAVING
u.id > 1
ORDER BY
u.id DESC,
r.id ASC
LIMIT
20, 10
该示例对应的单元测试位于 src/use_select_test.cj,测试断言了生成的 SQL 字符串、参数个数(8 个)以及关键参数值(如 likeAll 参数为 '%' + userName + '%'),可以作为接入 cj2sql 后自行验证的参照模板。此外,项目还提供 ORM 配合使用的真实示例(litem 项目的 complex_operation_test.cj),展示了在完整业务工程中组合使用 cj2sql 的姿势。
结语
通过 doc/use.md 所描述的这套 DSL,开发者在仓颉代码中即可完成从单表增删改查到联表、分组、子查询、关键字与函数扩展、方言切换的完整 SQL 生成闭环:编译期由 @cjSql 宏完成解析与校验,运行期由 SQL 语法树与 Builder 产出带绑定参数的 BoundSql,再配合 TableInfo 自定义映射与 SqlDialect 方言切换,能够较好地满足多数据库场景下的类型安全 SQL 编写需求。