Go go-flags 怎样给自定义值实现补全候选

用 go-flags 解析命令行时，固定的几个值可以直接写成 choice 标签；但如果候选值来自业务配置、内存字典或远程同步结果，就需要让自定义类型实现 flags.Completer。它的核心方法只有一个：接收用户已经输入的部分前缀，返回 []flags.Completion。

官方地址：https://pkg.go.dev/github.com/jessevdk/go-flags

最小实现是“自定义类型 + Complete(match string) + Completion{Item, Description}”。choice 负责限制最终允许值，Completer 负责根据当前前缀给出更友好的候选列表，两者解决的是不同问题。

choice 标签和 Completer 的职责边界

go-flags 已经提供了静态枚举能力，例如 choice:"dev" choice:"prod"。这适合环境名、日志级别这类候选集合稳定且很小的参数。候选值一旦需要带描述、按输入前缀过滤，或者由代码维护，就应该使用 Completer。

官方接口定义中，Completer 的 Complete 方法接收一个代表部分值的字符串，并返回可能的有效补全；Completion.Item 是补全项本身，Description 是可选说明。解析器会从字段对应的值或其地址上寻找这个接口，因此值类型字段通常要用指针接收者实现方法。

先定义带说明的候选值

示例把环境选择抽象成 Environment 类型。候选表使用结构体保存值和说明，而不是只返回一串字符串，这样补全界面可以同时展示“值是什么”和“它用于什么”。

package main

import (
    "fmt"
    "sort"
    "strings"

    "github.com/jessevdk/go-flags"
)

// Environment 是命令行参数最终接收的业务类型。
type Environment string

// environmentCandidate 把实际值和给读者看的说明放在一起。
type environmentCandidate struct {
    value       Environment
    description string
}

var environmentCandidates = []environmentCandidate{
    {value: "dev", description: "本地开发环境"},
    {value: "staging", description: "联调或预发布环境"},
    {value: "prod", description: "线上生产环境"},
}

func main() {
    var options struct {
        Env Environment `long:"env" description:"运行环境"`
    }

    // 解析器会从字段值或字段地址上寻找 Completer。
    _, err := flags.Parse(&options)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Println(options.Env)
}

// sortCandidates 让候选顺序稳定，避免数据来源顺序改变界面结果。
func sortCandidates(items []environmentCandidate) {
    sort.Slice(items, func(i, j int) bool {
        return items[i].value 

这段代码只负责准备类型和数据，真正让它参与补全的是下面的 Complete 方法。示例中的候选表可以替换成配置文件加载结果，但方法仍然应该返回稳定、可解释的值。

实现 Completer：前缀进来，候选出去

实现时要严格遵守接口签名：Complete(match string) []flags.Completion。这里用 strings.HasPrefix 做最直接的前缀匹配，并把业务值转换为 Item。如果没有匹配项，返回空切片即可，不要把“无匹配”伪装成一个非法候选。

// Complete 根据用户已输入的前缀返回环境候选。
// match 只代表部分值，不包含 --env= 这样的选项名前缀。
func (e *Environment) Complete(match string) []flags.Completion {
    candidates := append([]environmentCandidate(nil), environmentCandidates...)
    // 复制后再排序，避免补全请求改变全局候选表的顺序。
    sortCandidates(candidates)

    completions := make([]flags.Completion, 0, len(candidates))
    for _, candidate := range candidates {
        value := string(candidate.value)
        // 只返回以当前输入开头的值，保持候选和用户输入一致。
        if !strings.HasPrefix(value, match) {
            continue
        }
        completions = append(completions, flags.Completion{
            Item:        value,
            Description: candidate.description,
        })
    }
    return completions
}

方法使用指针接收者，是为了让字段地址满足 Completer。go-flags 的补全逻辑会尝试从值本身以及可取地址的值上找到接口；使用指针接收者时，Environment 仍然可以作为结构体字段保存最终解析结果。

还要注意 match 的含义：它是待补全值的前缀，不是完整的命令行参数。框架负责识别选项名，业务类型只需要关心 dev、st 这样的值。

把自定义类型绑定到选项

绑定不需要额外的注册表。只要结构体字段的类型能够实现 Completer，并且字段带有 long 或 short 标签，go-flags 就能把它作为某个选项的值类型。

var options struct {
    // 自定义类型保存解析后的值，long 标签声明命令行选项名。
    Env Environment `long:"env" description:"运行环境" value-name:"NAME"`
}

// 下面的字段仍然是普通 Go 值，不需要额外的接口字段或回调字段。
_, err := flags.Parse(&options)
if err != nil {
    // 解析错误直接交给调用方，避免把非法值当成有效环境。
    return err
}

如果自定义类型同时实现了值解析接口，例如 UnmarshalFlag，它负责把用户最终选中的字符串写入类型；Completer 只负责提供候选。把“展示候选”和“接受值”拆开，能让动态候选与最终解析保持清晰的职责边界。

空前缀、大小写和重复候选怎么处理

空前缀通常表示用户刚开始输入值，此时返回全部候选最实用；但候选很多时，应在类型内部设置上限或按业务分组，避免每次请求都构造很大的结果。大小写是否不敏感要由业务决定：环境名常常固定为小写，直接使用 HasPrefix 能避免“显示值”和“实际值”之间再次转换。

如果候选来自多个来源，建议先按值去重，再排序。排序不是接口强制要求，但稳定顺序会让补全结果更容易阅读，也便于调用方缓存和比较。Description 可以为空；不要把状态、密钥或内部路径放进说明字段，因为它可能被帮助输出或补全界面展示。

// uniqueCandidates 去掉重复值，并保留第一次出现的说明。
func uniqueCandidates(items []environmentCandidate) []environmentCandidate {
    seen := make(map[Environment]struct{}, len(items))
    result := make([]environmentCandidate, 0, len(items))
    for _, item := range items {
        // 空值没有业务意义时直接忽略，避免出现不可选择的候选。
        if item.value == "" {
            continue
        }
        if _, exists := seen[item.value]; exists {
            continue
        }
        seen[item.value] = struct{}{}
        result = append(result, item)
    }
    return result
}

choice、Completer 还是两者配合

选择方式时，关键不是“哪一个功能更多”，而是候选集合由谁维护、最终值是否必须严格受限。

要记住，补全候选不是安全校验。用户可以绕过补全直接传入文本，因此真正执行任务前仍应在解析或业务层验证值是否存在、是否有权限使用。

常见问题

为什么实现了 Complete 却没有候选？

先检查方法签名是否完全匹配，尤其是返回值必须是 []flags.Completion。再检查接收者：如果方法是指针接收者，字段必须是可取地址的普通字段，且解析时传入的是结构体指针。

可以只用 choice 标签显示描述吗？

choice 适合声明允许值，但它不是带说明的动态候选接口。需要 Item 和 Description 配对时，实现 Completer 更合适。

Complete 里能直接查询远程服务吗？

技术上可以把候选来源接到外部数据，但补全调用频繁且期待快速返回。更稳妥的做法是使用本地缓存、超时和空结果兜底，并把真正的合法性和权限检查留在解析后的业务流程。

总结

go-flags 给自定义值实现补全的最小闭环是：定义业务类型，实现 Completer，根据 match 返回 Completion，再把类型放进带有选项标签的结构体。固定白名单优先用 choice；动态候选用 Completer；两者配合时，把补全当作输入体验，把最终校验当作业务边界。