# internal/pkg 组件手册(Day 18) > 各组件均有单元/集成测试;本文示例为最小用法,完整字段见 `go doc ./internal/pkg/`。 ## cache(Redis 客户端 + 多级缓存) ```go // 单机/集群/哨兵统一客户端 rc, _ := cache.New(cache.Options{Mode: cache.ModeSingle, Addrs: []string{"127.0.0.1:16379"}}) _ = rc.Set(ctx, "k", []byte("v"), time.Minute).Err() // 两级缓存:本地 freecache 优先,Miss 查 Redis 并回填;全 Miss 回源 ml := cache.NewMultiLevel(rc, cache.MultiLevelOptions{LocalSizeMB: 16, LocalTTL: 30 * time.Second, RemoteTTL: 10 * time.Minute}) v, hitRemote, _ := ml.GetOrLoad(ctx, "account:cfg:1001", func(ctx context.Context) ([]byte, error) { return loadFromDB(1001) }) ``` ## lock(Redis 分布式锁) ```go lk := lock.New(rc) l, err := lk.TryLock(ctx, "job:dispatch", 30*time.Second) // SETNX+PX defer func() { _ = l.Unlock(ctx) }() // Lua 原子释放(防误删) // watchdog 每 TTL/3 自动续期;锁丢失即停;Unlock 幂等停止 ``` ## logger(zap + lumberjack) ```go _ = logger.Init(logger.Options{Level: "info", Format: "json", Output: []string{"stdout", "file"}, File: logger.FileOptions{Path: "/var/log/gosms/app.log", MaxSizeMB: 100, Compress: true}}) logger.L().Info("order_created", zap.Int64("order_id", 42)) logger.Level().SetLevel(zap.DebugLevel) // 动态级别(ETCD 热更新联动) ``` ## metrics(Prometheus) ```go // app 已装配 GET /metrics;业务埋点示例: metrics.SMSSubmitTotal.WithLabelValues("ok").Inc() metrics.HTTPRequestDuration.WithLabelValues("GET", "/health").Observe(0.012) ``` ## queue(Kafka 生产/消费/死信) ```go p, _ := queue.NewProducer(queue.ProducerConfig{Brokers: brokers, Logger: lg}) _ = p.Send(queue.TopicSubmit, []byte(mobile), payload) // 失败自动重试→.dlq cg, _ := queue.NewConsumerGroup(queue.ConsumerGroupConfig{ Consumer: queue.ConsumerConfig{Brokers: brokers, GroupID: "sender", Topics: []string{queue.TopicSubmit}, Handler: handle}, Producer: queue.ProducerConfig{Brokers: brokers, Logger: lg}, // 死信转投 MaxRetry: 3, // 单消息重试 3 次(指数退避) }) go func() { _ = cg.Run(ctx) }() cg.Pause(); cg.Resume() // 消费暂停/恢复(运维窗口) ``` ## errors / response(ISC:xxx 错误码与统一响应) ```go response.Success(c, data) response.Error(c, errors.Blacklist) // 403 {"code":"ISC:006","msg":"黑名单"} response.Page(c, list, total, page, 20) ``` ## jwt(签发/解析) ```go m := jwt.NewManager(secret, 2*time.Hour) tok, _ := m.Sign(1001, "alice", []string{"ops"}, []string{"account:read"}) claims, err := m.Parse(tok) // 强制 HMAC;过期/篡改返回错误 ``` ## casbin(RBAC,策略存 MySQL) ```go e, _ := casbin.New(gormDB) // 自动建 casbin_rule 并加载 ok, _ := e.Check(1001, "channel", "write") // account_id → resource:action _, _ = e.BindRole(1001, "ops") // 开户时绑定角色 ``` ## util(工具库) ```go util.IsValidMainlandMobile("+86 138-0013-8000") // true c, n := util.SmsLength("你好世界") // (4, 1) UCS2 计费 util.ExtractVariables("尊敬的{name}") // [name] sf, _ := util.NewSnowflake(1); id := sf.NextID() // 雪花 ID(多实例用 WorkerIDFromETCD) enc, _ := util.EncryptSecret(passphrase, apiKey) // AES-GCM 落库加密 ```