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")
// 结构化读取vardbConfigDatabaseConfigconfig.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"// 使用默认 loggerctx:=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")
deferspan.End()
logger.Info(ctx, "操作开始") // 自动包含 trace_idlogger.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")
iferr!=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"
)
typeUserstruct {
IDuint`gorm:"primarykey"`NamestringAgeint
}
funcmain() {
// 初始化 loggerlogger.Init(logger.WithStdout())
deferlogger.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),
)
iferr!=nil {
panic(err)
}
deferclient.Close()
ctx:=context.Background()
// 使用 GORM 的所有功能varuserUserclient.WithContext(ctx).First(&user, 1)
// 支持事务client.WithContext(ctx).Transaction(func(tx*gorm.DB) error {
tx.Create(&user)
returnnil
})
}

更多示例：orm/examples

🚀 快速开始

安装

go get github.com/Si40Code/kit

单独使用某个模块

// 只需要配置模块import"github.com/Si40Code/kit/config"funcmain() {
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"
)
funcmain() {
// 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"),
)
}

📖 文档

架构设计 - 了解项目的设计理念和目录结构
快速开始 - 从零开始的入门指南
API 参考 - 详细的 API 文档
最佳实践 - 生产环境使用建议
迁移指南 - 从其他库迁移到本 SDK

🌟 设计原则

1. 模块独立性

每个模块都可以独立使用，不强制依赖其他模块：

// ✅ 只使用 config，不需要其他模块import"github.com/Si40Code/kit/config"// ✅ 只使用 logger，不需要其他模块import"github.com/Si40Code/kit/logger"

2. 易用性优先

提供简洁的 API 和丰富的示例：

// 简单直观的 APIconfig.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.goconfig.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.goconfig.Init(
config.WithFile("config.yaml"),
config.WithEnv("APP_"), // APP_SERVER_PORT=8080
)
// 环境变量 APP_SERVER_PORT 会覆盖配置文件中的 server.portport:=config.GetInt("server.port")

3. 文件监控（热更新）

// examples/config/03_file_watch/main.goconfig.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.goapolloProvider:=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.yamlapp:
name: my-appversion: 1.0.0debug: falseserver:
host: 0.0.0.0port: 8080timeout: 30database:
host: localhostport: 3306username: rootpassword: secret123 # 变更日志中会自动脱敏为 ******database: mydblog:
level: infoformat: jsonoutput: stdout

🤝 贡献

欢迎贡献代码、报告问题或提出建议！

Fork 本项目
创建特性分支 (git checkout -b feature/amazing)
提交变更 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing)
提交 Pull Request

📜 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🗺️ 路线图

❓ 常见问题

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！

Name		Name	Last commit message	Last commit date
config		config
docs		docs
httpclient		httpclient
logger		logger
orm		orm
web		web
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
SUMMARY.md		SUMMARY.md
go.mod		go.mod
go.sum		go.sum
gopls.yaml		gopls.yaml

Latest commit

History

Folders and files

Repository files navigation

kit

🎯 项目目标

📦 模块列表

✅ Config - 配置管理模块

✅ Logger - 日志模块

✅ HTTPClient - HTTP 客户端模块

✅ ORM - 数据库 ORM 模块

🚀 快速开始

安装

单独使用某个模块

组合使用多个模块

📖 文档

🌟 设计原则

1. 模块独立性

2. 易用性优先

3. 统一的 API 风格

4. 生产就绪

📂 项目结构

🔧 配置模块详细说明

支持的配置源

使用示例

1. 基础用法

2. 环境变量覆盖

3. 文件监控（热更新）

4. 远程配置（Apollo）

5. 配置变更通知

📝 配置文件示例

🤝 贡献

📜 许可证

🗺️ 路线图

❓ 常见问题

Q: 为什么不直接使用 viper、zap？

Q: 可以只使用某一个模块吗？

Q: 如何从旧项目迁移？

📮 联系方式

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages