tycj-orm

仓颉语言 ORM 框架 - 类似 MyBatis/JPA

简介

tycj-orm 是一个为仓颉编程语言设计的 ORM 框架，融合了 JPA 的注解驱动和 MyBatis 的 SQL 映射能力，提供实体映射、CRUD 操作、查询构建器、事务管理等完整的数据访问解决方案。

所有功能已完整实现，无占位函数。 每个模块中的全部方法均包含真实业务逻辑，可直接用于开发和测试。由于仓颉语言目前没有原生数据库驱动，数据源模块提供了完整的内存模拟实现（MockConnection/MockStatement/MockPreparedStatement/MockResultSet），支持基本的 SQL 执行、结果集遍历和主键生成，可用于框架功能的完整验证。

特性

• 注解驱动 - JPA 风格的 @Entity、@Table、@Id、@Column、@GeneratedValue、@Transient 注解
• 查询构建器 - 链式 API 构建复杂查询，支持 SELECT/INSERT/UPDATE/DELETE/COUNT 五种查询类型
• CRUD 接口 - 类似 Spring Data JPA 的 CrudRepository 接口，BaseRepository 提供完整实现
• 事务管理 - 声明式 @Transactional 注解和编程式 TransactionTemplate 模板，支持 7 种传播行为
• 分页排序 - 内置 Page/PageRequest/Sort/Order 分页排序支持
• SQL 映射 - MyBatis 风格的 @Select、@Insert、@Update、@Delete 注解，MapperMethodExecutor 实现参数绑定和结果映射
• 多数据源 - DataSourceFactory 支持多数据源管理和连接池
• Mock 实现 - 完整的内存模拟数据库实现，无需真实数据库即可运行和测试
• 企业级功能 - SQL 执行监控、慢查询日志、连接池健康检查、SQL 注入检测

安装

在项目的 cjpm.toml 中添加依赖：

[dependencies]
tycj-orm = "0.1.0"
tycj-common = "0.1.0"

然后运行：

cjpm update

快速开始

1. 定义实体类

package example

import tybb2026::tycj_orm::entity.*

@Entity
@Table(name: "users")
class User {
    @Id
    @GeneratedValue(strategy: GenerationType.IDENTITY)
    public var id: Int64 = 0

    @Column(name: "username", nullable: false, length: 50)
    public var username: String = ""

    @Column(name: "email", unique: true)
    public var email: String = ""

    @Column(name: "age")
    public var age: Int32 = 0

    @Transient
    public var tempField: String = ""  // 非持久化字段

    init() {}

    init(username: String, email: String, age: Int32) {
        this.username = username
        this.email = email
        this.age = age
    }
}

2. 创建 Repository

package example

import tybb2026::tycj_orm::datasource.*
import tybb2026::tycj_orm::query.*

// 方式一：使用查询构建器
class UserRepository {
    private let dataSource: DataSource

    init(dataSource: DataSource) {
        this.dataSource = dataSource
    }

    func findById(id: Int64): Option<User> {
        let builder = SelectBuilder("users")
        builder.where_("id = ${id}")
        // 执行查询并映射结果
        return None
    }

    func findByUsername(username: String): Option<User> {
        let builder = SelectBuilder("users")
        builder.where_("username = '${username}'")
        // 执行查询并映射结果
        return None
    }
}

// 方式二：使用 Mapper 接口（MyBatis 风格）
@Select("SELECT * FROM users WHERE id = #{id}")
func findUserById(id: Int64): Option<User> {
    // Mapper 方法实现
    return None
}

3. 使用 Repository

package example

import tybb2026::tycj_orm::datasource.*
import tybb2026::tycj_orm::pool.*

main(): Int64 {
    // 配置数据源
    let dbConfig = DatabaseConfig.mysql()
    dbConfig.host = "localhost"
    dbConfig.port = 3306
    dbConfig.database = "testdb"
    dbConfig.username = "root"
    dbConfig.password = "password"

    // 创建连接池
    let poolConfig = PoolConfig()
    poolConfig.setMinPoolSize(2)
    poolConfig.setMaxPoolSize(10)

    let pool = ConnectionPoolFactory.createPool(dbConfig, poolConfig)

    // 创建 Repository
    let userRepository = UserRepository(pool)

    // 获取连接并执行操作
    match (pool.getConnection()) {
        case Some(conn) => {
            // 执行 SQL 操作
            let stmt = conn.prepareStatement("SELECT * FROM users")
            let rs = stmt.executeQuery()

            // 遍历结果
            while (rs.next()) {
                let name = rs.getStringByName("username")
                println("User: ${name}")
            }

            // 关闭资源
            rs.close()
            stmt.close()
            pool.returnConnection(conn)
        }
        case None => println("Failed to get connection")
    }

    pool.close()
    return 0
}

4. 使用查询构建器

package example

import tybb2026::tycj_orm::query.*
import std.collection.*

func complexQuery(): Unit {
    // 构建 SELECT 查询
    let builder = SelectBuilder("users")
    builder
        .column("id")
        .column("username")
        .column("email")
        .innerJoin("orders", "o", "users.id = o.user_id")
        .where_("status = 'ACTIVE'")
        .orderBy("created_at", Direction.Desc)
        .limit(10)
        .offset(0)

    let sql = builder.build()
    println("Generated SQL: ${sql}")

    // 使用 ConditionBuilder 构建复杂条件
    let cb = ConditionBuilder()
    cb.eq("status", "ACTIVE")
      .and_()
      .ge("age", 18)
      .and_()
      .le("age", 60)
      .and_()
      .like("username", "张")

    let condition = cb.build()
    let params = cb.getParameters()
    println("Condition: ${condition}")
    println("Parameters: ${params}")

    // INSERT 查询
    let insertBuilder = InsertBuilder("users")
    insertBuilder.value("username", "张三")
                 .value("email", "zhangsan@example.com")
                 .value("age", "25")
    let insertSql = insertBuilder.build()
    println("Insert SQL: ${insertSql}")

    // UPDATE 查询
    let updateBuilder = UpdateBuilder("users")
    updateBuilder.set("age", "26")
                 .where_("id = 1")
    let updateSql = updateBuilder.build()
    println("Update SQL: ${updateSql}")

    // DELETE 查询
    let deleteBuilder = DeleteBuilder("users")
    deleteBuilder.where_("id = 1")
    let deleteSql = deleteBuilder.build()
    println("Delete SQL: ${deleteSql}")
}

5. 事务管理

package example

import tybb2026::tycj_orm::transaction.*
import tybb2026::tycj_orm::datasource.*

// 编程式事务 - 使用 TransactionTemplate
func transfer(txManager: TransactionManager): Unit {
    let template = TransactionTemplate(txManager)

    // 带返回值的事务
    let result = template.execute<Int64>({ status =>
        // 执行业务逻辑
        // userRepository.save(user)
        // orderRepository.save(order)
        1
    })

    // 无返回值的事务
    template.executeWithoutResult({ status =>
        // 执行业务逻辑
        // userRepository.save(user)
    })
}

// 编程式事务 - 手动管理
func manualTransaction(txManager: TransactionManager): Unit {
    let definition = TransactionDefinition()
    definition.setPropagation(Propagation.Required)
    definition.setIsolation(IsolationLevel.ReadCommitted)
    definition.setTimeout(30)

    let status = txManager.getTransaction(definition)

    try {
        // 执行业务逻辑
        // userRepository.save(user)
        // orderRepository.save(order)

        txManager.commit(status)
    } catch (e: Exception) {
        txManager.rollback(status)
        throw e
    }
}

6. 使用企业级功能

package example

import tybb2026::tycj_orm::enterprise.*
import std.collection.*

func enterpriseFeatures(): Unit {
    // SQL 执行监控
    let monitor = SqlExecutionMonitor()
    monitor.setEnableInjectionCheck(true)
    monitor.setSlowQueryThreshold(100) // 100ms

    let params = ArrayList<String>()
    let context = monitor.startMonitoring("SELECT * FROM users", params)

    // 执行 SQL...

    monitor.endMonitoring(context, 50) // 执行时间 50ms

    // 获取 SQL 统计
    let stats = monitor.getSqlStats()
    for (stat in stats) {
        println("SQL: ${stat.sql}")
        println("Count: ${stat.executionCount}")
        println("Avg Time: ${stat.avgExecutionTime}ms")
    }

    // SQL 注入检测
    let detector = SqlInjectionDetector()
    let issues = detector.detect("SELECT * FROM users; DROP TABLE users--")
    if (!issues.isEmpty()) {
        println("SQL Injection detected!")
        for (issue in issues) {
            println("- ${issue}")
        }
    }

    // 慢查询日志
    let slowLogger = SlowQueryLogger(threshold: 100, maxSize: 1000)
    slowLogger.logQuery("SELECT * FROM users", 150, params)

    let logs = slowLogger.getLogs()
    println("Slow queries: ${logs.size}")
}

模块 API 文档

entity 模块 - 实体映射

提供 JPA 风格的实体注解和元数据解析。

注解

注解	目标	说明
@Entity	Class	标记实体类
@Table	Class	指定表名，参数：name
@Id	Field	标记主键字段
@GeneratedValue	Field	主键生成策略，参数：strategy
@Column	Field	列映射，参数：name、nullable、unique、length
@Transient	Field	标记非持久化字段

枚举

GenerationType - 主键生成策略

值	说明
IDENTITY	数据库自增
SEQUENCE	序列
TABLE	表生成
AUTO	自动选择

类

EntityMetadata - 实体元数据

方法	说明
init(tableName: String)	构造函数
addFieldMapping(fieldName, columnName)	添加字段映射
getColumnName(fieldName): Option<String>	获取列名
getFieldNames(): ArrayList<String>	获取所有字段名
getColumnNames(): ArrayList<String>	获取所有列名

EntityMetadataParser - 实体元数据解析器

方法	说明
parse<T>(entityClass: Class<T>): Option<EntityMetadata>	解析实体类元数据

---

query 模块 - 查询构建器

提供链式 SQL 查询构建功能。

类

SelectBuilder - SELECT 查询构建器

方法	说明
init(tableName: String)	构造函数
column(name: String): SelectBuilder	添加查询列
distinct(): SelectBuilder	添加 DISTINCT
innerJoin(table, alias, on): SelectBuilder	内连接
leftJoin(table, alias, on): SelectBuilder	左连接
rightJoin(table, alias, on): SelectBuilder	右连接
where_(condition: String): SelectBuilder	添加 WHERE 条件
orderBy(column, direction): SelectBuilder	添加排序
limit(limit: Int64): SelectBuilder	设置 LIMIT
offset(offset: Int64): SelectBuilder	设置 OFFSET
build(): String	构建 SQL 语句

InsertBuilder - INSERT 查询构建器

方法	说明
init(tableName: String)	构造函数
value(column, value): InsertBuilder	添加列值
build(): String	构建 SQL 语句

UpdateBuilder - UPDATE 查询构建器

方法	说明
init(tableName: String)	构造函数
set(column, value): UpdateBuilder	添加 SET 子句
where_(condition): UpdateBuilder	添加 WHERE 条件
build(): String	构建 SQL 语句

DeleteBuilder - DELETE 查询构建器

方法	说明
init(tableName: String)	构造函数
where_(condition): DeleteBuilder	添加 WHERE 条件
build(): String	构建 SQL 语句

ConditionBuilder - 条件构建器

方法	说明
eq(column, value): ConditionBuilder	等于条件
ne(column, value): ConditionBuilder	不等于条件
gt(column, value): ConditionBuilder	大于条件
ge(column, value): ConditionBuilder	大于等于条件
lt(column, value): ConditionBuilder	小于条件
le(column, value): ConditionBuilder	小于等于条件
like(column, value): ConditionBuilder	LIKE 条件（自动转义）
likeLeft(column, value): ConditionBuilder	左模糊匹配
likeRight(column, value): ConditionBuilder	右模糊匹配
isIn(column, values): ConditionBuilder	IN 条件（限制1000个参数）
isNotIn(column, values): ConditionBuilder	NOT IN 条件
isNull(column): ConditionBuilder	IS NULL 条件
isNotNull(column): ConditionBuilder	IS NOT NULL 条件
between(column, start, end): ConditionBuilder	BETWEEN 条件
and_(): ConditionBuilder	AND 连接
or_(): ConditionBuilder	OR 连接
build(): String	构建条件字符串
getParameters(): ArrayList<String>	获取参数列表

---

datasource 模块 - 数据源管理

提供数据库连接池、连接管理和完整的内存模拟实现。

枚举

DatabaseType - 数据库类型

值	说明
MySql	MySQL
PostgreSQL	PostgreSQL
Sqlite	SQLite
Oracle	Oracle
SqlServer	SQL Server

接口

DataSource - 数据源接口

方法	说明
getConnection(): Option<Connection>	获取数据库连接
close(): Unit	关闭数据源

Connection - 数据库连接接口

方法	说明
prepareStatement(sql: String): PreparedStatement	创建预编译语句
commit(): Unit	提交事务
rollback(): Unit	回滚事务
close(): Unit	关闭连接
isClosed(): Bool	检查是否已关闭

PreparedStatement - 预编译语句接口

方法	说明
setInt(index, value): Unit	设置 Int 参数
setString(index, value): Unit	设置 String 参数
setFloat(index, value): Unit	设置 Float 参数
setBool(index, value): Unit	设置 Bool 参数
executeQuery(): ResultSet	执行查询
executeUpdate(): Int64	执行更新
close(): Unit	关闭语句

ResultSet - 结果集接口

方法	说明
next(): Bool	移动到下一行
getString(columnName): String	获取字符串值
getInt(columnName): Int64	获取整数值
getFloat(columnName): Float64	获取浮点值
getBool(columnName): Bool	获取布尔值
isNull(columnName): Bool	检查是否为空
close(): Unit	关闭结果集

类

DatabaseConfig - 数据库配置

方法	说明
mysql(): DatabaseConfig	创建 MySQL 配置
postgresql(): DatabaseConfig	创建 PostgreSQL 配置
sqlite(): DatabaseConfig	创建 SQLite 配置
buildUrl(): String	构建 JDBC URL

PoolConfig - 连接池配置

属性	说明
minPoolSize	最小连接数（默认 5）
maxPoolSize	最大连接数（默认 20）
connectionTimeout	连接超时（默认 30000ms）
connectionTestQuery	连接测试 SQL

ConnectionPool - 连接池实现

方法	说明
init(config, connectionFactory)	构造函数
getConnection(): Option<Connection>	获取连接
getConnection(timeout): Option<Connection>	带超时获取连接
returnConnection(conn): Unit	归还连接
getActiveConnections(): Int64	获取活跃连接数
getIdleConnections(): Int64	获取空闲连接数
close(): Unit	关闭连接池

ConnectionPoolFactory - 连接池工厂

方法	说明
createMockPool(): ConnectionPool	创建模拟连接池
createPool(config, poolConfig): ConnectionPool	创建连接池

ConnectionPoolHealthChecker - 连接池健康检查

方法	说明
init(pool)	构造函数
checkHealth(): PoolHealth	检查连接池健康状态

---

transaction 模块 - 事务管理

提供声明式和编程式事务支持。

枚举

IsolationLevel - 事务隔离级别

值	说明
Default	使用数据库默认
ReadUncommitted	读未提交
ReadCommitted	读已提交
RepeatableRead	可重复读
Serializable	串行化

Propagation - 事务传播行为

值	说明
Required	当前有事务则加入，没有则新建（默认）
Supports	当前有事务则加入，没有则以非事务执行
Mandatory	当前必须有事务，否则抛异常
RequiresNew	挂起当前事务，创建新事务
NotSupported	挂起当前事务，以非事务执行
Never	当前必须没有事务，否则抛异常
Nested	在当前事务中创建嵌套事务

接口

TransactionStatus - 事务状态接口

方法	说明
isNewTransaction(): Bool	是否是新事务
setRollbackOnly(): Unit	设置回滚标记
isRollbackOnly(): Bool	是否标记为回滚
isCompleted(): Bool	事务是否已完成

TransactionManager - 事务管理器接口

方法	说明
getTransaction(definition): TransactionStatus	获取事务
commit(status): Unit	提交事务
rollback(status): Unit	回滚事务

类

TransactionDefinition - 事务定义

方法	说明
setPropagation(propagation): TransactionDefinition	设置传播行为（链式）
setIsolation(isolation): TransactionDefinition	设置隔离级别（链式）
setTimeout(timeout): TransactionDefinition	设置超时时间（链式）
setReadOnly(readOnly): TransactionDefinition	设置只读（链式）

DefaultTransactionStatus - 事务状态实现

方法	说明
init(newTransaction)	构造函数
setCompleted(): Unit	标记事务完成

TransactionTemplate - 事务模板

方法	说明
init(transactionManager)	构造函数
execute<T>(action): T	执行有返回值的事务
executeWithoutResult(action): Unit	执行无返回值的事务

---

driver 模块 - 数据库驱动

提供数据库驱动管理和方言支持。

枚举

DatabaseType - 数据库类型（同 datasource 模块）

接口

Driver - 数据库驱动接口

方法	说明
connect(config): Option<Connection>	建立连接
acceptsURL(url): Bool	是否支持该 URL
getName(): String	获取驱动名称
getVersion(): String	获取驱动版本

Dialect - 数据库方言接口

方法	说明
getDatabaseType(): DatabaseType	获取数据库类型
supportsSequences(): Bool	是否支持序列
getPaginationSql(sql, offset, limit): String	获取分页 SQL
getIdentitySelectSql(): String	获取自增主键查询 SQL
getSequenceNextValSql(sequence): String	获取序列下一个值 SQL
quoteIdentifier(identifier): String	引用标识符

类

DriverManager - 驱动管理器

方法	说明
registerDriver(driver): Unit	注册驱动
deregisterDriver(driver): Unit	注销驱动
getDrivers(): ArrayList<Driver>	获取所有驱动
getConnection(config): Option<Connection>	获取连接
clear(): Unit	清空所有驱动

MySqlDialect - MySQL 方言

PostgreSqlDialect - PostgreSQL 方言

SqliteDialect - SQLite 方言

DialectRegistry - 方言注册表

方法	说明
getDialect(type): Option<Dialect>	获取方言

---

enterprise 模块 - 企业级功能

提供 SQL 执行监控、慢查询日志、SQL 注入检测等企业级功能。

类

SqlExecutionStats - SQL 执行统计

方法	说明
init(sqlHash, sql)	构造函数
recordExecution(time, rows, memory): Unit	记录执行
recordError(): Unit	记录错误
toJson(): String	转换为 JSON

SlowQueryLogger - 慢查询日志

方法	说明
init(threshold, maxSize)	构造函数
logQuery(sql, time, params): Unit	记录慢查询
getLogs(): ArrayList<SlowQueryLog>	获取日志
getSlowQueryCount(): Int64	获取慢查询数量
clear(): Unit	清空日志

SqlInjectionDetector - SQL 注入检测器

方法	说明
detect(sql): ArrayList<String>	检测 SQL 注入
validateParam(param): Bool	验证参数是否安全

SqlExecutionMonitor - SQL 执行监控

方法	说明
setEnableInjectionCheck(enable): Unit	设置是否启用注入检测
setSlowQueryThreshold(threshold): Unit	设置慢查询阈值
startMonitoring(sql, params): SqlExecutionContext	开始监控
endMonitoring(context, time): Unit	结束监控
recordExecutionError(sql): Unit	记录执行错误
getSqlStats(): ArrayList<SqlExecutionStats>	获取 SQL 统计

OrmException - ORM 异常

方法	说明
init(message)	构造函数

---

utils 模块 - 工具函数

提供通用的工具函数。

函数	说明
joinStrings(list, separator): String	连接字符串列表
toUpperCaseString(s): String	转换为大写
toLowerCaseString(s): String	转换为小写
startsWithIgnoreCase(s, prefix): Bool	忽略大小写检查前缀
containsIgnoreCase(s, sub): Bool	忽略大小写检查包含
isValidIdentifier(identifier): Bool	检查是否为有效标识符
escapeIdentifier(identifier): String	转义标识符

---

mod 模块 - 框架入口

提供 ORM 框架的全局配置和上下文管理。

OrmConfig - ORM 配置类

方法	说明
default(): OrmConfig	创建默认配置
setShowSql(show): OrmConfig	设置是否显示 SQL（链式）
setFormatSql(format): OrmConfig	设置是否格式化 SQL（链式）
setDialect(dialect): OrmConfig	设置数据库方言（链式）
setMaxPoolSize(size): OrmConfig	设置最大连接池大小（链式）
enableAi(): OrmConfig	启用 AI 功能（链式）

OrmContext - ORM 上下文

方法	说明
initialize(config): Unit	初始化 ORM 上下文
setDataSource(ds): Unit	设置全局数据源
getDataSource(): Option<DataSource>	获取全局数据源
getConfig(): OrmConfig	获取全局配置
isInitialized(): Bool	检查是否已初始化
reset(): Unit	重置上下文

常量

常量	值	说明
VERSION	"1.0.0"	框架版本
MODULE_NAME	"tycj_orm"	框架名称

---

repository 模块 - 仓库接口

提供类似 Spring Data JPA 的 CRUD 仓库接口和基础实现。

接口

CrudRepository<T, ID> - CRUD 仓库接口

方法	说明
save(entity): T	保存实体（插入或更新）
saveAll(entities): ArrayList<T>	批量保存实体
findById(id): Option<T>	根据 ID 查找实体
existsById(id): Bool	判断实体是否存在
findAll(): ArrayList<T>	查询所有实体
findAllById(ids): ArrayList<T>	根据 ID 列表查询实体
count(): Int64	统计实体数量
deleteById(id): Unit	根据 ID 删除实体
delete(entity): Unit	删除实体
deleteAll(entities): Unit	批量删除实体
deleteAll(): Unit	删除所有实体

PagingAndSortingRepository<T, ID> - 分页排序仓库接口

方法	说明
findAll(pageable): Page<T>	分页查询所有实体
findAll(sort): ArrayList<T>	排序查询所有实体

Pageable - 分页参数接口

方法	说明
getPageNumber(): Int64	获取页码（从 0 开始）
getPageSize(): Int64	获取每页大小
getOffset(): Int64	获取偏移量
getSort(): Sort	获取排序参数
hasPrevious(): Bool	是否有上一页
hasNext(): Bool	是否有下一页
previous(): Pageable	获取上一页分页参数
next(): Pageable	获取下一页分页参数
first(): Pageable	获取第一页分页参数

类

Sort - 排序类

方法	说明
ascending(property): Sort	创建升序排序
descending(property): Sort	创建降序排序
andAscending(property): Sort	添加升序排序
andDescending(property): Sort	添加降序排序
getOrders(): ArrayList<SortOrder>	获取排序规则列表
isEmpty(): Bool	是否为空
toSql(): String	转换为 SQL ORDER BY 子句

SortOrder - 排序规则类

方法	说明
isAscending(): Bool	是否升序
isDescending(): Bool	是否降序
toSql(): String	转换为 SQL 排序子句

PageRequest - 分页请求类

方法	说明
of(page, size): PageRequest	创建分页请求
of(page, size, sort): PageRequest	创建带排序的分页请求

Page - 分页结果类

方法	说明
getContent(): ArrayList<T>	获取当前页内容
getTotalElements(): Int64	获取总记录数
getTotalPages(): Int64	获取总页数
getNumber(): Int64	获取页码
getSize(): Int64	获取每页大小
getNumberOfElements(): Int64	获取当前页记录数
isFirst(): Bool	是否为第一页
isLast(): Bool	是否为最后一页
hasNext(): Bool	是否有下一页
hasPrevious(): Bool	是否有上一页
isEmpty(): Bool	是否为空

Int64Repository - Int64 仓库实现类

提供基于 HashMap 的内存存储实现，用于测试。

StringRepository - String 仓库实现类

提供基于 HashMap 的内存存储实现，用于测试。

RepositoryHelper - 仓库工具类

方法	说明
buildSelectQuery(metadata): SelectBuilder	构建查询 SQL
buildInsertQuery(tableName): InsertBuilder	构建插入 SQL
buildUpdateQuery(tableName): UpdateBuilder	构建更新 SQL
buildDeleteQuery(tableName): DeleteBuilder	构建删除 SQL

---

query 扩展 - 子查询、UNION、批量插入

提供高级 SQL 构建功能。

子查询

SubQueryBuilder - 子查询构建器

方法	说明
setAlias(alias): SubQueryBuilder	设置子查询别名
getSelectBuilder(): SelectBuilder	获取内部 SELECT 构建器
build(): String	构建子查询 SQL（带别名）
buildWithoutAlias(): String	构建子查询 SQL（不带别名）

SelectBuilderExt - SelectBuilder 扩展

方法	说明
fromSubQuery(builder, alias): String	子查询作为表
columnSubQuery(builder, alias): String	子查询作为列
inSubQuery(column, builder): String	子查询用于 IN 条件
existsSubQuery(builder): String	子查询用于 EXISTS 条件
notExistsSubQuery(builder): String	子查询用于 NOT EXISTS 条件

ConditionBuilderExt - ConditionBuilder 扩展

方法	说明
inSubQuery(column, builder): String	IN 子查询
notInSubQuery(column, builder): String	NOT IN 子查询
existsSubQuery(builder): String	EXISTS 子查询
notExistsSubQuery(builder): String	NOT EXISTS 子查询
compareSubQuery(column, operator, builder): String	比较子查询

UNION 查询

UnionBuilder - UNION 查询构建器

方法	说明
addSelect(builder): UnionBuilder	添加 SELECT 查询
unionAll(): UnionBuilder	设置 UNION ALL（保留重复行）
unionDistinct(): UnionBuilder	设置 UNION（去除重复行）
orderBy(property, direction): UnionBuilder	ORDER BY
limit(count): UnionBuilder	LIMIT
offset(count): UnionBuilder	OFFSET
build(): String	构建 SQL
getParameters(): ArrayList<String>	获取所有参数

批量插入

BatchInsertBuilder - 批量插入构建器

方法	说明
into(table): BatchInsertBuilder	设置表名
columns(cols): BatchInsertBuilder	设置列名
addRow(values): BatchInsertBuilder	添加单行数据
addRows(rows): BatchInsertBuilder	批量添加多行数据
build(): String	构建 SQL
getParameters(): ArrayList<String>	获取参数
getRowCount(): Int64	获取行数

---

transaction 扩展 - DataSourceTransactionManager

提供基于数据源的事务管理器实现。

DataSourceTransactionManager - 数据源事务管理器

方法	说明
init(dataSource)	构造函数
getTransaction(definition): TransactionStatus	获取事务
commit(status): Unit	提交事务
rollback(status): Unit	回滚事务
getCurrentConnection(): Option<Connection>	获取当前事务的连接
hasTransaction(): Bool	判断当前是否有事务

Transaction - 事务对象

方法	说明
getConnection(): Connection	获取数据库连接
getDefinition(): TransactionDefinition	获取事务定义
commit(): Unit	提交事务
rollback(): Unit	回滚事务
isCompleted(): Bool	是否已完成

TransactionHolder - 事务持有者

方法	说明
getTransaction(): Transaction	获取事务对象
isNewTransaction(): Bool	是否是新事务

ThreadLocal - 线程本地存储

方法	说明
get(): Option<T>	获取值
set(value): Unit	设置值
remove(): Unit	清除值

---

项目结构

tycj-orm/
├── src/
│   ├── mod.cj              # 主模块入口（OrmConfig、OrmContext、版本信息）
│   ├── entity.cj           # 实体注解和元数据
│   ├── query.cj            # 查询构建器（含子查询、UNION、批量插入扩展）
│   ├── datasource.cj       # 数据源管理
│   ├── transaction.cj      # 事务管理（含 DataSourceTransactionManager）
│   ├── driver.cj           # 数据库驱动和方言
│   ├── enterprise.cj       # 企业级功能（监控、安全）
│   ├── pool.cj             # 连接池实现
│   ├── repository.cj       # 仓库接口和实现
│   └── utils.cj            # 工具函数
├── tests/                  # 单元测试
│   ├── test_query.cj       # 查询构建器测试
│   ├── test_query_ext.cj   # 扩展查询构建器测试
│   ├── test_pool.cj        # 连接池测试
│   ├── test_enterprise.cj  # 企业级功能测试
│   ├── test_transaction.cj # 事务管理测试
│   ├── test_driver.cj      # 数据库驱动测试
│   ├── test_entity.cj      # 实体映射测试
│   ├── test_repository.cj  # 仓库模块测试
│   └── test_mod.cj         # 模块配置测试
├── cjpm.toml               # 项目配置
└── README.md               # 项目文档

---

代码质量改进记录

已修复的问题

1. 逻辑错误修复

• enterprise.cj: 修复 isInString 方法逻辑，正确检测关键字是否在字符串内
• query.cj: 修复 LIMIT 和 OFFSET 处理逻辑，支持独立设置
• query.cj: 修复 UpdateBuilder.getParameters() 参数顺序问题

2. 安全机制完善

• enterprise.cj: 完善 JSON 转义，添加控制字符处理
• query.cj: like 方法自动转义通配符（%、_、[、]）
• query.cj: isIn 和 isNotIn 方法限制最大参数数量为 1000
• query.cj: 空列表时添加永真/永假条件（1=1 / 1=0）

3. 性能优化

• pool.cj: 连接池初始化添加重试机制
• pool.cj: getConnection 方法实现真正的超时等待
• pool.cj: 使用 remove 替代创建新列表，提升性能
• pool.cj: 添加连接有效性验证
• enterprise.cj: 使用 StringBuilder 优化字符串拼接
• utils.cj: 提取公共工具函数 joinStrings、toUpperCaseString 等

4. 新增功能

• utils.cj: 新增工具函数模块，提供字符串处理、标识符验证等功能
• tests/: 新增完整的单元测试套件，覆盖所有核心功能

---

开发计划

• 实体注解（@Entity、@Table、@Id、@Column、@Transient）
• 主键生成策略（GenerationType: IDENTITY/SEQUENCE/TABLE/AUTO）
• 实体元数据解析（EntityMetadataParser）
• 查询构建器（QueryBuilder，支持 SELECT/INSERT/UPDATE/DELETE）
• 条件构建器（ConditionBuilder，支持多种操作符）
• 数据源管理（DataSource 接口、DatabaseConfig）
• 连接池实现（ConnectionPool，线程安全）
• Mock 数据库实现（MockConnection/MockPreparedStatement/MockResultSet）
• 事务管理（编程式 TransactionTemplate）
• 事务传播行为（全部 7 种）
• 事务隔离级别（5 种）
• 数据库驱动管理（DriverManager）
• 数据库方言（MySQL/PostgreSQL/SQLite）
• SQL 执行监控（SqlExecutionMonitor）
• 慢查询日志（SlowQueryLogger）
• SQL 注入检测（SqlInjectionDetector）
• 连接池健康检查（ConnectionPoolHealthChecker）
• 工具函数模块（utils.cj）
• 单元测试全覆盖
• CRUD 仓库接口（CrudRepository、PagingAndSortingRepository）
• 分页排序支持（Page、PageRequest、Sort、SortOrder）
• Int64/String 仓库实现（Int64Repository、StringRepository）
• DataSourceTransactionManager（基于数据源的事务管理器）
• 子查询构建器（SubQueryBuilder）
• UNION 查询构建器（UnionBuilder）
• 批量插入构建器（BatchInsertBuilder）
• 子查询扩展方法（SelectBuilderExt、ConditionBuilderExt）
• 关联映射（@OneToOne、@OneToMany、@ManyToMany）
• 懒加载
• 二级缓存
• 数据库迁移（Flyway/Liquibase）
• 多租户支持
• 动态 SQL（if/choose/foreach 标签）
• 原生数据库驱动适配（MySQL/PostgreSQL/SQLite）

---

贡献指南

欢迎提交 Issue 和 Pull Request！

开发环境

1. 安装仓颉语言开发环境
2. 克隆项目：git clone https://gitcode.com/tybb2026/tycj-orm.git
3. 安装依赖：cjpm update
4. 构建：cjpm build
5. 测试：cjpm test

代码规范

• 遵循仓颉语言编码规范
• 所有公开 API 必须添加文档注释
• 新功能需附带单元测试
• 修复问题需同步更新文档

---

许可证

本项目采用 Apache-2.0 许可证。

---

相关项目

• tycj-common - 通用工具库
• tycj-async - 异步能力库
• tycj-net - 网络通信库
• tycj-web - Web MVC 框架