zcli

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 16, 2025 License: MIT Imports: 19 Imported by: 0

README

ZCli - 企业级 CLI 框架和系统服务管理扩展包

Go Reference Go Report Card MIT License

最近更新（2025-12-11）：✅ 服务管理全面迁移 ServiceRunner，移除并发管理器引用；✅ RunWait 统一信号处理并由 Run() 内置 15s 兜底；✅ 示例错误消息改为英文；⚠️ 需要 Go 1.23+。

ZCli 是一个基于 Cobra的现代化企业级命令行应用框架，提供了优雅的 API 设计、完整的系统服务管理、强大的错误处理系统、现代化的多语言支持和生产级的稳定性保障。

🌟 最新改进 (v0.2.0)

✨ 优雅的 API 设计
  • 服务接口抽象: 统一的 ServiceRunner 接口，支持依赖注入和模块化设计
  • 链式 Builder 模式: 流畅的 API 调用，支持 WithServiceRunner、WithService、WithValidator 等方法
  • 错误优先设计: 新增 BuildWithError 方法，提供更好的错误处理体验
  • 便利性 API: QuickService、QuickCLI 等快速创建函数，简化常见使用场景
🛡️ 强大的错误处理系统
  • 结构化错误: 完整的错误代码体系，支持错误分类和追踪
  • 错误聚合器: 批量处理多个错误，提供统一的错误报告
  • 预定义错误: 常用错误的快速创建函数，如 ErrServiceAlreadyRunning
  • 错误链追踪: 支持错误原因链追踪和上下文信息附加
🔒 并发安全保障
  • 原子操作: 使用 atomic.Bool 等原子类型确保状态一致性
  • 线程安全设计: 经过严格的并发安全测试，支持多线程环境
  • 状态管理: 完善的服务生命周期状态管理，支持状态监听器
  • 优雅关闭: 分级超时机制，确保服务可靠停止

✨ 核心特性

🎨 优雅的命令行界面
  • 智能彩色输出: 自动检测终端能力，支持彩色和无彩色模式
  • 自定义 Logo: 支持 ASCII 艺术 Logo 展示
  • 分组命令显示: 自动区分普通命令和系统服务命令
  • 优化的帮助系统: 美观的帮助信息展示和命令补全
🔧 企业级系统服务集成
  • 双运行模式: 支持前台开发调试模式和后台服务模式
  • 完整服务管理: install/start/stop/restart/status/uninstall
  • 高级服务配置: 用户权限、工作目录、依赖关系、环境变量、chroot 等
  • 跨平台支持: Windows、Linux、macOS 全平台兼容
  • 并发安全: 经过严格的并发安全测试，生产环境可靠
🌍 现代化多语言系统
  • 层次化语言包: Service/UI/Error/Format 四域架构
  • 智能回退机制: 缺失翻译自动回退到备用语言
  • 便利性 API: ServiceLocalizer 简化常用本地化操作
  • 动态扩展: 运行时注册自定义语言包
🛡️ 生产级稳定性
  • 优雅信号处理: RunWait 统一监听 SIGINT/SIGTERM/SIGQUIT，捕获后调用 sm.Stop()；Run() 内置 15s 兜底
  • 分级超时机制: 3+2 秒分级超时确保服务可靠停止
  • 权限检查: 智能的文件和目录权限验证
  • 错误恢复: 全面的错误处理和日志记录

📦 安装

go get github.com/darkit/zcli

最低要求: Go 1.23+ (使用了新特性)

🚀 快速开始

现代 API 示例（推荐）
package main

import (
    "context"
    "fmt"
    "log/slog"
    "os"
    "time"

    "github.com/darkit/zcli"
)

func main() {
    // 方式1: 使用便利性API快速创建（最简单）
    app := zcli.QuickService("myapp", "我的企业级应用", runService)

    // 方式2: 使用完整的Builder API（推荐用于复杂场景）
    app, err := zcli.NewBuilder("zh").
        WithName("myapp").
        WithDisplayName("我的企业级应用").
        WithDescription("这是一个演示企业级功能的应用").
        WithVersion("1.0.0").
        WithService(runService, stopService).  // 配置服务入口
        WithValidator(func(cfg *zcli.Config) error {  // 配置验证
            if cfg.Basic().Name == "" {
                return fmt.Errorf("应用名称不能为空")
            }
            return nil
        }).
        BuildWithError()  // 错误优先的构建方式

    if err != nil {
        slog.Error("应用构建失败", "error", err)
        os.Exit(1)
    }

    // 添加全局选项
    app.PersistentFlags().BoolP("debug", "d", false, "启用调试模式")
    app.PersistentFlags().StringP("config", "c", "", "配置文件路径")

    // 执行应用
    if err := app.Execute(); err != nil {
        slog.Error("应用执行失败", "error", err)
        os.Exit(1)
    }
}

// 服务主函数 - 使用context优雅处理生命周期
func runService(ctx context.Context) error {
    slog.Info("服务已启动，等待停止信号...")

    // 创建定时器
    ticker := time.NewTicker(time.Second)
    defer ticker.Stop()

    // 服务主循环 - 使用context.Done()优雅处理停止
    for {
        select {
        case <-ctx.Done():
            slog.Info("收到停止信号，准备退出服务循环")
            return nil
        case <-ticker.C:
            slog.Info("服务正在运行...")

            // 模拟业务逻辑可能出现的错误
            if err := processBusinessLogic(); err != nil {
                return fmt.Errorf("业务逻辑处理失败: %w", err)
            }
        }
    }
}

// 服务停止函数 - 执行清理工作
func stopService() error {
    slog.Info("执行服务清理工作...")

    // 模拟清理工作
    time.Sleep(100 * time.Millisecond)

    slog.Info("服务清理完成，已安全停止")
    return nil
}

func processBusinessLogic() error {
    // 模拟业务逻辑
    return nil
}
运行方式
# 前台运行模式 - 开发调试使用
./myapp run              # 在前台运行，可以看到日志，Ctrl+C停止

# 服务管理模式 - 生产环境使用
./myapp install          # 安装为系统服务
./myapp start            # 启动服务
./myapp status           # 查看服务状态
./myapp stop             # 停止服务
./myapp restart          # 重启服务
./myapp uninstall        # 卸载服务

# 其他功能
./myapp help             # 查看帮助
./myapp version          # 查看版本信息

🔧 高级配置

服务接口抽象和依赖注入
// 定义你的服务
type MyService struct {
    db     *Database
    cache  *Cache
    config *Config
}

func (s *MyService) Run(ctx context.Context) error {
    slog.Info("企业级服务已启动")

    ticker := time.NewTicker(5 * time.Second)
    defer ticker.Stop()

    for {
        select {
        case <-ctx.Done():
            slog.Info("收到停止信号，优雅关闭")
            return nil
        case <-ticker.C:
            if err := s.processBusinessLogic(); err != nil {
                return fmt.Errorf("业务处理失败: %w", err)
            }
        }
    }
}

func (s *MyService) Stop() error {
    slog.Info("正在关闭服务...")

    // 关闭数据库连接
    if err := s.db.Close(); err != nil {
        return fmt.Errorf("数据库关闭失败: %w", err)
    }

    // 关闭缓存连接
    if err := s.cache.Close(); err != nil {
        return fmt.Errorf("缓存关闭失败: %w", err)
    }

    return nil
}

func (s *MyService) Name() string {
    return "enterprise-service"
}

func (s *MyService) processBusinessLogic() error {
    // 实现业务逻辑
    return nil
}

func main() {
    // 初始化依赖
    db := &Database{} // 初始化数据库
    cache := &Cache{} // 初始化缓存
    config := &Config{} // 加载配置

    // 创建服务实例
    service := &MyService{
        db:     db,
        cache:  cache,
        config: config,
    }

    // 使用服务接口抽象
    app, err := zcli.NewBuilder("zh").
        WithName("enterprise-app").
        WithDisplayName("企业级服务应用").
        WithDescription("提供企业级功能的后台服务").
        WithVersion("2.1.0").

        // 高级服务配置
        WithWorkDir("/opt/enterprise-app").
        WithEnvVar("ENV", "production").
        WithEnvVar("LOG_LEVEL", "info").
        WithEnvVar("DB_HOST", "localhost:5432").
        WithDependencies("postgresql", "redis").

        // 使用服务接口抽象
        WithServiceRunner(service).

        // 添加配置验证
        WithValidator(func(cfg *zcli.Config) error {
            if cfg.Service().EnvVars["DB_HOST"] == "" {
                return fmt.Errorf("数据库主机不能为空")
            }
            return nil
        }).

        // 错误优先构建
        BuildWithError()

    if err != nil {
        slog.Error("应用构建失败", "error", err)
        os.Exit(1)
    }

    if err := app.Execute(); err != nil {
        slog.Error("应用执行失败", "error", err)
        os.Exit(1)
    }
}
错误处理示例
func main() {
    app, err := zcli.NewBuilder("zh").
        WithName("error-demo").
        WithService(runWithErrorHandling, stopService).
        BuildWithError()

    if err != nil {
        // 使用结构化错误处理
        if serviceErr, ok := zcli.GetServiceError(err); ok {
            slog.Error("服务错误",
                "code", serviceErr.Code,
                "service", serviceErr.Service,
                "operation", serviceErr.Operation,
                "message", serviceErr.Message)
        } else {
            slog.Error("构建失败", "error", err)
        }
        os.Exit(1)
    }

    app.Execute()
}

func runWithErrorHandling(ctx context.Context) error {
    // 使用错误聚合器收集多个错误
    aggregator := zcli.NewErrorAggregator()

    // 初始化各个组件
    if err := initDatabase(); err != nil {
        aggregator.Add(zcli.NewError(zcli.ErrServiceCreate).
            Service("database").
            Operation("init").
            Message("数据库初始化失败").
            Cause(err).
            Build())
    }

    if err := initCache(); err != nil {
        aggregator.Add(zcli.NewError(zcli.ErrServiceCreate).
            Service("cache").
            Operation("init").
            Message("缓存初始化失败").
            Cause(err).
            Build())
    }

    // 如果有错误，返回聚合的错误
    if aggregator.HasErrors() {
        return aggregator.Error()
    }

    // 服务主循环
    for {
        select {
        case <-ctx.Done():
            return nil
        default:
            // 处理业务逻辑
            time.Sleep(100 * time.Millisecond)
        }
    }
}

func initDatabase() error {
    // 模拟数据库初始化
    return nil
}

func initCache() error {
    // 模拟缓存初始化
    return nil
}
自定义命令
// 创建配置管理主命令
configCmd := &zcli.Command{
    Use:   "config",
    Short: "配置管理",
    Long:  "管理应用程序的配置文件和设置",
    Run: func(cmd *zcli.Command, args []string) {
        fmt.Println("配置管理功能")
    },
}

// 添加子命令
showCmd := &zcli.Command{
    Use:   "show",
    Short: "显示当前配置",
    Run: func(cmd *zcli.Command, args []string) {
        fmt.Println("当前配置:")
        fmt.Println("- 服务名称: myapp")
        fmt.Println("- 工作目录: /opt/myapp")
        fmt.Println("- 运行模式: 生产模式")
    },
}

editCmd := &zcli.Command{
    Use:   "edit",
    Short: "编辑配置",
    Run: func(cmd *zcli.Command, args []string) {
        fmt.Println("打开配置编辑器...")
    },
}

// 组织命令层次
configCmd.AddCommand(showCmd, editCmd)
app.AddCommand(configCmd)

🌍 多语言支持

内置语言切换
// 中文界面
app := zcli.NewBuilder("zh").Build()

// 英文界面
app := zcli.NewBuilder("en").Build()

// 也可以用WithLanguage方法
app := zcli.NewBuilder().WithLanguage("zh").Build()

📊 命令行界面效果

帮助界面示例
$ myapp --help

███████╗ ██████╗██╗     ██╗
╚══███╔╝██╔════╝██║     ██║
  ███╔╝ ██║     ██║     ██║
 ███╔╝  ██║     ██║     ██║
███████╗╚██████╗███████╗██║
╚══════╝ ╚═════╝╚══════╝╚═╝ v1.0.0

我的企业级应用

用法:
   myapp [参数]
   myapp [command] [参数]

选项:
   -h, --help      获取帮助
   -v, --version   显示版本信息
   -d, --debug     启用调试模式
   -c, --config    配置文件路径

可用命令:
   help        获取帮助
   config      配置管理

系统命令:
   run         运行服务          # 前台运行模式
   start       启动服务          # 后台服务模式
   stop        停止服务
   status      查看状态
   restart     重启服务
   install     安装服务
   uninstall   卸载服务

使用 'myapp [command] --help' 获取命令的更多信息

⚙️ 高级特性

1. 前台 vs 服务运行模式

ZCli 智能区分两种运行模式：

前台运行模式 (./myapp run):

  • 适用于开发和调试
  • 实时显示日志输出
  • 支持 Ctrl+C 优雅退出
  • Interactive 模式检测

服务运行模式 (通过系统服务):

  • 适用于生产环境部署
  • 后台运行，由系统服务管理器控制
  • 支持开机自启、自动重启等
  • 完整的生命周期管理

并发管理

  • sManager（默认）：面向 install/start/stop/status 等系统服务命令集，依赖 github.com/darkit/daemon，适合需要系统级安装/守护的场景。
2. Context 生命周期管理（自动信号处理）

ZCli 框架自动管理 Context 生命周期，提供优雅的信号处理和资源清理机制。

Context 的自动创建

框架内部自动创建带信号监听的 Context，无需手动处理：

// 框架内部自动执行（无需用户编写）
ctx, cancel := signal.NotifyContext(
    context.Background(),
    syscall.SIGINT,  // Ctrl+C
    syscall.SIGTERM, // 终止信号
    syscall.SIGQUIT, // 退出信号
)
生命周期流程
用户启动应用
    ↓
框架创建带信号监听的 Context
    ↓
自动传递给 runService(ctx)
    ↓
用户按 Ctrl+C
    ↓
ctx.Done()被触发
    ↓
服务优雅退出
    ↓
执行 stopService() 清理资源
为什么使用 func(ctx context.Context) error？

✅ 优势：

  1. 自动信号处理 - 无需手动处理 SIGINT/SIGTERM
func runService(ctx context.Context) error {
    ticker := time.NewTicker(time.Second)
    defer ticker.Stop()

    for {
        select {
        case <-ctx.Done():  // Ctrl+C 时自动触发
            slog.Info("收到停止信号，优雅退出")
            return nil
        case <-ticker.C:
            // 业务逻辑
        }
    }
}
  1. 优雅关闭链 - Context 可传递给所有依赖组件
func runService(ctx context.Context) error {
    // Context 传递给依赖组件
    db, _ := database.Connect(ctx)
    cache, _ := redis.Connect(ctx)

    // 当收到停止信号时，所有组件都能感知到
    // 数据库、缓存等会自动关闭连接
}
  1. 超时控制 - 基于父 Context 创建子 Context
func runService(ctx context.Context) error {
    // 为某个操作设置超时
    ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
    defer cancel()

    return doSomethingWithTimeout(ctx)
}

❌ 如果没有 Context（不推荐）：

// 需要手动处理信号
func runService() error {
    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)

    for {
        select {
        case <-sigChan:  // 手动处理
            return nil
        default:
            // 业务逻辑
        }
    }
}
完整生命周期示例
func runService(ctx context.Context) error {
    slog.Info("服务启动")

    // 1. 初始化资源（传递 ctx）
    db, err := database.Connect(ctx)
    if err != nil {
        return err
    }
    defer db.Close()

    // 2. 创建子 Context（可选）
    workCtx, cancel := context.WithCancel(ctx)
    defer cancel()

    // 3. 启动后台任务
    go backgroundTask(workCtx)

    // 4. 主循环
    ticker := time.NewTicker(time.Second)
    defer ticker.Stop()

    for {
        select {
        case <-ctx.Done():
            // 框架收到 Ctrl+C 时自动触发
            slog.Info("收到停止信号")

            // 取消所有子任务
            cancel()

            // 等待子任务完成
            time.Sleep(100 * time.Millisecond)

            return nil

        case <-ticker.C:
            // 正常业务逻辑
            if err := doWork(ctx); err != nil {
                return err
            }
        }
    }
}

func stopService() error {
    slog.Info("执行最终清理")
    // 这里执行无法通过 context 传递的清理工作
    // 例如：关闭文件句柄、保存状态、刷新缓冲区等
    return nil
}
分级超时保护机制

框架提供 3+2 秒分级超时保护：

收到停止信号（Ctrl+C）
    ↓
等待 3 秒（优雅退出期）
    ↓
[超时] 强制调用 stopService()
    ↓
再等待 2 秒（清理期）
    ↓
[超时] 强制终止进程

这确保即使服务卡死，也能在 5 秒内强制退出。

最佳实践
  1. 始终在 select 中监听 ctx.Done()
for {
    select {
    case <-ctx.Done():
        return ctx.Err()  // 返回取消原因
    case data := <-dataChan:
        processData(data)
    }
}
  1. 传递 Context 给所有阻塞操作
// 数据库查询
rows, err := db.QueryContext(ctx, sql)

// HTTP 请求
req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)

// gRPC 调用
conn, err := grpc.DialContext(ctx, addr)
  1. 避免存储 Context（反模式）
// ❌ 错误：不要将 context 存储在结构体中
type Service struct {
    ctx context.Context  // 违反 Go 官方建议
}

// ✅ 正确：通过参数传递
func (s *Service) Run(ctx context.Context) error {
    // 使用参数传递的 ctx
}
  1. 使用 Context 传递请求范围的值
// 传递请求 ID
ctx = context.WithValue(ctx, "requestID", uuid.New())

// 在下游获取
requestID := ctx.Value("requestID").(uuid.UUID)
3. 智能标志导出功能

ZCli 提供了强大的命令行标志导出功能，专门用于与外部包（如 Viper 配置管理）的集成：

基本用法
// 创建应用并添加各种标志
app := zcli.NewBuilder("zh").
    WithName("myapp").
    Build()

// 添加业务标志
app.PersistentFlags().StringP("config", "c", "", "配置文件路径")
app.Flags().IntP("port", "p", 8080, "服务端口")
app.Flags().BoolP("debug", "d", false, "调试模式")

// 导出给外部包使用（自动排除系统标志）
flags := app.ExportFlagsForViper()
WithBindPFlags(flags...)(viperConfig)
智能过滤机制

框架自动排除 23 个系统标志，确保只有业务标志传递给外部包：

// 自动排除的系统标志包括：
// - 帮助系统：help, h
// - 版本系统：version, v
// - 补全系统：completion, completion-*, gen-completion
// - 内部调试：__complete, __completeNoDesc, no-descriptions
// - 配置系统：config-help, print-config, validate-config
// ... 总计23个系统标志

// 检查标志类型
isSystem := app.IsSystemFlag("help")     // true - 系统标志
isSystem := app.IsSystemFlag("config")   // false - 业务标志

// 获取所有系统标志列表（调试用）
systemFlags := app.GetSystemFlags()  // 返回23个系统标志的完整列表
API 参考
方法 用途 返回值
ExportFlagsForViper(exclude...) 导出适用于 Viper 的标志 []*FlagSet
GetAllFlagSets() 获取所有标志集合 []*FlagSet
GetBindableFlagSets(exclude...) 获取可绑定的标志（排除系统标志） []*FlagSet
GetFilteredFlags(exclude...) 获取单个过滤后的标志集合 *FlagSet
GetFlagNames(includeInherited) 获取标志名称列表 []string
GetFilteredFlagNames(exclude...) 获取过滤后的标志名称 []string
IsSystemFlag(name) 检查是否为系统标志 bool
GetSystemFlags() 获取所有系统标志列表 []string

📚 API 参考

Builder API
核心构建方法
方法 说明 示例
NewBuilder(lang) 创建新的 Builder 实例 zcli.NewBuilder("zh")
Build() 构建 CLI 实例（可能 panic） builder.Build()
BuildWithError() 构建 CLI 实例，返回错误 app, err := builder.BuildWithError()
基础配置方法
方法 说明 示例
WithName(name) 设置应用名称 .WithName("myapp")
WithDisplayName(name) 设置显示名称 .WithDisplayName("我的应用")
WithDescription(desc) 设置应用描述 .WithDescription("应用描述")
WithVersion(version) 设置版本号 .WithVersion("1.0.0")
WithLanguage(lang) 设置语言 .WithLanguage("zh")
服务配置方法
方法 说明 示例
WithService(run, stop...) 配置服务函数 .WithService(runFunc, stopFunc)
WithServiceRunner(service) 配置服务接口实现 .WithServiceRunner(myService)
WithValidator(validator) 添加配置验证器 .WithValidator(validatorFunc)
WithWorkDir(dir) 设置工作目录 .WithWorkDir("/opt/app")
WithEnvVar(key, value) 添加环境变量 .WithEnvVar("ENV", "prod")
WithDependencies(deps...) 设置服务依赖 .WithDependencies("postgresql")
便利性 API
方法 说明 示例
QuickService(name, displayName, run) 快速创建服务应用 zcli.QuickService("app", "描述", runFunc)
QuickServiceWithStop(name, displayName, run, stop) 快速创建带停止函数的服务 zcli.QuickServiceWithStop(...)
QuickCLI(name, display, desc) 快速创建 CLI 工具 zcli.QuickCLI("tool", "工具", "描述")
服务接口
ServiceRunner 接口
type ServiceRunner interface {
    Run(ctx context.Context) error  // 运行服务
    Stop() error                    // 停止服务
    Name() string                   // 服务名称
}
实现示例
type MyService struct{}

func (s *MyService) Run(ctx context.Context) error {
    // 服务运行逻辑
    for {
        select {
        case <-ctx.Done():
            return nil
        default:
            // 处理业务逻辑
        }
    }
}

func (s *MyService) Stop() error {
    // 停止逻辑
    return nil
}

func (s *MyService) Name() string {
    return "my-service"
}
错误处理 API
错误创建和处理
函数 说明 示例
NewError(code) 创建错误构建器 zcli.NewError(zcli.ErrServiceStart)
NewErrorAggregator() 创建错误聚合器 aggregator := zcli.NewErrorAggregator()
GetServiceError(err) 获取服务错误 serviceErr, ok := zcli.GetServiceError(err)
预定义错误函数
函数 说明 示例
ErrServiceAlreadyRunning(name) 服务已运行错误 zcli.ErrServiceAlreadyRunning("myapp")
ErrServiceAlreadyStopped(name) 服务已停止错误 zcli.ErrServiceAlreadyStopped("myapp")
ErrServiceStartTimeout(name, timeout) 启动超时错误 zcli.ErrServiceStartTimeout("myapp", 30*time.Second)
错误构建器 API
err := zcli.NewError(zcli.ErrServiceStart).
    Service("myapp").                    // 设置服务名
    Operation("start").                  // 设置操作
    Message("启动失败").                 // 设置消息
    Cause(originalError).                // 设置原因
    Context("key", "value").             // 添加上下文
    Build()                              // 构建错误

🎯 设计原则和最佳实践

1. 错误优先设计
// ✅ 推荐：使用BuildWithError
app, err := zcli.NewBuilder("zh").
    WithName("myapp").
    BuildWithError()
if err != nil {
    // 处理错误
}

// ❌ 不推荐：可能panic的Build
app := zcli.NewBuilder("zh").
    WithName("myapp").
    Build() // 可能panic
2. 依赖注入和接口抽象
// ✅ 推荐：使用接口抽象
type DatabaseService interface {
    Connect() error
    Close() error
}

type MyService struct {
    db DatabaseService  // 依赖注入
}

app, _ := zcli.NewBuilder("zh").
    WithServiceRunner(myService).  // 接口抽象
    BuildWithError()
3. 配置验证
// ✅ 推荐:添加配置验证
app, err := zcli.NewBuilder("zh").
    WithName("myapp").
    WithValidator(func(cfg *zcli.Config) error {
        if cfg.Basic().Name == "" {
            return fmt.Errorf("应用名称不能为空")
        }
        return nil
    }).
    BuildWithError()
4. 结构化错误处理
// ✅ 推荐：使用结构化错误
aggregator := zcli.NewErrorAggregator()

if err := initDB(); err != nil {
    aggregator.Add(zcli.NewError(zcli.ErrServiceCreate).
        Service("database").
        Operation("init").
        Cause(err).
        Build())
}

if aggregator.HasErrors() {
    return aggregator.Error()
}

⚠️ 注意事项

系统权限
  • 服务管理功能需要适当的系统权限
  • Linux/macOS: 通常需要 sudo 权限安装系统服务
  • Windows: 需要管理员权限
平台兼容性
  • 某些终端可能不支持彩色输出，框架会自动检测并降级
  • Windows 服务和 Unix 守护进程的配置选项有所不同
  • 使用条件编译处理平台特定功能
并发安全
  • 服务函数应该是线程安全的
  • 避免在服务函数中使用全局变量
  • 使用 channel 或 context 进行 goroutine 间通信

📚 依赖项

  • Go 1.23+: 充分利用 Go 1.23 新特性
  • github.com/spf13/cobra: 命令行框架基础
  • github.com/fatih/color: 彩色输出支持
  • github.com/darkit/daemon: 跨平台系统服务管理

🆕 版本历史

v0.2.0 (Latest)
  • ✨ 新增服务接口抽象: ServiceRunner 接口统一服务管理
  • ✨ 增强 Builder 模式: 新增 WithServiceRunner、WithValidator 方法
  • ✨ 错误优先设计: 新增 BuildWithError 方法，提供更好的错误处理
  • ✨ 强大的错误处理系统: 结构化错误、错误聚合器、预定义错误函数
  • ✨ 并发安全保障: 原子操作、线程安全设计、状态管理
  • ✨ 便利性 API: QuickService、QuickCLI 等快速创建函数
  • 🔧 简化 API 设计: 移除过度封装的模板代码，专注核心功能
  • 🐛 修复并发问题: 解决服务管理中的 race condition 和死锁问题
  • 📚 完善文档: 全面更新 API 文档和使用示例
v0.1.x (Legacy)
  • 基础 CLI 框架功能
  • 系统服务管理
  • 多语言支持
  • 传统 API 设计

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发环境设置
git clone https://github.com/darkit/zcli.git
cd zcli
go mod tidy
go test -v  # 运行测试
测试
# 运行所有测试
go test -v

# 运行并发安全测试
go test -v -run TestServiceConcurrent

# 运行集成测试
go test -v -run TestFinalIntegration

📄 许可证

MIT License

ZCli: 让您的 CLI 应用更专业、更稳定、更易用。

Documentation

Overview

Package zcli 是一个基于cobra的命令行应用框架，提供了更友好的命令行界面和系统服务管理功能。

ZCli的主要特性包括：

友好的命令行界面:

  • 支持彩色输出，自动检测终端颜色支持
  • 自定义Logo显示
  • 分组显示命令（普通命令和系统命令）
  • 优化的帮助信息展示
  • 支持命令补全

系统服务集成:

  • 一键集成系统服务管理功能
  • 支持服务的安装、卸载、启动、停止、重启和状态查询
  • 支持服务配置的自定义（工作目录、环境变量等）
  • 跨平台支持 (Windows, Linux, macOS)

国际化支持:

  • 内置中文和英文支持
  • 可扩展的语言包系统
  • 支持自定义语言包和错误消息

版本信息管理:

  • 详细的版本信息展示
  • 支持构建信息的自定义
  • 支持调试/发布模式切换

使用示例: 

package main

import (
    "log/slog"
    "os"
    "time"

    "github.com/darkit/zcli"
)

var isRunning = true

func main() {
    workDir, _ := os.UserHomeDir()
    app := zcli.NewBuilder("zh").
        WithName("myapp").
        WithDisplayName("我的应用").
        WithDescription("这是一个示例应用").
        WithVersion("1.0.0").
        WithWorkDir(workDir).
        WithSystemService(run, stop).
        Build()

    // 执行应用
    if err := app.Execute(); err != nil {
        slog.Error(err.Error())
    }
}

func run() {
    slog.Info("服务已启动")
    isRunning = true
    ticker := time.NewTicker(time.Second)
    defer ticker.Stop()

    for range ticker.C {
        if !isRunning {
            break
        }
        slog.Info("服务正在运行...")
    }
}

func stop() {
    slog.Warn("服务停止中...")
    isRunning = false
    slog.Info("服务已停止")
}

主要结构:

Builder: CLI构建器，使用链式调用方式配置应用 

app := zcli.NewBuilder("zh").
    WithName("myapp").
    WithSystemService(run, stop).
    Build()

Cli: 命令行应用对象，封装了cobra.Command 

// 添加命令
app.AddCommand(myCommand)
// 执行应用
app.Execute()

Config: 应用配置，包含基本信息、运行时配置和服务配置

Language: 语言包定义，支持多语言

Command: 命令定义，等同于cobra.Command

最低Go版本要求: 1.19 (使用了atomic.Bool等特性)

更多信息和示例请参考: https://github.com/darkit/zcli

Package zcli 提供命令行工具构建功能，包括增强的错误处理机制。 本包实现了结构化错误处理、错误聚合和详细的错误追踪功能。

Index

Constants

This section is empty.

Variables

View Source 
var GlobalLanguageManager = NewLanguageManager("zh")

GlobalLanguageManager 全局语言包管理器

Functions

func CombineErrors added in v0.1.9 

func CombineErrors(errs ...error) error

CombineErrors 合并多个错误

func GetText added in v0.1.9 

func GetText(path string) string

GetText 从全局管理器获取文本

func IsErrorCode added in v0.1.9 

func IsErrorCode(err error, code ErrorCode) bool

IsErrorCode 检查错误代码

func IsServiceError added in v0.1.9 

func IsServiceError(err error) bool

IsServiceError 检查是否为服务错误

func RegisterLanguage added in v0.1.9 

func RegisterLanguage(lang *Language) error

RegisterLanguage 注册语言包到全局管理器

func SetLanguage added in v0.1.9 

func SetLanguage(langCode string) error

SetLanguage 设置全局语言

Types

type BaseService added in v0.1.9 

type BaseService struct {
	// contains filtered or unexported fields
}

BaseService 提供默认的服务实现，用户可以嵌入此结构体

func NewBaseService added in v0.1.9 

func NewBaseService(config ServiceConfig) (*BaseService, error)

NewBaseService 创建基础服务实例

func (*BaseService) AddStopHandler added in v0.1.9 

func (bs *BaseService) AddStopHandler(handler func() error)

AddStopHandler 添加停止处理函数

func (*BaseService) IsRunning added in v0.1.9 

func (bs *BaseService) IsRunning() bool

IsRunning 检查服务是否正在运行

func (*BaseService) Name added in v0.1.9 

func (bs *BaseService) Name() string

Name 返回服务名称

func (*BaseService) Run added in v0.1.9 

func (bs *BaseService) Run(ctx context.Context) error

Run 运行服务的默认实现，子类应该重写此方法

func (*BaseService) Stop added in v0.1.9 

func (bs *BaseService) Stop() error

Stop 停止服务

func (*BaseService) WaitForStop added in v0.1.9 

func (bs *BaseService) WaitForStop() <-chan struct{}

WaitForStop 等待停止信号

type Basic added in v0.1.6 

type Basic struct {
	Name        string // 服务名称
	DisplayName string // 显示名称
	Description string // 服务描述
	Version     string // 版本
	Language    string // 使用语言
	NoColor     bool   // 禁用彩色输出
}

Basic 基础配置

type BuildError added in v0.1.9 

type BuildError struct {
	Errors []error
}

BuildError 构建错误

func (*BuildError) Error added in v0.1.9 

func (be *BuildError) Error() string

func (*BuildError) Unwrap added in v0.1.9 

func (be *BuildError) Unwrap() []error

type Builder added in v0.1.6 

type Builder struct {
	// contains filtered or unexported fields
}

Builder CLI构建器 - 增强版

func NewBuilder added in v0.1.6 

func NewBuilder(lang ...string) *Builder

NewBuilder 创建CLI构建器 lang参数可选，指定默认语言

func (*Builder) Build added in v0.1.6 

func (b *Builder) Build() *Cli

Build 构建CLI实例

func (*Builder) BuildWithError added in v0.1.9 

func (b *Builder) BuildWithError() (*Cli, error)

BuildWithError 构建CLI实例，返回错误而不是panic

func (*Builder) MustBuild added in v0.1.9 

func (b *Builder) MustBuild() *Cli

MustBuild 构建CLI实例，失败时panic（用于确定不会失败的场景）

func (*Builder) WithBuildTime added in v0.1.8 

func (b *Builder) WithBuildTime(buildTime string) *Builder

WithBuildTime 设置构建时间

func (*Builder) WithCommand added in v0.1.6 

func (b *Builder) WithCommand(cmd *Command) *Builder

WithCommand 添加命令

func (*Builder) WithContext added in v0.1.7 

func (b *Builder) WithContext(ctx context.Context) *Builder

WithContext 设置名称

func (*Builder) WithCustomService added in v0.2.0 

func (b *Builder) WithCustomService(fn func(*Config)) *Builder

WithCustomService 配置服务（高级用法） 允许传入自定义配置函数来修改配置

func (*Builder) WithDebug added in v0.1.6 

func (b *Builder) WithDebug(debug bool) *Builder

WithDebug 设置调试模式

func (*Builder) WithDefaultConfig added in v0.1.6 

func (b *Builder) WithDefaultConfig() *Builder

WithDefaultConfig 使用默认配置

func (*Builder) WithDefaults added in v0.1.9 

func (b *Builder) WithDefaults() *Builder

WithDefaults 设置默认配置

func (*Builder) WithDependencies added in v0.1.6 

func (b *Builder) WithDependencies(deps ...string) *Builder

WithDependencies 设置依赖

func (*Builder) WithDescription added in v0.1.6 

func (b *Builder) WithDescription(desc string) *Builder

WithDescription 设置描述

func (*Builder) WithDisplayName added in v0.1.6 

func (b *Builder) WithDisplayName(name string) *Builder

WithDisplayName 设置显示名称

func (*Builder) WithEnvVar added in v0.1.6 

func (b *Builder) WithEnvVar(key, value string) *Builder

WithEnvVar 设置环境变量

func (*Builder) WithGitInfo added in v0.1.6 

func (b *Builder) WithGitInfo(commitID, branch, tag string) *Builder

WithGitInfo 设置Git信息

func (*Builder) WithLanguage added in v0.1.6 

func (b *Builder) WithLanguage(lang string) *Builder

WithLanguage 设置语言 

func (b *Builder) WithLogo(logo string) *Builder

WithLogo 设置Logo

func (*Builder) WithName added in v0.1.6 

func (b *Builder) WithName(name string) *Builder

WithName 设置名称

func (*Builder) WithQuickConfig added in v0.1.9 

func (b *Builder) WithQuickConfig(name, displayName, description, version string) *Builder

WithQuickConfig 快速配置基本信息

func (*Builder) WithRuntime added in v0.1.6 

func (b *Builder) WithRuntime(rt *Runtime) *Builder

WithRuntime 设置运行时配置

func (*Builder) WithService added in v0.1.6 

func (b *Builder) WithService(run RunFunc, stop ...StopFunc) *Builder

WithService 配置服务运行和停止函数（主入口） run: 服务运行函数，标准签名 func(ctx context.Context) error stop: 可选停止函数，标准签名 func() error

func (*Builder) WithServiceOptions added in v0.1.9 

func (b *Builder) WithServiceOptions(workDir string, envVars map[string]string, deps ...string) *Builder

WithServiceOptions 配置服务选项

func (*Builder) WithServiceRunner added in v0.1.9 

func (b *Builder) WithServiceRunner(service ServiceRunner) *Builder

WithServiceRunner 配置优雅的服务接口（推荐方式）

func (*Builder) WithShutdownTimeouts added in v0.2.0 

func (b *Builder) WithShutdownTimeouts(initial, grace time.Duration) *Builder

WithShutdownTimeouts 配置优雅退出的分级超时时间 initial: 首次等待时长；grace: 调用停止函数后的额外等待时长

func (*Builder) WithValidator added in v0.1.9 

func (b *Builder) WithValidator(validator func(*Config) error) *Builder

WithValidator 添加配置验证器

func (*Builder) WithVersion added in v0.1.6 

func (b *Builder) WithVersion(version string) *Builder

WithVersion 设置版本

func (*Builder) WithWorkDir added in v0.1.6 

func (b *Builder) WithWorkDir(dir string) *Builder

WithWorkDir 设置工作目录

type Cli added in v0.1.6 

type Cli struct {
	// contains filtered or unexported fields
}

Cli 是对 cobra.Command 的封装，提供更友好的命令行界面

func NewCli added in v0.1.6 

func NewCli(opts ...Option) *Cli

NewCli 创建一个新的命令对象

func QuickCLI added in v0.1.9 

func QuickCLI(name, displayName, description string) *Cli

QuickCLI 快速创建基础CLI应用

func QuickService added in v0.1.9 

func QuickService(name, displayName string, run RunFunc) *Cli

QuickService 快速创建服务应用（新签名）

func QuickServiceWithStop added in v0.1.9 

func QuickServiceWithStop(name, displayName string, run RunFunc, stop StopFunc) *Cli

QuickServiceWithStop 快速创建带停止函数的服务应用

func (*Cli) AddCommand added in v0.1.6 

func (c *Cli) AddCommand(cmds ...*Command)

AddCommand 添加一个或多个子命令到当前命令

func (*Cli) AddGroup added in v0.1.6 

func (c *Cli) AddGroup(groups ...*Group)

AddGroup 添加一个或多个命令组到当前命令

func (*Cli) AllChildCommandsHaveGroup added in v0.1.6 

func (c *Cli) AllChildCommandsHaveGroup() bool

AllChildCommandsHaveGroup 检查是否所有子命令都已分配到命令组中

func (*Cli) ArgsLenAtDash added in v0.1.6 

func (c *Cli) ArgsLenAtDash() int

ArgsLenAtDash 获取命令行中 "--" 之前的参数数量 用于区分命令参数和传递给外部命令的参数

func (*Cli) CalledAs added in v0.1.6 

func (c *Cli) CalledAs() string

CalledAs 返回命令在命令行中被调用时使用的名称 可能是命令的名称或别名

func (*Cli) Command added in v0.2.0 

func (c *Cli) Command() *cobra.Command

Command 返回底层的 cobra.Command 指针 用于需要直接操作 Cobra 原生 API 的高级场景

示例： 

cmd := app.Command()
cmd.AddCommand(customCmd)
cmd.PreRun = func(cmd *cobra.Command, args []string) {
    // 自定义预运行逻辑
}

func (*Cli) CommandPath added in v0.1.6 

func (c *Cli) CommandPath() string

CommandPath 返回从根命令到当前命令的完整路径

func (*Cli) CommandPathPadding added in v0.1.6 

func (c *Cli) CommandPathPadding() int

CommandPathPadding 返回命令路径的填充长度 用于格式化输出时对齐

func (*Cli) Commands added in v0.1.6 

func (c *Cli) Commands() []*Command

Commands 返回当前命令的所有直接子命令

func (*Cli) Config added in v0.2.0 

func (c *Cli) Config() Config

Config 返回配置的副本（用于调试） 注意：返回的是副本，修改不会影响原配置

func (*Cli) ContainsGroup added in v0.1.6 

func (c *Cli) ContainsGroup(groupID string) bool

ContainsGroup 检查是否包含指定ID的命令组

func (*Cli) Context added in v0.1.6 

func (c *Cli) Context() context.Context

Context 返回命令的上下文 如果未设置，则返回 background context

func (*Cli) Done added in v0.1.9 

func (c *Cli) Done() <-chan struct{}

Done 返回一个通道，当服务应该停止时会关闭 这为用户提供了优雅处理服务生命周期的方式

func (*Cli) Execute added in v0.1.6 

func (c *Cli) Execute() error

Execute 执行命令，这是启动应用程序的主要入口点

func (*Cli) ExecuteC added in v0.1.6 

func (c *Cli) ExecuteC() (*Command, error)

ExecuteC 执行命令并返回选中的命令 主要用于需要访问选中命令的场景

func (*Cli) ExecuteContext added in v0.1.6 

func (c *Cli) ExecuteContext(ctx context.Context) error

ExecuteContext 在指定的上下文中执行命令 可用于传递取消信号或超时控制

func (*Cli) ExecuteContextC added in v0.1.6 

func (c *Cli) ExecuteContextC(ctx context.Context) (*Command, error)

ExecuteContextC 在指定上下文中执行命令并返回选中的命令

func (*Cli) ExportFlagsForViper added in v0.1.9 

func (c *Cli) ExportFlagsForViper(excludeFlags ...string) []*FlagSet

ExportFlagsForViper 导出适用于 Viper 绑定的标志集合 这是一个便捷方法，返回可以直接用于 WithBindPFlags 的标志数组

func (*Cli) Flag added in v0.1.6 

func (c *Cli) Flag(name string) *Flag

Flag 获取指定名称的命令行标志

func (*Cli) FlagErrorFunc added in v0.1.6 

func (c *Cli) FlagErrorFunc() func(*Command, error) error

FlagErrorFunc 返回处理标志错误的函数

func (*Cli) Flags added in v0.1.6 

func (c *Cli) Flags() *FlagSet

Flags 返回命令的本地标志集

func (*Cli) GenBashCompletion added in v0.1.6 

func (c *Cli) GenBashCompletion(w io.Writer) error

GenBashCompletion 生成 Bash 补全脚本并写入指定的 Writer

func (*Cli) GenBashCompletionFile added in v0.1.6 

func (c *Cli) GenBashCompletionFile(filename string) error

GenBashCompletionFile 生成 Bash 补全脚本并保存到指定文件

func (*Cli) GenBashCompletionFileV2 added in v0.1.6 

func (c *Cli) GenBashCompletionFileV2(filename string, includeDesc bool) error

GenBashCompletionFileV2 生成新版本的 Bash 补全脚本并保存到文件 includeDesc 参数控制是否包含描述信息

func (*Cli) GenBashCompletionV2 added in v0.1.6 

func (c *Cli) GenBashCompletionV2(w io.Writer, includeDesc bool) error

GenBashCompletionV2 生成新版本的 Bash 补全脚本并写入 Writer

func (*Cli) GenFishCompletion added in v0.1.6 

func (c *Cli) GenFishCompletion(w io.Writer, includeDesc bool) error

GenFishCompletion 生成 Fish shell 补全脚本并写入 Writer

func (*Cli) GenFishCompletionFile added in v0.1.6 

func (c *Cli) GenFishCompletionFile(filename string, includeDesc bool) error

GenFishCompletionFile 生成 Fish shell 补全脚本并保存到文件

func (*Cli) GenPowerShellCompletion added in v0.1.6 

func (c *Cli) GenPowerShellCompletion(w io.Writer) error

GenPowerShellCompletion 生成 PowerShell 补全脚本并写入 Writer

func (*Cli) GenPowerShellCompletionFile added in v0.1.6 

func (c *Cli) GenPowerShellCompletionFile(filename string) error

GenPowerShellCompletionFile 生成 PowerShell 补全脚本并保存到文件

func (*Cli) GenPowerShellCompletionFileWithDesc added in v0.1.6 

func (c *Cli) GenPowerShellCompletionFileWithDesc(filename string) error

GenPowerShellCompletionFileWithDesc 生成包含描述的 PowerShell 补全脚本并保存到文件

func (*Cli) GenPowerShellCompletionWithDesc added in v0.1.6 

func (c *Cli) GenPowerShellCompletionWithDesc(w io.Writer) error

GenPowerShellCompletionWithDesc 生成包含描述的 PowerShell 补全脚本并写入 Writer

func (*Cli) GenZshCompletion added in v0.1.6 

func (c *Cli) GenZshCompletion(w io.Writer) error

GenZshCompletion 生成 Zsh 补全脚本并写入 Writer

func (*Cli) GenZshCompletionFile added in v0.1.6 

func (c *Cli) GenZshCompletionFile(filename string) error

GenZshCompletionFile 生成 Zsh 补全脚本并保存到文件

func (*Cli) GenZshCompletionFileNoDesc added in v0.1.6 

func (c *Cli) GenZshCompletionFileNoDesc(filename string) error

GenZshCompletionFileNoDesc 生成不包含描述的 Zsh 补全脚本并保存到文件

func (*Cli) GenZshCompletionNoDesc added in v0.1.6 

func (c *Cli) GenZshCompletionNoDesc(w io.Writer) error

GenZshCompletionNoDesc 生成不包含描述的 Zsh 补全脚本并写入 Writer

func (*Cli) GetAllFlagSets added in v0.1.9 

func (c *Cli) GetAllFlagSets() []*FlagSet

GetAllFlagSets 返回所有标志集合的切片，便于传递给外部包 返回顺序：[本地标志, 持久标志, 继承标志]

func (*Cli) GetBindableFlagSets added in v0.1.9 

func (c *Cli) GetBindableFlagSets(excludeFlags ...string) []*FlagSet

GetBindableFlagSets 返回适用于绑定的标志集合，自动排除常见的系统标志 excludeFlags: 额外需要排除的标志名称

func (*Cli) GetFilteredFlagNames added in v0.1.9 

func (c *Cli) GetFilteredFlagNames(excludeFlags ...string) []string

GetFilteredFlagNames 返回过滤后的标志名称列表

func (*Cli) GetFilteredFlags added in v0.1.9 

func (c *Cli) GetFilteredFlags(excludeFlags ...string) *FlagSet

GetFilteredFlags 返回过滤后的单个标志集合，包含所有非排除的标志

func (*Cli) GetFlagNames added in v0.1.9 

func (c *Cli) GetFlagNames(includeInherited bool) []string

GetFlagNames 返回所有标志的名称列表

func (*Cli) GetSystemFlags added in v0.1.9 

func (c *Cli) GetSystemFlags() []string

GetSystemFlags 返回当前被排除的系统标志列表（调试用）

func (*Cli) GlobalNormalizationFunc added in v0.1.6 

func (c *Cli) GlobalNormalizationFunc() func(f *FlagSet, name string) NormalizedName

GlobalNormalizationFunc 返回全局标志名称规范化函数

func (*Cli) Groups added in v0.1.6 

func (c *Cli) Groups() []*Group

Groups 返回命令的所有组

func (*Cli) HasAlias added in v0.1.6 

func (c *Cli) HasAlias(s string) bool

HasAlias 检查是否存在指定的别名

func (*Cli) HasAvailableFlags added in v0.1.6 

func (c *Cli) HasAvailableFlags() bool

HasAvailableFlags 检查命令是否有可用的标志

func (*Cli) HasAvailableInheritedFlags added in v0.1.6 

func (c *Cli) HasAvailableInheritedFlags() bool

HasAvailableInheritedFlags 检查命令是否有可用的继承标志

func (*Cli) HasAvailableLocalFlags added in v0.1.6 

func (c *Cli) HasAvailableLocalFlags() bool

HasAvailableLocalFlags 检查命令是否有可用的本地标志

func (*Cli) HasAvailablePersistentFlags added in v0.1.6 

func (c *Cli) HasAvailablePersistentFlags() bool

HasAvailablePersistentFlags 检查命令是否有可用的持久标志

func (*Cli) HasAvailableSubCommands added in v0.1.6 

func (c *Cli) HasAvailableSubCommands() bool

HasAvailableSubCommands 检查是否有可用的子命令

func (*Cli) HasExample added in v0.1.6 

func (c *Cli) HasExample() bool

HasExample 检查是否有示例

func (*Cli) HasFlags added in v0.1.6 

func (c *Cli) HasFlags() bool

HasFlags 检查命令是否定义了任何标志

func (*Cli) HasHelpSubCommands added in v0.1.6 

func (c *Cli) HasHelpSubCommands() bool

HasHelpSubCommands 检查是否有帮助子命令

func (*Cli) HasInheritedFlags added in v0.1.6 

func (c *Cli) HasInheritedFlags() bool

HasInheritedFlags 检查命令是否有继承的标志

func (*Cli) HasLocalFlags added in v0.1.6 

func (c *Cli) HasLocalFlags() bool

HasLocalFlags 检查命令是否有本地标志

func (*Cli) HasParent added in v0.1.6 

func (c *Cli) HasParent() bool

HasParent 检查是否有父命令

func (*Cli) HasPersistentFlags added in v0.1.6 

func (c *Cli) HasPersistentFlags() bool

HasPersistentFlags 检查命令是否有持久标志

func (*Cli) HasSubCommands added in v0.1.6 

func (c *Cli) HasSubCommands() bool

HasSubCommands 检查是否有子命令

func (*Cli) Help added in v0.1.6 

func (c *Cli) Help() error

Help 显示帮助信息

func (*Cli) HelpFunc added in v0.1.6 

func (c *Cli) HelpFunc() func(*Command, []string)

HelpFunc 返回帮助函数

func (*Cli) HelpTemplate added in v0.1.6 

func (c *Cli) HelpTemplate() string

HelpTemplate 返回帮助信息模板

func (*Cli) InOrStdin added in v0.1.6 

func (c *Cli) InOrStdin() io.Reader

InOrStdin 返回命令的输入流，默认为标准输入

func (*Cli) InheritedFlags added in v0.1.6 

func (c *Cli) InheritedFlags() *FlagSet

InheritedFlags 返回命令的继承标志集

func (*Cli) InitDefaultCompletionCmd added in v0.1.6 

func (c *Cli) InitDefaultCompletionCmd()

InitDefaultCompletionCmd 初始化默认的补全命令

func (*Cli) InitDefaultHelpCmd added in v0.1.6 

func (c *Cli) InitDefaultHelpCmd()

InitDefaultHelpCmd 初始化默认的帮助命令

func (*Cli) InitDefaultHelpFlag added in v0.1.6 

func (c *Cli) InitDefaultHelpFlag()

InitDefaultHelpFlag 初始化默认的帮助标志

func (*Cli) InitDefaultVersionFlag added in v0.1.6 

func (c *Cli) InitDefaultVersionFlag()

InitDefaultVersionFlag 初始化默认的版本标志

func (*Cli) IsAdditionalHelpTopicCommand added in v0.1.6 

func (c *Cli) IsAdditionalHelpTopicCommand() bool

IsAdditionalHelpTopicCommand 检查是否是额外的帮助主题命令

func (*Cli) IsAvailableCommand added in v0.1.6 

func (c *Cli) IsAvailableCommand() bool

IsAvailableCommand 检查命令是否可用

func (*Cli) IsSystemFlag added in v0.1.9 

func (c *Cli) IsSystemFlag(flagName string) bool

IsSystemFlag 检查指定标志是否为系统标志

func (*Cli) LocalFlags added in v0.1.6 

func (c *Cli) LocalFlags() *FlagSet

LocalFlags 返回命令的本地标志集

func (*Cli) LocalNonPersistentFlags added in v0.1.6 

func (c *Cli) LocalNonPersistentFlags() *FlagSet

LocalNonPersistentFlags 返回命令的非持久本地标志集

func (*Cli) MarkFlagCustom added in v0.1.6 

func (c *Cli) MarkFlagCustom(name string, f string) error

MarkFlagCustom 为指定标志添加自定义补全函数

func (*Cli) MarkFlagDirname added in v0.1.6 

func (c *Cli) MarkFlagDirname(name string) error

MarkFlagDirname 标记指定标志接受目录名作为参数

func (*Cli) MarkFlagFilename added in v0.1.6 

func (c *Cli) MarkFlagFilename(name string, extensions ...string) error

MarkFlagFilename 标记指定标志接受文件名作为参数

func (*Cli) MarkFlagRequired added in v0.1.6 

func (c *Cli) MarkFlagRequired(name string) error

MarkFlagRequired 标记指定标志为必需

func (*Cli) MarkFlagsMutuallyExclusive added in v0.1.6 

func (c *Cli) MarkFlagsMutuallyExclusive(flagNames ...string)

MarkFlagsMutuallyExclusive 标记多个标志互斥

func (*Cli) MarkFlagsOneRequired added in v0.1.6 

func (c *Cli) MarkFlagsOneRequired(flagNames ...string)

MarkFlagsOneRequired 标记多个标志中必须指定一个

func (*Cli) MarkFlagsRequiredTogether added in v0.1.6 

func (c *Cli) MarkFlagsRequiredTogether(flagNames ...string)

MarkFlagsRequiredTogether 标记多个标志必须同时使用

func (*Cli) MarkPersistentFlagDirname added in v0.1.6 

func (c *Cli) MarkPersistentFlagDirname(name string) error

MarkPersistentFlagDirname 标记指定的持久标志接受目录名作为参数

func (*Cli) MarkPersistentFlagFilename added in v0.1.6 

func (c *Cli) MarkPersistentFlagFilename(name string, extensions ...string) error

MarkPersistentFlagFilename 标记指定的持久标志接受文件名作为参数

func (*Cli) MarkPersistentFlagRequired added in v0.1.6 

func (c *Cli) MarkPersistentFlagRequired(name string) error

MarkPersistentFlagRequired 标记指定的持久标志为必需

func (*Cli) MarkZshCompPositionalArgumentFile added in v0.1.6 

func (c *Cli) MarkZshCompPositionalArgumentFile(argPosition int, patterns ...string) error

MarkZshCompPositionalArgumentFile 标记 Zsh 位置参数接受文件

func (*Cli) MarkZshCompPositionalArgumentWords added in v0.1.6 

func (c *Cli) MarkZshCompPositionalArgumentWords(argPosition int, words ...string) error

MarkZshCompPositionalArgumentWords 标记 Zsh 位置参数接受指定的词列表

func (*Cli) Name added in v0.1.6 

func (c *Cli) Name() string

Name 返回命令名称

func (*Cli) NameAndAliases added in v0.1.6 

func (c *Cli) NameAndAliases() string

NameAndAliases 返回命令名称及其所有别名

func (*Cli) NamePadding added in v0.1.6 

func (c *Cli) NamePadding() int

NamePadding 返回名称的填充长度

func (*Cli) NonInheritedFlags added in v0.1.6 

func (c *Cli) NonInheritedFlags() *FlagSet

NonInheritedFlags 返回命令的非继承标志集

func (*Cli) OutOrStderr added in v0.1.6 

func (c *Cli) OutOrStderr() io.Writer

OutOrStderr 返回命令的错误输出流，默认为标准错误

func (*Cli) OutOrStdout added in v0.1.6 

func (c *Cli) OutOrStdout() io.Writer

OutOrStdout 返回命令的标准输出流，默认为标准输出

func (*Cli) Parent added in v0.1.6 

func (c *Cli) Parent() *Command

Parent 返回父命令

func (*Cli) ParseFlags added in v0.1.6 

func (c *Cli) ParseFlags(args []string) error

ParseFlags 解析命令行参数中的标志

func (*Cli) PersistentFlags added in v0.1.6 

func (c *Cli) PersistentFlags() *FlagSet

PersistentFlags 返回命令的持久标志集

func (*Cli) Print added in v0.1.6 

func (c *Cli) Print(i ...interface{})

Print 打印到命令的标准输出

func (*Cli) PrintErr added in v0.1.6 

func (c *Cli) PrintErr(i ...interface{})

PrintErr 打印到命令的错误输出

func (*Cli) PrintErrf added in v0.1.6 

func (c *Cli) PrintErrf(format string, i ...interface{})

PrintErrf 格式化打印到命令的错误输出

func (*Cli) PrintErrln added in v0.1.6 

func (c *Cli) PrintErrln(i ...interface{})

PrintErrln 打印到命令的错误输出并换行

func (*Cli) Printf added in v0.1.6 

func (c *Cli) Printf(format string, i ...interface{})

Printf 格式化打印到命令的标准输出

func (*Cli) Println added in v0.1.6 

func (c *Cli) Println(i ...interface{})

Println 打印到命令的标准输出并换行

func (*Cli) RegisterFlagCompletionFunc added in v0.1.6 

func (c *Cli) RegisterFlagCompletionFunc(flagName string, f func(*Command, []string, string) ([]string, ShellCompDirective)) error

RegisterFlagCompletionFunc 注册标志的补全函数

func (*Cli) RemoveCommand added in v0.1.6 

func (c *Cli) RemoveCommand(cmds ...*Command)

RemoveCommand 移除指定的子命令

func (*Cli) ResetCommands added in v0.1.6 

func (c *Cli) ResetCommands()

ResetCommands 重置所有子命令

func (*Cli) ResetFlags added in v0.1.6 

func (c *Cli) ResetFlags()

ResetFlags 重置所有标志

func (*Cli) Root added in v0.1.6 

func (c *Cli) Root() *Command

Root 返回根命令

func (*Cli) Runnable added in v0.1.6 

func (c *Cli) Runnable() bool

Runnable 检查命令是否可运行

func (*Cli) SetArgs added in v0.1.6 

func (c *Cli) SetArgs(a []string)

SetArgs 设置命令的参数

func (*Cli) SetCompletionCommandGroupID added in v0.1.6 

func (c *Cli) SetCompletionCommandGroupID(groupID string)

SetCompletionCommandGroupID 设置补全命令的组ID

func (*Cli) SetContext added in v0.1.6 

func (c *Cli) SetContext(ctx context.Context)

SetContext 设置命令的上下文

func (*Cli) SetErr added in v0.1.6 

func (c *Cli) SetErr(newErr io.Writer)

SetErr 设置命令的错误输出流

func (*Cli) SetErrPrefix added in v0.1.6 

func (c *Cli) SetErrPrefix(s string)

SetErrPrefix 设置错误消息的前缀

func (*Cli) SetFlagErrorFunc added in v0.1.6 

func (c *Cli) SetFlagErrorFunc(f func(*Command, error) error)

SetFlagErrorFunc 设置处理标志错误的自定义函数

func (*Cli) SetGlobalNormalizationFunc added in v0.1.6 

func (c *Cli) SetGlobalNormalizationFunc(n func(f *FlagSet, name string) NormalizedName)

SetGlobalNormalizationFunc 设置全局标志名称规范化函数

func (*Cli) SetHelpCommand added in v0.1.6 

func (c *Cli) SetHelpCommand(cmd *Command)

SetHelpCommand 设置自定义的帮助命令

func (*Cli) SetHelpCommandGroupID added in v0.1.6 

func (c *Cli) SetHelpCommandGroupID(groupID string)

SetHelpCommandGroupID 设置帮助命令的组ID

func (*Cli) SetHelpFunc added in v0.1.6 

func (c *Cli) SetHelpFunc(f func(*Command, []string))

SetHelpFunc 设置自定义的帮助函数

func (*Cli) SetHelpTemplate added in v0.1.6 

func (c *Cli) SetHelpTemplate(s string)

SetHelpTemplate 设置帮助信息的模板

func (*Cli) SetIn added in v0.1.6 

func (c *Cli) SetIn(newIn io.Reader)

SetIn 设置命令的输入流

func (*Cli) SetOut added in v0.1.6 

func (c *Cli) SetOut(newOut io.Writer)

SetOut 设置命令的标准输出流

func (*Cli) SetOutput deprecated added in v0.1.6 

func (c *Cli) SetOutput(output io.Writer)

SetOutput 设置命令的输出流（同时影响标准输出和错误输出）

Deprecated: Use SetOut and/or SetErr instead

func (*Cli) SetServiceRunning added in v0.1.9 

func (c *Cli) SetServiceRunning(running bool)

SetServiceRunning 设置服务运行状态（内部使用） 用于在服务启动时传递正确的上下文

func (*Cli) SetUsageFunc added in v0.1.6 

func (c *Cli) SetUsageFunc(f func(*Command) error)

SetUsageFunc 设置自定义的使用说明函数

func (*Cli) SetUsageTemplate added in v0.1.6 

func (c *Cli) SetUsageTemplate(s string)

SetUsageTemplate 设置使用说明的模板

func (*Cli) SetVersionTemplate added in v0.1.6 

func (c *Cli) SetVersionTemplate(s string)

SetVersionTemplate 设置版本信息的模板

func (*Cli) SuggestionsFor added in v0.1.6 

func (c *Cli) SuggestionsFor(typedName string) []string

SuggestionsFor 返回针对给定输入的建议

func (*Cli) Traverse added in v0.1.6 

func (c *Cli) Traverse(args []string) (*Command, []string, error)

Traverse 遍历命令树查找匹配的命令

func (*Cli) Usage added in v0.1.6 

func (c *Cli) Usage() error

Usage 显示使用说明

func (*Cli) UsageFunc added in v0.1.6 

func (c *Cli) UsageFunc() func(*Command) error

UsageFunc 返回使用说明函数

func (*Cli) UsagePadding added in v0.1.6 

func (c *Cli) UsagePadding() int

UsagePadding 返回使用说明的填充长度

func (*Cli) UsageString added in v0.1.6 

func (c *Cli) UsageString() string

UsageString 返回使用说明字符串

func (*Cli) UsageTemplate added in v0.1.6 

func (c *Cli) UsageTemplate() string

UsageTemplate 返回使用说明模板

func (*Cli) UseLine added in v0.1.6 

func (c *Cli) UseLine() string

UseLine 返回命令的使用行

func (*Cli) ValidateArgs added in v0.1.6 

func (c *Cli) ValidateArgs(args []string) error

ValidateArgs 验证命令参数

func (*Cli) ValidateFlagGroups added in v0.1.6 

func (c *Cli) ValidateFlagGroups() error

ValidateFlagGroups 验证标志组

func (*Cli) ValidateRequiredFlags added in v0.1.6 

func (c *Cli) ValidateRequiredFlags() error

ValidateRequiredFlags 验证必需的标志

func (*Cli) VersionTemplate added in v0.1.6 

func (c *Cli) VersionTemplate() string

VersionTemplate 返回版本信息模板

func (*Cli) VisitParents added in v0.1.6 

func (c *Cli) VisitParents(fn func(*Command))

VisitParents 访问所有父命令

type Command added in v0.1.6 

type Command = cobra.Command

type CommandUI added in v0.1.9 

type CommandUI struct {
	Usage             string // 用法
	Options           string // 选项
	Examples          string // 示例
	Flags             string // 参数
	AvailableCommands string // 可用命令
	SystemCommands    string // 系统命令
	DefaultValue      string // 默认值格式: "(default: %s)"
}

CommandUI 命令界面相关文本

type CompletionOptions added in v0.1.6 

type CompletionOptions = cobra.CompletionOptions

type Config 

type Config struct {
	// contains filtered or unexported fields
}

Config 统一配置结构 字段已私有化，通过 getter 方法访问以防止外部直接修改

func NewConfig added in v0.1.6 

func NewConfig() *Config

NewConfig 创建默认配置

func (*Config) Basic added in v0.1.6 

func (c *Config) Basic() Basic

Basic 返回基础配置的副本，防止外部修改

func (*Config) Context added in v0.2.0 

func (c *Config) Context() context.Context

Context 返回配置的上下文

func (*Config) Runtime 

func (c *Config) Runtime() Runtime

Runtime 返回运行时配置的副本

func (*Config) Service added in v0.1.6 

func (c *Config) Service() ServiceConfig

Service 返回服务配置的深拷贝，防止外部通过切片/map 修改内部状态

type DefaultServiceFactory added in v0.1.9 

type DefaultServiceFactory struct{}

DefaultServiceFactory 默认服务工厂

func (*DefaultServiceFactory) CreateService added in v0.1.9 

func (dsf *DefaultServiceFactory) CreateService(config ServiceConfig) (ServiceRunner, error)

CreateService 创建默认服务

type ErrorAggregator added in v0.1.9 

type ErrorAggregator struct {
	// contains filtered or unexported fields
}

ErrorAggregator 错误聚合器

func NewErrorAggregator added in v0.1.9 

func NewErrorAggregator() *ErrorAggregator

NewErrorAggregator 创建错误聚合器

func (*ErrorAggregator) Add added in v0.1.9 

func (ea *ErrorAggregator) Add(err error)

Add 添加错误

func (*ErrorAggregator) Clear added in v0.1.9 

func (ea *ErrorAggregator) Clear()

Clear 清除所有错误

func (*ErrorAggregator) Count added in v0.1.9 

func (ea *ErrorAggregator) Count() int

Count 返回错误数量

func (*ErrorAggregator) Error added in v0.1.9 

func (ea *ErrorAggregator) Error() string

Error 返回聚合错误信息

func (*ErrorAggregator) Errors added in v0.1.9 

func (ea *ErrorAggregator) Errors() []error

Errors 返回所有错误

func (*ErrorAggregator) HasErrors added in v0.1.9 

func (ea *ErrorAggregator) HasErrors() bool

HasErrors 检查是否有错误

type ErrorBuilder added in v0.1.9 

type ErrorBuilder struct {
	// contains filtered or unexported fields
}

ErrorBuilder 错误构建器

func NewError added in v0.1.9 

func NewError(code ErrorCode) *ErrorBuilder

NewError 创建新的错误构建器

func (*ErrorBuilder) Build added in v0.1.9 

func (eb *ErrorBuilder) Build() *ServiceError

Build 构建错误

func (*ErrorBuilder) Cause added in v0.1.9 

func (eb *ErrorBuilder) Cause(cause error) *ErrorBuilder

Cause 设置原因错误

func (*ErrorBuilder) Context added in v0.1.9 

func (eb *ErrorBuilder) Context(key string, value any) *ErrorBuilder

Context 添加上下文信息

func (*ErrorBuilder) Message added in v0.1.9 

func (eb *ErrorBuilder) Message(message string) *ErrorBuilder

Message 设置错误消息

func (*ErrorBuilder) Messagef added in v0.1.9 

func (eb *ErrorBuilder) Messagef(format string, args ...any) *ErrorBuilder

Messagef 设置格式化错误消息

func (*ErrorBuilder) Operation added in v0.1.9 

func (eb *ErrorBuilder) Operation(operation string) *ErrorBuilder

Operation 设置操作名称

func (*ErrorBuilder) Service added in v0.1.9 

func (eb *ErrorBuilder) Service(service string) *ErrorBuilder

Service 设置服务名称

func (*ErrorBuilder) Stack added in v0.1.9 

func (eb *ErrorBuilder) Stack(stack []string) *ErrorBuilder

Stack 添加堆栈信息

type ErrorCode added in v0.1.9 

type ErrorCode string

ErrorCode 错误代码类型 

const (
	// 配置相关错误
	ErrConfigValidation ErrorCode = "CONFIG_VALIDATION"
	ErrConfigMissing    ErrorCode = "CONFIG_MISSING"
	ErrConfigInvalid    ErrorCode = "CONFIG_INVALID"

	// 服务相关错误
	ErrServiceCreate   ErrorCode = "SERVICE_CREATE"
	ErrServiceStart    ErrorCode = "SERVICE_START"
	ErrServiceStop     ErrorCode = "SERVICE_STOP"
	ErrServiceRestart  ErrorCode = "SERVICE_RESTART"
	ErrServiceNotFound ErrorCode = "SERVICE_NOT_FOUND"
	ErrServiceRunning  ErrorCode = "SERVICE_ALREADY_RUNNING"
	ErrServiceStopped  ErrorCode = "SERVICE_ALREADY_STOPPED"
	ErrServiceTimeout  ErrorCode = "SERVICE_TIMEOUT"

	// 系统相关错误
	ErrPermission        ErrorCode = "PERMISSION_DENIED"
	ErrPathNotFound      ErrorCode = "PATH_NOT_FOUND"
	ErrPathInvalid       ErrorCode = "PATH_INVALID"
	ErrExecutableInvalid ErrorCode = "EXECUTABLE_INVALID"

	// 运行时错误
	ErrRuntime          ErrorCode = "RUNTIME_ERROR"
	ErrContextCancelled ErrorCode = "CONTEXT_CANCELLED"
	ErrTimeout          ErrorCode = "TIMEOUT"

	// 网络和通信错误
	ErrNetwork    ErrorCode = "NETWORK_ERROR"
	ErrConnection ErrorCode = "CONNECTION_ERROR"
)

type ErrorDomain added in v0.1.9 

type ErrorDomain struct {
	Prefix  string        // 错误前缀
	Service ServiceErrors // 服务错误
	System  SystemErrors  // 系统错误
	Help    HelpErrors    // 帮助错误
}

ErrorDomain 错误域 - 集中管理所有错误信息

type ErrorHandler added in v0.1.9 

type ErrorHandler interface {
	HandleError(err error) error
}

ErrorHandler 错误处理器接口

type FParseErrWhitelist added in v0.1.6 

type FParseErrWhitelist = cobra.FParseErrWhitelist

type Flag added in v0.1.6 

type Flag = pflag.Flag

type FlagSet added in v0.1.6 

type FlagSet = pflag.FlagSet

type FormatDomain added in v0.1.9 

type FormatDomain struct {
	ServiceStatus    string // "Service %s: %s"
	ErrorWithDetail  string // "Error: %s"
	TimeoutMessage   string // "Timeout after %d seconds"
	PermissionDenied string // "Required: %v, Current: %v"
	PathError        string // "Path error: %s"
}

FormatDomain 格式化域 - 提供格式化模板

type FuncService added in v0.1.9 

type FuncService struct {
	*BaseService
	// contains filtered or unexported fields
}

FuncService 基于函数的服务实现，用于简单场景

func NewFuncService added in v0.1.9 

func NewFuncService(config ServiceConfig, runFunc func(context.Context) error, stopFunc func() error) (*FuncService, error)

NewFuncService 创建函数式服务

func (*FuncService) Run added in v0.1.9 

func (fs *FuncService) Run(ctx context.Context) error

Run 运行服务

type FuncServiceFactory added in v0.1.9 

type FuncServiceFactory struct {
	// contains filtered or unexported fields
}

FuncServiceFactory 函数式服务工厂

func NewFuncServiceFactory added in v0.1.9 

func NewFuncServiceFactory(runFunc func(context.Context) error, stopFunc func() error) *FuncServiceFactory

NewFuncServiceFactory 创建函数式服务工厂

func (*FuncServiceFactory) CreateService added in v0.1.9 

func (fsf *FuncServiceFactory) CreateService(config ServiceConfig) (ServiceRunner, error)

CreateService 创建函数式服务

type Group added in v0.1.6 

type Group = cobra.Group

type HelpErrors added in v0.1.9 

type HelpErrors struct {
	UnknownTopic string // 未知帮助主题
}

HelpErrors 帮助相关错误

type HelpUI added in v0.1.9 

type HelpUI struct {
	Command     string // 帮助命令
	Description string // 帮助描述
	Usage       string // 帮助使用说明格式: "Use '%s [command] --help' for more information"
}

HelpUI 帮助界面相关文本

type Language added in v0.1.6 

type Language struct {
	Code    string        // 语言代码 (如: "zh", "en")
	Name    string        // 语言名称 (如: "中文", "English")
	Service ServiceDomain // 服务域
	UI      UIDomain      // 界面域
	Error   ErrorDomain   // 错误域
	Format  FormatDomain  // 格式化域
}

Language 新的层次化语言包结构

type LanguageManager added in v0.1.9 

type LanguageManager struct {
	// contains filtered or unexported fields
}

LanguageManager 智能语言包管理器

func GetLanguageManager added in v0.1.9 

func GetLanguageManager() *LanguageManager

GetLanguageManager 获取全局语言包管理器

func NewLanguageManager added in v0.1.9 

func NewLanguageManager(primaryLang string) *LanguageManager

NewLanguageManager 创建语言包管理器

func (*LanguageManager) GetPrimary added in v0.1.9 

func (lm *LanguageManager) GetPrimary() *Language

GetPrimary 获取主要语言包

func (*LanguageManager) GetText added in v0.1.9 

func (lm *LanguageManager) GetText(path string) string

GetText 智能获取文本，支持回退机制

func (*LanguageManager) RegisterLanguage added in v0.1.9 

func (lm *LanguageManager) RegisterLanguage(lang *Language) error

RegisterLanguage 注册新的语言包

func (*LanguageManager) SetPrimary added in v0.1.9 

func (lm *LanguageManager) SetPrimary(langCode string) error

SetPrimary 设置主要语言

type Logger added in v0.1.9 

type Logger interface {
	Error(msg string, fields ...any)
	Warn(msg string, fields ...any)
	Info(msg string, fields ...any)
}

Logger 日志接口

type LoggingErrorHandler added in v0.1.9 

type LoggingErrorHandler struct {
	// contains filtered or unexported fields
}

LoggingErrorHandler 日志记录错误处理器

func NewLoggingErrorHandler added in v0.1.9 

func NewLoggingErrorHandler(logger Logger) *LoggingErrorHandler

NewLoggingErrorHandler 创建日志错误处理器

func (*LoggingErrorHandler) HandleError added in v0.1.9 

func (leh *LoggingErrorHandler) HandleError(err error) error

HandleError 处理错误

type ManagedService added in v0.1.9 

type ManagedService struct {
	ServiceRunner
	// contains filtered or unexported fields
}

ManagedService 带生命周期管理的服务

func NewManagedService added in v0.1.9 

func NewManagedService(runner ServiceRunner, lifecycle ServiceLifecycle) *ManagedService

NewManagedService 创建带生命周期管理的服务

func (*ManagedService) Run added in v0.1.9 

func (ms *ManagedService) Run(ctx context.Context) error

Run 运行带生命周期管理的服务

type NormalizedName added in v0.1.6 

type NormalizedName = pflag.NormalizedName

type Option added in v0.1.6 

type Option func(*Config)

Option CLI 选项函数

func WithConfig added in v0.1.6 

func WithConfig(cfg *Config) Option

WithConfig 创建配置选项（深拷贝传入的配置）

type PositionalArgs added in v0.1.6 

type PositionalArgs = cobra.PositionalArgs

type RecoveryErrorHandler added in v0.1.9 

type RecoveryErrorHandler struct {
	// contains filtered or unexported fields
}

RecoveryErrorHandler 恢复错误处理器

func NewRecoveryErrorHandler added in v0.1.9 

func NewRecoveryErrorHandler(retryCount int, retryDelay time.Duration) *RecoveryErrorHandler

NewRecoveryErrorHandler 创建恢复错误处理器

func (*RecoveryErrorHandler) HandleError added in v0.1.9 

func (reh *RecoveryErrorHandler) HandleError(err error) error

HandleError 处理错误并尝试恢复

type RunFunc added in v0.2.0 

type RunFunc func(ctx context.Context) error

RunFunc 服务运行函数签名 标准 Go 惯例：接收 context 用于优雅关闭，返回 error 用于错误处理

type Runtime added in v0.1.6 

type Runtime struct {
	Run       RunFunc      // 启动函数，标准签名：func(ctx context.Context) error
	Stop      StopFunc     // 停止函数，标准签名：func() error
	BuildInfo *VersionInfo // 构建信息

	// ShutdownInitial 优雅退出的初次等待时长，默认 3s
	ShutdownInitial time.Duration
	// ShutdownGrace 在调用停止函数后的额外等待时长，默认 2s
	ShutdownGrace time.Duration
}

Runtime 运行时配置

type ServiceConfig added in v0.1.9 

type ServiceConfig struct {
	Name         string            `validate:"required,min=3,max=50"`
	DisplayName  string            `validate:"required,max=100"`
	Description  string            `validate:"max=500"`
	Version      string            `validate:"semver"`
	WorkDir      string            `validate:"dir_path"`
	Username     string            `validate:"username"`
	Dependencies []string          `validate:"dive,required"`
	EnvVars      map[string]string `validate:"dive,keys,required,endkeys,required"`
	Arguments    []string
	Executable   string
	ChRoot       string
	Options      map[string]interface{}
}

ServiceConfig 服务配置结构，提供完整的类型安全

func (*ServiceConfig) Validate added in v0.1.9 

func (sc *ServiceConfig) Validate() error

Validate 验证配置的有效性

type ServiceDomain added in v0.1.9 

type ServiceDomain struct {
	Operations ServiceOperations // 服务操作
	Status     ServiceStatus     // 服务状态
	Messages   ServiceMessages   // 服务消息
}

ServiceDomain 服务域 - 专注于服务相关的所有文本

type ServiceError added in v0.1.9 

type ServiceError struct {
	Code      ErrorCode      `json:"code"`
	Operation string         `json:"operation"`
	Service   string         `json:"service"`
	Message   string         `json:"message"`
	Cause     error          `json:"cause,omitempty"`
	Context   map[string]any `json:"context,omitempty"`
	Timestamp time.Time      `json:"timestamp"`
	Stack     []string       `json:"stack,omitempty"`
}

ServiceError 增强的服务错误类型

func ErrConfigValidationFailed added in v0.1.9 

func ErrConfigValidationFailed(details []error) *ServiceError

ErrConfigValidationFailed configuration validation failed错误

func ErrPathNotExists added in v0.1.9 

func ErrPathNotExists(path string) *ServiceError

ErrPathNotExists 路径不存在错误

func ErrPermissionDenied added in v0.1.9 

func ErrPermissionDenied(path string, required, current string) *ServiceError

ErrPermissionDenied 权限被拒绝错误

func ErrServiceAlreadyRunning added in v0.1.9 

func ErrServiceAlreadyRunning(service string) *ServiceError

ErrServiceAlreadyRunning 服务已在运行错误

func ErrServiceAlreadyStopped added in v0.1.9 

func ErrServiceAlreadyStopped(service string) *ServiceError

ErrServiceAlreadyStopped service already stopped错误

func ErrServiceNotInstalled added in v0.1.9 

func ErrServiceNotInstalled(service string) *ServiceError

ErrServiceNotInstalled service is not installed错误

func ErrServiceStartTimeout added in v0.1.9 

func ErrServiceStartTimeout(service string, timeout time.Duration) *ServiceError

ErrServiceStartTimeout 服务启动超时错误

func ErrServiceStopTimeout added in v0.1.9 

func ErrServiceStopTimeout(service string, timeout time.Duration) *ServiceError

ErrServiceStopTimeout 服务停止超时错误

func GetServiceError added in v0.1.9 

func GetServiceError(err error) (*ServiceError, bool)

GetServiceError 获取服务错误

func NewServiceError added in v0.1.9 

func NewServiceError(code ErrorCode, operation, service, message string) *ServiceError

NewServiceError 创建新的服务错误

func WrapError added in v0.1.9 

func WrapError(err error, code ErrorCode, operation string) *ServiceError

WrapError 包装普通错误为服务错误

func (*ServiceError) Error added in v0.1.9 

func (se *ServiceError) Error() string

Error 实现error接口

func (*ServiceError) GetCode added in v0.1.9 

func (se *ServiceError) GetCode() ErrorCode

GetCode 获取错误代码

func (*ServiceError) GetContext added in v0.1.9 

func (se *ServiceError) GetContext() map[string]any

GetContext 获取上下文信息

func (*ServiceError) GetOperation added in v0.1.9 

func (se *ServiceError) GetOperation() string

GetOperation 获取操作名称

func (*ServiceError) GetService added in v0.1.9 

func (se *ServiceError) GetService() string

GetService 获取服务名称

func (*ServiceError) Is added in v0.1.9 

func (se *ServiceError) Is(target error) bool

Is 检查错误类型

func (*ServiceError) ToJSON added in v0.1.9 

func (se *ServiceError) ToJSON() map[string]any

ToJSON 转换为JSON格式

func (*ServiceError) Unwrap added in v0.1.9 

func (se *ServiceError) Unwrap() error

Unwrap 展开错误链

func (*ServiceError) WithCause added in v0.1.9 

func (se *ServiceError) WithCause(cause error) *ServiceError

WithCause 添加原因错误

func (*ServiceError) WithContext added in v0.1.9 

func (se *ServiceError) WithContext(key string, value any) *ServiceError

WithContext 添加上下文信息

func (*ServiceError) WithStack added in v0.1.9 

func (se *ServiceError) WithStack(stack []string) *ServiceError

WithStack 添加堆栈信息

type ServiceErrors added in v0.1.9 

type ServiceErrors struct {
	CreateConfig    string // 创建配置失败
	CreateService   string // 创建服务失败
	GetStatus       string // 获取状态失败
	StartFailed     string // 启动失败
	StopFailed      string // 停止失败
	RestartFailed   string // 重启失败
	InstallFailed   string // 安装失败
	UninstallFailed string // 卸载失败
	RunFailed       string // 运行失败
	NotFound        string // 服务未找到
	AlreadyRunning  string // 服务已在运行
	Timeout         string // 操作超时
	TimeoutWarning  string // 超时警告
	ForceTerminate  string // 强制终止
}

ServiceErrors 服务相关错误

type ServiceFactory added in v0.1.9 

type ServiceFactory interface {
	CreateService(config ServiceConfig) (ServiceRunner, error)
}

ServiceFactory 服务工厂接口

type ServiceLifecycle added in v0.1.9 

type ServiceLifecycle interface {
	// BeforeStart 服务启动前调用
	BeforeStart() error

	// AfterStart 服务启动后调用
	AfterStart() error

	// BeforeStop 服务停止前调用
	BeforeStop() error

	// AfterStop 服务停止后调用
	AfterStop() error
}

ServiceLifecycle 服务生命周期管理接口

type ServiceLocalizer added in v0.1.9 

type ServiceLocalizer struct {
	// contains filtered or unexported fields
}

ServiceLocalizer 服务本地化器，提供便利的API

func NewServiceLocalizer added in v0.1.9 

func NewServiceLocalizer(manager *LanguageManager, colors *colors) *ServiceLocalizer

NewServiceLocalizer 创建服务本地化器

func (*ServiceLocalizer) FormatError added in v0.1.9 

func (sl *ServiceLocalizer) FormatError(errorType string, args ...interface{}) string

FormatError 格式化错误消息

func (*ServiceLocalizer) FormatServiceStatus added in v0.1.9 

func (sl *ServiceLocalizer) FormatServiceStatus(serviceName, status string) string

FormatServiceStatus 格式化服务状态

func (*ServiceLocalizer) GetError added in v0.1.9 

func (sl *ServiceLocalizer) GetError(errorType string) string

GetError 获取错误文本

func (*ServiceLocalizer) GetFormat added in v0.1.9 

func (sl *ServiceLocalizer) GetFormat(formatType string) string

GetFormat 获取格式化模板

func (*ServiceLocalizer) GetOperation added in v0.1.9 

func (sl *ServiceLocalizer) GetOperation(operation string) string

GetOperation 获取操作文本

func (*ServiceLocalizer) GetStatus added in v0.1.9 

func (sl *ServiceLocalizer) GetStatus(status string) string

GetStatus 获取状态文本

func (*ServiceLocalizer) LogError added in v0.1.9 

func (sl *ServiceLocalizer) LogError(errorType string, err error)

LogError 记录错误日志

func (*ServiceLocalizer) LogInfo added in v0.1.9 

func (sl *ServiceLocalizer) LogInfo(serviceName, status string)

LogInfo 记录信息日志

func (*ServiceLocalizer) LogSuccess added in v0.1.9 

func (sl *ServiceLocalizer) LogSuccess(serviceName, operation string)

LogSuccess 记录成功日志

func (*ServiceLocalizer) LogWarning added in v0.1.9 

func (sl *ServiceLocalizer) LogWarning(message string, args ...interface{})

LogWarning 记录警告日志

type ServiceMessages added in v0.1.6 

type ServiceMessages struct {
	Installing     string // 正在安装...
	Uninstalling   string // 正在卸载...
	Starting       string // 正在启动...
	Stopping       string // 正在停止...
	Restarting     string // 正在重启...
	CheckingStatus string // 正在检查状态...
	TimeoutWarning string // 超时警告
	ForceTerminate string // 强制终止
}

ServiceMessages 服务操作过程中的提示消息

type ServiceOperations added in v0.1.9 

type ServiceOperations struct {
	Install   string // 安装
	Uninstall string // 卸载
	Start     string // 启动
	Stop      string // 停止
	Restart   string // 重启
	Run       string // 运行
	Status    string // 查看状态
}

ServiceOperations 服务操作相关文本

type ServiceRunner added in v0.1.9 

type ServiceRunner interface {
	// Run 运行服务主逻辑，接收上下文用于优雅关闭
	Run(ctx context.Context) error

	// Stop 停止服务，执行清理工作
	Stop() error

	// Name 返回服务名称
	Name() string
}

ServiceRunner 定义服务运行接口，提供类型安全的服务管理

func NewSimpleService added in v0.1.9 

func NewSimpleService(name string, runFunc func(context.Context) error, stopFunc func() error) ServiceRunner

NewSimpleService 创建简单服务实现

type ServiceStatus added in v0.1.9 

type ServiceStatus struct {
	Running        string // 正在运行
	Stopped        string // 已停止
	Unknown        string // 未知状态
	NotInstalled   string // 未安装
	AlreadyExists  string // 已存在
	AlreadyRunning string // 已在运行
	AlreadyStopped string // 已停止
	Success        string // 成功
}

ServiceStatus 服务状态相关文本

type ShellCompDirective added in v0.1.6 

type ShellCompDirective = cobra.ShellCompDirective

type StopFunc added in v0.2.0 

type StopFunc func() error

StopFunc 服务停止函数签名 返回 error 用于报告停止过程中的错误

type SystemErrors added in v0.1.9 

type SystemErrors struct {
	PathNotExist      string // 路径不存在
	GetPathInfo       string // 获取路径信息失败
	InsufficientPerm  string // 权限不足
	GetExecPath       string // 获取可执行文件路径失败
	ExecPermission    string // 可执行文件权限检查失败
	WorkDirPermission string // 工作目录权限检查失败
	ChrootPermission  string // chroot目录权限检查失败
}

SystemErrors 系统相关错误

type TimeoutService added in v0.1.9 

type TimeoutService struct {
	ServiceRunner
	// contains filtered or unexported fields
}

TimeoutService 带超时的服务包装器

func NewTimeoutService added in v0.1.9 

func NewTimeoutService(service ServiceRunner, startTimeout, stopTimeout time.Duration) *TimeoutService

NewTimeoutService 创建带超时的服务

func (*TimeoutService) Run added in v0.1.9 

func (ts *TimeoutService) Run(ctx context.Context) error

Run 带超时的运行

func (*TimeoutService) Stop added in v0.1.9 

func (ts *TimeoutService) Stop() error

Stop 带超时的停止

type UIDomain added in v0.1.9 

type UIDomain struct {
	Commands CommandUI // 命令界面
	Help     HelpUI    // 帮助界面
	Version  VersionUI // 版本界面
}

UIDomain 界面域 - 专注于用户界面相关文本

type ValidationError added in v0.1.9 

type ValidationError struct {
	Errors []error
}

ValidationError 配置验证错误

func (*ValidationError) Error added in v0.1.9 

func (ve *ValidationError) Error() string

func (*ValidationError) Unwrap added in v0.1.9 

func (ve *ValidationError) Unwrap() []error

type VersionInfo added in v0.1.6 

type VersionInfo struct {
	Version      string      `json:"version"`      // 版本号
	GoVersion    string      `json:"goVersion"`    // Go版本
	GitCommit    string      `json:"gitCommit"`    // Git提交哈希
	GitBranch    string      `json:"gitBranch"`    // Git分支
	GitTag       string      `json:"gitTag"`       // Git标签
	Platform     string      `json:"platform"`     // 运行平台
	Architecture string      `json:"architecture"` // 系统架构
	Compiler     string      `json:"compiler"`     // 编译器
	Debug        atomic.Bool `json:"debug"`        // 调试模式
	BuildTime    time.Time   `json:"buildTime"`    // 构建时间
}

VersionInfo 构建信息

func NewVersion added in v0.1.6 

func NewVersion() *VersionInfo

NewVersion 创建版本信息

func (*VersionInfo) String added in v0.1.6 

func (vi *VersionInfo) String() string

String 返回格式化的构建信息

type VersionUI added in v0.1.9 

type VersionUI struct {
	Command     string // 版本命令
	Description string // 版本描述
	Label       string // 版本标签
}

VersionUI 版本界面相关文本

Source Files

View all Source files

Directories

Path Synopsis
demos command
legacy command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.