151 lines
3.8 KiB
Markdown
151 lines
3.8 KiB
Markdown
# GoCommon 工具类库文档
|
||
|
||
## 目录
|
||
|
||
- [数据库迁移工具](./migration.md) - 数据库版本管理和迁移
|
||
- [完整使用指南](../MIGRATION.md) ⭐ - 独立工具，零耦合，Docker友好
|
||
- [日期转换工具](./datetime.md) - 日期时间处理和时区转换
|
||
- [HTTP Restful工具](./http.md) - HTTP请求响应处理和分页
|
||
- [中间件工具](./middleware.md) - 生产级HTTP中间件（CORS、时区、日志、Recovery、限流）
|
||
- [配置工具](./config.md) - 外部配置文件加载和管理
|
||
- [存储工具](./storage.md) - 文件上传和查看（OSS、MinIO）
|
||
- [邮件工具](./email.md) - SMTP邮件发送
|
||
- [短信工具](./sms.md) - 阿里云短信发送
|
||
- [Excel导出工具](./excel.md) - 数据导出到Excel文件
|
||
- [工厂工具](./factory.md) - 从配置直接创建已初始化客户端对象
|
||
- [日志工具](./logger.md) - 统一的日志记录功能
|
||
- [国际化工具](./i18n.md) - 多语言内容管理和国际化支持
|
||
|
||
## 快速开始
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
go get git.toowon.com/jimmy/go-common
|
||
```
|
||
|
||
### 使用示例
|
||
|
||
#### 数据库迁移（独立工具，零耦合）
|
||
|
||
```bash
|
||
# 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`）：
|
||
```sql
|
||
CREATE TABLE users (id BIGINT PRIMARY KEY AUTO_INCREMENT, ...);
|
||
```
|
||
|
||
**优势**：独立工具，零耦合，支持命令行参数，Docker友好
|
||
|
||
详细说明：[MIGRATION.md](../MIGRATION.md)
|
||
|
||
#### 日期转换
|
||
|
||
**推荐方式：通过 factory 使用（黑盒模式）**
|
||
|
||
```go
|
||
import "git.toowon.com/jimmy/go-common/factory"
|
||
|
||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||
now := fac.Now("Asia/Shanghai")
|
||
str := fac.FormatDateTime(now)
|
||
```
|
||
|
||
**或者直接使用 tools 包：**
|
||
|
||
```go
|
||
import "git.toowon.com/jimmy/go-common/tools"
|
||
|
||
tools.SetDefaultTimeZone(tools.AsiaShanghai)
|
||
now := tools.Now()
|
||
str := tools.FormatDateTime(now)
|
||
```
|
||
|
||
#### HTTP响应（Factory黑盒模式，推荐）
|
||
|
||
```go
|
||
import (
|
||
"net/http"
|
||
"git.toowon.com/jimmy/go-common/factory"
|
||
"git.toowon.com/jimmy/go-common/tools"
|
||
)
|
||
|
||
func GetUser(w http.ResponseWriter, r *http.Request) {
|
||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||
|
||
// 获取查询参数（使用类型转换方法）
|
||
id := tools.ConvertInt64(r.URL.Query().Get("id"), 0)
|
||
|
||
// 返回成功响应
|
||
fac.Success(w, data)
|
||
}
|
||
|
||
http.HandleFunc("/user", GetUser)
|
||
```
|
||
|
||
#### 中间件（生产级配置）
|
||
|
||
```go
|
||
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)
|
||
})
|
||
```
|
||
|
||
#### 配置管理
|
||
|
||
```go
|
||
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
|
||
|