internal/pkg 组件手册(Day 18)
各组件均有单元/集成测试;本文示例为最小用法,完整字段见
go doc ./internal/pkg/<name>。
cache(Redis 客户端 + 多级缓存)
// 单机/集群/哨兵统一客户端
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 分布式锁)
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)
_ = 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)
// app 已装配 GET /metrics;业务埋点示例:
metrics.SMSSubmitTotal.WithLabelValues("ok").Inc()
metrics.HTTPRequestDuration.WithLabelValues("GET", "/health").Observe(0.012)
queue(Kafka 生产/消费/死信)
p, _ := queue.NewProducer(queue.ProducerConfig{Brokers: brokers, Logger: lg})
_ = p.Send(queue.TopicSubmit, []byte(mobile), payload) // 失败自动重试→<topic>.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 错误码与统一响应)
response.Success(c, data)
response.Error(c, errors.Blacklist) // 403 {"code":"ISC:006","msg":"黑名单"}
response.Page(c, list, total, page, 20)
jwt(签发/解析)
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)
e, _ := casbin.New(gormDB) // 自动建 casbin_rule 并加载
ok, _ := e.Check(1001, "channel", "write") // account_id → resource:action
_, _ = e.BindRole(1001, "ops") // 开户时绑定角色
util(工具库)
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 落库加密