从旧版本升级到ajalt/clikt新版本的迁移指南

从旧版本升级到ajalt/clikt新版本的迁移指南

clikt Multiplatform command line interface parsing for Kotlin 项目地址: https://gitcode.com/gh_mirrors/cl/clikt

概述

ajalt/clikt是一个功能强大的Kotlin命令行解析库，随着版本迭代，开发者需要了解如何将现有代码迁移到新版本。本文将详细介绍从3.0到5.0版本的主要变更点和迁移方法。

升级到5.0版本

核心方法变为扩展函数

在5.0版本中，一些核心方法被重构为扩展函数，这要求开发者显式导入相关包。

// 新增导入语句
import com.github.ajalt.clikt.core.main
import com.github.ajalt.clikt.core.obj
import com.github.ajalt.clikt.core.terminal

fun main(args: Array<String>) = MyCommand().main(args)

fun example() {
    val ctx = MyCommand().currentContext
    ctx.terminal.info(ctx.obj)
}

这种变化使得API设计更加一致，同时减少了核心类的负担。

CliktCommand构造函数简化

5.0版本对CliktCommand类进行了重大重构，将大部分构造函数参数移出，改为可覆盖的属性或方法：

class MyCommand : CliktCommand(name="mycommand") {
    override fun help(context: Context) = "自定义帮助信息"
    override fun helpEpilog(context: Context) = "命令尾部信息"
    override val invokeWithoutSubcommand = true
    // 其他可覆盖属性...
}

这种变化使得类定义更加清晰，参数设置更加灵活。下表列出了所有迁移的参数：

| 移除的参数名 | 新的替代方式 | |-------------|------------| | help | override fun help() | | epilog | override fun helpEpilog() | | invokeWithoutSubcommand | override val invokeWithoutSubcommand | | printHelpOnEmptyArgs | override val printHelpOnEmptyArgs |

Markdown功能模块化

为提高核心库的轻量性，Markdown渲染功能被移到了独立模块：

1. 首先添加依赖：

dependencies {
   implementation("com.github.ajalt.clikt:clikt-markdown:$cliktVersion")
}

2. 然后在命令中安装Markdown格式化器：

val command = MyCommand().installMordantMarkdown()

这种模块化设计使得不需要Markdown功能的项目可以保持更小的体积。

Context构建器属性重命名

为提高API一致性，Context构建器的部分属性被重命名：

| 旧属性名 | 新属性名 | |---------|---------| | envvarReader | readEnvvar | | correctionSuggestor | suggestTypoCorrection |

旧名称仍作为废弃属性保留，但建议尽快迁移到新名称。

升级到4.0版本

帮助格式系统重构

4.0版本移除了CliktHelpFormatter类，改用MordantHelpFormatter：

• 构造函数现在接收Context而非Localization
• 移除了控制大小和间距的参数
• 格式化方法签名发生了变化

提示输入功能改进

CliktConsole类被移除，改为使用命令的terminal属性。

提示输入API现在使用Mordant的提示功能，转换lambda现在返回ConversionResult而非抛出异常：

val input = prompt("请输入数字") {
    it.toIntOrNull()
        ?.let { ConversionResult.Valid(it) }
        ?: ConversionResult.Invalid("$it 不是有效的整数")
}

这种设计使得错误处理更加明确和类型安全。

升级到3.0版本

Maven坐标变更

Clikt的Maven groupId从com.github.ajalt变更为com.github.ajalt.clikt，完整坐标为： com.github.ajalt.clikt:clikt:3.0.0

环境变量分割行为变更

移除了envvarSplit参数，环境变量值不再自动分割。如需分割，可显式使用split()方法：

val option: Pair<String, String> by option().split(",")

实验性API变更

值源API和补全生成API不再需要显式opt-in，可以直接使用。

本地化改进

所有字符串现在通过Localization对象定义，移除了字符串参数，改为函数调用：

context {
    localization = Localization().apply {
        override fun usageTitle() = "用法"
    }
}

迁移建议

1. 逐步迁移：先升级到3.0，再逐步升级到更高版本
2. 利用IDE提示：现代IDE能很好地识别废弃API，可帮助快速定位需要修改的代码
3. 测试覆盖：确保有充分的测试覆盖，特别是在修改提示输入和环境变量处理逻辑时
4. 查阅完整变更日志：本文仅涵盖主要变更，完整变更请参考官方变更日志

通过遵循这些指南，您可以顺利将现有Clikt项目迁移到最新版本，享受新特性和改进带来的好处。

clikt Multiplatform command line interface parsing for Kotlin 项目地址: https://gitcode.com/gh_mirrors/cl/clikt