Go Kong 怎样注册自定义参数类型解析器

Go Kong 可以用 kong.MapperFunc 实现自定义解码逻辑，再在 kong.New 中通过 kong.TypeMapper(reflect.TypeOf(T{}), mapper) 注册到具体 Go 类型。解析器从 DecodeContext.Scan 读取参数，成功后把业务值写入 reflect.Value；希望仅部分字段启用某种语法时，可改用 NamedMapper 配合 type 标签。

官方地址：https://github.com/alecthomas/kong

确定业务参数的输入语法

假设命令行提供 --window，调用方希望写 --window=12..28，程序内部则得到 Window{Low:12, High:28}。这里把语法定义为闭区间，允许相等端点，只接受 0 到 1000 之间的整数，并要求下界不大于上界。这个约定属于应用接口，不是 Kong 内置的区间类型。

自定义解析器的价值是让结构体字段直接表达业务含义，避免每个命令执行函数重新拆字符串。为了让输入来源和转换职责清楚，示例把纯字符串转换函数 parseWindow 与 Kong Mapper 适配层分开；转换层不读取文件、不访问网络，也不启动业务任务。

实现解析和原子赋值

Mapper 的 Decode 接收上下文和目标值。函数适配器 MapperFunc 满足这个接口，适合简短的单值参数。ctx.Scan.PopValueInto 负责取出一个参数值；适配器将它交给 parseWindow，所有判断成功后再一次性 target.Set。

这种先解析局部值再赋值的设计，可避免先写 Low、后解析 High 失败时残留不完整状态。它不表示整个 CLI 模型具有事务回滚：其他字段可能已被解析，Parse 返回错误后应停止使用本次业务配置。接口定义见MapperFunc 官方文档。

在构建 Kong 时注册 TypeMapper

package main

import (
    "fmt"
    "os"
    "reflect"
    "strconv"
    "strings"

    "github.com/alecthomas/kong"
)

type Window struct {
    Low, High int
}

// parseWindow 只处理本应用定义的闭区间语法，不依赖 Kong 或网络。
func parseWindow(raw string) (Window, error) {
    left, right, ok := strings.Cut(raw, "..")
    if !ok || left == "" || right == "" {
        return Window{}, fmt.Errorf("区间格式应为 LOW..HIGH")
    }
    low, err := strconv.Atoi(left)
    if err != nil {
        return Window{}, fmt.Errorf("下界必须是整数: %w", err)
    }
    high, err := strconv.Atoi(right)
    if err != nil {
        return Window{}, fmt.Errorf("上界必须是整数: %w", err)
    }
    if low  1000 || low > high {
        return Window{}, fmt.Errorf("区间需满足 0 

代码使用 strings.Cut，因此需要支持该 API 的 Go 工具链。字段为 Window 值类型，注册时也使用 reflect.TypeOf(Window{})。注册项放在 kong.New 的选项中，让模型构建时就能知道如何映射这个类型；不要等 Parse 完才尝试补上。

按示例规则，参数 --window=12..28 应形成 Low 为 12、High 为 28 的值；--window=28..12 会返回区间顺序错误，缺少 --window 则由 required 约束报告。以上为代码与接口约定推导，本文没有执行程序或生成终端截图。

Window 使用数值边界表达业务约束，help 与 placeholder 则告诉使用者应该输入何种格式。只注册解析器并不会自动生成详尽语法说明，所以错误提示与帮助文本要一起维护。

选择命名或字段级注册范围

TypeMapper 把规则关联到具体类型，适合当前程序中所有 Window 都遵循同一语法的情况。如果有的字段接受区间、有的字段需要另一种表示，可以用 NamedMapper 注册命名规则，再在对应字段声明 type:"window"；命名并不要求字段类型名称也叫 window。

例如 NamedMapper("window", windowMapper) 要配合 Window 字段上的 type:"window"，并保留 required、help 等原标签；这是替代 TypeMapper 的另一种绑定方式，不必对同一字段堆叠多套注册。

如果类型自己实现 MapperValue，当前 Kong 的类型查找逻辑会先识别该接口；不要假设另加 TypeMapper 就一定覆盖类型自带解析。支持标准文本解码的类型，也可评估 encoding.TextUnmarshaler 是否更适合跨命令行与配置复用。注册接口和查找行为可参考选项实现及Mapper 实现。

解释错误返回及兼容策略

解析层直接返回缺值、格式、范围等错误，由入口决定展示与退出码。不要在 Mapper 内 os.Exit 或吞掉错误后返回零值，因为零值本身可能恰好是合法业务值，调用方无法分辨解析失败。

修改输入语法会影响脚本兼容性。例如从 12..28 改为 12:28，不能只改实现而不改帮助与调用文档。若需要过渡期同时接受两种形式，应明确规范形式、旧形式支持周期以及歧义处理；不要用“能解析就行”掩盖接口变化。

为什么自定义字段没有走 TypeMapper？先检查注册的 reflect.Type 与字段实际类型是否一致，再查看类型是否实现了优先处理的解码接口，或字段是否显式指定其他映射规则。

Mapper 必须用反射解析所有字段吗？不必。反射只用于拿到并写回目标；字符串到 Window 的转换可放在普通 Go 函数中，规则更容易独立阅读和复用。

可以让一个 Mapper 消费多个独立参数吗？接口能访问 Scanner，但这会改变命令行消费契约。本文选择一个参数字符串对应一个业务值，范围语法包含在单个值里，帮助与错误更直观。

先固定语法与范围，再选择精确的注册范围，最后将错误交给调用入口处理，就能让自定义参数类型成为清楚的命令行接口，而不是分散在各命令中的临时字符串拆解。