注解

本文将指导您如何配置注解。

@Table 表名设置

用于指定数据类的表名，该注解的生效优先级高于📚全局设置 - 全局表名策略的优先级。

参数：

@Table("tb_user")
data class User(
    val id: Int? = null,
    val name: String? = null,
    val age: Int? = null
) : KPojo

带 DDL 形态的表与列映射示例见 📚表与列。

@TableIndex 表索引

用于指定数据表的索引。

在使用wrapper.table.createTable(instance)、wrapper.table.createTable<T>()、wrapper.table.syncTable(instance)或wrapper.table.syncTable<T>()时生效。

参数：

单列索引使用@TableIndex(columns = [...])，并传入一个列名。

import com.kotlinorm.annotations.Column
import com.kotlinorm.annotations.Table
import com.kotlinorm.annotations.TableIndex
import com.kotlinorm.interfaces.KPojo

@Table("tb_user")
@TableIndex(
    name = "idx_name_create_time",
    columns = ["name", "create_time"],
    type = "UNIQUE",
    method = "BTREE"
)
data class User(
    val id: Int? = null,
    val name: String? = null,
    @Column("create_time")
    val createTime: String? = null
) : KPojo

CREATE UNIQUE INDEX `idx_name_create_time` ON `tb_user` (`name`, `create_time`) USING BTREE

type、method、concurrently、KTableIndex和方言表现见 📚索引类型和索引方法。

@CreateTime 表创建时间

用于指定数据表是否开启创建时间策略，该注解的生效优先级高于📚全局设置 - 创建时间策略的优先级。

参数：

// 在全局开启创建时间的情况下取消某张表的创建时间功能
Kronos.createTimeStrategy = KronosCommonStrategy(enabled = true, field = Field("create_time", "createTime"))

@CreateTime(enable = false)
data class User(
    val id: Int? = null,
    val createTime: String? = null // 或者直接删除该字段，禁用创建时间功能
) : KPojo

// 在全局关闭创建时间的情况下开启某张表的创建时间功能
Kronos.createTimeStrategy = KronosCommonStrategy(enabled = false, field = Field("create_time", "createTime"))

@CreateTime
data class User(
  val id: Int? = null,
  val createTime: String? = null // 创建时间字段
) : KPojo

@UpdateTime 表更新时间

用于指定数据表是否开启更新时间策略，该注解的生效优先级高于📚全局设置 - 更新时间策略的优先级。

参数：

// 在全局开启更新时间的情况下取消某张表的更新时间功能
Kronos.updateTimeStrategy = KronosCommonStrategy(enabled = true, field = Field("update_time", "updateTime"))

@UpdateTime(enable = false)
data class User(
  val id: Int? = null,
  val updateTime: String? = null // 或者直接删除该字段，禁用更新时间功能
) : KPojo

// 在全局关闭更新时间的情况下开启某张表的更新时间功能
Kronos.updateTimeStrategy = KronosCommonStrategy(enabled = false, field = Field("update_time", "updateTime"))

@UpdateTime
data class User(
    val id: Int? = null,
    val updateTime: String? = null // 更新时间字段
) : KPojo

@LogicDelete 表逻辑删除

用于指定数据表是否开启逻辑删除策略，该注解的生效优先级高于📚全局设置 - 逻辑删除策略的优先级。

参数：

// 在全局开启逻辑删除的情况下取消某张表的逻辑删除功能
Kronos.logicDeleteStrategy = KronosCommonStrategy(enabled = true, field = Field("deleted"))

@LogicDelete(enable = false)
data class User(
    val id: Int? = null,
    @Default("0") // @Default("false") for Postgres
    val deleted: Boolean? = null // 或者直接删除该字段，禁用逻辑删除功能
) : KPojo


// 在全局关闭逻辑删除的情况下开启某张表的逻辑删除功能
Kronos.logicDeleteStrategy = KronosCommonStrategy(enabled = false, field = Field("deleted"))

@LogicDelete
data class User(
  val id: Int? = null,
  @Default("0") // @Default("false") for Postgres
  val deleted: Boolean? = null // 逻辑删除字段
) : KPojo

@Column 列名

用于指定数据表的列名，该注解的生效优先级高于📚全局设置 - 全局列名策略的优先级。

参数：

data class User(
    @Column("user_name")
    val name: String? = null
) : KPojo

@DateTimeFormat 日期时间格式

用于指定数据表的日期/时间格式，该注解的生效优先级高于📚全局设置 - 默认日期时间格式的优先级。

参数：

data class User(
    @DateTimeFormat("yyyy-MM-dd")
    val birthday: String? = null
) : KPojo

@Serialize JSON 字段

对象或集合属性需要保存为 JSON 时使用该注解。在应用启动时配置 Gson 或 Kotlinx Serialization，之后仍直接使用属性原本的 Kotlin 类型。

data class User(
    @Serialize
    val info: List<String>? = emptyList()
) : KPojo

完整配置和示例见 📚序列化。

@Cascade 级联关系声明

此注解用于声明列的级联关系，详细定义及用法请参考📚进阶用法 - 级联关系定义。

请将此注解加在类型为KPojo或Collection<KPojo>的属性上，确保当前定义的表内有关联字段（如以下例子中的companyId）。

参数：

// 一对多级联关系示例
@Table("tb_user")
data class Employee(
    val id: Int? = null,
    val companyId: Int? = null,
    @Cascade(["companyId"], ["id"], SET_DEFAULT, ["0"])
    val company: Company? = null
) : KPojo

@Table("tb_company")
data class Company(
    val id: Int? = null,
    val employees: List<Employee>? = null
) : KPojo

一对一、一对多和多字段关系示例见 📚级联映射。

@Ignore 忽略字段

此注解用于在部分操作中忽略字段。默认 @Ignore 等价于 @Ignore([IgnoreAction.ALL])。

参数：

IgnoreAction.ALL 会将属性排除为非数据库列。

@Table("tb_user")
data class User(
    var id: Int? = null,
    @Ignore
    var displayName: String? = null
) : KPojo

IgnoreAction.TO_MAP 会让 KPojo.toDataMap() 跳过该属性。

@Table("tb_user")
data class User(
    var id: Int? = null,
    @Ignore([IgnoreAction.TO_MAP])
    var temporaryToken: String? = null
) : KPojo

val data = User(id = 1, temporaryToken = "token").toDataMap()

IgnoreAction.FROM_MAP 会让 KPojo.fromMapData() 和 KPojo.safeFromMapData() 跳过该属性。

@Table("tb_user")
data class User(
    var id: Int? = null,
    @Ignore([IgnoreAction.FROM_MAP])
    var localState: String? = null
) : KPojo

val user = User().fromMapData<User>(mapOf("id" to 1, "localState" to "draft"))

IgnoreAction.SELECT 会让 select() 的默认字段列表跳过该属性。

@Table("tb_user")
data class User(
    var id: Int? = null,
    @Ignore([IgnoreAction.SELECT])
    var name: String? = null
) : KPojo

SELECT `id`
FROM `tb_user`

IgnoreAction.CASCADE_SELECT 会让级联查询跳过该关系属性。

@Table("tb_user")
data class Employee(
  val id: Int? = null,
  val companyId: Int? = null,
  @Cascade(["companyId"], ["id"], SET_DEFAULT, ["0"])
  val company: Company? = null
) : KPojo

@Table("tb_company")
data class Company(
  val id: Int? = null,
  @Ignore([IgnoreAction.CASCADE_SELECT])
  val employees: List<Employee>? = null
) : KPojo

请注意，此注解是单向的，即给employees加上@Ignore([CASCADE_SELECT])注解，employees不会被级联查询，但是company会被级联查询。

@PrimaryKey 列主键设置

此注解用于声明列为主键。

参数：

@Table("tb_user")
data class User(
    @PrimaryKey(identity = true)
    val id: Int? = null
) : KPojo

使用自增主键时，请保证id列的类型为Int或Long类型，否则无法正确生成主键。

使用uuid作为主键时，请保证id列的类型为String类型，否则无法正确生成主键。

使用雪花算法时，自增字段必须为Long类型，否则无法正确生成主键，请您在配置文件中配置datacenterId和workerId，参考：📚主键生成器 - SNOWFLAKE 雪花算法主键。

使用自定义主键时，请提前设置配置自定义主键生成器customIdGenerator(KIdGenerator<T>)，参考：📚主键生成器 - CUSTOM 自定义生成器主键。

@ColumnType 列类型及长度

对于不同的数据库类型，kronos会根据kotlin类型自动转换类型，您可以参考📚Kotlin列类型推断 查看Kotlin数据类型在各个数据库中的映射关系。 您可以通过此注解声明列类型及长度，如果不指定则使用默认的类型及长度，全部类型信息请参考：📚Kronos列类型。

参数：

@Table("tb_user")
data class User(
    @ColumnType(KColumnType.CHAR, 10)
    val name: String? = null
) : KPojo

@Default 列默认值

此注解用于声明列的数据库默认值。

参数：

@Table("tb_user")
data class User(
    @Default("0")
    val score: Int? = null
) : KPojo

@Default 会把内容原样写入表结构 DDL，参数不是 Kotlin 值，Kronos 也不会自动把一种数据库方言的表达式转换成另一种方言。下面按自动推断出的 Kotlin 类型列出推荐的默认值字面量：

例如，Boolean 默认值必须使用目标数据库接受的表达式：

// PostgreSQL 或 H2
@Default("false")
var enabled: Boolean? = null

// MySQL、SQLite、SQLServer、Oracle 或 DM8
@Default("0")
var enabled: Boolean? = null

PostgreSQL 不接受 BOOLEAN DEFAULT 0 和 BOOLEAN DEFAULT 1，应改用 false 和 true。如果同一个模型需要在多个数据库上建表，请在 schema 定义或迁移脚本中分别维护方言默认值。CURRENT_DATE、CURRENT_TIMESTAMP 等数据库函数同样会作为原生表达式写入，必须符合目标数据库语法。非空二进制默认值会受到数据库版本和具体列类型限制，应放在方言专用迁移脚本中，不要依赖一套可移植的 @Default 写法。

@NonNull 列非空约束

此注解用于声明列为非空，如果不指定则使用默认的非空约束

@Table("tb_user")
data class User(
    @NonNull
    val name: String? = null
) : KPojo

@CreateTime 创建时间列

此注解用于声明列为创建时间字段，如果不指定则使用📚全局设置 - 创建时间策略。

参数：

@Table("tb_user")
data class User(
    @CreateTime
    val created: String? = null
) : KPojo

@UpdateTime 更新时间列

此注解用于声明列为更新时间字段，如果不指定则使用📚全局设置 - 更新时间策略。

参数：

@Table("tb_user")
data class User(
    @UpdateTime
    val updated: String? = null
) : KPojo

@LogicDelete 逻辑删除列

此注解用于声明列为逻辑删除字段，如果不指定则使用📚全局设置 - 逻辑删除策略。

参数：

@Table("tb_user")
data class User(
    @LogicDelete
    @Default("0") // @Default("false") for Postgres
    val deleted: Boolean? = null
) : KPojo

@Version 乐观锁（版本）列

此注解用于声明列为乐观锁（版本）字段，如果不指定则使用📚全局设置 - 乐观锁（版本）策略。

参数：

@Table("tb_user")
data class User(
    @Version
    val version: Int? = null
) : KPojo