go-common/docs/README.md

GoCommon 工具类库文档

目录

• 数据库迁移工具 - 数据库版本管理和迁移
  • 完整使用指南 ⭐ - 独立工具，零耦合，Docker友好
• 日期转换工具 - 日期时间处理和时区转换
• HTTP Restful工具 - HTTP请求响应处理和分页
• 中间件工具 - 生产级HTTP中间件（CORS、时区、日志、Recovery、限流）
• 配置工具 - 外部配置文件加载和管理
• 存储工具 - 文件上传和查看（OSS、MinIO）
• 邮件工具 - SMTP邮件发送
• 短信工具 - 阿里云短信发送
• 工厂工具 - 从配置直接创建已初始化客户端对象
• 日志工具 - 统一的日志记录功能

快速开始

安装

go get git.toowon.com/jimmy/go-common

使用示例

数据库迁移（独立工具，零耦合）

# 1. 复制模板：templates/migrate/main.go -> cmd/migrate/main.go
# 2. 创建迁移文件：migrations/20240101000001_create_users.sql

# 3. 开发环境
go run cmd/migrate/main.go up

# 4. 生产环境（编译后使用，推荐）
go build -o bin/migrate cmd/migrate/main.go
./bin/migrate up                              # 使用默认配置
./bin/migrate up -config /path/to/config.json # 指定配置
./bin/migrate status                          # 查看状态

# 5. Docker（挂载配置，修改无需重启）
# docker-compose.yml:
# volumes:
#   - ./config.json:/app/config.json:ro
# command: sh -c "./migrate up && ./server"

迁移文件示例（migrations/20240101000001_create_users.sql）：

CREATE TABLE users (id BIGINT PRIMARY KEY AUTO_INCREMENT, ...);

优势：独立工具，零耦合，支持命令行参数，Docker友好

详细说明：MIGRATION.md

日期转换

推荐方式：通过 factory 使用（黑盒模式）

import "git.toowon.com/jimmy/go-common/factory"

fac, _ := factory.NewFactoryFromFile("config.json")
now := fac.Now("Asia/Shanghai")
str := fac.FormatDateTime(now)

或者直接使用 tools 包：

import "git.toowon.com/jimmy/go-common/tools"

tools.SetDefaultTimeZone(tools.AsiaShanghai)
now := tools.Now()
str := tools.FormatDateTime(now)

HTTP响应（Handler黑盒模式）

import (
    "net/http"
    commonhttp "git.toowon.com/jimmy/go-common/http"
)

func GetUser(h *commonhttp.Handler) {
    id := h.GetQueryInt64("id", 0)
    h.Success(data)
}

http.HandleFunc("/user", commonhttp.HandleFunc(GetUser))

中间件（生产级配置）

import (
    "time"
    "git.toowon.com/jimmy/go-common/middleware"
    commonhttp "git.toowon.com/jimmy/go-common/http"
)

// 完整的中间件链
chain := middleware.NewChain(
    middleware.Recovery(nil),   // Panic恢复
    middleware.Logging(nil),    // 请求日志
    middleware.RateLimitByIP(100, time.Minute), // 限流
    middleware.CORS(nil),       // CORS
    middleware.Timezone,        // 时区
)

handler := chain.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
    h := commonhttp.NewHandler(w, r)
    timezone := h.GetTimezone()
    h.Success(data)
})

配置管理

import "git.toowon.com/jimmy/go-common/config"

// 从文件加载配置
cfg, err := config.LoadFromFile("./config.json")

// 获取各种配置
dsn, _ := cfg.GetDatabaseDSN()
redisAddr := cfg.GetRedisAddr()
corsConfig := cfg.GetCORS()

版本

v1.0.0

许可证

MIT