pkg/config — 配置管理

基于 Viper 的配置管理包，支持多格式配置文件、环境变量、文件监控、保护模式和热重载。

安装

import "github.com/tokmz/qi/pkg/config"

快速使用

cfg := config.New(
    config.WithConfigFile("./config.yaml"),
    config.WithAutoWatch(true),
    config.WithOnChange(func() {
        log.Println("配置已变更")
    }),
)

if err := cfg.Load(); err != nil {
    log.Fatal(err)
}

// 读取配置
addr := cfg.GetString("server.addr")
port := cfg.GetInt("server.port")
debug := cfg.GetBool("app.debug")

// 泛型读取
timeout := config.Get[time.Duration](cfg, "server.timeout")

// 反序列化到结构体
var serverCfg ServerConfig
cfg.UnmarshalKey("server", &serverCfg)

Options

API

pkg/cache — 缓存

统一缓存抽象层，支持 Memory 和 Redis 两种驱动，内置序列化、SingleFlight 防穿透和 OpenTelemetry 追踪。

安装

import "github.com/tokmz/qi/pkg/cache"

快速使用

// 内存缓存
c, err := cache.NewWithOptions(
    cache.WithMemory(&cache.MemoryConfig{
        MaxSize:         1000,
        CleanupInterval: 5 * time.Minute,
    }),
    cache.WithKeyPrefix("app:"),
    cache.WithDefaultTTL(10 * time.Minute),
)

// Redis 缓存
c, err := cache.NewWithOptions(
    cache.WithRedis(&cache.RedisConfig{
        Addr:     "localhost:6379",
        Password: "",
        DB:       0,
    }),
)

// 统一接口
c.Set(ctx, "key", value, 5*time.Minute)
val, err := c.Get(ctx, "key")
c.Delete(ctx, "key")
exists, _ := c.Exists(ctx, "key")

Cache 接口

pkg/logger — 日志

基于 Zap 的高性能日志包，支持多输出、文件轮转、采样、Hook 和 Context 自动提取 TraceID/UID。

快速使用

import "github.com/tokmz/qi/pkg/logger"

// 开发环境
log := logger.Default()

// 生产环境
log, err := logger.NewWithOptions(
    logger.WithLevel(logger.InfoLevel),
    logger.WithFormat(logger.FormatJSON),
    logger.WithFileOutput("./logs/app.log"),
    logger.WithRotateOutput(&logger.RotateConfig{
        MaxSize:    100,  // MB
        MaxBackups: 10,
        MaxAge:     30,   // 天
        Compress:   true,
    }),
    logger.WithCaller(true),
)

// 基础日志
log.Info("server started", zap.String("addr", ":8080"))
log.Error("request failed", zap.Error(err))

// 带 Context（自动提取 TraceID/UID）
log.InfoContext(ctx, "user login", zap.Int64("uid", uid))

// 子 Logger
reqLog := log.With(zap.String("module", "auth"))
reqLog.Info("token verified")

Logger 接口

Options

pkg/orm — 数据库 ORM

基于 GORM 的数据库封装，支持 MySQL/PostgreSQL/SQLite，内置连接池、读写分离和 OpenTelemetry 追踪。

快速使用

import "github.com/tokmz/qi/pkg/orm"

db, err := orm.New(&orm.Config{
    Type: orm.MySQL,
    DSN:  "user:pass@tcp(127.0.0.1:3306)/dbname?charset=utf8mb4",
    MaxOpenConns: 100,
    MaxIdleConns: 10,
    MaxLifetime:  time.Hour,
    EnableTrace:  true,
    LogLevel:     "info",
})

// 读写分离
db, err := orm.New(&orm.Config{
    Type: orm.MySQL,
    DSN:  "user:pass@tcp(master:3306)/db",
    ReadWriteSplit: &orm.ReadWriteSplitConfig{
        ReadDSNs: []string{
            "user:pass@tcp(slave1:3306)/db",
            "user:pass@tcp(slave2:3306)/db",
        },
        Policy: "random",
    },
})

Config

pkg/tracing — 链路追踪

OpenTelemetry 链路追踪封装，支持 OTLP gRPC/HTTP、Jaeger、Zipkin 导出器，内置采样策略。

快速使用

import "github.com/tokmz/qi/pkg/tracing"

tp, err := tracing.NewTracerProvider(&tracing.Config{
    ServiceName:    "my-service",
    ServiceVersion: "1.0.0",
    Environment:    "production",
    ExporterType:   "otlp-grpc",
    Endpoint:       "localhost:4317",
    SampleRate:     0.1,
})
defer tracing.Shutdown(context.Background())

Config

pkg/job — 任务调度

功能完整的任务调度器，支持 Cron 表达式、一次性/间隔/延迟任务、重试、超时、并发控制、批量更新和缓存优化。

快速使用

import "github.com/tokmz/qi/pkg/job"

// 创建调度器
scheduler := job.NewScheduler(storage, job.DefaultConfig())

// 注册处理器
scheduler.RegisterHandlerFunc("send-email", func(ctx context.Context, payload string) (string, error) {
    // 处理任务
    return "sent", nil
})

// 添加 Cron 任务
scheduler.AddJob(ctx, &job.Job{
    ID:       "daily-report",
    Name:     "每日报告",
    Type:     job.TypeCron,
    Handler:  "send-email",
    CronExpr: "0 9 * * *",
    Payload:  `{"type":"daily"}`,
})

// 添加一次性延迟任务
scheduler.AddJob(ctx, &job.Job{
    ID:      "welcome-email",
    Name:    "欢迎邮件",
    Type:    job.TypeOnce,
    Handler: "send-email",
    Delay:   5 * time.Minute,
})

// 启动调度器
scheduler.Start(ctx)
defer scheduler.Stop(ctx)

任务类型

Scheduler API