cj2sql 使用指南:仓颉宏驱动的类型安全 SQL 生成与增删改查实战

原创2026-10-13 12:18:331,384 阅读
文章标签:数据库ORM后端

cj2sql 使用指南:仓颉宏驱动的类型安全 SQL 生成与增删改查实战

cj2sql 是一个基于仓颉(Cangjie)宏系统构建的 SQL 生成框架:在编译期通过 @cjSql 宏展开,将仓颉函数中的特定代码结构转换为 SQL 抽象语法树,最终生成可执行的 SQL 字符串与绑定参数。本指南以 doc/use.md 为主体,结合仓库源码与测试用例,系统讲解查询、更新、删除、插入四大 DML 操作的完整写法,覆盖 like/in/exists/between/case when 等关键字扩展、SQL 函数扩展、实体与表信息映射以及多数据库方言支持。读完本文,你将能够用纯仓颉语法声明式地编写任意增删改查逻辑,并获得带占位符与参数列表的 BoundSql 结果。

一、环境准备与依赖引入

在使用 cj2sql 之前,需要先配置仓颉编译器环境与项目依赖(详见 README.md):

  1. 设置 STDX 模块环境变量:cj2sql 依赖仓颉标准扩展库(STDX),需设置类似 CANGJIE_STDX_PATH=path\to\cangjie-stdx-windows-x64-x.x.x.x\windows_x86_64_llvm\dynamic\stdx 的环境变量,否则编译会失败。
  2. 添加依赖配置:在项目 cjpm.toml 中声明依赖:
[dependencies]
  cj2sql = { git = "https://gitcode.com/Cangjie-SIG/cj2sql" }
  1. 运行单元测试:在工程根目录执行 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 动态扩展

当默认的类名/属性名映射不满足实际表结构时,可按三步自定义表信息:

  1. 表信息元数据:实现接口 cj2sql.sql.meta.TableInfo,提供 databaseName、schemaName、tableName、propNames、getColumnName 等能力(接口定义见 src/sql/meta/table_info.cj);
  2. 表信息工厂:实现接口 cj2sql.sql.meta.TableFactory,负责 getTableInfo / registerTableInfo(接口定义见 src/sql/meta/table_factory.cj);
  3. 替换原表信息工厂:调用 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 ?, ?
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 编写需求。

登录后查看全文
cj2sql