全局设置

本文将指导您如何全局设置Kronos。

先用下表选择需要配置的全局项。

编译插件配置在构建工具中完成。source set 和诊断检查见 📚编译器插件。

默认数据源设置

在执行 ORM 操作前设置 Kronos.dataSource。没有显式传入 wrapper 的操作，会调用这个函数取得默认数据源。

数据源 wrapper 的创建方式见 📚连接到数据库。

import com.kotlinorm.Kronos
import com.kotlinorm.wrappers.KronosJdbcWrapper
import org.apache.commons.dbcp2.BasicDataSource

val wrapper = KronosJdbcWrapper(BasicDataSource())

Kronos.dataSource = { wrapper }

默认数据源的默认值为NoneDataSourceWrapper，在使用前请务必修改您的配置文件。

单次操作需要使用其他数据源时，把 wrapper 传给 execute(wrapper)。

val archiveWrapper = KronosJdbcWrapper(archiveDataSource)

User(id = 1)
    .update()
    .set { it.name = "Kronos ORM" }
    .where()
    .execute(archiveWrapper)

应用需要按运行时上下文选择数据源时，在 Kronos.dataSource 函数里返回不同 wrapper。

import com.kotlinorm.Kronos

Kronos.dataSource = {
    if (TenantContext.current() == "archive") archiveWrapper else primaryWrapper
}

全局表名策略

表名策略指在默认情况下（无注解配置），kronos自动根据Kotlin类名生成数据库的表名，如：TbUser -> tb_user。

参数：

创建来自定义表名策略KronosNamingStrategy详见：📚概念 - 命名策略。

LineHumpNamingStrategy 表名

该策略将kotlin类名转换为下划线分隔的小写字符串，如：ADataClass -> a_data_class ，将数据库表/列名转为驼峰命名，如：user_name -> userName。

import com.kotlinorm.Kronos

Kronos.tableNamingStrategy = Kronos.lineHumpNamingStrategy

UserProfile -> user_profile

NoneNamingStrategy 表名

NoneNamingStrategy 保持 Kotlin 类名和数据库名称原样。Kronos 默认使用该策略。

import com.kotlinorm.Kronos

Kronos.tableNamingStrategy = Kronos.noneNamingStrategy

UserProfile -> UserProfile

全局列名策略

同全局表名策略类似，列名策略指在默认情况下，kronos自动根据Kotlin类的属性名生成列名，如：classId -> class_id。

参数：

Kotlin 属性名需要映射到数据库列名时，给字段设置同样的命名策略。

import com.kotlinorm.Kronos

Kronos.fieldNamingStrategy = Kronos.lineHumpNamingStrategy

userName -> user_name

创建时间策略

用于设置所有表的创建时间字段。

参数：

通过创建KronosCommonStrategy自定义创建时间策略，详见：📚概念 - 通用策略）。

创建时间策略的全局默认关闭，需要手动开启。

全局设置创建时间后，KPojo中必须拥有该成员属性，否则该策略不会对该表生效。

import com.kotlinorm.Kronos
import com.kotlinorm.beans.config.KronosCommonStrategy
import com.kotlinorm.beans.dsl.Field

Kronos.createTimeStrategy = KronosCommonStrategy(enabled = true, field = Field("create_time", "createTime"))

在单个模型上配置 @CreateTime 可以覆盖全局设置，见 📚注解。

更新时间策略

用于设置所有表的更新时间字段（是否开启、kotlin属性名及数据库列名）。

参数：

通过创建KronosCommonStrategy自定义更新时间策略，详见：📚概念 - 通用策略）。

更新时间策略的全局默认关闭，需要手动开启。

全局设置更新时间后，KPojo中必须拥有该成员属性，否则该策略不会对该表生效。

import com.kotlinorm.Kronos
import com.kotlinorm.beans.config.KronosCommonStrategy
import com.kotlinorm.beans.dsl.Field

Kronos.updateTimeStrategy = KronosCommonStrategy(enabled = true, field = Field("update_time", "updateTime"))

在单个模型上配置 @UpdateTime 可以覆盖全局设置，见 📚注解。

逻辑删除策略

用于设置所有表的逻辑删除字段（是否开启、kotlin属性名及数据库列名）。

参数：

通过创建KronosCommonStrategy自定义逻辑删除策略，详见：📚概念 - 通用策略）。

逻辑删除策略的全局默认关闭，需要手动开启。

全局设置逻辑删除后，KPojo中必须拥有该成员属性，否则该策略不会对该表生效。

import com.kotlinorm.Kronos
import com.kotlinorm.beans.config.KronosCommonStrategy
import com.kotlinorm.beans.dsl.Field

Kronos.logicDeleteStrategy = KronosCommonStrategy(enabled = true, field = Field("deleted"))

SELECT `id`, `name`, `deleted`
FROM `user`
WHERE `user`.`deleted` = 0

在单个模型上配置 @LogicDelete 可以覆盖全局设置，见 📚注解。

乐观锁（版本）策略

用于设置所有表的乐观锁版本字段（是否开启、kotlin属性名及数据库列名）。

参数：

通过创建KronosCommonStrategy自定义乐观锁（版本）策略，详见：📚概念 - 通用策略）。

乐观锁策略的全局默认关闭，需要手动开启。

全局设置乐观锁后，KPojo中必须拥有该成员属性，否则该策略不会对该表生效。

import com.kotlinorm.Kronos
import com.kotlinorm.beans.config.KronosCommonStrategy
import com.kotlinorm.beans.dsl.Field

Kronos.optimisticLockStrategy = KronosCommonStrategy(enabled = true, field = Field("version"))

在单个模型上配置 @Version 可以覆盖全局设置，见 📚注解。

默认日期时间格式

用于指定默认日期时间格式，默认值为 yyyy-MM-dd HH:mm:ss。

参数：

Kronos默认使用yyyy-MM-dd HH:mm:ss格式化日期/时间，你可以通过以下方式修改默认格式：

import com.kotlinorm.Kronos

Kronos.defaultDateFormat = "yyyy-MM-dd HH:mm:ss"

在单个模型上配置 @DateTimeFormat 可以覆盖全局设置，见 📚注解。

时间时区

Kronos.timeZone 是 common API 统一使用的 IANA 时区字符串。默认值为 null，表示使用当前平台 的 system default。JVM 使用 ZoneId 解析，Native 使用 kotlinx.datetime.TimeZone 解析。

kotlin.time.Instant 以及兼容的 kotlinx.datetime.Instant 表示 UTC 时间点。自动 codec 或时间策略 需要把时间点转换成本地日历值时使用该配置；LocalDate、LocalDateTime 和 LocalTime 继续保持 无时区文本语义。

import com.kotlinorm.Kronos

Kronos.timeZone = null              // 使用平台 system default
Kronos.timeZone = "UTC"
Kronos.timeZone = "Asia/Shanghai"

无值策略

Kotlin 条件为 true 时使用 .takeIf(...) 保留谓词，条件为 false 时使用 .takeUnless(...) 保留谓词。

val name: String? = null

val users = User()
    .select()
    .where { (it.name == name).takeIf(name != null) }
    .toList()

Boolean 判定按普通 Kotlin 代码执行。例如 (it.status == 0).takeUnless(includeInactive) 会在 includeInactive 为 true 时跳过状态谓词。

SELECT `id`, `name`
FROM `user`

需要生成 SQL IS NULL 时，使用 == null 或 isNull。

val users = User()
    .select()
    .where { it.name == null }
    .toList()

SELECT `id`, `name`
FROM `user`
WHERE `user`.`name` IS NULL

在 DELETE 和 UPDATE 操作中请谨慎使用 NoValueStrategyType.Ignore，以免造成全表删除或全表更新。

详见 📚无值处理。

自定义值映射

模型属性使用 Money 等领域值、数据库列保存标量值时，在应用启动时注册映射。完整的 Money 示例见 📚自定义值映射。

JSON 对象和集合使用 @Serialize，配置方式见 📚序列化。

日志输出路径及开关

通过 Kronos.logging 统一配置日志开关、内置输出位置和适配器类型。

参数：

设置 logging.path 后，Kronos 会向控制台和指定路径输出日志。输出位置和 logger 适配器见 📚Kronos-logging。

import com.kotlinorm.Kronos

Kronos.logging.enabled = false
// 重新开启时保留原配置。
Kronos.logging.enabled = true
Kronos.logging.path = ["console", "/var/log/kronos"]

Map 值转换

应用输入是 Map 时，使用 safeMapperTo 创建新模型，使用 safeFromMapData 填充已有模型。两个 API 都会将 Map key 与模型属性匹配，并转换兼容的值。完整的 Map 与模型、模型与模型 API 参考见 📚Map/KPojo类型转换。

import com.kotlinorm.interfaces.KPojo
import com.kotlinorm.utils.Extensions.safeMapperTo

data class User(
    var id: Int? = null,
    var name: String? = null,
) : KPojo

val input = mapOf("id" to 1L, "name" to "Kronos")

val created = input.safeMapperTo<User>()
// User(id = 1, name = "Kronos")

val updated = User().safeFromMapData<User>(input)
// User(id = 1, name = "Kronos")

输入边界已经完成值规范化时，设置 strictSetValue = true。开启后，内置数值、布尔值和日期时间值在符合模型属性类型时可以直接使用；已注册的自定义映射仍然可用。例如，User.id: Int? 接受 Int 输入，传入 Long 时会报告映射错误。

import com.kotlinorm.Kronos

Kronos.strictSetValue = true