README
¶
kit
一个模块化、易用、生产就绪的 Go 工具包，帮助开发者快速构建可观测的应用。
🎯 项目目标
kit 旨在提供一套开箱即用的 Go 工具包，内置可观测性支持（日志、追踪、指标），帮助开发者：
- 🚀 快速替换老项目中的遗留模块
- 📦 独立使用每个模块，无强制依赖
- 📚 通过丰富的示例快速上手
- 🏗️ 统一的 API 设计，降低学习成本
- ⚡ 生产级性能和稳定性
📦 模块列表
✅ Config - 配置管理模块
强大且易用的配置管理，基于 koanf 封装。
特性：
- 支持多种配置源：文件（YAML/JSON/TOML）、环境变量、远程配置
- 配置热更新：文件监控、远程配置推送
- 配置变更日志：自动记录配置变更历史
- 敏感信息脱敏：自动隐藏密码、token 等
- 线程安全：并发读取无问题
快速开始：
import "github.com/Si40Code/kit/config"
// 初始化配置
config.Init(
config.WithFile("config.yaml"),
config.WithEnv("APP_"),
config.WithFileWatcher(),
)
// 读取配置
dbHost := config.GetString("database.host")
dbPort := config.GetInt("database.port")
// 结构化读取
var dbConfig DatabaseConfig
config.Unmarshal("database", &dbConfig)
// 监听配置变更
config.OnChange(func() {
log.Println("Config changed!")
})
更多示例： config/examples
✅ Logger - 日志模块
高性能、易用的日志模块，基于 zap 封装。
特性：
- 五级日志：Debug、Info、Warn、Error、Fatal
- 双 API 风格：结构化字段 + Map 字段
- 多种输出：stdout、文件、远程（OTLP）
- 日志切割：基于大小、时间、数量
- Trace 集成：自动关联 OpenTelemetry
- Error 标记：Error/Fatal 自动标记 span
- 全局 + 实例：同时支持两种使用方式
快速开始：
import "github.com/Si40Code/kit/logger"
// 使用默认 logger
ctx := context.Background()
logger.Info(ctx, "应用启动", "version", "1.0.0")
// 初始化自定义配置
logger.Init(
logger.WithLevel(logger.InfoLevel),
logger.WithFormat(logger.JSONFormat),
logger.WithFile("/var/log/app.log",
logger.WithFileMaxSize(100),
logger.WithFileMaxAge(30),
),
logger.WithOTLP("signoz:4317"),
logger.WithTrace("my-service"),
)
// 结构化日志
logger.Info(ctx, "用户登录",
"user_id", 12345,
"ip", "192.168.1.1",
)
// Trace 集成
tracer := otel.Tracer("my-service")
ctx, span := tracer.Start(ctx, "operation")
defer span.End()
logger.Info(ctx, "操作开始") // 自动包含 trace_id
logger.Error(ctx, "操作失败") // 自动标记 span 为 error
更多示例： logger/examples
✅ HTTPClient - HTTP 客户端模块
生产级的 HTTP 客户端，基于 resty 封装。
特性：
- OpenTelemetry Trace 集成：自动创建和传播 span
- 完整的日志记录：记录请求/响应的所有详情
- 详细的 Metric：收集 DNS、TCP、TLS 等性能数据
- 自动重试：支持可配置的重试机制
- 连接池优化：高效的连接复用和管理
- 统一的 Option 配置：遵循 kit 的设计风格
快速开始：
import "github.com/Si40Code/kit/httpclient"
// 创建客户端
client := httpclient.New(
httpclient.WithLogger(logger.Default()),
httpclient.WithTrace("my-service"),
httpclient.WithTimeout(10*time.Second),
)
// 发起请求
ctx := context.Background()
resp, err := client.R(ctx).
SetHeader("Authorization", "Bearer token").
SetBody(data).
Post("https://api.example.com/endpoint")
if err != nil {
logger.Error(ctx, "请求失败", "error", err)
return
}
logger.Info(ctx, "请求成功", "status", resp.StatusCode())
更多示例： httpclient/examples
✅ ORM - 数据库 ORM 模块
生产级的 ORM 客户端，基于 GORM 封装。
特性：
- 完整的日志记录：自动记录所有 SQL 查询
- OpenTelemetry Trace 集成：每个查询自动创建独立 span
- 详细的 Metric：收集查询类型、表名、耗时、错误等
- 慢查询检测：自动识别并警告慢查询
- 灵活的错误处理：可配置查询无数据时不返回错误
- 连接池管理：生产级连接池配置
- 完全兼容 GORM：直接暴露
*gorm.DB
快速开始：
import (
"github.com/Si40Code/kit/logger"
"github.com/Si40Code/kit/orm"
"gorm.io/driver/mysql"
)
type User struct {
ID uint `gorm:"primarykey"`
Name string
Age int
}
func main() {
// 初始化 logger
logger.Init(logger.WithStdout())
defer logger.Sync()
// 创建 ORM 客户端
dsn := "user:password@tcp(127.0.0.1:3306)/dbname?charset=utf8mb4&parseTime=True"
client, err := orm.New(
mysql.Open(dsn),
orm.WithLogger(logger.Default()),
orm.WithTrace("my-service"),
orm.WithSlowThreshold(100*time.Millisecond),
orm.WithMaxOpenConns(100),
)
if err != nil {
panic(err)
}
defer client.Close()
ctx := context.Background()
// 使用 GORM 的所有功能
var user User
client.WithContext(ctx).First(&user, 1)
// 支持事务
client.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
tx.Create(&user)
return nil
})
}
更多示例： orm/examples
🚀 快速开始
安装
go get github.com/Si40Code/kit
单独使用某个模块
// 只需要配置模块
import "github.com/Si40Code/kit/config"
func main() {
config.Init(config.WithFile("config.yaml"))
appName := config.GetString("app.name")
fmt.Println("App:", appName)
}
组合使用多个模块
import (
"github.com/Si40Code/kit/config"
"github.com/Si40Code/kit/logger"
"github.com/Si40Code/kit/httpclient"
)
func main() {
// 1. 初始化配置
config.Init(
config.WithFile("config.yaml"),
config.WithEnv("APP_"),
)
// 2. 基于配置初始化日志
logger.Init(
logger.WithLevel(logger.ParseLevel(config.GetString("log.level"))),
logger.WithFormat(logger.Format(config.GetString("log.format"))),
)
// 3. 创建 HTTP 客户端
client := httpclient.New(
httpclient.WithTimeout(config.GetInt("http.timeout")),
httpclient.WithLogger(logger.Default()),
)
ctx := context.Background()
logger.Info(ctx, "App started",
"name", config.GetString("app.name"),
)
}
📖 文档
🌟 设计原则
1. 模块独立性
每个模块都可以独立使用，不强制依赖其他模块：
// ✅ 只使用 config，不需要其他模块
import "github.com/Si40Code/kit/config"
// ✅ 只使用 logger，不需要其他模块
import "github.com/Si40Code/kit/logger"
2. 易用性优先
提供简洁的 API 和丰富的示例：
// 简单直观的 API
config.Init(config.WithFile("config.yaml"))
value := config.GetString("key")
// 每个模块都有 5+ 个实际用例
// 参见 config/examples/
3. 统一的 API 风格
所有模块采用一致的 Options 模式：
// Config 模块
config.Init(
config.WithFile("config.yaml"),
config.WithEnv("APP_"),
)
// Logger 模块（即将推出）
logger.Init(
logger.WithLevel("info"),
logger.WithFormat("json"),
)
// HTTPClient 模块（即将推出）
client := httpclient.New(
httpclient.WithTimeout(30),
httpclient.WithRetry(3),
)
4. 生产就绪
- ✅ 完善的错误处理
- ✅ 线程安全
- ✅ 性能优化
- ✅ 完整的单元测试
- ✅ 实战场景验证
📂 项目结构
kit/
├── config/ # 配置管理模块
│ ├── examples/ # 9+ 使用示例
│ └── README.md # 模块文档
├── logger/ # 日志模块
│ ├── examples/ # 5+ 使用示例
│ └── README.md # 模块文档
├── httpclient/ # HTTP 客户端模块
│ ├── examples/ # 4+ 使用示例
│ └── README.md # 模块文档
├── orm/ # 数据库 ORM 模块
│ ├── examples/ # 4+ 使用示例
│ └── README.md # 模块文档
├── web/ # Web 框架模块
│ ├── examples/ # 8+ 使用示例
│ └── README.md # 模块文档
├── examples/ # 综合示例和最佳实践
└── docs/ # 项目文档
详细结构请参考 ARCHITECTURE.md
🔧 配置模块详细说明
支持的配置源
| 配置源 | 说明 | 优先级 |
|---|---|---|
| 文件 | 支持 YAML、JSON、TOML | 低 |
| 环境变量 | 覆盖文件配置 | 中 |
| 远程配置 | Apollo、Nacos 等 | 高 |
使用示例
1. 基础用法
// examples/config/01_basic_usage/main.go
config.Init(config.WithFile("config.yaml"))
host := config.GetString("server.host")
port := config.GetInt("server.port")
debug := config.GetBool("app.debug")
2. 环境变量覆盖
// examples/config/02_env_override/main.go
config.Init(
config.WithFile("config.yaml"),
config.WithEnv("APP_"), // APP_SERVER_PORT=8080
)
// 环境变量 APP_SERVER_PORT 会覆盖配置文件中的 server.port
port := config.GetInt("server.port")
3. 文件监控（热更新）
// examples/config/03_file_watch/main.go
config.Init(
config.WithFile("config.yaml"),
config.WithFileWatcher(), // 启用文件监控
)
config.OnChange(func() {
fmt.Println("配置已更新！")
newValue := config.GetString("some.value")
})
4. 远程配置（Apollo）
// examples/config/04_remote_config/main.go
apolloProvider := NewApolloProvider(apolloConfig)
config.Init(
config.WithFile("config.yaml"), // 本地兜底配置
config.WithRemote(apolloProvider), // 远程配置
)
5. 配置变更通知
// examples/config/05_change_notification/main.go
// 配置变更会自动输出 JSON 格式的日志
// {"type":"config_change","source":"file","key":"server.port","old":"8080","new":"9090","change":"UPDATE","timestamp":"2024-01-01T12:00:00Z"}
📝 配置文件示例
# config.yaml
app:
name: my-app
version: 1.0.0
debug: false
server:
host: 0.0.0.0
port: 8080
timeout: 30
database:
host: localhost
port: 3306
username: root
password: secret123 # 变更日志中会自动脱敏为 ******
database: mydb
log:
level: info
format: json
output: stdout
🤝 贡献
欢迎贡献代码、报告问题或提出建议！
- Fork 本项目
- 创建特性分支 (
git checkout -b feature/amazing) - 提交变更 (
git commit -m 'Add amazing feature') - 推送到分支 (
git push origin feature/amazing) - 提交 Pull Request
📜 许可证
本项目采用 MIT 许可证 - 详见 LICENSE 文件
🗺️ 路线图
- v0.1 - Config 模块
- v0.2 - Logger 模块
- v0.3 - HTTPClient 模块
- v0.4 - ORM 模块
- v0.5 - Web 模块
- v0.6 - Cache 模块
- v1.0 - 正式版本发布
❓ 常见问题
Q: 为什么不直接使用 viper、zap？
A: 本 SDK 是对优秀开源库的封装，提供了：
- 更简洁的 API
- 统一的使用风格
- 开箱即用的最佳实践
- 丰富的使用示例
- 生产环境验证的配置
Q: 可以只使用某一个模块吗？
A: 完全可以！所有模块都是独立的，按需导入即可：
import "github.com/Si40Code/kit/config"
Q: 如何从旧项目迁移？
A: 我们提供了详细的迁移指南，涵盖：
- 从 viper 迁移到 config
- 从 logrus 迁移到 logger
- 从 resty 迁移到 httpclient
📮 联系方式
- 问题反馈：GitHub Issues
- 功能建议：GitHub Discussions
⭐ 如果这个项目对你有帮助，请给个 Star！
Directories
¶
Click to show internal directories.
Click to hide internal directories.