Ktorm 4.0 版本升级指南：解决实体类生成与权限问题

前言

Ktorm 作为一款优秀的 Kotlin ORM 框架，在 4.0 版本中引入了 KSP（Kotlin Symbol Processing）来简化实体类的定义。本文将详细介绍如何从 3.6 版本平滑升级到 4.0 版本，并解决升级过程中可能遇到的常见问题。

实体类定义的变化

在 Ktorm 3.6 版本中，我们需要手动定义实体接口和对应的表对象：

// 3.6 版本写法
interface Admin : Entity<Admin> {
    companion object : Entity.Factory<Admin>()
    val id: Int
    var email: String
    // 其他属性...
}

object Admins : Table<Admin>("admins") {
    val id = int("id").primaryKey().bindTo { it.id }
    // 其他列定义...
}

而在 4.0 版本中，我们可以使用注解简化定义：

// 4.0 版本写法
@Table("admins")
interface Admin : Entity<Admin> {
    @PrimaryKey
    var id: Int
    var email: String
    // 其他属性...
}

常见升级问题及解决方案

1. 数据库权限错误

问题现象：升级后出现 SELECT command denied to user 错误，但仅影响部分表。

原因分析：这是因为在 KSP 配置中可能误加了 schema 参数：

ksp {
    arg("ktorm.schema", "test") // 这会导致生成的 SQL 包含 schema 前缀
}

解决方案：移除 KSP 配置中的 schema 参数即可。

2. 复杂类型处理

对于 List<String> 等复杂类型，4.0 版本需要显式指定 SQL 类型：

@Column(sqlType = JsonSqlType::class)
var pictures: List<String>

3. 其他注意事项

• 确保所有非空属性都有初始值或使用 ? 声明为可空
• 检查所有主键字段是否添加了 @PrimaryKey 注解
• 枚举类型可以继续使用 enum 函数绑定

升级建议

1. 逐步迁移：可以先迁移部分实体类，验证无误后再全面升级
2. 版本控制：使用 Git 等版本控制工具，方便回退
3. 测试覆盖：确保有足够的测试用例覆盖核心功能

总结

Ktorm 4.0 通过 KSP 大大简化了实体类的定义工作，但在升级过程中需要注意配置项的调整和复杂类型的处理。遵循本文的指导，可以顺利完成升级并享受新版本带来的便利。