jimmy/go-common
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: jimmy:v0.2.0
Branches Tags
jimmy:main
jimmy:v1.0.0 jimmy:v0.6.5 jimmy:v0.6.3 jimmy:v0.6.2 jimmy:v0.6.1 jimmy:v0.6.0 jimmy:v0.5.7 jimmy:v0.5.6 jimmy:v0.5.5 jimmy:v0.5.3 jimmy:v0.5.2 jimmy:v0.5.1 jimmy:v0.5.0 jimmy:v0.2.3 jimmy:v0.2.2 jimmy:v0.2.1 jimmy:v0.2.0 jimmy:v0.1.0 jimmy:v0.0.2 jimmy:v0.0.1
..
compare: jimmy:v1.0.0
Branches Tags
jimmy:main
jimmy:v1.0.0 jimmy:v0.6.5 jimmy:v0.6.3 jimmy:v0.6.2 jimmy:v0.6.1 jimmy:v0.6.0 jimmy:v0.5.7 jimmy:v0.5.6 jimmy:v0.5.5 jimmy:v0.5.3 jimmy:v0.5.2 jimmy:v0.5.1 jimmy:v0.5.0 jimmy:v0.2.3 jimmy:v0.2.2 jimmy:v0.2.1 jimmy:v0.2.0 jimmy:v0.1.0 jimmy:v0.0.2 jimmy:v0.0.1

16 Commits
v0.2.0 ... v1.0.0

Author SHA1 Message Date
Jimmy Xue
6072ec57e8 重构项目的实现,优化使用方法与使用逻辑 2026-06-25 00:03:59 +08:00
Jimmy Xue
a6e8101e09 添加本地上传的功能 2026-01-30 21:40:21 +08:00
Jimmy Xue
38ebe73e45 调整Excel导出时使用的方法 2025-12-28 12:33:06 +08:00
Jimmy Xue
e3d9bbbcc5 调整Excel导出时使用的方法 2025-12-28 12:15:37 +08:00
Jimmy Xue
47cbdbb2de 增加导出数据到Excel的方法 2025-12-28 11:53:24 +08:00
Jimmy Xue
f8f4df4073 增加多语言支持 2025-12-07 10:32:36 +08:00
Jimmy Xue
684923f9cb 调整request的方法，增加类型转换的方法 2025-12-07 09:31:59 +08:00
Jimmy Xue
545c6ef6a4 增加getuint64/32的方法 2025-12-07 01:09:52 +08:00
Jimmy Xue
5cfa0d7ce5 PageRequest增加了keyword 2025-12-07 01:03:25 +08:00
Jimmy Xue
f62e8ecebf 增加time的函数,crypto的函数 2025-12-07 00:51:02 +08:00
Jimmy Xue
339920a940 调整项目结构,factory只负责暴露方法，不实现业务细节 2025-12-07 00:04:01 +08:00
Jimmy Xue
b66f345281 修复迁移时,数据库未指定的情况下数据库脚本混乱的问题 2025-12-06 22:03:57 +08:00
Jimmy Xue
6547e7bca8 调整迁移的逻辑 2025-12-06 21:38:53 +08:00
Jimmy Xue
6146178111 调整工厂模式的方法 2025-12-05 00:07:15 +08:00
Jimmy Xue
0650feb0d2 调整工具类的方法，优化方法调用及增加迁移工具及其用法 2025-12-04 22:30:48 +08:00
Jimmy Xue
de8fc13f18 日志方法增加异步与同步的方法 2025-11-30 21:01:47 +08:00
77 changed files with 5293 additions and 7411 deletions
Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -1 +1,2 @@
.cursor
.DS_Store

429
INTEGRATION.md Normal file
View File

@@ -0,0 +1,429 @@
# GoCommon 业务项目对接操作手册
本文档供**引用 GoCommon 的业务项目**使用。按本手册对接即可，无需重复沟通基础设施实现方式。
模块路径：`git.toowon.com/jimmy/go-common`
> 本文档只描述**目标架构**，重构时一步到位，**不提供过渡期用法，不考虑向后兼容**。
---
## 1. 对接原则
| 原则 | 说明 |
|------|------|
| Factory 只是入口 | 启动时初始化一次，通过 getter 获取各模块**对象** |
| 能力在模块自身 | 使用 `log.Info()`、`db.Find()`、`store.Upload()`，不在 Factory 上堆透传方法 |
| 按需引用 | 用什么模块取什么对象；无状态工具直接 `import tools` |
| 不重写基础设施 | 数据库连接、Redis 客户端、统一 HTTP 出参、中间件链由 GoCommon 提供 |
| 业务只管业务 | Service 返回数据；Handler 交给 `http.Handler` 出参；Migration 只写 SQL 文件 |
---
## 2. 环境准备
### 2.1 配置私有模块
```bash
go env -w GOPRIVATE=git.toowon.com
go env -w GONOPROXY=git.toowon.com
go env -w GONOSUMDB=git.toowon.com
```
### 2.2 Git 认证（SSH 推荐）
```bash
git config --global url."git@git.toowon.com:".insteadOf "https://git.toowon.com/"
```
### 2.3 安装依赖
```bash
go get git.toowon.com/jimmy/go-common@v2.0.0
```
在 `go.mod` 中：
```go
require git.toowon.com/jimmy/go-common v2.0.0
```
配置示例见 [`config/example.json`](./config/example.json)。
---
## 3. 推荐项目结构
```text
your-project/
├── config.json
├── cmd/
│ ├── server/main.go
│ └── migrate/main.go # 从 templates/migrate/main.go 复制
├── migrations/
│ └── 20240101000001_create_users.sql
├── locales/ # i18n（可选）
│ ├── zh-CN.json
│ └── en-US.json
├── internal/
│ ├── handler/
│ └── service/
└── go.mod
```
---
## 4. 启动初始化（只做一次）
```go
package main
import (
"log"
"net/http"
"git.toowon.com/jimmy/go-common/factory"
)
func main() {
if err := factory.Init("config.json"); err != nil {
log.Fatal(err)
}
app := factory.Default()
chain := app.MiddlewareChain()
chain.Append(yourAuthMiddleware)
userSvc, err := NewUserService(app)
if err != nil {
log.Fatal(err)
}
http.Handle("/api/users", chain.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
listUsers(w, r, userSvc, app)
}))
log.Fatal(http.ListenAndServe(":8080", nil))
}
```
**禁止**在每个 Handler 里 `NewFromFile` / `Init`。全局只初始化一次，通过 `factory.Default()` 或注入 `*factory.Factory`。
---
## 5. 获取模块对象（Factory getter）
连接与客户端由 Factory **lazy 初始化并缓存**。业务侧**不要**自行 `gorm.Open` / `redis.NewClient`。
| 模块 | API | 用法 |
|------|-----|------|
| 配置 | `app.Config()` | 读原始配置 |
| 数据库 | `app.Database()` | `db.Find(&users)`、`db.Transaction(...)` |
| Redis | `app.Redis()` | `rds.Set(ctx, key, val, ttl)` |
| 日志 | `app.Logger()` | `log.Info(...)`，退出前 `log.Close()` |
| 存储 | `app.Storage()` | `store.Upload(ctx, key, reader)` |
| 邮件 | `app.Email()` | `mail.SendEmail(...)` |
| 短信 | `app.SMS()` | `sms.SendSMS(...)` |
| Excel | `app.Excel()` | `ex.ExportToFile(...)` |
| 国际化 | `app.I18n()` | 供 `http.Handler` 注入；或 `i18n.GetMessage(...)` |
| 中间件链 | `app.MiddlewareChain()` | `chain.Append(...).ThenFunc(...)` |
| 迁移 | `app.Migrator("migrations")` | `m.Up()` / `m.Status()` / `m.Down()` |
### 注入 Service 示例
```go
type UserService struct {
db *gorm.DB
rds *redis.Client
}
func NewUserService(app *factory.Factory) (*UserService, error) {
db, err := app.Database()
if err != nil {
return nil, err
}
rds, err := app.Redis()
if err != nil {
return nil, err
}
return &UserService{db: db, rds: rds}, nil
}
func (s *UserService) List(page, size int) (users []User, total int64, err error) {
s.db.Model(&User{}).Count(&total)
err = s.db.Offset((page-1)*size).Limit(size).Find(&users).Error
return
}
```
`config.json` 未配置的模块，调用 getter 会返回错误——**只配置使用的模块即可**。
---
## 6. HTTP 统一出参
### 6.1 职责划分
| 层级 | 做什么 |
|------|--------|
| Service | 返回 `[]User`、`total`、业务 error |
| Handler | 解析请求、调 Service、通过 `http.Handler` 出参 |
| `http.Handler` | PageData → Response → JSON（结构 / 编码 / 语种 / 时间统一） |
**禁止**在 Service 拼 JSON，**禁止**在业务项目自定义 `Response` 结构，**禁止**经 Factory 出参（无 `app.Success` / `app.Error`）。
### 6.2 标准响应格式
```json
{
"code": 0,
"message": "success",
"timestamp": 1704067200,
"data": {}
}
```
分页时 `data`：
```json
{
"list": [],
"total": 100,
"page": 1,
"pageSize": 20
}
```
类型定义在 `http` 包：`http.Response`、`http.PageData`。
### 6.3 Handler 用法（唯一方式）
中间件链须包含 `Language`、`Timezone`（`MiddlewareChain()` 已默认组装）。
```go
import commonhttp "git.toowon.com/jimmy/go-common/http"
func listUsers(w http.ResponseWriter, r *http.Request, svc *UserService, app *factory.Factory) {
i18n, _ := app.I18n()
h := commonhttp.NewHandler(w, r, commonhttp.WithI18n(i18n))
var req ListUserRequest
if err := h.ParseJSON(&req); err != nil {
h.Error("common.invalid_request")
return
}
p := h.Pagination()
users, total, err := svc.List(p.GetPage(), p.GetPageSize())
if err != nil {
h.Error("user.list_failed")
return
}
h.SuccessPage(users, total)
}
```
`http.Handler` 统一负责：
- `Content-Type: application/json; charset=utf-8`
- 从 context 读取语种、时区
- 消息码（如 `user.not_found`）经 i18n 转为文案与业务 code
- `timestamp` 按统一时区策略写入
### 6.4 请求头约定
| Header | 用途 |
|--------|------|
| `Accept-Language` | 响应消息语种 |
| `X-Timezone` | 时区（默认 `Asia/Shanghai`） |
---
## 7. 数据库迁移
执行框架已封装，业务**只写 SQL 文件**。
### 7.1 推荐：独立 migrate 命令（与 Web 解耦）
```bash
cp templates/migrate/main.go cmd/migrate/main.go
go build -o bin/migrate cmd/migrate/main.go
./bin/migrate up
./bin/migrate status
./bin/migrate down
./bin/migrate up -config config.json -dir migrations
```
```sql
-- migrations/20240101000001_create_users.sql
CREATE TABLE users (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(255) NOT NULL
);
```
```sql
-- migrations/20240101000001_create_users.down.sql
DROP TABLE IF EXISTS users;
```
独立 CLI 内部调用 `migration.RunMigrationsFromConfigWithCommand`，无需业务实现连接逻辑。
### 7.2 可选：经 Factory（开发 / 小项目）
```go
m, err := app.Migrator("migrations")
if err != nil {
log.Fatal(err)
}
if err := m.Up(); err != nil {
log.Fatal(err)
}
```
### 7.3 Docker
```yaml
command: sh -c "./bin/migrate up && ./bin/server"
volumes:
- ./config.json:/app/config.json:ro
- ./migrations:/app/migrations:ro
```
---
## 8. 各模块按需对接
### 8.1 日志
```go
log, _ := app.Logger()
defer log.Close()
log.Info("服务启动")
```
### 8.2 存储
```go
store, _ := app.Storage()
store.Upload(ctx, "images/a.jpg", fileReader, "image/jpeg")
url, _ := store.GetURL("images/a.jpg", 3600)
```
不经 Factory 时：`storage.NewStorage(storage.StorageTypeLocal, cfg)`。
### 8.3 邮件 / 短信
```go
mail, _ := app.Email()
defer mail.Close()
// HTTP 通知类：异步，不阻塞请求
mail.SendEmailAsync(r.Context(), []string{"a@b.com"}, "主题", "正文")
// 验证码等需等待结果：同步
mail.SendEmail([]string{"a@b.com"}, "主题", "正文")
sms, _ := app.SMS()
defer sms.Close()
sms.SendSMSAsync(r.Context(), []string{"13800138000"}, map[string]string{"code": "123456"})
sms.SendSMS([]string{"13800138000"}, map[string]string{"code": "123456"})
```
### 8.4 Excel
```go
ex := app.Excel()
ex.ExportToFile("users.xlsx", "用户列表", columns, users)
```
### 8.5 国际化
```go
i18n, _ := app.I18n()
i18n.LoadFromDir("locales")
msg := i18n.GetMessage("zh-CN", "user.not_found")
```
HTTP 出参的 i18n 通过 `NewHandler(..., WithI18n(i18n))` 注入，Handler 内用消息码调用 `h.Error("user.not_found")`。
### 8.6 无状态工具（不经 Factory）
```go
import "git.toowon.com/jimmy/go-common/tools"
tools.Now()
tools.MD5("text")
tools.YuanToCents(100.5)
```
---
## 9. config.json 最小示例
```json
{
"database": {
"type": "mysql",
"host": "localhost",
"port": 3306,
"user": "root",
"password": "password",
"database": "mydb"
},
"logger": {
"level": "info",
"output": "both",
"filePath": "./logs/app.log",
"async": true
},
"i18n": {
"defaultLang": "zh-CN",
"localesDir": "locales"
}
}
```
完整字段见 [`config/example.json`](./config/example.json)。
---
## 10. 反模式（禁止）
- 每个 Handler 内 `factory.Init` / `NewFromFile`
- 业务 Service 内写 HTTP JSON 响应
- 自行 `gorm.Open` / `redis.NewClient`
- 使用 Factory 透传：`LogInfo`、`RedisSet`、`Success`、`Error`、`Now`、`MD5` 等
- 直接调用 `http.Success(w, ...)` 包级函数（应使用 `http.Handler`）
- 在业务项目复制 GoCommon 的 Response / 中间件实现
---
## 11. 故障排除
**无法下载模块：**
```bash
go env -w GOPRIVATE=git.toowon.com
git config --global url."git@git.toowon.com:".insteadOf "https://git.toowon.com/"
go get git.toowon.com/jimmy/go-common@latest
```
**依赖错误：** `go clean -modcache && go mod tidy`
**getter 报 config is nil：** 补充 `config.json` 对应段，或不调用该 getter
**迁移找不到文件：** 检查 `-dir` 与 SQL 文件命名
---
## 12. 文档与版本
| 文档 | 用途 |
|------|------|
| 本文档 | 业务项目对接 |
| [README.md](./README.md) | 库概述 |
| [VERSION.md](./VERSION.md) | 版本发布 |
版本升级见 [VERSION.md](./VERSION.md)。

298
README.md
View File

@@ -1,278 +1,56 @@
# GoCommon - Go通用工具类库
# GoCommon - Go 通用工具类库
这是一个Go语言开发的通用工具类库，为其他Go项目提供常用的工具方法集合。
供其他 Go 项目引用的通用工具集合。业务项目对接请直接阅读：
## 功能模块
**[业务项目对接操作手册（INTEGRATION.md）](./INTEGRATION.md)**
### 1. 数据库迁移工具 (migration)
提供数据库迁移功能，支持MySQL、PostgreSQL、SQLite等数据库。
## 模块路径
### 2. 日期转换工具 (datetime)
提供日期时间转换功能，支持时区设定和多种格式转换。
### 3. HTTP Restful工具 (http)
提供HTTP请求/响应处理工具，包含标准化的响应结构、分页支持和HTTP状态码与业务状态码的分离。
### 4. 中间件工具 (middleware)
提供常用的HTTP中间件，包括CORS处理和时区管理。
### 5. 配置工具 (config)
提供从外部文件加载配置的功能，支持数据库、OSS、Redis、CORS、MinIO等配置。
### 6. 存储工具 (storage)
提供文件上传和查看功能，支持OSS和MinIO两种存储方式，并提供HTTP处理器。
### 7. 邮件工具 (email)
提供SMTP邮件发送功能，支持纯文本和HTML邮件，使用Go标准库实现。
### 8. 短信工具 (sms)
提供阿里云短信发送功能，支持模板短信和批量发送，使用Go标准库实现。
### 9. 工厂工具 (factory)
提供从配置文件直接创建已初始化客户端对象的功能，包括数据库、Redis、邮件、短信、日志等，避免调用方重复实现创建逻辑。
### 10. 日志工具 (logger)
提供统一的日志记录功能，支持多种日志级别和输出方式，使用Go标准库实现。
```
git.toowon.com/jimmy/go-common
```
## 安装
### 1. 配置私有仓库（重要）
由于本项目使用私有 Git 仓库，需要先配置 `GOPRIVATE` 环境变量：
```bash
# 使用 go env 命令配置（推荐，永久生效）
go env -w GOPRIVATE=git.toowon.com
# 验证配置
go env GOPRIVATE
go get git.toowon.com/jimmy/go-common@v2.0.0
```
**详细配置说明请参考 [SETUP.md](./SETUP.md)**
## 设计概要
**遇到问题？请查看 [故障排除指南](./TROUBLESHOOTING.md)**
- **Factory**：入口，启动时初始化一次，按需 getter 获取模块对象（DB、Redis、Logger 等）
- **各模块包**：能力在对象方法上（`log.Info()`、`store.Upload()`）
- **http 包**：统一 HTTP 出参（Response / PageData / Handler）
- **migration**：独立 CLI 或 Factory 执行 SQL 迁移
- **tools**：无状态工具函数，直接 import
### 2. 安装模块
## 功能模块
```bash
# 安装最新版本（推荐用于开发）
go get git.toowon.com/jimmy/go-common@latest
| 模块 | 包路径 | 说明 |
|------|--------|------|
| 配置 | `config` | JSON 配置加载 |
| 工厂 | `factory` | 统一入口与 lazy getter |
| HTTP | `http` | 请求解析、统一响应 |
| 中间件 | `middleware` | CORS、日志、Recovery、限流、语种、时区 |
| 工具 | `tools` | 时间、加密、金额、类型转换 |
| 日志 | `logger` | 异步日志 |
| 存储 | `storage` | Local / OSS / MinIO |
| 邮件 / 短信 | `email` / `sms` | SMTP、阿里云短信 |
| Excel | `excel` | 数据导出 |
| 国际化 | `i18n` | 多语言消息 |
| 迁移 | `migration` | SQL 版本管理 |
# 安装特定版本（推荐用于生产）
go get git.toowon.com/jimmy/go-common@v1.0.0
```
## 文档
**版本管理说明请参考 [VERSION.md](./VERSION.md)**
| 文档 | 说明 |
|------|------|
| [INTEGRATION.md](./INTEGRATION.md) | 业务项目对接操作手册 |
| [VERSION.md](./VERSION.md) | 版本管理与发布 |
| [templates/](./templates/) | migrate 等脚手架模板 |
| [config/example.json](./config/example.json) | 配置文件示例 |
| [examples/](./examples/) | 代码示例 |
## 使用示例
详细的使用说明请参考各模块的文档：
- [数据库迁移工具文档](./docs/migration.md)
- [日期转换工具文档](./docs/datetime.md)
- [HTTP Restful工具文档](./docs/http.md)
- [中间件工具文档](./docs/middleware.md)
- [配置工具文档](./docs/config.md)
- [存储工具文档](./docs/storage.md)
- [邮件工具文档](./docs/email.md)
- [短信工具文档](./docs/sms.md)
- [工厂工具文档](./docs/factory.md)
- [日志工具文档](./docs/logger.md)
### 快速示例
#### 数据库迁移
```go
import "git.toowon.com/jimmy/go-common/migration"
migrator := migration.NewMigrator(db)
migrator.AddMigration(migration.Migration{
Version: "20240101000001",
Description: "create_users_table",
Up: func(db *gorm.DB) error {
return db.Exec("CREATE TABLE users ...").Error
},
})
migrator.Up()
```
#### 日期转换
```go
import "git.toowon.com/jimmy/go-common/datetime"
datetime.SetDefaultTimeZone(datetime.AsiaShanghai)
now := datetime.Now()
str := datetime.FormatDateTime(now)
```
#### HTTP响应（Handler黑盒模式）
```go
import (
"net/http"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
// 使用Handler（黑盒模式）
func GetUser(h *commonhttp.Handler) {
id := h.GetQueryInt64("id", 0) // 无需传递r
h.Success(data) // 无需传递w
}
http.HandleFunc("/user", commonhttp.HandleFunc(GetUser))
```
#### 中间件
```go
import (
"git.toowon.com/jimmy/go-common/middleware"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
// CORS + 时区中间件
chain := middleware.NewChain(
middleware.CORS(),
middleware.Timezone,
)
handler := chain.ThenFunc(yourHandler)
// 在Handler中获取时区
func handler(h *commonhttp.Handler) {
timezone := h.GetTimezone()
}
```
#### 配置管理
```go
import "git.toowon.com/jimmy/go-common/config"
// 从文件加载配置
cfg, err := config.LoadFromFile("./config.json")
// 获取各种配置
dsn, _ := cfg.GetDatabaseDSN()
redisAddr := cfg.GetRedisAddr()
corsConfig := cfg.GetCORS()
```
#### 文件上传和查看（推荐使用工厂黑盒模式）
```go
import (
"context"
"git.toowon.com/jimmy/go-common/factory"
)
fac, _ := factory.NewFactoryFromFile("./config.json")
ctx := context.Background()
// 黑盒模式（推荐，自动选择OSS或MinIO）
file, _ := os.Open("test.jpg")
url, _ := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")
// 获取文件URL
url, _ := fac.GetFileURL("images/test.jpg", 0) // 永久有效
url, _ := fac.GetFileURL("images/test.jpg", 3600) // 1小时后过期
// 或使用存储处理器（需要HTTP处理器时）
storage, _ := storage.NewStorage(storage.StorageTypeOSS, cfg)
uploadHandler := storage.NewUploadHandler(...)
```
#### 邮件发送（推荐使用工厂黑盒模式）
```go
import "git.toowon.com/jimmy/go-common/factory"
fac, _ := factory.NewFactoryFromFile("./config.json")
// 黑盒模式（推荐）
fac.SendEmail([]string{"user@example.com"}, "主题", "正文")
fac.SendEmail([]string{"user@example.com"}, "主题", "纯文本", "<h1>HTML内容</h1>")
// 或获取客户端对象（需要高级功能时）
emailClient, _ := fac.GetEmailClient()
emailClient.SendSimple(...)
```
#### 短信发送（推荐使用工厂黑盒模式）
```go
import "git.toowon.com/jimmy/go-common/factory"
fac, _ := factory.NewFactoryFromFile("./config.json")
// 黑盒模式（推荐）
fac.SendSMS([]string{"13800138000"}, map[string]string{"code": "123456"})
// 或获取客户端对象（需要高级功能时）
smsClient, _ := fac.GetSMSClient()
smsClient.SendSimple(...)
```
#### 使用工厂（黑盒模式，推荐）
```go
import (
"context"
"git.toowon.com/jimmy/go-common/factory"
)
// 从配置文件创建工厂（最推荐）
fac, _ := factory.NewFactoryFromFile("./config.json")
ctx := context.Background()
// 日志（黑盒模式，直接调用）
fac.LogInfo("用户登录成功")
fac.LogError("登录失败: %v", err)
// 邮件发送（黑盒模式，直接调用）
fac.SendEmail([]string{"user@example.com"}, "验证码", "您的验证码是：123456")
// 短信发送（黑盒模式，直接调用）
fac.SendSMS([]string{"13800138000"}, map[string]string{"code": "123456"})
// 文件上传（黑盒模式，自动选择OSS或MinIO）
file, _ := os.Open("test.jpg")
url, _ := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")
// 获取文件URL
url, _ := fac.GetFileURL("images/test.jpg", 0) // 永久有效
url, _ := fac.GetFileURL("images/test.jpg", 3600) // 1小时后过期
// Redis操作（黑盒模式，直接调用）
fac.RedisSet(ctx, "key", "value", time.Hour)
value, _ := fac.RedisGet(ctx, "key")
fac.RedisDelete(ctx, "key")
// 数据库（黑盒模式，获取已初始化对象）
db, _ := fac.GetDatabase()
db.Find(&users)
// Redis客户端（黑盒模式，获取已初始化对象）
redisClient, _ := fac.GetRedisClient()
redisClient.HGet(ctx, "key", "field").Result()
```
更多示例请查看 [examples](./examples/) 目录。
## 版本管理
当前版本：**v1.0.0**
### 如何指定版本
在 `go.mod` 文件中指定版本：
```go
require (
git.toowon.com/jimmy/go-common v1.0.0
)
```
或者使用命令行：
```bash
# 使用最新版本
go get git.toowon.com/jimmy/go-common@latest
# 使用特定版本
go get git.toowon.com/jimmy/go-common@v1.0.0
```
**详细版本管理说明请参考 [VERSION.md](./VERSION.md)**
## 许可证
MIT License

174
SETUP.md
View File

@@ -1,174 +0,0 @@
# 项目配置说明
## GOPRIVATE 环境变量配置
由于本项目使用私有 Git 仓库 (`git.toowon.com`)，需要配置 `GOPRIVATE` 环境变量，让 Go 工具链知道这些模块是私有的，不要通过公共代理下载。
### 配置方法
#### 方法一：临时配置（当前终端会话有效）
```bash
# macOS/Linux
export GOPRIVATE=git.toowon.com
# Windows (PowerShell)
$env:GOPRIVATE="git.toowon.com"
# Windows (CMD)
set GOPRIVATE=git.toowon.com
```
#### 方法二：永久配置（推荐）
**macOS/Linux:**
1. 编辑 shell 配置文件（根据你使用的 shell 选择）：
```bash
# 如果是 zsh（macOS 默认）
nano ~/.zshrc
# 如果是 bash
nano ~/.bashrc
# 或
nano ~/.bash_profile
```
2. 添加以下内容：
```bash
export GOPRIVATE=git.toowon.com
```
3. 保存文件并重新加载配置：
```bash
# zsh
source ~/.zshrc
# bash
source ~/.bashrc
```
**Windows:**
1. 打开"系统属性" -> "高级" -> "环境变量"
2. 在"用户变量"或"系统变量"中点击"新建"
3. 变量名：`GOPRIVATE`
4. 变量值：`git.toowon.com`
5. 点击"确定"保存
#### 方法三：使用 go env 命令（推荐，Go 1.13+）
```bash
# 设置 GOPRIVATE
go env -w GOPRIVATE=git.toowon.com
# 查看当前配置
go env GOPRIVATE
# 如果需要设置多个私有仓库，用逗号分隔
go env -w GOPRIVATE=git.toowon.com,github.com/your-org
```
### 验证配置
```bash
# 查看 GOPRIVATE 配置
go env GOPRIVATE
# 应该输出: git.toowon.com
```
### 其他相关环境变量（可选）
如果需要更细粒度的控制，还可以配置：
```bash
# GOPRIVATE: 私有模块，不通过代理下载，不校验 checksum
go env -w GOPRIVATE=git.toowon.com
# GONOPROXY: 不通过代理下载的模块（默认与 GOPRIVATE 相同）
go env -w GONOPROXY=git.toowon.com
# GONOSUMDB: 不校验 checksum 的模块（默认与 GOPRIVATE 相同）
go env -w GONOSUMDB=git.toowon.com
```
### Git 认证配置
由于是私有仓库，还需要配置 Git 认证：
#### 方法一：使用 SSH（推荐）
1. 确保已配置 SSH 密钥
2. 使用 SSH URL：
```bash
git config --global url."git@git.toowon.com:".insteadOf "https://git.toowon.com/"
```
#### 方法二：使用 HTTPS + 个人访问令牌
1. 在 Git 服务器上生成个人访问令牌
2. 配置 Git 凭据：
```bash
git config --global credential.helper store
```
3. 首次访问时会提示输入用户名和令牌
#### 方法三：在 URL 中包含凭据（不推荐，安全性较低）
```bash
# 在 go.mod 中使用（不推荐）
# 或者通过 .netrc 文件配置
```
### 常见问题
#### 问题1：go get 失败，提示找不到模块
**解决方案：**
1. 确认 GOPRIVATE 已正确配置
2. 确认 Git 认证已配置
3. 尝试手动克隆仓库验证：
```bash
git clone git@git.toowon.com:jimmy/go-common.git
```
#### 问题2：go mod download 失败
**解决方案：**
```bash
# 清除模块缓存
go clean -modcache
# 重新下载
go mod download
```
#### 问题3：IDE 无法识别模块
**解决方案：**
1. 重启 IDE
2. 在 IDE 中执行：`go mod tidy`
3. 确认 IDE 的 Go 环境变量配置正确
### 完整配置示例
```bash
# 1. 配置 GOPRIVATE
go env -w GOPRIVATE=git.toowon.com
# 2. 配置 Git SSH（如果使用 SSH）
git config --global url."git@git.toowon.com:".insteadOf "https://git.toowon.com/"
# 3. 验证配置
go env | grep GOPRIVATE
# 4. 测试模块下载
go get git.toowon.com/jimmy/go-common@latest
```
### 参考文档
- [Go Modules 官方文档](https://go.dev/ref/mod)
- [Go 私有模块配置](https://go.dev/ref/mod#private-modules)

208
TROUBLESHOOTING.md
View File

@@ -1,208 +0,0 @@
# 故障排除指南
## 常见问题
### 1. 伪版本错误 (Pseudo-version error)
**错误信息：**
```
go: github.com/pmezard/go-difflib@v1.1.1-0.20181226105442-5d4384ee4fb2: invalid pseudo-version: preceding tag (v1.1.0) not found
```
**原因：**
- Go 模块缓存损坏
- 依赖版本冲突
- 间接依赖使用了无效的伪版本
**解决方案：**
#### 方案1：清理模块缓存（推荐）
```bash
# 清理 Go 模块缓存
go clean -modcache
# 重新下载依赖
go mod download
# 整理依赖
go mod tidy
```
#### 方案2：在调用方项目中解决
如果是在调用方项目中遇到此问题：
```bash
# 进入调用方项目目录
cd /path/to/your/project
# 清理模块缓存
go clean -modcache
# 删除 go.sum 文件（可选，会自动重新生成）
rm go.sum
# 重新获取依赖
go get git.toowon.com/jimmy/go-common@v0.0.1
# 整理依赖
go mod tidy
```
#### 方案3：使用代理（如果网络问题）
```bash
# 设置 Go 代理（国内用户推荐）
go env -w GOPROXY=https://goproxy.cn,direct
# 或者使用官方代理
go env -w GOPROXY=https://proxy.golang.org,direct
```
#### 方案4：强制更新依赖
```bash
# 强制更新所有依赖
go get -u ./...
# 或者更新特定依赖
go get -u git.toowon.com/jimmy/go-common@latest
```
### 2. 私有仓库访问问题
**错误信息：**
```
go: git.toowon.com/jimmy/go-common@v0.0.1: unrecognized import path
```
**解决方案：**
```bash
# 配置 GOPRIVATE
go env -w GOPRIVATE=git.toowon.com
# 配置 Git 认证（如果需要）
git config --global url."git@git.toowon.com:".insteadOf "https://git.toowon.com/"
```
详细说明请参考 [SETUP.md](./SETUP.md)
### 3. 版本标签不存在
**错误信息：**
```
go: git.toowon.com/jimmy/go-common@v0.0.1: invalid version: unknown revision
```
**解决方案：**
1. 确认版本标签已创建并推送：
```bash
# 在库项目中查看标签
git tag -l
# 如果标签不存在，创建并推送
git tag -a v0.0.1 -m "Release v0.0.1"
git push origin v0.0.1
```
2. 在调用方项目中清理缓存后重试：
```bash
go clean -modcache
go get git.toowon.com/jimmy/go-common@v0.0.1
```
### 4. 依赖版本冲突
**错误信息：**
```
go: conflicting versions for module
```
**解决方案：**
```bash
# 查看依赖树
go mod graph | grep conflicting-module
# 更新冲突的依赖
go get -u conflicting-module@latest
# 整理依赖
go mod tidy
```
### 5. 网络连接问题
**错误信息：**
```
dial tcp: lookup proxy.golang.org: no such host
```
**解决方案：**
```bash
# 使用国内代理
go env -w GOPROXY=https://goproxy.cn,direct
# 或者使用七牛云代理
go env -w GOPROXY=https://goproxy.io,direct
# 禁用代理（直接访问）
go env -w GOPROXY=direct
```
## 通用排查步骤
如果遇到其他问题，按以下步骤排查：
1. **清理缓存**
```bash
go clean -modcache
```
2. **验证模块**
```bash
go mod verify
```
3. **整理依赖**
```bash
go mod tidy
```
4. **查看依赖图**
```bash
go mod graph
```
5. **查看模块信息**
```bash
go list -m all
```
6. **检查 Go 环境**
```bash
go env
```
## 获取帮助
如果以上方法都无法解决问题，请：
1. 检查 Go 版本（建议使用 Go 1.21 或更高版本）
```bash
go version
```
2. 查看详细的错误信息
```bash
go get -v git.toowon.com/jimmy/go-common@v0.0.1
```
3. 检查项目仓库是否有对应的版本标签
4. 联系项目维护者

16
VERSION.md
View File

@@ -121,11 +121,23 @@ go get -u=minor git.toowon.com/jimmy/go-common
## 当前版本
当前版本：**v1.0.0**
当前版本：**v2.0.0**
## 版本历史
- **v1.0.0** (当前版本)
- **v2.0.0** (当前版本，Breaking)
- Factory 精简为 `Init` / `Default()` + lazy getter，删除全部透传方法
- HTTP 出参统一由 `http.Handler` 负责，删除包级 `Success` / `SystemError`
- Logger API 精简为 `Debug/Info/Error(msg, fields)`，新增 Request ID + `FromContext`
- email / sms 新增异步队列 + `Close()`
- 中间件链默认顺序：Recovery → RequestID → Logging → …
- **v1.0.0**
- 初始版本
- 包含所有基础工具类：migration、datetime、http、middleware、config、storage、email、sms、factory、logger
- **v1.1.0** (未发布)
- storage：新增本地文件夹存储（LocalStorage）
- config：新增 `localStorage` 配置段
- factory：支持 Local/MinIO/OSS 自动选择

167
config/config.go
View File

@@ -5,8 +5,6 @@ import (
"fmt"
"os"
"path/filepath"
"git.toowon.com/jimmy/go-common/middleware"
)
// Config 应用配置
@@ -16,9 +14,33 @@ type Config struct {
Redis *RedisConfig `json:"redis"`
CORS *CORSConfig `json:"cors"`
MinIO *MinIOConfig `json:"minio"`
Local *LocalStorageConfig `json:"localStorage"`
Email *EmailConfig `json:"email"`
SMS *SMSConfig `json:"sms"`
Logger *LoggerConfig `json:"logger"`
I18n *I18nConfig `json:"i18n"`
RateLimit *RateLimitConfig `json:"rateLimit"`
}
// I18nConfig 国际化配置
type I18nConfig struct {
DefaultLang string `json:"defaultLang"`
LocalesDir string `json:"localesDir"`
}
// LocalStorageConfig 本地存储配置
// 用于将文件保存到本地文件夹（适合开发环境、单机部署等场景）
type LocalStorageConfig struct {
// BaseDir 本地文件保存根目录（必填）
// 示例: "./uploads" 或 "/var/app/uploads"
BaseDir string `json:"baseDir"`
// PublicURL 对外访问URL（可选）
// 1) 若包含 "{objectKey}" 占位符，则会替换为 url.QueryEscape(objectKey)
// 示例: "http://localhost:8080/file?key={objectKey}" （配合 ProxyHandler 使用）
// 2) 若不包含占位符，则作为URL前缀，自动拼接 objectKey
// 示例: "http://localhost:8080/static/" => "http://localhost:8080/static/<objectKey>"
PublicURL string `json:"publicURL"`
}
// DatabaseConfig 数据库配置
@@ -193,6 +215,23 @@ type EmailConfig struct {
// Timeout 连接超时时间（秒）
Timeout int `json:"timeout"`
// Async 是否异步发送（默认 true，省略时启用）
Async *bool `json:"async"`
// Workers 异步 worker 数量（默认 2）
Workers int `json:"workers"`
// QueueSize 异步队列大小（默认 1000）
QueueSize int `json:"queueSize"`
}
// IsAsync 是否启用异步（默认 true）
func (c *EmailConfig) IsAsync() bool {
if c == nil || c.Async == nil {
return true
}
return *c.Async
}
// SMSConfig 短信配置（阿里云短信）
@@ -217,11 +256,28 @@ type SMSConfig struct {
// Timeout 请求超时时间（秒）
Timeout int `json:"timeout"`
// Async 是否异步发送（默认 true，省略时启用）
Async *bool `json:"async"`
// Workers 异步 worker 数量（默认 2）
Workers int `json:"workers"`
// QueueSize 异步队列大小（默认 1000）
QueueSize int `json:"queueSize"`
}
// IsAsync 是否启用异步（默认 true）
func (c *SMSConfig) IsAsync() bool {
if c == nil || c.Async == nil {
return true
}
return *c.Async
}
// LoggerConfig 日志配置
type LoggerConfig struct {
// Level 日志级别: debug, info, warn, error
// Level 日志级别: debug, info, error
Level string `json:"level"`
// Output 输出方式: stdout, stderr, file, both
@@ -235,6 +291,38 @@ type LoggerConfig struct {
// DisableTimestamp 禁用时间戳
DisableTimestamp bool `json:"disableTimestamp"`
// Async 是否使用异步模式（默认 true，省略时启用）
Async *bool `json:"async"`
// BufferSize 异步模式下的缓冲区大小（默认1000）
BufferSize int `json:"bufferSize"`
}
// IsAsync 是否启用异步（默认 true）
func (c *LoggerConfig) IsAsync() bool {
if c == nil || c.Async == nil {
return true
}
return *c.Async
}
// RateLimitConfig 限流配置
type RateLimitConfig struct {
// Enable 是否启用限流
Enable bool `json:"enable"`
// Rate 每个时间窗口允许的请求数量
Rate int `json:"rate"`
// Period 时间窗口（秒）
Period int `json:"period"`
// ByIP 按IP限流
ByIP bool `json:"byIP"`
// ByUserID 按用户ID限流（从X-User-ID header获取）
ByUserID bool `json:"byUserID"`
}
// LoadFromFile 从文件加载配置
@@ -342,13 +430,19 @@ func (c *Config) setDefaults() {
// 邮件默认值
if c.Email != nil {
if c.Email.Port == 0 {
c.Email.Port = 587 // 默认使用587端口（TLS）
c.Email.Port = 587
}
if c.Email.From == "" {
c.Email.From = c.Email.Username
}
if c.Email.Timeout == 0 {
c.Email.Timeout = 30
c.Email.Timeout = 5
}
if c.Email.Workers == 0 {
c.Email.Workers = 2
}
if c.Email.QueueSize == 0 {
c.Email.QueueSize = 1000
}
}
@@ -358,7 +452,13 @@ func (c *Config) setDefaults() {
c.SMS.Region = "cn-hangzhou"
}
if c.SMS.Timeout == 0 {
c.SMS.Timeout = 10
c.SMS.Timeout = 5
}
if c.SMS.Workers == 0 {
c.SMS.Workers = 2
}
if c.SMS.QueueSize == 0 {
c.SMS.QueueSize = 1000
}
}
@@ -370,6 +470,27 @@ func (c *Config) setDefaults() {
if c.Logger.Output == "" {
c.Logger.Output = "stdout"
}
if c.Logger.BufferSize == 0 {
c.Logger.BufferSize = 1000
}
}
// i18n 默认值
if c.I18n != nil && c.I18n.DefaultLang == "" {
c.I18n.DefaultLang = "zh-CN"
}
// 限流默认值
if c.RateLimit != nil {
if c.RateLimit.Rate == 0 {
c.RateLimit.Rate = 100 // 默认每个窗口100个请求
}
if c.RateLimit.Period == 0 {
c.RateLimit.Period = 60 // 默认时间窗口60秒
}
if !c.RateLimit.ByIP && !c.RateLimit.ByUserID {
c.RateLimit.ByIP = true // 默认按IP限流
}
}
}
@@ -388,20 +509,11 @@ func (c *Config) GetRedis() *RedisConfig {
return c.Redis
}
// GetCORS 获取CORS配置，并转换为middleware.CORSConfig
func (c *Config) GetCORS() *middleware.CORSConfig {
if c.CORS == nil {
return middleware.DefaultCORSConfig()
}
return &middleware.CORSConfig{
AllowedOrigins: c.CORS.AllowedOrigins,
AllowedMethods: c.CORS.AllowedMethods,
AllowedHeaders: c.CORS.AllowedHeaders,
ExposedHeaders: c.CORS.ExposedHeaders,
AllowCredentials: c.CORS.AllowCredentials,
MaxAge: c.CORS.MaxAge,
}
// GetCORS 获取CORS配置
// 返回的是 config.CORSConfig，需要转换为 middleware.CORSConfig 时
// 可以使用 middleware.CORSFromConfig() 函数
func (c *Config) GetCORS() *CORSConfig {
return c.CORS
}
// GetMinIO 获取MinIO配置
@@ -409,6 +521,11 @@ func (c *Config) GetMinIO() *MinIOConfig {
return c.MinIO
}
// GetLocalStorage 获取本地存储配置
func (c *Config) GetLocalStorage() *LocalStorageConfig {
return c.Local
}
// GetEmail 获取邮件配置
func (c *Config) GetEmail() *EmailConfig {
return c.Email
@@ -424,6 +541,11 @@ func (c *Config) GetLogger() *LoggerConfig {
return c.Logger
}
// GetI18n 获取国际化配置
func (c *Config) GetI18n() *I18nConfig {
return c.I18n
}
// GetDatabaseDSN 获取数据库连接字符串
func (c *Config) GetDatabaseDSN() (string, error) {
if c.Database == nil {
@@ -498,3 +620,8 @@ func (c *Config) GetRedisAddr() string {
// 构建地址
return fmt.Sprintf("%s:%d", c.Redis.Host, c.Redis.Port)
}
// BoolPtr 返回 bool 指针（用于配置默认值）
func BoolPtr(v bool) *bool {
return &v
}

15
config/example.json
View File

@@ -50,6 +50,10 @@
"region": "us-east-1",
"domain": "http://localhost:9000"
},
"localStorage": {
"baseDir": "./uploads",
"publicURL": "http://localhost:8080/file?key={objectKey}"
},
"email": {
"host": "smtp.example.com",
"port": 587,
@@ -75,7 +79,16 @@
"output": "stdout",
"filePath": "",
"prefix": "app",
"disableTimestamp": false
"disableTimestamp": false,
"async": false,
"bufferSize": 1000
},
"rateLimit": {
"enable": true,
"rate": 100,
"period": 60,
"byIP": true,
"byUserID": false
}
}

112
docs/README.md
View File

@@ -1,112 +0,0 @@
# GoCommon 工具类库文档
## 目录
- [数据库迁移工具](./migration.md) - 数据库版本管理和迁移
- [日期转换工具](./datetime.md) - 日期时间处理和时区转换
- [HTTP Restful工具](./http.md) - HTTP请求响应处理和分页
- [中间件工具](./middleware.md) - CORS和时区处理中间件
- [配置工具](./config.md) - 外部配置文件加载和管理
- [存储工具](./storage.md) - 文件上传和查看（OSS、MinIO）
- [邮件工具](./email.md) - SMTP邮件发送
- [短信工具](./sms.md) - 阿里云短信发送
- [工厂工具](./factory.md) - 从配置直接创建已初始化客户端对象
- [日志工具](./logger.md) - 统一的日志记录功能
## 快速开始
### 安装
```bash
go get git.toowon.com/jimmy/go-common
```
### 使用示例
#### 数据库迁移
```go
import "git.toowon.com/jimmy/go-common/migration"
migrator := migration.NewMigrator(db)
migrator.AddMigration(migration.Migration{
Version: "20240101000001",
Description: "create_users_table",
Up: func(db *gorm.DB) error {
return db.Exec("CREATE TABLE users ...").Error
},
})
migrator.Up()
```
#### 日期转换
```go
import "git.toowon.com/jimmy/go-common/datetime"
datetime.SetDefaultTimeZone(datetime.AsiaShanghai)
now := datetime.Now()
str := datetime.FormatDateTime(now)
```
#### HTTP响应（Handler黑盒模式）
```go
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))
```
#### 中间件
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/middleware"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
// CORS + 时区中间件
chain := middleware.NewChain(
middleware.CORS(),
middleware.Timezone,
)
handler := chain.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
// 在Handler中获取时区
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

516
docs/config.md
View File

@@ -1,516 +0,0 @@
# 配置工具文档
## 概述
配置工具提供了从外部文件加载和管理应用配置的功能，支持数据库、OSS、Redis、CORS、MinIO、邮件、短信等常用服务的配置。
## 功能特性
- 支持从外部JSON文件加载配置
- 支持数据库配置（MySQL、PostgreSQL、SQLite）
- 支持OSS对象存储配置（阿里云、腾讯云、AWS、七牛云等）
- 支持Redis配置
- 支持CORS配置（与middleware包集成）
- 支持MinIO配置
- 支持邮件配置（SMTP）
- 支持短信配置（阿里云短信）
- 自动设置默认值
- 自动生成数据库连接字符串（DSN）
- 自动生成Redis地址
## 配置文件格式
配置文件采用JSON格式，支持以下配置项：
```json
{
"database": {
"type": "mysql",
"host": "localhost",
"port": 3306,
"user": "root",
"password": "password",
"database": "testdb",
"charset": "utf8mb4",
"maxOpenConns": 100,
"maxIdleConns": 10,
"connMaxLifetime": 3600
},
"oss": {
"provider": "aliyun",
"endpoint": "oss-cn-hangzhou.aliyuncs.com",
"accessKeyId": "your-access-key-id",
"accessKeySecret": "your-access-key-secret",
"bucket": "your-bucket-name",
"region": "cn-hangzhou",
"useSSL": true,
"domain": "https://cdn.example.com"
},
"redis": {
"host": "localhost",
"port": 6379,
"password": "",
"database": 0,
"maxRetries": 3,
"poolSize": 10,
"minIdleConns": 5,
"dialTimeout": 5,
"readTimeout": 3,
"writeTimeout": 3
},
"cors": {
"allowedOrigins": ["*"],
"allowedMethods": ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
"allowedHeaders": ["Content-Type", "Authorization", "X-Requested-With", "X-Timezone"],
"exposedHeaders": [],
"allowCredentials": false,
"maxAge": 86400
},
"minio": {
"endpoint": "localhost:9000",
"accessKeyId": "minioadmin",
"secretAccessKey": "minioadmin",
"useSSL": false,
"bucket": "test-bucket",
"region": "us-east-1",
"domain": "http://localhost:9000"
},
"email": {
"host": "smtp.example.com",
"port": 587,
"username": "your-email@example.com",
"password": "your-email-password",
"from": "your-email@example.com",
"fromName": "Your App Name",
"useTLS": true,
"useSSL": false,
"timeout": 30
},
"sms": {
"accessKeyId": "your-aliyun-access-key-id",
"accessKeySecret": "your-aliyun-access-key-secret",
"region": "cn-hangzhou",
"signName": "Your Sign Name",
"templateCode": "SMS_123456789",
"endpoint": "",
"timeout": 10
}
}
```
## 使用方法
### 1. 加载配置文件
```go
import "git.toowon.com/jimmy/go-common/config"
// 从文件加载配置（支持绝对路径和相对路径）
config, err := config.LoadFromFile("/path/to/config.json")
if err != nil {
log.Fatal(err)
}
// 或者从字节数组加载
data := []byte(`{"database": {...}}`)
config, err := config.LoadFromBytes(data)
```
### 2. 获取数据库配置
```go
// 获取数据库配置对象
dbConfig := config.GetDatabase()
if dbConfig != nil {
fmt.Printf("Database: %s@%s:%d/%s\n",
dbConfig.User, dbConfig.Host, dbConfig.Port, dbConfig.Database)
}
// 获取数据库连接字符串（DSN）
dsn, err := config.GetDatabaseDSN()
if err != nil {
log.Fatal(err)
}
// MySQL: "root:password@tcp(localhost:3306)/testdb?charset=utf8mb4&parseTime=True&loc=UTC"
// PostgreSQL: "host=localhost port=5432 user=root password=password dbname=testdb timezone=UTC sslmode=disable"
// 注意：数据库时间统一使用UTC时间
```
### 3. 获取OSS配置
```go
ossConfig := config.GetOSS()
if ossConfig != nil {
fmt.Printf("OSS Provider: %s\n", ossConfig.Provider)
fmt.Printf("Endpoint: %s\n", ossConfig.Endpoint)
fmt.Printf("Bucket: %s\n", ossConfig.Bucket)
}
```
### 4. 获取Redis配置
```go
redisConfig := config.GetRedis()
if redisConfig != nil {
fmt.Printf("Redis: %s:%d\n", redisConfig.Host, redisConfig.Port)
}
// 获取Redis地址（格式: host:port）
addr := config.GetRedisAddr()
// 输出: "localhost:6379"
```
### 5. 获取CORS配置
```go
// 获取CORS配置（返回middleware.CORSConfig类型，可直接用于中间件）
corsConfig := config.GetCORS()
// 使用CORS中间件
import "git.toowon.com/jimmy/go-common/middleware"
chain := middleware.NewChain(
middleware.CORS(corsConfig),
)
```
### 6. 获取MinIO配置
```go
minioConfig := config.GetMinIO()
if minioConfig != nil {
fmt.Printf("MinIO Endpoint: %s\n", minioConfig.Endpoint)
fmt.Printf("Bucket: %s\n", minioConfig.Bucket)
}
```
## 配置项说明
### DatabaseConfig 数据库配置
| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| Type | string | 数据库类型: mysql, postgres, sqlite | - |
| Host | string | 数据库主机 | - |
| Port | int | 数据库端口 | - |
| User | string | 数据库用户名 | - |
| Password | string | 数据库密码 | - |
| Database | string | 数据库名称 | - |
| Charset | string | 字符集（MySQL使用） | utf8mb4 |
| MaxOpenConns | int | 最大打开连接数 | 100 |
| MaxIdleConns | int | 最大空闲连接数 | 10 |
| ConnMaxLifetime | int | 连接最大生存时间（秒） | 3600 |
| DSN | string | 数据库连接字符串（如果设置，优先使用） | - |
### OSSConfig OSS配置
| 字段 | 类型 | 说明 |
|------|------|------|
| Provider | string | 提供商: aliyun, tencent, aws, qiniu |
| Endpoint | string | 端点地址 |
| AccessKeyID | string | 访问密钥ID |
| AccessKeySecret | string | 访问密钥 |
| Bucket | string | 存储桶名称 |
| Region | string | 区域 |
| UseSSL | bool | 是否使用SSL |
| Domain | string | 自定义域名（CDN域名） |
### RedisConfig Redis配置
| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| Host | string | Redis主机 | - |
| Port | int | Redis端口 | 6379 |
| Password | string | Redis密码 | - |
| Database | int | Redis数据库编号 | 0 |
| MaxRetries | int | 最大重试次数 | 3 |
| PoolSize | int | 连接池大小 | 10 |
| MinIdleConns | int | 最小空闲连接数 | 5 |
| DialTimeout | int | 连接超时时间（秒） | 5 |
| ReadTimeout | int | 读取超时时间（秒） | 3 |
| WriteTimeout | int | 写入超时时间（秒） | 3 |
| Addr | string | Redis地址（如果设置，优先使用） | - |
### CORSConfig CORS配置
| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| AllowedOrigins | []string | 允许的源 | ["*"] |
| AllowedMethods | []string | 允许的HTTP方法 | ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"] |
| AllowedHeaders | []string | 允许的请求头 | ["Content-Type", "Authorization", "X-Requested-With", "X-Timezone"] |
| ExposedHeaders | []string | 暴露给客户端的响应头 | [] |
| AllowCredentials | bool | 是否允许发送凭证 | false |
| MaxAge | int | 预检请求的缓存时间（秒） | 86400 |
### MinIOConfig MinIO配置
| 字段 | 类型 | 说明 |
|------|------|------|
| Endpoint | string | MinIO端点地址 |
| AccessKeyID | string | 访问密钥ID |
| SecretAccessKey | string | 密钥 |
| UseSSL | bool | 是否使用SSL |
| Bucket | string | 存储桶名称 |
| Region | string | 区域 |
| Domain | string | 自定义域名 |
### EmailConfig 邮件配置
| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| Host | string | SMTP服务器地址 | - |
| Port | int | SMTP服务器端口 | 587 |
| Username | string | 发件人邮箱 | - |
| Password | string | 邮箱密码或授权码 | - |
| From | string | 发件人邮箱地址（如果为空，使用Username） | Username |
| FromName | string | 发件人名称 | - |
| UseTLS | bool | 是否使用TLS | false |
| UseSSL | bool | 是否使用SSL | false |
| Timeout | int | 连接超时时间（秒） | 30 |
### SMSConfig 短信配置（阿里云短信）
| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| AccessKeyID | string | 阿里云AccessKey ID | - |
| AccessKeySecret | string | 阿里云AccessKey Secret | - |
| Region | string | 区域（如：cn-hangzhou） | cn-hangzhou |
| SignName | string | 短信签名 | - |
| TemplateCode | string | 短信模板代码 | - |
| Endpoint | string | 服务端点（可选，默认使用区域端点） | - |
| Timeout | int | 请求超时时间（秒） | 10 |
### LoggerConfig 日志配置
| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| Level | string | 日志级别: debug, info, warn, error | info |
| Output | string | 输出方式: stdout, stderr, file, both | stdout |
| FilePath | string | 日志文件路径（当output为file或both时必需） | - |
| Prefix | string | 日志前缀 | - |
| DisableTimestamp | bool | 禁用时间戳 | false |
## 完整示例
### 示例1：加载配置并使用
```go
package main
import (
"log"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/middleware"
"gorm.io/driver/mysql"
"gorm.io/gorm"
)
func main() {
// 加载配置
cfg, err := config.LoadFromFile("./config.json")
if err != nil {
log.Fatal(err)
}
// 使用数据库配置
dsn, err := cfg.GetDatabaseDSN()
if err != nil {
log.Fatal(err)
}
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
if err != nil {
log.Fatal(err)
}
// 使用Redis配置
redisAddr := cfg.GetRedisAddr()
fmt.Printf("Redis Address: %s\n", redisAddr)
// 使用CORS配置
corsConfig := cfg.GetCORS()
chain := middleware.NewChain(
middleware.CORS(corsConfig),
)
// 使用OSS配置
ossConfig := cfg.GetOSS()
if ossConfig != nil {
fmt.Printf("OSS Provider: %s\n", ossConfig.Provider)
}
// 使用MinIO配置
minioConfig := cfg.GetMinIO()
if minioConfig != nil {
fmt.Printf("MinIO Endpoint: %s\n", minioConfig.Endpoint)
}
}
```
### 示例2：部分配置
配置文件可以只包含需要的配置项：
```json
{
"database": {
"type": "mysql",
"host": "localhost",
"port": 3306,
"user": "root",
"password": "password",
"database": "testdb"
},
"redis": {
"host": "localhost",
"port": 6379
}
}
```
未配置的部分会返回nil，需要在使用前检查：
```go
cfg, _ := config.LoadFromFile("./config.json")
dbConfig := cfg.GetDatabase()
if dbConfig != nil {
// 使用数据库配置
}
ossConfig := cfg.GetOSS()
if ossConfig == nil {
// OSS未配置
}
```
### 示例3：使用DSN字段
如果配置文件中直接提供了DSN，会优先使用：
```json
{
"database": {
"type": "mysql",
"dsn": "root:password@tcp(localhost:3306)/testdb?charset=utf8mb4&parseTime=True"
}
}
```
```go
dsn, err := cfg.GetDatabaseDSN()
// 直接返回配置中的DSN，不会重新构建
```
## API 参考
### LoadFromFile(filePath string) (*Config, error)
从文件加载配置。
**参数：**
- `filePath`: 配置文件路径（支持绝对路径和相对路径）
**返回：** 配置对象和错误信息
### LoadFromBytes(data []byte) (*Config, error)
从字节数组加载配置。
**参数：**
- `data`: JSON格式的配置数据
**返回：** 配置对象和错误信息
### (c *Config) GetDatabase() *DatabaseConfig
获取数据库配置。
**返回：** 数据库配置对象（可能为nil）
### (c *Config) GetDatabaseDSN() (string, error)
获取数据库连接字符串。
**返回：** DSN字符串和错误信息
### (c *Config) GetOSS() *OSSConfig
获取OSS配置。
**返回：** OSS配置对象（可能为nil）
### (c *Config) GetRedis() *RedisConfig
获取Redis配置。
**返回：** Redis配置对象（可能为nil）
### (c *Config) GetRedisAddr() string
获取Redis地址（格式: host:port）。
**返回：** Redis地址字符串
### (c *Config) GetCORS() *middleware.CORSConfig
获取CORS配置，并转换为middleware.CORSConfig类型。
**返回：** CORS配置对象（如果配置为nil，返回默认配置）
### (c *Config) GetMinIO() *MinIOConfig
获取MinIO配置。
**返回：** MinIO配置对象（可能为nil）
### (c *Config) GetEmail() *EmailConfig
获取邮件配置。
**返回：** 邮件配置对象（可能为nil）
### (c *Config) GetSMS() *SMSConfig
获取短信配置。
**返回：** 短信配置对象（可能为nil）
### (c *Config) GetLogger() *LoggerConfig
获取日志配置。
**返回：** 日志配置对象（可能为nil）
## 注意事项
1. **配置文件路径**：
- 支持绝对路径和相对路径
- 相对路径基于当前工作目录
2. **默认值**：
- 配置加载时会自动设置默认值
- 如果配置项为nil，对应的Get方法会返回nil
3. **DSN优先级**：
- 如果配置中设置了DSN字段，会优先使用
- 否则会根据配置项自动构建DSN
4. **配置验证**：
- 当前版本不进行配置验证，请确保配置正确
- 建议在生产环境中添加配置验证逻辑
5. **安全性**：
- 配置文件可能包含敏感信息（密码、密钥等）
- 建议将配置文件放在安全的位置，不要提交到版本控制系统
- 可以使用环境变量或配置管理服务
6. **数据库时区**：
- 数据库时间统一使用UTC时间存储
- DSN中会自动设置UTC时区（MySQL: loc=UTC, PostgreSQL: timezone=UTC）
- 时区转换应在应用层处理，使用datetime工具包进行时区转换
## 配置文件示例
完整配置文件示例请参考 `config/example.json`

461
docs/datetime.md
View File

@@ -1,461 +0,0 @@
# 日期转换工具文档
## 概述
日期转换工具提供了丰富的日期时间处理功能，支持时区设定、格式转换、时间计算等常用操作。
## 功能特性
- 支持时区设定和转换
- 支持多种时间格式的解析和格式化
- 提供常用时间格式常量
- 支持Unix时间戳转换
- 提供时间计算功能（添加天数、月数、年数等）
- 提供时间范围获取功能（开始/结束时间）
- 支持将任意时区时间转换为UTC时间（用于数据库存储）
## 使用方法
### 1. 设置默认时区
```go
import "git.toowon.com/jimmy/go-common/datetime"
// 设置默认时区为上海时区
err := datetime.SetDefaultTimeZone(datetime.AsiaShanghai)
if err != nil {
log.Fatal(err)
}
```
### 2. 获取当前时间
```go
// 使用默认时区
now := datetime.Now()
// 使用指定时区
now := datetime.Now(datetime.AsiaShanghai)
now := datetime.Now("America/New_York")
```
### 3. 解析时间字符串
```go
// 使用默认时区解析
t, err := datetime.Parse("2006-01-02 15:04:05", "2024-01-01 12:00:00")
if err != nil {
log.Fatal(err)
}
// 使用指定时区解析
t, err := datetime.Parse("2006-01-02 15:04:05", "2024-01-01 12:00:00", datetime.AsiaShanghai)
// 使用常用格式解析
t, err := datetime.ParseDateTime("2024-01-01 12:00:00")
t, err := datetime.ParseDate("2024-01-01")
```
### 4. 格式化时间
```go
t := time.Now()
// 使用默认时区格式化
str := datetime.Format(t, "2006-01-02 15:04:05")
// 使用指定时区格式化
str := datetime.Format(t, "2006-01-02 15:04:05", datetime.AsiaShanghai)
// 使用常用格式
str := datetime.FormatDateTime(t) // "2006-01-02 15:04:05"
str := datetime.FormatDate(t) // "2006-01-02"
str := datetime.FormatTime(t) // "15:04:05"
```
### 5. 时区转换
```go
t := time.Now()
// 转换到指定时区
t2, err := datetime.ToTimezone(t, datetime.AsiaShanghai)
if err != nil {
log.Fatal(err)
}
```
### 6. Unix时间戳转换
```go
t := time.Now()
// 转换为Unix时间戳（秒）
unix := datetime.ToUnix(t)
// 从Unix时间戳创建时间
t2 := datetime.FromUnix(unix)
// 转换为Unix毫秒时间戳
unixMilli := datetime.ToUnixMilli(t)
// 从Unix毫秒时间戳创建时间
t3 := datetime.FromUnixMilli(unixMilli)
```
### 7. 时间计算
```go
t := time.Now()
// 添加天数
t1 := datetime.AddDays(t, 7)
// 添加月数
t2 := datetime.AddMonths(t, 1)
// 添加年数
t3 := datetime.AddYears(t, 1)
```
### 8. 时间范围获取
```go
t := time.Now()
// 获取一天的开始时间（00:00:00）
start := datetime.StartOfDay(t)
// 获取一天的结束时间（23:59:59.999999999）
end := datetime.EndOfDay(t)
// 获取月份的开始时间
monthStart := datetime.StartOfMonth(t)
// 获取月份的结束时间
monthEnd := datetime.EndOfMonth(t)
// 获取年份的开始时间
yearStart := datetime.StartOfYear(t)
// 获取年份的结束时间
yearEnd := datetime.EndOfYear(t)
```
### 9. 时间差计算
```go
t1 := time.Now()
t2 := time.Now().Add(24 * time.Hour)
// 计算天数差
days := datetime.DiffDays(t1, t2)
// 计算小时差
hours := datetime.DiffHours(t1, t2)
// 计算分钟差
minutes := datetime.DiffMinutes(t1, t2)
// 计算秒数差
seconds := datetime.DiffSeconds(t1, t2)
```
### 10. 转换为UTC时间（用于数据库存储）
```go
// 将任意时区的时间转换为UTC
t := time.Now() // 当前时区的时间
utcTime := datetime.ToUTC(t)
// 从指定时区转换为UTC
t, _ := datetime.ParseDateTime("2024-01-01 12:00:00", datetime.AsiaShanghai)
utcTime, err := datetime.ToUTCFromTimezone(t, datetime.AsiaShanghai)
// 解析时间字符串并直接转换为UTC
utcTime, err := datetime.ParseDateTimeToUTC("2024-01-01 12:00:00", datetime.AsiaShanghai)
// 解析日期并转换为UTC（当天的00:00:00 UTC）
utcTime, err := datetime.ParseDateToUTC("2024-01-01", datetime.AsiaShanghai)
```
## API 参考
### 时区常量
```go
const (
UTC = "UTC"
AsiaShanghai = "Asia/Shanghai"
AmericaNewYork = "America/New_York"
EuropeLondon = "Europe/London"
AsiaTokyo = "Asia/Tokyo"
)
```
### 常用时间格式
```go
CommonLayouts.DateTime = "2006-01-02 15:04"
CommonLayouts.DateTimeSec = "2006-01-02 15:04:05"
CommonLayouts.Date = "2006-01-02"
CommonLayouts.Time = "15:04"
CommonLayouts.TimeSec = "15:04:05"
CommonLayouts.ISO8601 = "2006-01-02T15:04:05Z07:00"
CommonLayouts.RFC3339 = time.RFC3339
CommonLayouts.RFC3339Nano = time.RFC3339Nano
```
### 主要函数
#### SetDefaultTimeZone(timezone string) error
设置默认时区。
**参数：**
- `timezone`: 时区字符串，如 "Asia/Shanghai"
**返回：** 错误信息
#### Now(timezone ...string) time.Time
获取当前时间。
**参数：**
- `timezone`: 可选，时区字符串，不指定则使用默认时区
**返回：** 时间对象
#### Parse(layout, value string, timezone ...string) (time.Time, error)
解析时间字符串。
**参数：**
- `layout`: 时间格式，如 "2006-01-02 15:04:05"
- `value`: 时间字符串
- `timezone`: 可选，时区字符串
**返回：** 时间对象和错误信息
#### Format(t time.Time, layout string, timezone ...string) string
格式化时间。
**参数：**
- `t`: 时间对象
- `layout`: 时间格式
- `timezone`: 可选，时区字符串
**返回：** 格式化后的时间字符串
#### ToTimezone(t time.Time, timezone string) (time.Time, error)
转换时区。
**参数：**
- `t`: 时间对象
- `timezone`: 目标时区
**返回：** 转换后的时间对象和错误信息
#### ToUnix(t time.Time) int64
转换为Unix时间戳（秒）。
#### FromUnix(sec int64, timezone ...string) time.Time
从Unix时间戳创建时间。
#### ToUnixMilli(t time.Time) int64
转换为Unix毫秒时间戳。
#### FromUnixMilli(msec int64, timezone ...string) time.Time
从Unix毫秒时间戳创建时间。
#### AddDays(t time.Time, days int) time.Time
添加天数。
#### AddMonths(t time.Time, months int) time.Time
添加月数。
#### AddYears(t time.Time, years int) time.Time
添加年数。
#### StartOfDay(t time.Time, timezone ...string) time.Time
获取一天的开始时间。
#### EndOfDay(t time.Time, timezone ...string) time.Time
获取一天的结束时间。
#### StartOfMonth(t time.Time, timezone ...string) time.Time
获取月份的开始时间。
#### EndOfMonth(t time.Time, timezone ...string) time.Time
获取月份的结束时间。
#### StartOfYear(t time.Time, timezone ...string) time.Time
获取年份的开始时间。
#### EndOfYear(t time.Time, timezone ...string) time.Time
获取年份的结束时间。
#### DiffDays(t1, t2 time.Time) int
计算两个时间之间的天数差。
#### DiffHours(t1, t2 time.Time) int64
计算两个时间之间的小时差。
#### DiffMinutes(t1, t2 time.Time) int64
计算两个时间之间的分钟差。
#### DiffSeconds(t1, t2 time.Time) int64
计算两个时间之间的秒数差。
### UTC转换函数
#### ToUTC(t time.Time) time.Time
将时间转换为UTC时间。
**参数：**
- `t`: 时间对象（可以是任意时区）
**返回：** UTC时间
#### ToUTCFromTimezone(t time.Time, timezone string) (time.Time, error)
从指定时区转换为UTC时间。
**参数：**
- `t`: 时间对象（会被视为指定时区的时间）
- `timezone`: 源时区
**返回：** UTC时间和错误信息
#### ParseToUTC(layout, value string, timezone ...string) (time.Time, error)
解析时间字符串并转换为UTC时间。
**参数：**
- `layout`: 时间格式，如 "2006-01-02 15:04:05"
- `value`: 时间字符串
- `timezone`: 源时区，如果为空则使用默认时区
**返回：** UTC时间和错误信息
#### ParseDateTimeToUTC(value string, timezone ...string) (time.Time, error)
解析日期时间字符串并转换为UTC时间（便捷方法）。
**参数：**
- `value`: 时间字符串（格式: 2006-01-02 15:04:05）
- `timezone`: 源时区，如果为空则使用默认时区
**返回：** UTC时间和错误信息
#### ParseDateToUTC(value string, timezone ...string) (time.Time, error)
解析日期字符串并转换为UTC时间（便捷方法）。
**参数：**
- `value`: 日期字符串（格式: 2006-01-02）
- `timezone`: 源时区，如果为空则使用默认时区
**返回：** UTC时间（当天的00:00:00 UTC时间）和错误信息
## 注意事项
1. **时区字符串**：必须符合IANA时区数据库格式
2. **默认时区**：默认时区为UTC，建议在应用启动时设置合适的默认时区
3. **时间格式**：时间格式字符串必须使用Go的特定时间（2006-01-02 15:04:05）
4. **时间范围函数**：所有时间范围函数（StartOfDay、EndOfDay等）都会考虑时区
5. **数据库存储**：
- 数据库时间统一使用UTC时间存储
- 使用`ToUTC`、`ParseToUTC`等方法将时间转换为UTC后存储到数据库
- 从数据库读取UTC时间后，使用`ToTimezone`转换为用户时区显示
## 完整示例
### 示例1：基本使用
```go
package main
import (
"fmt"
"log"
"time"
"git.toowon.com/jimmy/go-common/datetime"
)
func main() {
// 设置默认时区
datetime.SetDefaultTimeZone(datetime.AsiaShanghai)
// 获取当前时间
now := datetime.Now()
fmt.Printf("Current time: %s\n", datetime.FormatDateTime(now))
// 时区转换
t, _ := datetime.ParseDateTime("2024-01-01 12:00:00")
t2, _ := datetime.ToTimezone(t, datetime.AmericaNewYork)
fmt.Printf("Time in New York: %s\n", datetime.FormatDateTime(t2))
}
```
### 示例2：UTC转换（数据库存储场景）
```go
package main
import (
"fmt"
"log"
"git.toowon.com/jimmy/go-common/datetime"
)
func main() {
// 从请求中获取时间（假设是上海时区）
requestTimeStr := "2024-01-01 12:00:00"
requestTimezone := datetime.AsiaShanghai
// 转换为UTC时间（用于数据库存储）
dbTime, err := datetime.ParseDateTimeToUTC(requestTimeStr, requestTimezone)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Request time (Shanghai): %s\n", requestTimeStr)
fmt.Printf("Database time (UTC): %s\n", datetime.FormatDateTime(dbTime, datetime.UTC))
// 从数据库读取UTC时间，转换为用户时区显示
userTimezone := datetime.AsiaShanghai
displayTime, err := datetime.ToTimezone(dbTime, userTimezone)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Display time (Shanghai): %s\n", datetime.FormatDateTime(displayTime, userTimezone))
}
```
完整示例请参考：
- `examples/datetime_example.go` - 基本使用示例
- `examples/datetime_utc_example.go` - UTC转换示例

332
docs/email.md
View File

@@ -1,332 +0,0 @@
# 邮件工具文档
## 概述
邮件工具提供了SMTP邮件发送功能，使用Go标准库实现，无需第三方依赖。
## 功能特性
- 支持SMTP邮件发送
- 支持TLS/SSL加密
- 支持发送原始邮件内容（完全由外部控制）
- 支持便捷方法发送简单邮件
- 使用配置工具统一管理配置
## 使用方法
### 1. 创建邮件发送器
```go
import (
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/email"
)
// 从配置加载
cfg, err := config.LoadFromFile("./config.json")
if err != nil {
log.Fatal(err)
}
emailConfig := cfg.GetEmail()
if emailConfig == nil {
log.Fatal("email config is nil")
}
// 创建邮件发送器
mailer, err := email.NewEmail(emailConfig)
if err != nil {
log.Fatal(err)
}
```
### 2. 发送原始邮件内容（推荐，最灵活）
```go
// 外部构建完整的邮件内容（MIME格式）
emailBody := []byte(`From: sender@example.com
To: recipient@example.com
Subject: 邮件主题
Content-Type: text/html; charset=UTF-8
<html>
<body>
<h1>邮件内容</h1>
<p>这是由外部构建的完整邮件内容</p>
</body>
</html>
`)
// 发送邮件（工具只负责SMTP发送，不构建内容）
err := mailer.SendRaw(
[]string{"recipient@example.com"}, // 收件人列表
emailBody, // 完整的邮件内容
)
if err != nil {
log.Fatal(err)
}
```
### 3. 发送简单邮件（便捷方法）
```go
// 发送纯文本邮件（内部会构建邮件内容）
err := mailer.SendSimple(
[]string{"recipient@example.com"},
"邮件主题",
"邮件正文内容",
)
if err != nil {
log.Fatal(err)
}
```
### 4. 发送HTML邮件（便捷方法）
```go
// 发送HTML邮件（内部会构建邮件内容）
htmlBody := `
<html>
<body>
<h1>欢迎</h1>
<p>这是一封HTML邮件</p>
</body>
</html>
`
err := mailer.SendHTML(
[]string{"recipient@example.com"},
"邮件主题",
htmlBody,
)
if err != nil {
log.Fatal(err)
}
```
### 5. 使用Message结构发送（便捷方法）
```go
import "git.toowon.com/jimmy/go-common/email"
msg := &email.Message{
To: []string{"to@example.com"},
Cc: []string{"cc@example.com"},
Bcc: []string{"bcc@example.com"},
Subject: "邮件主题",
Body: "纯文本正文",
HTMLBody: "<html><body><h1>HTML正文</h1></body></html>",
}
err := mailer.Send(msg)
if err != nil {
log.Fatal(err)
}
```
## API 参考
### NewEmail(cfg *config.EmailConfig) (*Email, error)
创建邮件发送器。
**参数：**
- `cfg`: 邮件配置对象
**返回：** 邮件发送器实例和错误信息
### (e *Email) SendRaw(recipients []string, body []byte) error
发送原始邮件内容（推荐使用，最灵活）。
**参数：**
- `recipients`: 收件人列表（To、Cc、Bcc的合并列表）
- `body`: 完整的邮件内容（MIME格式），由外部构建
**返回：** 错误信息
**说明：** 此方法允许外部完全控制邮件内容，工具只负责SMTP发送。
### (e *Email) Send(msg *Message) error
发送邮件（使用Message结构，内部会构建邮件内容）。
**参数：**
- `msg`: 邮件消息对象
**返回：** 错误信息
**说明：** 如果需要完全控制邮件内容，请使用SendRaw方法。
### (e *Email) SendSimple(to []string, subject, body string) error
发送简单邮件（便捷方法）。
**参数：**
- `to`: 收件人列表
- `subject`: 主题
- `body`: 正文
### (e *Email) SendHTML(to []string, subject, htmlBody string) error
发送HTML邮件（便捷方法）。
**参数：**
- `to`: 收件人列表
- `subject`: 主题
- `htmlBody`: HTML正文
### Message 结构体
```go
type Message struct {
To []string // 收件人列表
Cc []string // 抄送列表（可选）
Bcc []string // 密送列表（可选）
Subject string // 主题
Body string // 正文（纯文本）
HTMLBody string // HTML正文（可选）
Attachments []Attachment // 附件列表（可选）
}
```
### Attachment 结构体
```go
type Attachment struct {
Filename string // 文件名
Content []byte // 文件内容
ContentType string // 文件类型
}
```
## 配置说明
邮件配置通过 `config.EmailConfig` 提供：
| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| Host | string | SMTP服务器地址 | - |
| Port | int | SMTP服务器端口 | 587 |
| Username | string | 发件人邮箱 | - |
| Password | string | 邮箱密码或授权码 | - |
| From | string | 发件人邮箱地址 | Username |
| FromName | string | 发件人名称 | - |
| UseTLS | bool | 是否使用TLS | false |
| UseSSL | bool | 是否使用SSL | false |
| Timeout | int | 连接超时时间（秒） | 30 |
## 常见SMTP服务器配置
### Gmail
```json
{
"host": "smtp.gmail.com",
"port": 587,
"useTLS": true,
"useSSL": false
}
```
### QQ邮箱
```json
{
"host": "smtp.qq.com",
"port": 587,
"useTLS": true,
"useSSL": false
}
```
### 163邮箱
```json
{
"host": "smtp.163.com",
"port": 25,
"useTLS": false,
"useSSL": false
}
```
### 企业邮箱（SSL）
```json
{
"host": "smtp.exmail.qq.com",
"port": 465,
"useTLS": false,
"useSSL": true
}
```
## 注意事项
1. **推荐使用SendRaw方法**：
- `SendRaw`方法允许外部完全控制邮件内容
- 可以构建任意格式的MIME邮件（包括复杂附件、多部分内容等）
- 工具只负责SMTP发送，不构建内容
2. **邮件内容构建**：
- 使用`SendRaw`时，需要外部构建完整的MIME格式邮件内容
- 可以参考RFC 5322标准构建邮件内容
- 便捷方法（`Send`、`SendSimple`、`SendHTML`）内部会构建简单格式的邮件内容
3. **密码/授权码**：
- 很多邮箱服务商需要使用授权码而不是登录密码
- Gmail、QQ邮箱等需要开启SMTP服务并获取授权码
4. **端口选择**：
- 587端口：通常使用TLS（STARTTLS）
- 465端口：通常使用SSL
- 25端口：通常不使用加密（不推荐）
5. **TLS vs SSL**：
- UseTLS=true：使用STARTTLS（推荐，端口587）
- UseSSL=true：使用SSL（端口465）
6. **错误处理**：
- 所有操作都应该进行错误处理
- 建议记录详细的错误日志
## 完整示例
```go
package main
import (
"log"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/email"
)
func main() {
// 加载配置
cfg, err := config.LoadFromFile("./config.json")
if err != nil {
log.Fatal(err)
}
// 创建邮件发送器
mailer, err := email.NewEmail(cfg.GetEmail())
if err != nil {
log.Fatal(err)
}
// 发送邮件
err = mailer.SendSimple(
[]string{"recipient@example.com"},
"测试邮件",
"这是一封测试邮件",
)
if err != nil {
log.Fatal(err)
}
log.Println("邮件发送成功")
}
```
## 示例
完整示例请参考 `examples/email_example.go`

481
docs/factory.md
View File

@@ -1,481 +0,0 @@
# 工厂工具文档
## 概述
工厂工具提供了从配置直接创建已初始化客户端对象的功能，并提供了黑盒模式的便捷方法，让调用方无需关心底层实现细节，大大降低业务复杂度。
## 功能特性
- **黑盒模式**：提供直接调用的方法，无需获取客户端对象
- **延迟初始化**：所有客户端在首次使用时才创建
- **自动选择**：存储类型（OSS/MinIO）根据配置自动选择
- **统一接口**：所有操作通过工厂方法调用
- **向后兼容**：保留 `GetXXX()` 方法，需要时可获取对象
## 使用方法
### 1. 创建工厂（推荐）
```go
import "git.toowon.com/jimmy/go-common/factory"
// 方式1：直接从配置文件创建（最推荐）
fac, err := factory.NewFactoryFromFile("./config.json")
if err != nil {
log.Fatal(err)
}
// 方式2：从配置对象创建
cfg, _ := config.LoadFromFile("./config.json")
fac := factory.NewFactory(cfg)
```
### 2. 日志记录（黑盒模式，推荐）
```go
// 简单日志
fac.LogDebug("调试信息: %s", "test")
fac.LogInfo("用户登录成功")
fac.LogWarn("警告信息")
fac.LogError("错误信息: %v", err)
// 带字段的日志
fac.LogInfof(map[string]interface{}{
"user_id": 123,
"ip": "192.168.1.1",
}, "用户登录成功")
fac.LogErrorf(map[string]interface{}{
"error_code": 1001,
}, "登录失败: %v", err)
```
### 3. 邮件发送（黑盒模式，推荐）
```go
// 简单邮件
err := fac.SendEmail(
[]string{"user@example.com"},
"验证码",
"您的验证码是：123456",
)
// HTML邮件
err := fac.SendEmail(
[]string{"user@example.com"},
"验证码",
"纯文本内容",
"<h1>HTML内容</h1>",
)
```
### 4. 短信发送（黑盒模式，推荐）
```go
// 使用配置中的模板代码
resp, err := fac.SendSMS(
[]string{"13800138000"},
map[string]string{"code": "123456"},
)
// 指定模板代码
resp, err := fac.SendSMS(
[]string{"13800138000"},
map[string]string{"code": "123456"},
"SMS_123456789", // 模板代码
)
```
### 5. 文件上传和查看（黑盒模式，推荐）
```go
import (
"context"
"os"
)
ctx := context.Background()
// 上传文件（自动选择OSS或MinIO）
file, _ := os.Open("test.jpg")
defer file.Close()
url, err := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")
if err != nil {
log.Fatal(err)
}
fmt.Println("文件URL:", url)
// 获取文件URL（永久有效）
url, _ := fac.GetFileURL("images/test.jpg", 0)
// 获取临时访问URL（1小时后过期）
url, _ := fac.GetFileURL("images/test.jpg", 3600)
```
### 6. Redis操作（黑盒模式，推荐）
```go
import "context"
ctx := context.Background()
// 设置值（不过期）
err := fac.RedisSet(ctx, "user:123", "value")
// 设置值（带过期时间）
err := fac.RedisSet(ctx, "user:123", "value", time.Hour)
// 获取值
value, err := fac.RedisGet(ctx, "user:123")
// 删除键
err := fac.RedisDelete(ctx, "user:123", "user:456")
// 检查键是否存在
exists, err := fac.RedisExists(ctx, "user:123")
```
### 7. 数据库操作（黑盒模式）
```go
// 获取数据库对象（已初始化，黑盒模式）
db, err := fac.GetDatabase()
if err != nil {
log.Fatal(err)
}
// 直接使用GORM，无需自己实现创建逻辑
var users []User
db.Find(&users)
db.Create(&user)
```
### 8. Redis操作（获取客户端对象）
```go
import (
"context"
"github.com/redis/go-redis/v9"
)
ctx := context.Background()
// 获取Redis客户端对象（已初始化，黑盒模式）
redisClient, err := fac.GetRedisClient()
if err != nil {
log.Fatal(err)
}
// 直接使用Redis客户端，无需自己实现创建逻辑
val, err := redisClient.Get(ctx, "key").Result()
if err != nil && err != redis.Nil {
log.Printf("Redis error: %v", err)
} else if err == redis.Nil {
fmt.Println("Key not found")
} else {
fmt.Printf("Value: %s\n", val)
}
// 使用高级功能（如Hash操作）
redisClient.HSet(ctx, "user:123", "name", "John")
name, _ := redisClient.HGet(ctx, "user:123", "name").Result()
```
## 完整示例
```go
package main
import (
"context"
"log"
"os"
"time"
"git.toowon.com/jimmy/go-common/factory"
)
func main() {
// 创建工厂
fac, err := factory.NewFactoryFromFile("./config.json")
if err != nil {
log.Fatal(err)
}
ctx := context.Background()
// 日志记录（黑盒模式）
fac.LogInfo("应用启动")
fac.LogInfof(map[string]interface{}{
"version": "1.0.0",
}, "应用启动成功")
// 邮件发送（黑盒模式）
err = fac.SendEmail(
[]string{"user@example.com"},
"欢迎",
"欢迎使用我们的服务",
)
if err != nil {
fac.LogError("发送邮件失败: %v", err)
}
// 短信发送（黑盒模式）
resp, err := fac.SendSMS(
[]string{"13800138000"},
map[string]string{"code": "123456"},
)
if err != nil {
fac.LogError("发送短信失败: %v", err)
} else {
fac.LogInfo("短信发送成功: %s", resp.RequestID)
}
// 文件上传（黑盒模式，自动选择OSS或MinIO）
file, _ := os.Open("test.jpg")
defer file.Close()
url, err := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")
if err != nil {
fac.LogError("上传文件失败: %v", err)
} else {
fac.LogInfo("文件上传成功: %s", url)
}
// Redis操作（黑盒模式）
err = fac.RedisSet(ctx, "user:123", "value", time.Hour)
if err != nil {
fac.LogError("Redis设置失败: %v", err)
}
value, err := fac.RedisGet(ctx, "user:123")
if err != nil {
fac.LogError("Redis获取失败: %v", err)
} else {
fac.LogInfo("Redis值: %s", value)
}
// 数据库操作
db, err := fac.GetDatabase()
if err != nil {
fac.LogError("数据库连接失败: %v", err)
} else {
var count int64
db.Table("users").Count(&count)
fac.LogInfo("用户数量: %d", count)
}
}
```
## API 参考
### 工厂创建
#### NewFactory(cfg *config.Config) *Factory
创建工厂实例。
**参数：**
- `cfg`: 配置对象
**返回：** 工厂实例
#### NewFactoryFromFile(filePath string) (*Factory, error)
从配置文件直接创建工厂实例（便捷方法）。
**参数：**
- `filePath`: 配置文件路径
**返回：** 工厂实例和错误信息
**说明：** 这是推荐的使用方式，一步完成配置加载和工厂创建。
### 日志方法（黑盒模式）
#### LogDebug(message string, args ...interface{})
记录调试日志。
#### LogDebugf(fields map[string]interface{}, message string, args ...interface{})
记录调试日志（带字段）。
#### LogInfo(message string, args ...interface{})
记录信息日志。
#### LogInfof(fields map[string]interface{}, message string, args ...interface{})
记录信息日志（带字段）。
#### LogWarn(message string, args ...interface{})
记录警告日志。
#### LogWarnf(fields map[string]interface{}, message string, args ...interface{})
记录警告日志（带字段）。
#### LogError(message string, args ...interface{})
记录错误日志。
#### LogErrorf(fields map[string]interface{}, message string, args ...interface{})
记录错误日志（带字段）。
### 邮件方法（黑盒模式）
#### SendEmail(to []string, subject, body string, htmlBody ...string) error
发送邮件。
**参数：**
- `to`: 收件人列表
- `subject`: 邮件主题
- `body`: 邮件正文（纯文本）
- `htmlBody`: HTML正文（可选，如果设置了会优先使用）
### 短信方法（黑盒模式）
#### SendSMS(phoneNumbers []string, templateParam interface{}, templateCode ...string) (*sms.SendResponse, error)
发送短信。
**参数：**
- `phoneNumbers`: 手机号列表
- `templateParam`: 模板参数（map或JSON字符串）
- `templateCode`: 模板代码（可选，如果为空使用配置中的模板代码）
### 存储方法（黑盒模式）
#### UploadFile(ctx context.Context, objectKey string, reader io.Reader, contentType ...string) (string, error)
上传文件。
**参数：**
- `ctx`: 上下文
- `objectKey`: 对象键（文件路径）
- `reader`: 文件内容
- `contentType`: 文件类型（可选）
**返回：** 文件访问URL和错误信息
**说明：** 自动根据配置选择OSS或MinIO（优先级：MinIO > OSS）
#### GetFileURL(objectKey string, expires int64) (string, error)
获取文件访问URL。
**参数：**
- `objectKey`: 对象键
- `expires`: 过期时间（秒），0表示永久有效
**返回：** 文件访问URL和错误信息
### Redis方法（黑盒模式）
#### RedisGet(ctx context.Context, key string) (string, error)
获取Redis值。
**参数：**
- `ctx`: 上下文
- `key`: Redis键
**返回：** 值和错误信息（key不存在时返回空字符串）
#### RedisSet(ctx context.Context, key string, value interface{}, expiration ...time.Duration) error
设置Redis值。
**参数：**
- `ctx`: 上下文
- `key`: Redis键
- `value`: Redis值
- `expiration`: 过期时间（可选，0表示不过期）
#### RedisDelete(ctx context.Context, keys ...string) error
删除Redis键。
**参数：**
- `ctx`: 上下文
- `keys`: Redis键列表
#### RedisExists(ctx context.Context, key string) (bool, error)
检查Redis键是否存在。
**参数：**
- `ctx`: 上下文
- `key`: Redis键
**返回：** 是否存在和错误信息
### 数据库方法
#### GetDatabase() (*gorm.DB, error)
获取数据库连接对象（已初始化）。
**返回：** 已初始化的GORM数据库对象和错误信息
**说明：**
- 支持MySQL、PostgreSQL、SQLite
- 自动配置连接池参数
- 数据库时间统一使用UTC时区
- 延迟初始化，首次调用时创建连接
- 黑盒模式：只需传递config对象，无需自己实现创建逻辑
### Redis方法
#### GetRedisClient() (*redis.Client, error)
获取Redis客户端对象（已初始化）。
**返回：** 已初始化的Redis客户端对象和错误信息
**说明：**
- 自动处理所有配置检查和连接测试
- 自动设置默认值（连接池大小、超时时间等）
- 连接失败时会自动关闭客户端并返回错误
- 返回的客户端已通过Ping测试，可直接使用
- 黑盒模式：只需传递config对象，无需自己实现创建逻辑
- 推荐使用 `RedisGet`、`RedisSet`、`RedisDelete` 等方法直接操作Redis
- 如果需要使用Redis的高级功能（如Hash、List、Set等），可以使用此方法获取客户端对象
### 配置方法
#### GetConfig() *config.Config
获取配置对象。
**返回：** 配置对象
## 设计优势
### 优势总结
1. **降低复杂度**：调用方无需关心客户端对象的创建和管理
2. **延迟初始化**：所有客户端在首次使用时才创建，提高性能
3. **自动选择**：存储类型根据配置自动选择，无需手动指定
4. **统一接口**：所有操作通过工厂方法调用，接口统一
5. **容错处理**：日志初始化失败时自动回退到标准输出
6. **代码简洁**：只提供黑盒模式方法，保持代码简洁清晰
## 注意事项
1. **配置检查**：工厂方法会自动检查配置是否存在，如果配置为nil会返回错误
2. **错误处理**：所有方法都可能返回错误，需要正确处理
3. **延迟初始化**：所有客户端在首次使用时才创建，首次调用可能稍慢
4. **存储选择**：存储类型根据配置自动选择（优先级：MinIO > OSS）
5. **数据库对象**：数据库保持返回GORM对象，因为GORM已经提供了很好的抽象
6. **黑盒模式**：所有功能都通过工厂方法直接调用，无需获取底层客户端对象
## 示例
完整示例请参考 `examples/factory_example.go`

584
docs/http.md
View File

@@ -1,584 +0,0 @@
# HTTP Restful工具文档
## 概述
HTTP Restful工具提供了标准化的HTTP请求和响应处理功能，采用Handler黑盒模式，封装了`ResponseWriter`和`Request`，提供简洁的API，无需每次都传递这两个参数。
## 功能特性
- **黑盒模式**：封装`ResponseWriter`和`Request`，提供简洁的API
- **标准化的响应结构**：`{code, message, timestamp, data}`
- **分离HTTP状态码和业务状态码**
- **支持分页响应**
- **提供便捷的请求参数解析方法**
- **支持JSON请求体解析**
## 响应结构
### 标准响应结构
```json
{
"code": 0,
"message": "success",
"timestamp": 1704067200,
"data": {}
}
```
### 分页响应结构
```json
{
"code": 0,
"message": "success",
"timestamp": 1704067200,
"data": {
"list": [],
"total": 100,
"page": 1,
"pageSize": 10
}
}
```
## 使用方法
### 1. 创建Handler
```go
import (
"net/http"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
// 方式1：使用HandleFunc包装器（推荐，最简洁）
func GetUser(h *commonhttp.Handler) {
id := h.GetQueryInt64("id", 0)
h.Success(data)
}
http.HandleFunc("/user", commonhttp.HandleFunc(GetUser))
// 方式2：手动创建Handler（需要更多控制时）
http.HandleFunc("/user", func(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
GetUser(h)
})
```
### 2. 成功响应
```go
func handler(h *commonhttp.Handler) {
// 简单成功响应（data为nil）
h.Success(nil)
// 带数据的成功响应
data := map[string]interface{}{
"id": 1,
"name": "test",
}
h.Success(data)
// 带消息的成功响应
h.SuccessWithMessage("操作成功", data)
}
```
### 3. 错误响应
```go
func handler(h *commonhttp.Handler) {
// 业务错误（HTTP 200，业务code非0）
h.Error(1001, "用户不存在")
// 系统错误（HTTP 500）
h.SystemError("服务器内部错误")
// 其他HTTP错误状态码，使用WriteJSON直接指定
// 请求错误（HTTP 400）
h.WriteJSON(http.StatusBadRequest, 400, "请求参数错误", nil)
// 未授权（HTTP 401）
h.WriteJSON(http.StatusUnauthorized, 401, "未登录", nil)
// 禁止访问（HTTP 403）
h.WriteJSON(http.StatusForbidden, 403, "无权限访问", nil)
// 未找到（HTTP 404）
h.WriteJSON(http.StatusNotFound, 404, "资源不存在", nil)
}
```
### 4. 分页响应
```go
func handler(h *commonhttp.Handler) {
// 获取分页参数
pagination := h.ParsePaginationRequest()
page := pagination.GetPage()
pageSize := pagination.GetSize()
// 查询数据（示例）
list, total := getDataList(page, pageSize)
// 返回分页响应（使用默认消息）
h.SuccessPage(list, total, page, pageSize)
// 返回分页响应（自定义消息）
h.SuccessPage(list, total, page, pageSize, "查询成功")
}
```
### 5. 解析请求
#### 解析JSON请求体
```go
func handler(h *commonhttp.Handler) {
type CreateUserRequest struct {
Name string `json:"name"`
Email string `json:"email"`
}
var req CreateUserRequest
if err := h.ParseJSON(&req); err != nil {
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
// 使用req...
}
```
#### 获取查询参数
```go
func handler(h *commonhttp.Handler) {
// 获取字符串参数
name := h.GetQuery("name", "")
email := h.GetQuery("email", "default@example.com")
// 获取整数参数
id := h.GetQueryInt("id", 0)
age := h.GetQueryInt("age", 18)
// 获取int64参数
userId := h.GetQueryInt64("userId", 0)
// 获取布尔参数
isActive := h.GetQueryBool("isActive", false)
// 获取浮点数参数
price := h.GetQueryFloat64("price", 0.0)
}
```
#### 获取表单参数
```go
func handler(h *commonhttp.Handler) {
// 获取表单字符串
name := h.GetFormValue("name", "")
// 获取表单整数
age := h.GetFormInt("age", 0)
// 获取表单int64
userId := h.GetFormInt64("userId", 0)
// 获取表单布尔值
isActive := h.GetFormBool("isActive", false)
}
```
#### 获取请求头
```go
func handler(h *commonhttp.Handler) {
token := h.GetHeader("Authorization", "")
contentType := h.GetHeader("Content-Type", "application/json")
}
```
#### 获取分页参数
**方式1：使用 PaginationRequest 结构（推荐）**
```go
func handler(h *commonhttp.Handler) {
// 定义请求结构（包含分页字段）
type ListUserRequest struct {
Keyword string `json:"keyword"`
commonhttp.PaginationRequest // 嵌入分页请求结构
}
// 从JSON请求体解析（分页字段会自动解析）
var req ListUserRequest
if err := h.ParseJSON(&req); err != nil {
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
// 使用分页方法
page := req.GetPage() // 获取页码（默认1）
size := req.GetSize() // 获取每页数量（默认20，最大100，优先使用page_size）
offset := req.GetOffset() // 计算偏移量
}
// 或者从查询参数/form解析分页
func handler(h *commonhttp.Handler) {
pagination := h.ParsePaginationRequest()
page := pagination.GetPage()
size := pagination.GetSize()
offset := pagination.GetOffset()
}
```
#### 获取时区
```go
func handler(h *commonhttp.Handler) {
// 从请求的context中获取时区
// 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
// 如果未设置，返回默认时区 AsiaShanghai
timezone := h.GetTimezone()
}
```
### 6. 访问原始对象
如果需要访问原始的`ResponseWriter`或`Request`：
```go
func handler(h *commonhttp.Handler) {
// 获取原始ResponseWriter
w := h.ResponseWriter()
// 获取原始Request
r := h.Request()
// 获取Context
ctx := h.Context()
}
```
## 完整示例
```go
package main
import (
"log"
"net/http"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
// 用户结构
type User struct {
ID int64 `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
}
// 用户列表接口
func GetUserList(h *commonhttp.Handler) {
// 获取分页参数
pagination := h.ParsePaginationRequest()
page := pagination.GetPage()
pageSize := pagination.GetSize()
// 获取查询参数
keyword := h.GetQuery("keyword", "")
// 查询数据
users, total := queryUsers(keyword, page, pageSize)
// 返回分页响应
h.SuccessPage(users, total, page, pageSize)
}
// 创建用户接口
func CreateUser(h *commonhttp.Handler) {
// 解析请求体
var req struct {
Name string `json:"name"`
Email string `json:"email"`
}
if err := h.ParseJSON(&req); err != nil {
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
// 参数验证
if req.Name == "" {
h.Error(1001, "用户名不能为空")
return
}
// 创建用户
user, err := createUser(req.Name, req.Email)
if err != nil {
h.SystemError("创建用户失败")
return
}
// 返回成功响应
h.SuccessWithMessage("创建成功", user)
}
// 获取用户详情接口
func GetUser(h *commonhttp.Handler) {
// 获取查询参数
id := h.GetQueryInt64("id", 0)
if id == 0 {
h.WriteJSON(http.StatusBadRequest, 400, "用户ID不能为空", nil)
return
}
// 查询用户
user, err := getUserByID(id)
if err != nil {
h.SystemError("查询用户失败")
return
}
if user == nil {
h.Error(1002, "用户不存在")
return
}
h.Success(user)
}
func main() {
// 使用HandleFunc包装器（推荐）
http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
switch h.Request().Method {
case http.MethodGet:
GetUserList(h)
case http.MethodPost:
CreateUser(h)
default:
h.WriteJSON(http.StatusMethodNotAllowed, 405, "方法不支持", nil)
}
}))
http.HandleFunc("/user", commonhttp.HandleFunc(GetUser))
log.Println("Server started on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}
```
## API 参考
### Handler结构
Handler封装了`ResponseWriter`和`Request`，提供更简洁的API。
```go
type Handler struct {
w http.ResponseWriter
r *http.Request
}
```
### 创建Handler
#### NewHandler(w http.ResponseWriter, r *http.Request) *Handler
创建Handler实例。
#### HandleFunc(fn func(*Handler)) http.HandlerFunc
将Handler函数转换为标准的http.HandlerFunc（便捷包装器）。
**示例：**
```go
http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
h.Success(data)
}))
```
### Handler响应方法
#### (h *Handler) Success(data interface{})
成功响应，HTTP 200，业务code 0。
#### (h *Handler) SuccessWithMessage(message string, data interface{})
带消息的成功响应。
#### (h *Handler) Error(code int, message string)
业务错误响应，HTTP 200，业务code非0。
#### (h *Handler) SystemError(message string)
系统错误响应，HTTP 500，业务code 500。
#### (h *Handler) WriteJSON(httpCode, code int, message string, data interface{})
写入JSON响应（自定义）。
**参数：**
- `httpCode`: HTTP状态码
- `code`: 业务状态码
- `message`: 响应消息
- `data`: 响应数据
#### (h *Handler) SuccessPage(list interface{}, total int64, page, pageSize int, message ...string)
分页成功响应。
**参数：**
- `list`: 数据列表
- `total`: 总记录数
- `page`: 当前页码
- `pageSize`: 每页大小
- `message`: 响应消息（可选，如果为空则使用默认消息 "success"）
### Handler请求解析方法
#### (h *Handler) ParseJSON(v interface{}) error
解析JSON请求体。
#### (h *Handler) GetQuery(key, defaultValue string) string
获取查询参数（字符串）。
#### (h *Handler) GetQueryInt(key string, defaultValue int) int
获取查询参数（整数）。
#### (h *Handler) GetQueryInt64(key string, defaultValue int64) int64
获取查询参数（int64）。
#### (h *Handler) GetQueryBool(key string, defaultValue bool) bool
获取查询参数（布尔值）。
#### (h *Handler) GetQueryFloat64(key string, defaultValue float64) float64
获取查询参数（浮点数）。
#### (h *Handler) GetFormValue(key, defaultValue string) string
获取表单值（字符串）。
#### (h *Handler) GetFormInt(key string, defaultValue int) int
获取表单值（整数）。
#### (h *Handler) GetFormInt64(key string, defaultValue int64) int64
获取表单值（int64）。
#### (h *Handler) GetFormBool(key string, defaultValue bool) bool
获取表单值（布尔值）。
#### (h *Handler) GetHeader(key, defaultValue string) string
获取请求头。
#### (h *Handler) ParsePaginationRequest() *PaginationRequest
从请求中解析分页参数。
**说明：**
- 支持从查询参数和form表单中解析
- 优先级：查询参数 > form表单
- 如果请求体是JSON格式且包含分页字段，建议先使用`ParseJSON`解析完整请求体到包含`PaginationRequest`的结构体中
#### (h *Handler) GetTimezone() string
从请求的context中获取时区。
**说明：**
- 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
- 如果未设置，返回默认时区 AsiaShanghai
### Handler访问原始对象
#### (h *Handler) ResponseWriter() http.ResponseWriter
获取原始的ResponseWriter（需要时使用）。
#### (h *Handler) Request() *http.Request
获取原始的Request（需要时使用）。
#### (h *Handler) Context() context.Context
获取请求的Context。
### 分页请求结构
#### PaginationRequest
分页请求结构，支持从JSON和form中解析分页参数。
**字段：**
- `Page`: 页码（默认1）
- `Size`: 每页数量（兼容旧版本）
- `PageSize`: 每页数量（推荐使用，优先于Size）
**方法：**
- `GetPage() int`: 获取页码，如果未设置则返回默认值1
- `GetSize() int`: 获取每页数量，优先使用PageSize，如果未设置则使用Size，默认20，最大100
- `GetOffset() int`: 计算数据库查询的偏移量
#### ParsePaginationRequest(r *http.Request) *PaginationRequest
从请求中解析分页参数（内部函数，Handler内部使用）。
## 状态码说明
### HTTP状态码
- `200`: 正常响应（包括业务错误）
- `400`: 请求参数错误
- `401`: 未授权
- `403`: 禁止访问
- `404`: 资源不存在
- `500`: 系统内部错误
### 业务状态码
- `0`: 成功
- `非0`: 业务错误（具体错误码由业务定义）
## 注意事项
1. **HTTP状态码与业务状态码分离**：
- 业务错误（如用户不存在、参数验证失败等）返回HTTP 200，业务code非0
- 只有系统异常（如数据库连接失败、程序panic等）才返回HTTP 500
2. **分页参数限制**：
- page最小值为1
- pageSize最小值为1，最大值为100
3. **响应格式统一**：
- 所有响应都遵循标准结构
- timestamp为Unix时间戳（秒）
4. **错误处理**：
- 使用`Error`方法返回业务错误（HTTP 200，业务code非0）
- 使用`SystemError`返回系统错误（HTTP 500）
- 其他HTTP错误状态码（400, 401, 403, 404等）使用`WriteJSON`方法直接指定
5. **黑盒模式**：
- 所有功能都通过Handler对象调用，无需传递`w`和`r`参数
- 代码更简洁，减少调用方工作量
## 示例
完整示例请参考 `examples/http_handler_example.go`

266
docs/logger.md
View File

@@ -1,266 +0,0 @@
# 日志工具文档
## 概述
日志工具提供了统一的日志记录功能，使用Go标准库实现，无需第三方依赖。
## 功能特性
- 支持多种日志级别（debug, info, warn, error）
- 支持多种输出方式（stdout, stderr, file, both）
- 支持日志文件自动创建
- 支持日志前缀
- 支持禁用时间戳
- 支持带字段的日志记录
- 使用配置工具统一管理配置
## 使用方法
### 1. 从配置创建日志记录器（推荐）
```go
import (
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/factory"
)
// 加载配置
cfg, err := config.LoadFromFile("./config.json")
if err != nil {
log.Fatal(err)
}
// 使用工厂创建日志记录器（已初始化，可直接使用）
fac := factory.NewFactory(cfg)
logger, err := fac.GetLogger()
if err != nil {
log.Fatal(err)
}
// 直接使用
logger.Info("Application started")
logger.Error("Failed to connect: %v", err)
```
### 2. 直接创建日志记录器
```go
import (
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/logger"
)
// 从配置获取日志配置
cfg, _ := config.LoadFromFile("./config.json")
loggerConfig := cfg.GetLogger()
// 创建日志记录器
logger, err := logger.NewLogger(loggerConfig)
if err != nil {
log.Fatal(err)
}
// 使用默认配置（如果loggerConfig为nil）
logger, err := logger.NewLogger(nil)
```
### 3. 基本日志记录
```go
// 记录不同级别的日志
logger.Debug("Debug message: %s", "debug info")
logger.Info("Info message: %s", "info")
logger.Warn("Warning message: %s", "warning")
logger.Error("Error message: %s", "error")
// 致命错误（会退出程序）
logger.Fatal("Fatal error: %s", "fatal")
// 恐慌错误（会触发panic）
logger.Panic("Panic error: %s", "panic")
```
### 4. 带字段的日志记录
```go
// 记录带字段的日志
fields := map[string]interface{}{
"user_id": 123,
"action": "login",
}
logger.Infof(fields, "User logged in")
logger.Errorf(fields, "Failed to process request")
```
## API 参考
### NewLogger(cfg *config.LoggerConfig) (*Logger, error)
创建日志记录器。
**参数：**
- `cfg`: 日志配置对象（如果为nil，使用默认配置）
**返回：** 日志记录器实例和错误信息
### (l *Logger) Debug(format string, v ...interface{})
记录调试日志。
### (l *Logger) Info(format string, v ...interface{})
记录信息日志。
### (l *Logger) Warn(format string, v ...interface{})
记录警告日志。
### (l *Logger) Error(format string, v ...interface{})
记录错误日志。
### (l *Logger) Fatal(format string, v ...interface{})
记录致命错误日志并退出程序。
### (l *Logger) Panic(format string, v ...interface{})
记录恐慌日志并触发panic。
### (l *Logger) Debugf(fields map[string]interface{}, format string, v ...interface{})
记录调试日志（带字段）。
### (l *Logger) Infof(fields map[string]interface{}, format string, v ...interface{})
记录信息日志（带字段）。
### (l *Logger) Warnf(fields map[string]interface{}, format string, v ...interface{})
记录警告日志（带字段）。
### (l *Logger) Errorf(fields map[string]interface{}, format string, v ...interface{})
记录错误日志（带字段）。
## 配置说明
日志配置通过 `config.LoggerConfig` 提供：
| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| Level | string | 日志级别: debug, info, warn, error | info |
| Output | string | 输出方式: stdout, stderr, file, both | stdout |
| FilePath | string | 日志文件路径（当output为file或both时必需） | - |
| Prefix | string | 日志前缀 | - |
| DisableTimestamp | bool | 禁用时间戳 | false |
## 配置示例
### 输出到标准输出
```json
{
"logger": {
"level": "info",
"output": "stdout",
"prefix": "app"
}
}
```
### 输出到文件
```json
{
"logger": {
"level": "debug",
"output": "file",
"filePath": "./logs/app.log",
"prefix": "app"
}
}
```
### 同时输出到标准输出和文件
```json
{
"logger": {
"level": "info",
"output": "both",
"filePath": "./logs/app.log",
"prefix": "app",
"disableTimestamp": false
}
}
```
## 日志级别说明
- **debug**: 调试信息，最详细的日志级别
- **info**: 一般信息，正常的程序运行信息
- **warn**: 警告信息，可能的问题但不影响程序运行
- **error**: 错误信息，程序运行中的错误
## 注意事项
1. **文件路径**：
- 当output为`file`或`both`时，必须提供`filePath`
- 日志文件目录会自动创建（如果不存在）
2. **日志级别**：
- 设置为`debug`时，会记录所有级别的日志
- 设置为`info`时，会记录info、warn、error级别的日志
- 设置为`warn`时，只记录warn和error级别的日志
- 设置为`error`时，只记录error级别的日志
3. **文件权限**：
- 日志文件创建时使用0666权限
- 目录创建时使用0755权限
4. **性能考虑**：
- 使用标准库log包，性能较好
- 文件输出使用追加模式，不会覆盖已有日志
## 完整示例
```go
package main
import (
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/factory"
)
func main() {
// 加载配置
cfg, err := config.LoadFromFile("./config.json")
if err != nil {
log.Fatal(err)
}
// 使用工厂创建日志记录器
fac := factory.NewFactory(cfg)
logger, err := fac.GetLogger()
if err != nil {
log.Fatal(err)
}
// 使用日志记录器
logger.Info("Application started")
// 记录带字段的日志
logger.Infof(map[string]interface{}{
"user_id": 123,
"action": "login",
}, "User logged in successfully")
logger.Error("An error occurred: %v", err)
}
```
## 示例
完整示例请参考 `examples/logger_example.go`

446
docs/middleware.md
View File

@@ -1,446 +0,0 @@
# 中间件工具文档
## 概述
中间件工具提供了常用的HTTP中间件功能，包括CORS处理和时区管理。
## 功能特性
- **CORS中间件**：支持跨域资源共享配置
- **时区中间件**：从请求头读取时区信息，支持默认时区设置
- **中间件链**：提供便捷的中间件链式调用
## CORS中间件
### 功能说明
CORS中间件用于处理跨域资源共享，支持：
- 配置允许的源（支持通配符）
- 配置允许的HTTP方法
- 配置允许的请求头
- 配置暴露的响应头
- 支持凭证传递
- 预检请求缓存时间设置
### 使用方法
#### 基本使用（默认配置）
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/middleware"
)
func main() {
handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 处理请求
})
// 使用默认CORS配置
corsHandler := middleware.CORS()(handler)
http.Handle("/api", corsHandler)
http.ListenAndServe(":8080", nil)
}
```
#### 自定义配置
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/middleware"
)
func main() {
// 自定义CORS配置
corsConfig := &middleware.CORSConfig{
AllowedOrigins: []string{
"https://example.com",
"https://app.example.com",
"*.example.com", // 支持通配符
},
AllowedMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
AllowedHeaders: []string{
"Content-Type",
"Authorization",
"X-Requested-With",
"X-Timezone",
},
ExposedHeaders: []string{"X-Total-Count"},
AllowCredentials: true,
MaxAge: 3600, // 1小时
}
handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 处理请求
})
corsHandler := middleware.CORS(corsConfig)(handler)
http.Handle("/api", corsHandler)
http.ListenAndServe(":8080", nil)
}
```
#### 允许所有源（开发环境）
```go
corsConfig := &middleware.CORSConfig{
AllowedOrigins: []string{"*"},
AllowedMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
AllowedHeaders: []string{"*"},
}
corsHandler := middleware.CORS(corsConfig)(handler)
```
### CORSConfig 配置说明
| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| AllowedOrigins | []string | 允许的源，支持 "*" 和 "*.example.com" | ["*"] |
| AllowedMethods | []string | 允许的HTTP方法 | ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"] |
| AllowedHeaders | []string | 允许的请求头 | ["Content-Type", "Authorization", "X-Requested-With", "X-Timezone"] |
| ExposedHeaders | []string | 暴露给客户端的响应头 | [] |
| AllowCredentials | bool | 是否允许发送凭证 | false |
| MaxAge | int | 预检请求缓存时间（秒） | 86400 |
### 注意事项
1. 如果 `AllowCredentials` 为 `true`，`AllowedOrigins` 不能使用 "*"，必须指定具体的源
2. 通配符支持：`"*.example.com"` 会匹配 `"https://app.example.com"` 等子域名
3. 预检请求（OPTIONS）会自动处理，无需在业务代码中处理
## 时区中间件
### 功能说明
时区中间件用于从请求头读取时区信息，并存储到context中，方便后续使用。
- 从请求头 `X-Timezone` 读取时区
- 如果未传递时区信息，使用默认时区 `AsiaShanghai`
- 时区信息存储到context中，可通过Handler的`GetTimezone()`方法获取
- 自动验证时区有效性，无效时区会回退到默认时区
### 使用方法
#### 基本使用（默认时区 AsiaShanghai）
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/middleware"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/datetime"
)
func handler(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
// 从Handler获取时区
timezone := h.GetTimezone()
// 使用时区
now := datetime.Now(timezone)
datetime.FormatDateTime(now, timezone)
h.Success(map[string]interface{}{
"timezone": timezone,
"time": datetime.FormatDateTime(now),
})
}
func main() {
handler := middleware.Timezone(http.HandlerFunc(handler))
http.Handle("/api", handler)
http.ListenAndServe(":8080", nil)
}
```
#### 自定义默认时区
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/datetime"
)
func handler(w http.ResponseWriter, r *http.Request) {
// 处理请求
}
func main() {
// 使用自定义默认时区
handler := middleware.TimezoneWithDefault(datetime.UTC)(http.HandlerFunc(handler))
http.Handle("/api", handler)
http.ListenAndServe(":8080", nil)
}
```
#### 在业务代码中使用时区
```go
import (
"net/http"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/datetime"
)
func GetUserList(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
// 从Handler获取时区
timezone := h.GetTimezone()
// 使用时区进行时间处理
now := datetime.Now(timezone)
// 查询数据时使用时区
startTime := datetime.StartOfDay(now, timezone)
endTime := datetime.EndOfDay(now, timezone)
// 返回数据
h.Success(map[string]interface{}{
"timezone": timezone,
"startTime": datetime.FormatDateTime(startTime),
"endTime": datetime.FormatDateTime(endTime),
})
}
```
### 请求头格式
客户端需要在请求头中传递时区信息：
```
X-Timezone: Asia/Shanghai
```
支持的时区格式（IANA时区数据库）：
- `Asia/Shanghai`
- `America/New_York`
- `Europe/London`
- `UTC`
- 等等
### 注意事项
1. 如果请求头中未传递 `X-Timezone`，默认使用 `AsiaShanghai`
2. 如果传递的时区无效，会自动回退到默认时区
3. 时区信息存储在context中，可以在整个请求生命周期中使用
4. 建议在CORS配置中包含 `X-Timezone` 请求头
## 中间件链
### 功能说明
中间件链提供便捷的中间件组合方式，支持链式调用。
### 使用方法
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/middleware"
)
func handler(w http.ResponseWriter, r *http.Request) {
// 处理请求
}
func main() {
// 创建中间件链
chain := middleware.NewChain(
middleware.CORS(),
middleware.Timezone,
)
// 应用到处理器
handler := chain.ThenFunc(handler)
http.Handle("/api", handler)
http.ListenAndServe(":8080", nil)
}
```
#### 链式追加中间件
```go
chain := middleware.NewChain(middleware.CORS())
chain.Append(middleware.Timezone)
handler := chain.ThenFunc(handler)
```
## 完整示例
### 示例1：CORS + 时区中间件
```go
package main
import (
"log"
"net/http"
"git.toowon.com/jimmy/go-common/middleware"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/datetime"
)
func apiHandler(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
// 从Handler获取时区
timezone := h.GetTimezone()
now := datetime.Now(timezone)
h.Success(map[string]interface{}{
"message": "Hello",
"timezone": timezone,
"time": datetime.FormatDateTime(now),
})
}
func main() {
// 配置CORS
corsConfig := &middleware.CORSConfig{
AllowedOrigins: []string{"*"},
AllowedMethods: []string{"GET", "POST", "OPTIONS"},
AllowedHeaders: []string{"Content-Type", "Authorization", "X-Timezone"},
}
// 创建中间件链
chain := middleware.NewChain(
middleware.CORS(corsConfig),
middleware.Timezone,
)
// 应用中间件
handler := chain.ThenFunc(apiHandler)
http.Handle("/api", handler)
log.Println("Server started on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}
```
### 示例2：与路由框架集成
```go
package main
import (
"net/http"
"git.toowon.com/jimmy/go-common/middleware"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
func main() {
mux := http.NewServeMux()
// 创建中间件链
chain := middleware.NewChain(
middleware.CORS(),
middleware.Timezone,
)
// 应用中间件到所有路由
mux.Handle("/api/users", chain.ThenFunc(getUsers))
mux.Handle("/api/posts", chain.ThenFunc(getPosts))
http.ListenAndServe(":8080", mux)
}
func getUsers(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
timezone := h.GetTimezone()
// 处理逻辑
h.Success(nil)
}
func getPosts(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
timezone := h.GetTimezone()
// 处理逻辑
h.Success(nil)
}
```
## API 参考
### CORS中间件
#### CORS(config ...*CORSConfig) func(http.Handler) http.Handler
创建CORS中间件。
**参数：**
- `config`: 可选的CORS配置，不指定则使用默认配置
**返回：** 中间件函数
#### DefaultCORSConfig() *CORSConfig
返回默认的CORS配置。
### 时区中间件
#### Timezone(next http.Handler) http.Handler
时区处理中间件（默认时区为 AsiaShanghai）。
#### TimezoneWithDefault(defaultTimezone string) func(http.Handler) http.Handler
时区处理中间件（可自定义默认时区）。
**参数：**
- `defaultTimezone`: 默认时区字符串
**返回：** 中间件函数
#### GetTimezoneFromContext(ctx context.Context) string
从context中获取时区。
### 中间件链
#### NewChain(middlewares ...func(http.Handler) http.Handler) *Chain
创建新的中间件链。
#### (c *Chain) Then(handler http.Handler) http.Handler
将中间件链应用到处理器。
#### (c *Chain) ThenFunc(handler http.HandlerFunc) http.Handler
将中间件链应用到处理器函数。
#### (c *Chain) Append(middlewares ...func(http.Handler) http.Handler) *Chain
追加中间件到链中。
## 注意事项
1. **CORS配置**：
- 生产环境建议明确指定允许的源，避免使用 "*"
- 如果使用凭证（cookies），必须明确指定源，不能使用 "*"
2. **时区处理**：
- 时区信息存储在context中，确保中间件在处理器之前执行
- 时区验证失败时会自动回退到默认时区，不会返回错误
3. **中间件顺序**：
- CORS中间件应该放在最外层，以便处理预检请求
- 时区中间件可以放在CORS之后
4. **性能考虑**：
- CORS预检请求会被缓存，减少重复请求
- 时区验证只在请求头存在时进行，性能影响很小

324
docs/migration.md
View File

@@ -1,324 +0,0 @@
# 数据库迁移工具文档
## 概述
数据库迁移工具提供了数据库版本管理和迁移功能，支持MySQL、PostgreSQL、SQLite等数据库。使用GORM作为数据库操作库，可以方便地进行数据库结构的版本控制。
## 功能特性
- 支持迁移版本管理
- 支持迁移和回滚操作
- 支持从文件系统加载迁移文件
- 支持迁移状态查询
- 自动创建迁移记录表
- 事务支持，确保迁移的原子性
## 使用方法
### 1. 创建迁移器
```go
import (
"gorm.io/driver/mysql"
"gorm.io/gorm"
"git.toowon.com/jimmy/go-common/migration"
)
// 初始化数据库连接
dsn := "user:password@tcp(localhost:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local"
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
// 创建迁移器
migrator := migration.NewMigrator(db)
// 或者指定自定义的迁移记录表名
migrator := migration.NewMigrator(db, "my_migrations")
```
### 2. 添加迁移
#### 方式一：代码方式添加迁移
```go
migrator.AddMigration(migration.Migration{
Version: "20240101000001",
Description: "create_users_table",
Up: func(db *gorm.DB) error {
return db.Exec(`
CREATE TABLE users (
id INT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(255) NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
`).Error
},
Down: func(db *gorm.DB) error {
return db.Exec("DROP TABLE IF EXISTS users").Error
},
})
```
#### 方式二：批量添加迁移
```go
migrations := []migration.Migration{
{
Version: "20240101000001",
Description: "create_users_table",
Up: func(db *gorm.DB) error {
return db.Exec("CREATE TABLE users ...").Error
},
Down: func(db *gorm.DB) error {
return db.Exec("DROP TABLE users").Error
},
},
{
Version: "20240101000002",
Description: "add_index_to_users",
Up: func(db *gorm.DB) error {
return db.Exec("CREATE INDEX idx_email ON users(email)").Error
},
Down: func(db *gorm.DB) error {
return db.Exec("DROP INDEX idx_email ON users").Error
},
},
}
migrator.AddMigrations(migrations...)
```
#### 方式三：从文件加载迁移
```go
// 文件命名格式: {version}_{description}.sql 或 {version}_{description}.up.sql
// 例如: 20240101000001_create_users_table.up.sql
// 对应的回滚文件: 20240101000001_create_users_table.down.sql
migrations, err := migration.LoadMigrationsFromFiles("./migrations", "*.up.sql")
if err != nil {
log.Fatal(err)
}
migrator.AddMigrations(migrations...)
```
### 3. 执行迁移
```go
// 执行所有未应用的迁移
err := migrator.Up()
if err != nil {
log.Fatal(err)
}
```
### 4. 回滚迁移
```go
// 回滚最后一个迁移
err := migrator.Down()
if err != nil {
log.Fatal(err)
}
```
### 5. 查看迁移状态
```go
status, err := migrator.Status()
if err != nil {
log.Fatal(err)
}
for _, s := range status {
fmt.Printf("Version: %s, Description: %s, Applied: %v\n",
s.Version, s.Description, s.Applied)
}
```
### 6. 重置迁移
#### 方式一：仅清空迁移记录（不回滚数据库变更）
```go
// 直接调用（需要传入确认标志）
err := migrator.Reset(true)
if err != nil {
log.Fatal(err)
}
// 交互式确认（推荐，会提示警告信息）
err := migrator.ResetWithConfirm()
if err != nil {
log.Fatal(err)
}
```
#### 方式二：回滚所有迁移并清空记录
```go
// 直接调用（需要传入确认标志）
err := migrator.ResetAll(true)
if err != nil {
log.Fatal(err)
}
// 交互式确认（推荐，会提示警告信息）
err := migrator.ResetAllWithConfirm()
if err != nil {
log.Fatal(err)
}
```
**注意：**
- `Reset()` 仅清空迁移记录表，不会回滚已执行的数据库变更
- `ResetAll()` 会回滚所有已应用的迁移（执行Down函数），然后清空记录
- 交互式方法会显示详细的警告信息，需要输入确认文本才能执行
### 7. 生成迁移版本号
```go
// 生成基于时间戳的版本号
version := migration.GenerateVersion()
// 输出: 1704067200 (Unix时间戳)
```
## API 参考
### Migration 结构体
```go
type Migration struct {
Version string // 迁移版本号（必须唯一）
Description string // 迁移描述
Up func(*gorm.DB) error // 升级函数
Down func(*gorm.DB) error // 回滚函数（可选）
}
```
### Migrator 方法
#### NewMigrator(db *gorm.DB, tableName ...string) *Migrator
创建新的迁移器。
**参数：**
- `db`: GORM数据库连接
- `tableName`: 可选，迁移记录表名，默认为 "schema_migrations"
**返回：** 迁移器实例
#### AddMigration(migration Migration)
添加单个迁移。
#### AddMigrations(migrations ...Migration)
批量添加迁移。
#### Up() error
执行所有未应用的迁移。按版本号升序执行。
**返回：** 错误信息
#### Down() error
回滚最后一个已应用的迁移。
**返回：** 错误信息
#### Status() ([]MigrationStatus, error)
查看所有迁移的状态。
**返回：** 迁移状态列表和错误信息
#### Reset(confirm bool) error
重置所有迁移记录（仅清空记录表，不回滚数据库变更）。
**参数：**
- `confirm`: 确认标志，必须为true才能执行
**返回：** 错误信息
**注意：** 此操作只清空迁移记录，不会回滚已执行的迁移操作。如果需要回滚迁移，请先使用Down方法逐个回滚。
#### ResetWithConfirm() error
交互式重置所有迁移记录（带确认提示）。
**返回：** 错误信息
**说明：** 会显示警告信息，需要输入"RESET"（全大写）才能执行。
#### ResetAll(confirm bool) error
重置所有迁移并回滚所有已应用的迁移。
**参数：**
- `confirm`: 确认标志，必须为true才能执行
**返回：** 错误信息
**注意：** 此操作会回滚所有已应用的迁移（执行Down函数），然后清空迁移记录。操作不可逆，请谨慎使用。
#### ResetAllWithConfirm() error
交互式重置所有迁移并回滚（带确认提示）。
**返回：** 错误信息
**说明：** 会显示警告信息，需要输入"RESET ALL"（全大写）才能执行。
### MigrationStatus 结构体
```go
type MigrationStatus struct {
Version string // 版本号
Description string // 描述
Applied bool // 是否已应用
}
```
### 辅助函数
#### LoadMigrationsFromFiles(dir string, pattern string) ([]Migration, error)
从文件系统加载迁移文件。
**参数：**
- `dir`: 迁移文件目录
- `pattern`: 文件匹配模式，如 "*.up.sql"
**返回：** 迁移列表和错误信息
**文件命名格式：** `{version}_{description}.up.sql`
**示例：**
- `20240101000001_create_users_table.up.sql` - 升级文件
- `20240101000001_create_users_table.down.sql` - 回滚文件（可选）
#### GenerateVersion() string
生成基于时间戳的迁移版本号。
**返回：** Unix时间戳字符串
## 注意事项
1. **迁移版本号**：必须唯一，建议使用时间戳格式
2. **事务支持**：迁移操作在事务中执行，失败会自动回滚
3. **自动创建表**：迁移记录表会自动创建，无需手动创建
4. **回滚文件**：如果迁移文件没有对应的down文件，回滚操作会失败
5. **执行顺序**：迁移按版本号升序执行，确保顺序正确
6. **重置操作**：
- `Reset()` 只清空迁移记录，不会回滚数据库变更
- `ResetAll()` 会回滚所有迁移，操作不可逆
- 建议使用交互式方法（`ResetWithConfirm`、`ResetAllWithConfirm`）以确保安全
- 在生产环境使用重置功能前，请确保已备份数据库
## 示例
完整示例请参考 `examples/migration_example.go`

370
docs/sms.md
View File

@@ -1,370 +0,0 @@
# 短信工具文档
## 概述
短信工具提供了阿里云短信发送功能，使用Go标准库实现，无需第三方依赖。
## 功能特性
- 支持阿里云短信服务
- 支持发送原始请求（完全由外部控制请求参数）
- 支持模板短信发送
- 支持批量发送
- 自动签名计算
- 使用配置工具统一管理配置
## 使用方法
### 1. 创建短信发送器
```go
import (
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/sms"
)
// 从配置加载
cfg, err := config.LoadFromFile("./config.json")
if err != nil {
log.Fatal(err)
}
smsConfig := cfg.GetSMS()
if smsConfig == nil {
log.Fatal("SMS config is nil")
}
// 创建短信发送器
smsClient, err := sms.NewSMS(smsConfig)
if err != nil {
log.Fatal(err)
}
```
### 2. 发送原始请求（推荐，最灵活）
```go
// 外部构建完整的请求参数
params := map[string]string{
"PhoneNumbers": "13800138000,13900139000",
"SignName": "我的签名",
"TemplateCode": "SMS_123456789",
"TemplateParam": `{"code":"123456","expire":"5"}`,
}
// 发送短信（工具只负责添加系统参数、计算签名并发送）
resp, err := smsClient.SendRaw(params)
if err != nil {
log.Fatal(err)
}
fmt.Printf("发送成功，RequestID: %s\n", resp.RequestID)
```
### 3. 发送简单短信（便捷方法）
```go
// 使用配置中的模板代码发送短信
templateParam := map[string]string{
"code": "123456",
}
resp, err := smsClient.SendSimple(
[]string{"13800138000"},
templateParam,
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("发送成功，RequestID: %s\n", resp.RequestID)
```
### 4. 使用指定模板发送短信（便捷方法）
```go
// 使用指定的模板代码发送短信
templateParam := map[string]string{
"code": "123456",
"expire": "5",
}
resp, err := smsClient.SendWithTemplate(
[]string{"13800138000"},
"SMS_123456789", // 模板代码
templateParam,
)
if err != nil {
log.Fatal(err)
}
```
### 5. 使用SendRequest结构发送（便捷方法）
```go
import "git.toowon.com/jimmy/go-common/sms"
req := &sms.SendRequest{
PhoneNumbers: []string{"13800138000", "13900139000"},
TemplateCode: "SMS_123456789",
TemplateParam: map[string]string{
"code": "123456",
},
SignName: "我的签名", // 可选，如果为空使用配置中的签名
}
resp, err := smsClient.Send(req)
if err != nil {
log.Fatal(err)
}
```
### 6. 使用JSON字符串作为模板参数
```go
// TemplateParam可以是JSON字符串
req := &sms.SendRequest{
PhoneNumbers: []string{"13800138000"},
TemplateCode: "SMS_123456789",
TemplateParam: `{"code":"123456","expire":"5"}`, // 直接使用JSON字符串
}
resp, err := smsClient.Send(req)
```
## API 参考
### NewSMS(cfg *config.SMSConfig) (*SMS, error)
创建短信发送器。
**参数：**
- `cfg`: 短信配置对象
**返回：** 短信发送器实例和错误信息
### (s *SMS) SendRaw(params map[string]string) (*SendResponse, error)
发送原始请求（推荐使用，最灵活）。
**参数：**
- `params`: 请求参数map，工具只负责添加必要的系统参数（如签名、时间戳等）并发送
**返回：** 发送响应和错误信息
**说明：** 此方法允许外部完全控制请求参数，工具只负责添加系统参数、计算签名并发送。
### (s *SMS) Send(req *SendRequest) (*SendResponse, error)
发送短信（使用SendRequest结构）。
**参数：**
- `req`: 发送请求对象
**返回：** 发送响应和错误信息
**说明：** 如果需要完全控制请求参数，请使用SendRaw方法。
### (s *SMS) SendSimple(phoneNumbers []string, templateParam map[string]string) (*SendResponse, error)
发送简单短信（便捷方法，使用配置中的模板代码）。
**参数：**
- `phoneNumbers`: 手机号列表
- `templateParam`: 模板参数
### (s *SMS) SendWithTemplate(phoneNumbers []string, templateCode string, templateParam map[string]string) (*SendResponse, error)
使用指定模板发送短信（便捷方法）。
**参数：**
- `phoneNumbers`: 手机号列表
- `templateCode`: 模板代码
- `templateParam`: 模板参数
### SendRequest 结构体
```go
type SendRequest struct {
PhoneNumbers []string // 手机号列表
TemplateCode string // 模板代码（可选，如果为空使用配置中的）
TemplateParam interface{} // 模板参数（可以是map[string]string或JSON字符串）
SignName string // 签名（可选，如果为空使用配置中的）
}
```
### SendResponse 结构体
```go
type SendResponse struct {
RequestID string // 请求ID
Code string // 响应码（OK表示成功）
Message string // 响应消息
BizID string // 业务ID
}
```
## 配置说明
短信配置通过 `config.SMSConfig` 提供：
| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| AccessKeyID | string | 阿里云AccessKey ID | - |
| AccessKeySecret | string | 阿里云AccessKey Secret | - |
| Region | string | 区域（如：cn-hangzhou） | cn-hangzhou |
| SignName | string | 短信签名 | - |
| TemplateCode | string | 短信模板代码 | - |
| Endpoint | string | 服务端点（可选） | - |
| Timeout | int | 请求超时时间（秒） | 10 |
## 阿里云短信配置步骤
1. **开通阿里云短信服务**
- 登录阿里云控制台
- 开通短信服务
2. **创建AccessKey**
- 在AccessKey管理页面创建AccessKey
- 保存AccessKey ID和Secret
3. **申请短信签名**
- 在短信服务控制台申请签名
- 等待审核通过
4. **创建短信模板**
- 在短信服务控制台创建模板
- 模板格式示例：`您的验证码是${code}，有效期${expire}分钟`
- 等待审核通过，获取模板代码（如：SMS_123456789）
5. **配置参数**
```json
{
"sms": {
"accessKeyId": "your-access-key-id",
"accessKeySecret": "your-access-key-secret",
"region": "cn-hangzhou",
"signName": "您的签名",
"templateCode": "SMS_123456789"
}
}
```
## 模板参数示例
### 验证码模板
模板内容：`您的验证码是${code}，有效期${expire}分钟`
```go
templateParam := map[string]string{
"code": "123456",
"expire": "5",
}
```
### 通知模板
模板内容：`您的订单${orderNo}已发货，物流单号：${trackingNo}`
```go
templateParam := map[string]string{
"orderNo": "ORD123456",
"trackingNo": "SF1234567890",
}
```
## 响应码说明
| Code | 说明 |
|------|------|
| OK | 发送成功 |
| InvalidSignName | 签名不存在 |
| InvalidTemplateCode | 模板不存在 |
| InvalidPhoneNumbers | 手机号格式错误 |
| Throttling | 请求被限流 |
| 其他 | 参考阿里云短信服务错误码文档 |
## 注意事项
1. **推荐使用SendRaw方法**：
- `SendRaw`方法允许外部完全控制请求参数
- 可以发送任意阿里云短信API支持的请求
- 工具只负责添加系统参数、计算签名并发送
2. **模板参数格式**：
- `TemplateParam`可以是`map[string]string`或JSON字符串
- 如果使用JSON字符串，必须是有效的JSON格式
- 模板参数必须与模板中定义的变量匹配
3. **AccessKey安全**：
- AccessKey具有账户权限，请妥善保管
- 建议使用子账户AccessKey，并限制权限
4. **签名和模板**：
- 签名和模板需要先申请并审核通过
- 模板参数必须与模板中定义的变量匹配
5. **手机号格式**：
- 支持国内手机号（11位数字）
- 支持国际手机号（需要加国家代码）
6. **发送频率**：
- 注意阿里云的发送频率限制
- 建议实现发送频率控制
7. **错误处理**：
- 所有操作都应该进行错误处理
- 建议记录详细的错误日志
- 注意区分业务错误和系统错误
8. **批量发送**：
- 支持一次发送给多个手机号
- 注意批量发送的数量限制
## 完整示例
```go
package main
import (
"fmt"
"log"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/sms"
)
func main() {
// 加载配置
cfg, err := config.LoadFromFile("./config.json")
if err != nil {
log.Fatal(err)
}
// 创建短信发送器
smsClient, err := sms.NewSMS(cfg.GetSMS())
if err != nil {
log.Fatal(err)
}
// 发送验证码短信
templateParam := map[string]string{
"code": "123456",
"expire": "5",
}
resp, err := smsClient.SendSimple(
[]string{"13800138000"},
templateParam,
)
if err != nil {
log.Fatal(err)
}
fmt.Printf("发送成功，RequestID: %s\n", resp.RequestID)
}
```
## 示例
完整示例请参考 `examples/sms_example.go`

496
docs/storage.md
View File

@@ -1,496 +0,0 @@
# 存储工具文档
## 概述
存储工具提供了文件上传和查看功能，支持OSS和MinIO两种存储方式，并提供HTTP处理器用于文件上传和代理查看。
## 功能特性
- 支持OSS对象存储（阿里云、腾讯云、AWS、七牛云等）
- 支持MinIO对象存储
- 提供统一的存储接口
- 支持文件上传HTTP处理器
- 支持文件代理查看HTTP处理器
- 支持文件大小和扩展名限制
- 自动生成唯一文件名
- 支持自定义对象键前缀
## 使用方法
### 1. 创建存储实例
```go
import (
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/storage"
)
// 加载配置
cfg, err := config.LoadFromFile("./config.json")
if err != nil {
log.Fatal(err)
}
// 创建OSS存储实例
ossStorage, err := storage.NewStorage(storage.StorageTypeOSS, cfg)
if err != nil {
log.Fatal(err)
}
// 创建MinIO存储实例
minioStorage, err := storage.NewStorage(storage.StorageTypeMinIO, cfg)
if err != nil {
log.Fatal(err)
}
```
### 2. 上传文件
```go
import (
"context"
"os"
"git.toowon.com/jimmy/go-common/storage"
)
// 打开文件
file, err := os.Open("test.jpg")
if err != nil {
log.Fatal(err)
}
defer file.Close()
// 上传文件
ctx := context.Background()
objectKey := "images/test.jpg"
err = ossStorage.Upload(ctx, objectKey, file, "image/jpeg")
if err != nil {
log.Fatal(err)
}
// 获取文件URL
url, err := ossStorage.GetURL(objectKey, 0)
if err != nil {
log.Fatal(err)
}
fmt.Printf("File URL: %s\n", url)
```
### 3. 使用HTTP处理器上传文件
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/storage"
)
// 创建上传处理器
uploadHandler := storage.NewUploadHandler(storage.UploadHandlerConfig{
Storage: ossStorage,
MaxFileSize: 10 * 1024 * 1024, // 10MB
AllowedExts: []string{".jpg", ".jpeg", ".png", ".gif"},
ObjectPrefix: "images/",
})
// 注册路由
http.Handle("/upload", uploadHandler)
http.ListenAndServe(":8080", nil)
```
**上传请求示例：**
```bash
curl -X POST http://localhost:8080/upload \
-F "file=@test.jpg" \
-F "prefix=images/"
```
**响应示例：**
```json
{
"code": 0,
"message": "Upload successful",
"timestamp": 1704067200,
"data": {
"objectKey": "images/test_1704067200000000000.jpg",
"url": "https://bucket.oss-cn-hangzhou.aliyuncs.com/images/test_1704067200000000000.jpg",
"size": 102400,
"contentType": "image/jpeg",
"uploadTime": "2024-01-01T12:00:00Z"
}
}
```
### 4. 使用HTTP处理器查看文件
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/storage"
)
// 创建代理查看处理器
proxyHandler := storage.NewProxyHandler(ossStorage)
// 注册路由
http.Handle("/file", proxyHandler)
http.ListenAndServe(":8080", nil)
```
**查看请求示例：**
```
GET /file?key=images/test.jpg
```
### 5. 生成对象键
```go
import "git.toowon.com/jimmy/go-common/storage"
// 生成简单对象键
objectKey := storage.GenerateObjectKey("images/", "test.jpg")
// 输出: "images/test.jpg"
// 生成带日期的对象键
objectKey := storage.GenerateObjectKeyWithDate("images", "test.jpg")
// 输出: "images/2024/01/01/test.jpg"
```
### 6. 删除文件
```go
ctx := context.Background()
err := ossStorage.Delete(ctx, "images/test.jpg")
if err != nil {
log.Fatal(err)
}
```
### 7. 检查文件是否存在
```go
ctx := context.Background()
exists, err := ossStorage.Exists(ctx, "images/test.jpg")
if err != nil {
log.Fatal(err)
}
if exists {
fmt.Println("File exists")
}
```
## API 参考
### Storage 接口
```go
type Storage interface {
// Upload 上传文件
Upload(ctx context.Context, objectKey string, reader io.Reader, contentType ...string) error
// GetURL 获取文件访问URL
GetURL(objectKey string, expires int64) (string, error)
// Delete 删除文件
Delete(ctx context.Context, objectKey string) error
// Exists 检查文件是否存在
Exists(ctx context.Context, objectKey string) (bool, error)
// GetObject 获取文件内容
GetObject(ctx context.Context, objectKey string) (io.ReadCloser, error)
}
```
### NewStorage(storageType StorageType, cfg *config.Config) (Storage, error)
创建存储实例。
**参数：**
- `storageType`: 存储类型（`storage.StorageTypeOSS` 或 `storage.StorageTypeMinIO`）
- `cfg`: 配置对象
**返回：** 存储实例和错误信息
### UploadHandler
文件上传HTTP处理器。
#### NewUploadHandler(cfg UploadHandlerConfig) *UploadHandler
创建上传处理器。
**配置参数：**
- `Storage`: 存储实例
- `MaxFileSize`: 最大文件大小（字节），0表示不限制
- `AllowedExts`: 允许的文件扩展名，空表示不限制
- `ObjectPrefix`: 对象键前缀
#### 请求格式
- **方法**: POST
- **表单字段**:
- `file`: 文件（必需）
- `prefix`: 对象键前缀（可选，会覆盖配置中的前缀）
#### 响应格式
```json
{
"code": 0,
"message": "Upload successful",
"timestamp": 1704067200,
"data": {
"objectKey": "images/test.jpg",
"url": "https://...",
"size": 102400,
"contentType": "image/jpeg",
"uploadTime": "2024-01-01T12:00:00Z"
}
}
```
### ProxyHandler
文件代理查看HTTP处理器。
#### NewProxyHandler(storage Storage) *ProxyHandler
创建代理查看处理器。
#### 请求格式
- **方法**: GET
- **URL参数**:
- `key`: 对象键（必需）
#### 响应
直接返回文件内容，设置适当的Content-Type。
### 辅助函数
#### GenerateObjectKey(prefix, filename string) string
生成对象键。
#### GenerateObjectKeyWithDate(prefix, filename string) string
生成带日期的对象键（格式: prefix/YYYY/MM/DD/filename）。
## 完整示例
### 示例1：文件上传和查看
```go
package main
import (
"log"
"net/http"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/storage"
)
func main() {
// 加载配置
cfg, err := config.LoadFromFile("./config.json")
if err != nil {
log.Fatal(err)
}
// 创建存储实例（使用OSS）
ossStorage, err := storage.NewStorage(storage.StorageTypeOSS, cfg)
if err != nil {
log.Fatal(err)
}
// 创建上传处理器
uploadHandler := storage.NewUploadHandler(storage.UploadHandlerConfig{
Storage: ossStorage,
MaxFileSize: 10 * 1024 * 1024, // 10MB
AllowedExts: []string{".jpg", ".jpeg", ".png", ".gif", ".pdf"},
ObjectPrefix: "uploads/",
})
// 创建代理查看处理器
proxyHandler := storage.NewProxyHandler(ossStorage)
// 创建中间件链
chain := middleware.NewChain(
middleware.CORS(cfg.GetCORS()),
middleware.Timezone,
)
// 注册路由
mux := http.NewServeMux()
mux.Handle("/upload", chain.Then(uploadHandler))
mux.Handle("/file", chain.Then(proxyHandler))
log.Println("Server started on :8080")
log.Fatal(http.ListenAndServe(":8080", mux))
}
```
### 示例2：直接使用存储接口
```go
package main
import (
"context"
"fmt"
"log"
"os"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/storage"
)
func main() {
// 加载配置
cfg, err := config.LoadFromFile("./config.json")
if err != nil {
log.Fatal(err)
}
// 创建存储实例
s, err := storage.NewStorage(storage.StorageTypeMinIO, cfg)
if err != nil {
log.Fatal(err)
}
// 打开文件
file, err := os.Open("test.jpg")
if err != nil {
log.Fatal(err)
}
defer file.Close()
// 生成对象键
objectKey := storage.GenerateObjectKeyWithDate("images", "test.jpg")
// 上传文件
ctx := context.Background()
err = s.Upload(ctx, objectKey, file, "image/jpeg")
if err != nil {
log.Fatal(err)
}
// 获取文件URL
url, err := s.GetURL(objectKey, 0)
if err != nil {
log.Fatal(err)
}
fmt.Printf("File uploaded: %s\n", url)
}
```
## 注意事项
1. **OSS和MinIO SDK实现**：
- 当前实现提供了接口和框架，但具体的OSS和MinIO SDK集成需要根据实际使用的SDK实现
- 需要在`oss.go`和`minio.go`中实现具体的SDK调用
2. **文件大小限制**：
- 建议设置合理的文件大小限制
- 大文件上传可能需要分片上传
3. **文件扩展名验证**：
- 建议限制允许的文件类型，防止上传恶意文件
- 仅验证扩展名不够安全，建议结合文件内容验证
4. **安全性**：
- 上传接口应该添加身份验证
- 代理查看接口可以添加访问控制
5. **性能优化**：
- 对于大文件，考虑使用分片上传
- 代理查看可以添加缓存机制
6. **错误处理**：
- 所有操作都应该进行错误处理
- 建议记录详细的错误日志
## 实现OSS和MinIO SDK集成
由于不同的OSS提供商和MinIO有不同的SDK，当前实现提供了框架，需要根据实际情况集成：
### OSS SDK集成示例（阿里云OSS）
```go
import (
"github.com/aliyun/aliyun-oss-go-sdk/oss"
)
func NewOSSStorage(cfg *config.OSSConfig) (*OSSStorage, error) {
client, err := oss.New(cfg.Endpoint, cfg.AccessKeyID, cfg.AccessKeySecret)
if err != nil {
return nil, err
}
storage := &OSSStorage{
config: cfg,
client: client,
}
return storage, nil
}
func (s *OSSStorage) Upload(ctx context.Context, objectKey string, reader io.Reader, contentType ...string) error {
bucket, err := s.client.Bucket(s.config.Bucket)
if err != nil {
return err
}
options := []oss.Option{}
if len(contentType) > 0 && contentType[0] != "" {
options = append(options, oss.ContentType(contentType[0]))
}
return bucket.PutObject(objectKey, reader, options...)
}
```
### MinIO SDK集成示例
```go
import (
"github.com/minio/minio-go/v7"
"github.com/minio/minio-go/v7/pkg/credentials"
)
func NewMinIOStorage(cfg *config.MinIOConfig) (*MinIOStorage, error) {
client, err := minio.New(cfg.Endpoint, &minio.Options{
Creds: credentials.NewStaticV4(cfg.AccessKeyID, cfg.SecretAccessKey, ""),
Secure: cfg.UseSSL,
})
if err != nil {
return nil, err
}
storage := &MinIOStorage{
config: cfg,
client: client,
}
return storage, nil
}
func (s *MinIOStorage) Upload(ctx context.Context, objectKey string, reader io.Reader, contentType ...string) error {
ct := "application/octet-stream"
if len(contentType) > 0 && contentType[0] != "" {
ct = contentType[0]
}
_, err := s.client.PutObject(ctx, s.config.Bucket, objectKey, reader, -1, minio.PutObjectOptions{
ContentType: ct,
})
return err
}
```
## 示例
完整示例请参考 `examples/storage_example.go`

354
email/email.go
View File

@@ -2,274 +2,272 @@ package email
import (
"bytes"
"context"
"crypto/tls"
"fmt"
"net"
"net/smtp"
"sync"
"sync/atomic"
"time"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/logger"
)
// Email 邮件发送器
type Email struct {
config *config.EmailConfig
async bool
queue chan emailTask
workers int
wg sync.WaitGroup
closed bool
mu sync.Mutex
dropped atomic.Uint64
}
type emailTask struct {
to []string
subject string
body string
htmlBody string
requestID string
}
// NewEmail 创建邮件发送器
func NewEmail(cfg *config.EmailConfig) (*Email, error) {
if cfg == nil {
func NewEmail(cfg *config.Config) *Email {
if cfg == nil || cfg.Email == nil {
return &Email{config: nil}
}
e := &Email{
config: cfg.Email,
async: cfg.Email.IsAsync(),
workers: cfg.Email.Workers,
}
if e.workers <= 0 {
e.workers = 2
}
queueSize := cfg.Email.QueueSize
if queueSize <= 0 {
queueSize = 1000
}
if e.async {
e.queue = make(chan emailTask, queueSize)
for i := 0; i < e.workers; i++ {
e.wg.Add(1)
go e.worker()
}
}
return e
}
func (e *Email) worker() {
defer e.wg.Done()
for task := range e.queue {
if err := e.SendEmail(task.to, task.subject, task.body, task.htmlBody); err != nil {
fields := map[string]any{
"error": err.Error(),
"request_id": task.requestID,
"to": task.to,
}
logger.FromContext(context.Background()).Error("async email send failed", fields)
}
}
}
func (e *Email) getEmailConfig() (*config.EmailConfig, error) {
if e.config == nil {
return nil, fmt.Errorf("email config is nil")
}
if cfg.Host == "" {
if e.config.Host == "" {
return nil, fmt.Errorf("email host is required")
}
if cfg.Username == "" {
if e.config.Username == "" {
return nil, fmt.Errorf("email username is required")
}
if cfg.Password == "" {
if e.config.Password == "" {
return nil, fmt.Errorf("email password is required")
}
// 设置默认值
if cfg.Port == 0 {
cfg.Port = 587
if e.config.Port == 0 {
e.config.Port = 587
}
if cfg.From == "" {
cfg.From = cfg.Username
if e.config.From == "" {
e.config.From = e.config.Username
}
if cfg.Timeout == 0 {
cfg.Timeout = 30
if e.config.Timeout == 0 {
e.config.Timeout = 5
}
return &Email{
config: cfg,
}, nil
return e.config, nil
}
// Message 邮件消息
type Message struct {
// To 收件人列表
To []string
// Cc 抄送列表（可选）
Cc []string
// Bcc 密送列表（可选）
Bcc []string
// Subject 主题
Subject string
// Body 正文（纯文本）
Body string
// HTMLBody HTML正文（可选，如果设置了会优先使用）
HTMLBody string
// Attachments 附件列表（可选）
Attachments []Attachment
}
// Attachment 附件
type Attachment struct {
// Filename 文件名
Filename string
// Content 文件内容
Content []byte
// ContentType 文件类型（如：application/pdf）
ContentType string
// SendEmail 同步发送邮件（验证码等需等待结果的场景）
func (e *Email) SendEmail(to []string, subject, body string, htmlBody ...string) error {
cfg, err := e.getEmailConfig()
if err != nil {
return err
}
msg := &Message{To: to, Subject: subject, Body: body}
if len(htmlBody) > 0 && htmlBody[0] != "" {
msg.HTMLBody = htmlBody[0]
}
return e.send(msg, cfg)
}
// SendRaw 发送原始邮件内容
// recipients: 收件人列表（To、Cc、Bcc的合并列表）
// body: 完整的邮件内容（MIME格式），由外部构建
func (e *Email) SendRaw(recipients []string, body []byte) error {
if len(recipients) == 0 {
// SendEmailAsync 异步发送邮件（HTTP 通知类场景）
func (e *Email) SendEmailAsync(ctx context.Context, to []string, subject, body string, htmlBody ...string) {
task := emailTask{
to: append([]string(nil), to...),
subject: subject,
body: body,
requestID: logger.RequestIDFromContext(ctx),
}
if len(htmlBody) > 0 {
task.htmlBody = htmlBody[0]
}
if !e.async {
_ = e.SendEmail(task.to, task.subject, task.body, task.htmlBody)
return
}
select {
case e.queue <- task:
default:
e.dropped.Add(1)
logger.FromContext(ctx).Error("email queue full, task dropped", map[string]any{
"to": to,
})
}
}
// Close 关闭异步 worker
func (e *Email) Close() error {
if !e.async {
return nil
}
e.mu.Lock()
if e.closed {
e.mu.Unlock()
return nil
}
e.closed = true
e.mu.Unlock()
close(e.queue)
e.wg.Wait()
return nil
}
func (e *Email) send(msg *Message, cfg *config.EmailConfig) error {
if msg == nil {
return fmt.Errorf("message is nil")
}
if len(msg.To) == 0 {
return fmt.Errorf("recipients are required")
}
if len(body) == 0 {
return fmt.Errorf("email body is required")
if msg.Subject == "" {
return fmt.Errorf("subject is required")
}
if msg.Body == "" && msg.HTMLBody == "" {
return fmt.Errorf("body or HTMLBody is required")
}
// 连接SMTP服务器
addr := fmt.Sprintf("%s:%d", e.config.Host, e.config.Port)
auth := smtp.PlainAuth("", e.config.Username, e.config.Password, e.config.Host)
emailBody, err := e.buildEmailBody(msg, cfg)
if err != nil {
return fmt.Errorf("failed to build email body: %w", err)
}
// 创建连接
conn, err := net.DialTimeout("tcp", addr, time.Duration(e.config.Timeout)*time.Second)
recipients := append(msg.To, msg.Cc...)
recipients = append(recipients, msg.Bcc...)
addr := net.JoinHostPort(cfg.Host, fmt.Sprintf("%d", cfg.Port))
auth := smtp.PlainAuth("", cfg.Username, cfg.Password, cfg.Host)
conn, err := net.DialTimeout("tcp", addr, time.Duration(cfg.Timeout)*time.Second)
if err != nil {
return fmt.Errorf("failed to connect to SMTP server: %w", err)
}
defer conn.Close()
// 创建SMTP客户端
client, err := smtp.NewClient(conn, e.config.Host)
client, err := smtp.NewClient(conn, cfg.Host)
if err != nil {
return fmt.Errorf("failed to create SMTP client: %w", err)
}
defer client.Close()
// TLS/SSL处理
if e.config.UseSSL {
// SSL模式（端口通常是465）
tlsConfig := &tls.Config{
ServerName: e.config.Host,
}
if err := client.StartTLS(tlsConfig); err != nil {
return fmt.Errorf("failed to start TLS: %w", err)
}
} else if e.config.UseTLS {
// TLS模式（STARTTLS，端口通常是587）
tlsConfig := &tls.Config{
ServerName: e.config.Host,
}
if cfg.UseSSL || cfg.UseTLS {
tlsConfig := &tls.Config{ServerName: cfg.Host}
if err := client.StartTLS(tlsConfig); err != nil {
return fmt.Errorf("failed to start TLS: %w", err)
}
}
// 认证
if err := client.Auth(auth); err != nil {
return fmt.Errorf("failed to authenticate: %w", err)
}
// 设置发件人
if err := client.Mail(e.config.From); err != nil {
if err := client.Mail(cfg.From); err != nil {
return fmt.Errorf("failed to set sender: %w", err)
}
// 设置收件人
for _, to := range recipients {
if err := client.Rcpt(to); err != nil {
return fmt.Errorf("failed to set recipient %s: %w", to, err)
}
}
// 发送邮件内容
writer, err := client.Data()
if err != nil {
return fmt.Errorf("failed to get data writer: %w", err)
}
_, err = writer.Write(body)
if err != nil {
writer.Close()
if _, err = writer.Write(emailBody); err != nil {
_ = writer.Close()
return fmt.Errorf("failed to write email body: %w", err)
}
err = writer.Close()
if err != nil {
if err = writer.Close(); err != nil {
return fmt.Errorf("failed to close writer: %w", err)
}
// 退出
if err := client.Quit(); err != nil {
return fmt.Errorf("failed to quit: %w", err)
}
return nil
}
// Send 发送邮件（使用Message结构，内部会构建邮件内容）
// 注意：如果需要完全控制邮件内容，请使用SendRaw方法
func (e *Email) Send(msg *Message) error {
if msg == nil {
return fmt.Errorf("message is nil")
}
if len(msg.To) == 0 {
return fmt.Errorf("recipients are required")
}
if msg.Subject == "" {
return fmt.Errorf("subject is required")
}
if msg.Body == "" && msg.HTMLBody == "" {
return fmt.Errorf("body or HTMLBody is required")
}
// 构建邮件内容
emailBody, err := e.buildEmailBody(msg)
if err != nil {
return fmt.Errorf("failed to build email body: %w", err)
}
// 合并收件人列表
recipients := append(msg.To, msg.Cc...)
recipients = append(recipients, msg.Bcc...)
// 使用SendRaw发送
return e.SendRaw(recipients, emailBody)
}
// buildEmailBody 构建邮件内容
func (e *Email) buildEmailBody(msg *Message) ([]byte, error) {
func (e *Email) buildEmailBody(msg *Message, cfg *config.EmailConfig) ([]byte, error) {
var buf bytes.Buffer
// 邮件头
from := e.config.From
if e.config.FromName != "" {
from = fmt.Sprintf("%s <%s>", e.config.FromName, e.config.From)
from := cfg.From
if cfg.FromName != "" {
from = fmt.Sprintf("%s <%s>", cfg.FromName, cfg.From)
}
buf.WriteString(fmt.Sprintf("From: %s\r\n", from))
// 收件人
buf.WriteString(fmt.Sprintf("To: %s\r\n", joinEmails(msg.To)))
// 抄送
if len(msg.Cc) > 0 {
buf.WriteString(fmt.Sprintf("Cc: %s\r\n", joinEmails(msg.Cc)))
}
// 主题
buf.WriteString(fmt.Sprintf("Subject: %s\r\n", msg.Subject))
// 内容类型
if msg.HTMLBody != "" {
// 多部分邮件（HTML + 纯文本）
boundary := "----=_Part_" + fmt.Sprint(time.Now().UnixNano())
buf.WriteString("MIME-Version: 1.0\r\n")
buf.WriteString(fmt.Sprintf("Content-Type: multipart/alternative; boundary=\"%s\"\r\n", boundary))
buf.WriteString("\r\n")
// 纯文本部分
buf.WriteString("--" + boundary + "\r\n")
buf.WriteString("Content-Type: text/plain; charset=UTF-8\r\n")
buf.WriteString("Content-Transfer-Encoding: quoted-printable\r\n")
buf.WriteString("\r\n")
buf.WriteString(msg.Body)
buf.WriteString("\r\n")
// HTML部分
buf.WriteString("--" + boundary + "\r\n")
buf.WriteString("Content-Type: text/html; charset=UTF-8\r\n")
buf.WriteString("Content-Transfer-Encoding: quoted-printable\r\n")
buf.WriteString("\r\n")
buf.WriteString(msg.HTMLBody)
buf.WriteString("\r\n")
buf.WriteString(fmt.Sprintf("Content-Type: multipart/alternative; boundary=\"%s\"\r\n\r\n", boundary))
buf.WriteString("--" + boundary + "\r\nContent-Type: text/plain; charset=UTF-8\r\n\r\n")
buf.WriteString(msg.Body + "\r\n")
buf.WriteString("--" + boundary + "\r\nContent-Type: text/html; charset=UTF-8\r\n\r\n")
buf.WriteString(msg.HTMLBody + "\r\n")
buf.WriteString("--" + boundary + "--\r\n")
} else {
// 纯文本邮件
buf.WriteString("Content-Type: text/plain; charset=UTF-8\r\n")
buf.WriteString("Content-Transfer-Encoding: quoted-printable\r\n")
buf.WriteString("\r\n")
buf.WriteString(msg.Body)
buf.WriteString("\r\n")
buf.WriteString("Content-Type: text/plain; charset=UTF-8\r\n\r\n")
buf.WriteString(msg.Body + "\r\n")
}
return buf.Bytes(), nil
}
// joinEmails 连接邮箱地址
func joinEmails(emails []string) string {
if len(emails) == 0 {
return ""
@@ -280,27 +278,3 @@ func joinEmails(emails []string) string {
}
return result
}
// SendSimple 发送简单邮件（便捷方法）
// to: 收件人
// subject: 主题
// body: 正文
func (e *Email) SendSimple(to []string, subject, body string) error {
return e.Send(&Message{
To: to,
Subject: subject,
Body: body,
})
}
// SendHTML 发送HTML邮件（便捷方法）
// to: 收件人
// subject: 主题
// htmlBody: HTML正文
func (e *Email) SendHTML(to []string, subject, htmlBody string) error {
return e.Send(&Message{
To: to,
Subject: subject,
HTMLBody: htmlBody,
})
}

26
examples/config_example.go
View File

@@ -1,3 +1,6 @@
//go:build example
// +build example
package main
import (
@@ -65,16 +68,27 @@ func main() {
// 4. 使用CORS配置
fmt.Println("\n=== CORS Config ===")
corsConfig := cfg.GetCORS()
if corsConfig != nil {
fmt.Printf("Allowed Origins: %v\n", corsConfig.AllowedOrigins)
fmt.Printf("Allowed Methods: %v\n", corsConfig.AllowedMethods)
fmt.Printf("Max Age: %d\n", corsConfig.MaxAge)
configCORS := cfg.GetCORS()
if configCORS != nil {
fmt.Printf("Allowed Origins: %v\n", configCORS.AllowedOrigins)
fmt.Printf("Allowed Methods: %v\n", configCORS.AllowedMethods)
fmt.Printf("Max Age: %d\n", configCORS.MaxAge)
}
// 使用CORS配置创建中间件
var middlewareCORS *middleware.CORSConfig
if configCORS != nil {
middlewareCORS = middleware.NewCORSConfig(
configCORS.AllowedOrigins,
configCORS.AllowedMethods,
configCORS.AllowedHeaders,
configCORS.ExposedHeaders,
configCORS.AllowCredentials,
configCORS.MaxAge,
)
}
chain := middleware.NewChain(
middleware.CORS(corsConfig),
middleware.CORS(middlewareCORS),
)
fmt.Printf("CORS middleware created: %v\n", chain != nil)

56
examples/datetime_example.go
View File

@@ -1,56 +0,0 @@
package main
import (
"fmt"
"log"
"time"
"git.toowon.com/jimmy/go-common/datetime"
)
func main() {
// 设置默认时区
err := datetime.SetDefaultTimeZone(datetime.AsiaShanghai)
if err != nil {
log.Fatal(err)
}
// 获取当前时间
now := datetime.Now()
fmt.Printf("Current time: %s\n", datetime.FormatDateTime(now))
// 解析时间字符串
t, err := datetime.ParseDateTime("2024-01-01 12:00:00")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Parsed time: %s\n", datetime.FormatDateTime(t))
// 时区转换
t2, err := datetime.ToTimezone(t, datetime.AmericaNewYork)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Time in New York: %s\n", datetime.FormatDateTime(t2))
// Unix时间戳
unix := datetime.ToUnix(now)
fmt.Printf("Unix timestamp: %d\n", unix)
t3 := datetime.FromUnix(unix)
fmt.Printf("From Unix: %s\n", datetime.FormatDateTime(t3))
// 时间计算
tomorrow := datetime.AddDays(now, 1)
fmt.Printf("Tomorrow: %s\n", datetime.FormatDate(tomorrow))
// 时间范围
startOfDay := datetime.StartOfDay(now)
endOfDay := datetime.EndOfDay(now)
fmt.Printf("Start of day: %s\n", datetime.FormatDateTime(startOfDay))
fmt.Printf("End of day: %s\n", datetime.FormatDateTime(endOfDay))
// 时间差
diff := datetime.DiffDays(now, tomorrow)
fmt.Printf("Days difference: %d\n", diff)
}

74
examples/datetime_utc_example.go
View File

@@ -1,74 +0,0 @@
package main
import (
"fmt"
"log"
"time"
"git.toowon.com/jimmy/go-common/datetime"
)
func main() {
// 示例1：将当前时间转换为UTC
fmt.Println("=== Example 1: Convert Current Time to UTC ===")
now := time.Now()
utcTime := datetime.ToUTC(now)
fmt.Printf("Local time: %s\n", datetime.FormatDateTime(now))
fmt.Printf("UTC time: %s\n", datetime.FormatDateTime(utcTime))
// 示例2：从指定时区转换为UTC
fmt.Println("\n=== Example 2: Convert from Specific Timezone to UTC ===")
// 解析上海时区的时间
shanghaiTime, err := datetime.ParseDateTime("2024-01-01 12:00:00", datetime.AsiaShanghai)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Shanghai time: %s\n", datetime.FormatDateTime(shanghaiTime, datetime.AsiaShanghai))
// 转换为UTC
utcTime2, err := datetime.ToUTCFromTimezone(shanghaiTime, datetime.AsiaShanghai)
if err != nil {
log.Fatal(err)
}
fmt.Printf("UTC time: %s\n", datetime.FormatDateTime(utcTime2, datetime.UTC))
// 示例3：解析时间字符串并直接转换为UTC
fmt.Println("\n=== Example 3: Parse and Convert to UTC ===")
utcTime3, err := datetime.ParseDateTimeToUTC("2024-01-01 12:00:00", datetime.AsiaShanghai)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Parsed from Shanghai timezone, UTC: %s\n", datetime.FormatDateTime(utcTime3, datetime.UTC))
// 示例4：解析日期并转换为UTC
fmt.Println("\n=== Example 4: Parse Date and Convert to UTC ===")
utcTime4, err := datetime.ParseDateToUTC("2024-01-01", datetime.AsiaShanghai)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Date parsed from Shanghai timezone, UTC: %s\n", datetime.FormatDateTime(utcTime4, datetime.UTC))
// 示例5：数据库存储场景
fmt.Println("\n=== Example 5: Database Storage Scenario ===")
// 从请求中获取时间（假设是上海时区）
requestTimeStr := "2024-01-01 12:00:00"
requestTimezone := datetime.AsiaShanghai
// 转换为UTC时间（用于数据库存储）
dbTime, err := datetime.ParseDateTimeToUTC(requestTimeStr, requestTimezone)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Request time (Shanghai): %s\n", requestTimeStr)
fmt.Printf("Database time (UTC): %s\n", datetime.FormatDateTime(dbTime, datetime.UTC))
// 从数据库读取UTC时间，转换为用户时区显示
userTimezone := datetime.AsiaShanghai
displayTime, err := datetime.ToTimezone(dbTime, userTimezone)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Display time (Shanghai): %s\n", datetime.FormatDateTime(displayTime, userTimezone))
}

8
examples/doc.go Normal file
View File

@@ -0,0 +1,8 @@
// Package examples contains build-tagged example programs.
//
// 所有示例程序默认不参与 `go test ./...` 编译，避免多个 main 冲突。
//
// 运行示例：
// go run -tags example ./examples/storage_example.go
package examples

113
examples/email_example.go
View File

@@ -1,3 +1,6 @@
//go:build example
// +build example
package main
import (
@@ -5,117 +8,35 @@ import (
"log"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/email"
"git.toowon.com/jimmy/go-common/factory"
)
func main() {
// 加载配置
cfg, err := config.LoadFromFile("./config/example.json")
if err != nil {
log.Fatal("Failed to load config:", err)
log.Fatal(err)
}
// 创建邮件发送器
emailConfig := cfg.GetEmail()
if emailConfig == nil {
log.Fatal("Email config is nil")
}
mailer, err := email.NewEmail(emailConfig)
app := factory.New(cfg)
mail, err := app.Email()
if err != nil {
log.Fatal("Failed to create email client:", err)
log.Fatal(err)
}
defer mail.Close()
// 示例1：发送原始邮件内容（推荐，最灵活）
fmt.Println("=== Example 1: Send Raw Email Content ===")
// 外部构建完整的邮件内容（MIME格式）
emailBody := []byte(`From: ` + emailConfig.From + `
To: recipient@example.com
Subject: 原始邮件测试
Content-Type: text/html; charset=UTF-8
<html>
<body>
<h1>这是原始邮件内容</h1>
<p>由外部完全控制邮件格式和内容</p>
</body>
</html>
`)
err = mailer.SendRaw(
[]string{"recipient@example.com"},
emailBody,
)
if err != nil {
log.Printf("Failed to send raw email: %v", err)
} else {
fmt.Println("Raw email sent successfully")
}
// 示例2：发送简单邮件（便捷方法）
fmt.Println("\n=== Example 2: Send Simple Email ===")
err = mailer.SendSimple(
// 同步发送（验证码等需等待结果）
err = mail.SendEmail(
[]string{"recipient@example.com"},
"测试邮件",
"这是一封测试邮件，使用Go标准库发送。",
"这是一封测试邮件。",
)
if err != nil {
log.Printf("Failed to send email: %v", err)
log.Printf("sync send failed: %v", err)
} else {
fmt.Println("Email sent successfully")
fmt.Println("sync email sent")
}
// 示例3：发送HTML邮件
fmt.Println("\n=== Example 3: Send HTML Email ===")
htmlBody := `
<html>
<head>
<meta charset="UTF-8">
</head>
<body>
<h1>欢迎使用邮件服务</h1>
<p>这是一封HTML格式的邮件。</p>
<p>支持<strong>富文本</strong>格式。</p>
</body>
</html>
`
err = mailer.SendHTML(
[]string{"recipient@example.com"},
"HTML邮件测试",
htmlBody,
)
if err != nil {
log.Printf("Failed to send HTML email: %v", err)
} else {
fmt.Println("HTML email sent successfully")
}
// 示例4：发送完整邮件（包含抄送、密送）
fmt.Println("\n=== Example 4: Send Full Email ===")
msg := &email.Message{
To: []string{"to@example.com"},
Cc: []string{"cc@example.com"},
Bcc: []string{"bcc@example.com"},
Subject: "完整邮件示例",
Body: "这是纯文本正文",
HTMLBody: `
<html>
<body>
<h1>这是HTML正文</h1>
<p>支持同时发送纯文本和HTML版本。</p>
</body>
</html>
`,
}
err = mailer.Send(msg)
if err != nil {
log.Printf("Failed to send full email: %v", err)
} else {
fmt.Println("Full email sent successfully")
}
fmt.Println("\nNote: Make sure your email configuration is correct and SMTP service is enabled.")
// 异步发送（HTTP 通知类）
mail.SendEmailAsync(nil, []string{"recipient@example.com"}, "异步通知", "后台发送，不阻塞请求")
fmt.Println("async email enqueued")
}

69
examples/excel_example.go Normal file
View File

@@ -0,0 +1,69 @@
//go:build example
// +build example
package main
import (
"fmt"
"log"
"os"
"time"
"git.toowon.com/jimmy/go-common/excel"
"git.toowon.com/jimmy/go-common/factory"
"git.toowon.com/jimmy/go-common/tools"
)
type User struct {
ID int `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
CreatedAt time.Time `json:"created_at"`
Status int `json:"status"`
}
func main() {
app := factory.New(nil)
ex := app.Excel()
users := []User{
{ID: 1, Name: "Alice", Email: "alice@example.com", CreatedAt: time.Now(), Status: 1},
{ID: 2, Name: "Bob", Email: "bob@example.com", CreatedAt: time.Now(), Status: 0},
}
columns := []excel.ExportColumn{
{Header: "ID", Field: "ID", Width: 10},
{Header: "姓名", Field: "Name", Width: 20},
{Header: "邮箱", Field: "Email", Width: 30},
{
Header: "创建时间",
Field: "CreatedAt",
Format: excel.AdaptTimeFormatter(tools.FormatDateTime),
},
{
Header: "状态",
Field: "Status",
Format: func(value interface{}) string {
if status, ok := value.(int); ok && status == 1 {
return "启用"
}
return "禁用"
},
},
}
if err := ex.ExportToFile("users.xlsx", "用户列表", columns, users); err != nil {
log.Fatal(err)
}
fmt.Println("exported users.xlsx")
f, err := os.Create("users_http.xlsx")
if err != nil {
log.Fatal(err)
}
defer f.Close()
if err := ex.ExportToWriter(f, "用户列表", columns, users); err != nil {
log.Fatal(err)
}
fmt.Println("exported users_http.xlsx")
}

186
examples/factory_example.go
View File

@@ -1,186 +0,0 @@
package main
import (
"context"
"fmt"
"log"
"os"
"time"
"git.toowon.com/jimmy/go-common/factory"
"github.com/redis/go-redis/v9"
)
func main() {
// 方式1：直接从配置文件创建工厂（推荐）
fac, err := factory.NewFactoryFromFile("./config/example.json")
if err != nil {
log.Fatal("Failed to create factory:", err)
}
ctx := context.Background()
// ========== 日志记录（黑盒模式，推荐） ==========
fac.LogInfo("应用启动")
fac.LogDebug("调试信息: %s", "test")
fac.LogWarn("警告信息")
fac.LogError("错误信息: %v", fmt.Errorf("test error"))
// 带字段的日志
fac.LogInfof(map[string]interface{}{
"user_id": 123,
"ip": "192.168.1.1",
}, "用户登录成功")
fac.LogErrorf(map[string]interface{}{
"error_code": 1001,
"user_id": 123,
}, "登录失败: %v", fmt.Errorf("invalid password"))
// ========== 邮件发送（黑盒模式，推荐） ==========
err = fac.SendEmail(
[]string{"user@example.com"},
"验证码",
"您的验证码是：123456",
)
if err != nil {
fac.LogError("发送邮件失败: %v", err)
} else {
fac.LogInfo("邮件发送成功")
}
// HTML邮件
err = fac.SendEmail(
[]string{"user@example.com"},
"欢迎",
"纯文本内容",
"<h1>HTML内容</h1>",
)
if err != nil {
fac.LogError("发送HTML邮件失败: %v", err)
}
// ========== 短信发送（黑盒模式，推荐） ==========
resp, err := fac.SendSMS(
[]string{"13800138000"},
map[string]string{"code": "123456"},
)
if err != nil {
fac.LogError("发送短信失败: %v", err)
} else {
fac.LogInfo("短信发送成功: %s", resp.RequestID)
}
// 指定模板代码
resp, err = fac.SendSMS(
[]string{"13800138000"},
map[string]string{"code": "123456"},
"SMS_123456789", // 模板代码
)
if err != nil {
fac.LogError("发送短信失败: %v", err)
}
// ========== 文件上传（黑盒模式，推荐，自动选择OSS或MinIO） ==========
file, err := os.Open("test.jpg")
if err == nil {
defer file.Close()
url, err := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")
if err != nil {
fac.LogError("上传文件失败: %v", err)
} else {
fac.LogInfo("文件上传成功: %s", url)
}
}
// ========== 获取文件URL（黑盒模式） ==========
// 永久有效
url, err := fac.GetFileURL("images/test.jpg", 0)
if err != nil {
fac.LogError("获取文件URL失败: %v", err)
} else {
fac.LogInfo("文件URL: %s", url)
}
// 临时访问URL（1小时后过期）
url, err = fac.GetFileURL("images/test.jpg", 3600)
if err != nil {
fac.LogError("获取临时URL失败: %v", err)
} else {
fac.LogInfo("临时URL: %s", url)
}
// ========== Redis操作（黑盒模式，推荐） ==========
// 设置值（不过期）
err = fac.RedisSet(ctx, "user:123", "value")
if err != nil {
fac.LogError("Redis设置失败: %v", err)
}
// 设置值（带过期时间）
err = fac.RedisSet(ctx, "user:123", "value", time.Hour)
if err != nil {
fac.LogError("Redis设置失败: %v", err)
}
// 获取值
value, err := fac.RedisGet(ctx, "user:123")
if err != nil {
fac.LogError("Redis获取失败: %v", err)
} else {
fac.LogInfo("Redis值: %s", value)
}
// 删除键
err = fac.RedisDelete(ctx, "user:123", "user:456")
if err != nil {
fac.LogError("Redis删除失败: %v", err)
}
// 检查键是否存在
exists, err := fac.RedisExists(ctx, "user:123")
if err != nil {
fac.LogError("Redis检查失败: %v", err)
} else {
fac.LogInfo("键是否存在: %v", exists)
}
// ========== 数据库操作（黑盒模式，获取对象） ==========
db, err := fac.GetDatabase()
if err != nil {
fac.LogError("数据库连接失败: %v", err)
} else {
// 直接使用GORM，无需自己实现创建逻辑
var count int64
if err := db.Table("users").Count(&count).Error; err != nil {
fac.LogError("查询用户数量失败: %v", err)
} else {
fac.LogInfo("用户数量: %d", count)
}
}
// ========== Redis操作（获取客户端对象，黑盒模式） ==========
redisClient, err := fac.GetRedisClient()
if err != nil {
fac.LogError("Redis客户端不可用: %v", err)
} else {
// 直接使用Redis客户端，无需自己实现创建逻辑
val, err := redisClient.Get(ctx, "test_key").Result()
if err != nil && err != redis.Nil {
fac.LogError("Redis错误: %v", err)
} else if err == redis.Nil {
fac.LogInfo("Redis键不存在")
} else {
fac.LogInfo("Redis值: %s", val)
}
// 使用高级功能（如Hash操作）
redisClient.HSet(ctx, "user:123", "name", "John")
name, _ := redisClient.HGet(ctx, "user:123", "name").Result()
fac.LogInfo("Redis Hash值: %s", name)
}
fac.LogInfo("示例执行完成")
}

117
examples/http_handler_example.go
View File

@@ -1,109 +1,52 @@
//go:build example
// +build example
package main
import (
"log"
"net/http"
"git.toowon.com/jimmy/go-common/factory"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
// 用户结构
type User struct {
ID int64 `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
}
// 获取用户列表（使用Handler黑盒模式）
func GetUserList(h *commonhttp.Handler) {
// 获取分页参数（简洁方式）
pagination := h.ParsePaginationRequest()
page := pagination.GetPage()
pageSize := pagination.GetSize()
func main() {
if err := factory.Init("config.json"); err != nil {
log.Fatal(err)
}
app := factory.Default()
chain := app.MiddlewareChain()
// 获取查询参数（简洁方式）
_ = h.GetQuery("keyword", "") // 示例：获取查询参数
http.Handle("/users", chain.ThenFunc(listUsers))
log.Fatal(http.ListenAndServe(":8080", nil))
}
// 模拟查询数据
func listUsers(w http.ResponseWriter, r *http.Request) {
app := factory.Default()
i18n, _ := app.I18n()
h := commonhttp.NewHandler(w, r, commonhttp.WithI18n(i18n))
var req struct {
Keyword string `json:"keyword"`
commonhttp.PaginationRequest
}
if err := h.ParseJSON(&req); err != nil {
h.Error("common.invalid_request")
return
}
p := h.Pagination()
users := []User{
{ID: 1, Name: "User1", Email: "user1@example.com"},
{ID: 2, Name: "User2", Email: "user2@example.com"},
}
total := int64(100)
// 返回分页响应（简洁方式）
h.SuccessPage(users, total, page, pageSize)
h.SuccessPage(users, 100)
_ = p
}
// 创建用户（使用Handler黑盒模式）
func CreateUser(h *commonhttp.Handler) {
// 解析请求体（简洁方式）
var req struct {
Name string `json:"name"`
Email string `json:"email"`
}
if err := h.ParseJSON(&req); err != nil {
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
// 参数验证
if req.Name == "" {
h.Error(1001, "用户名不能为空")
return
}
// 模拟创建用户
user := User{
ID: 1,
Name: req.Name,
Email: req.Email,
}
// 返回成功响应（简洁方式）
h.SuccessWithMessage("创建成功", user)
}
// 获取用户详情（使用Handler黑盒模式）
func GetUser(h *commonhttp.Handler) {
// 获取查询参数（简洁方式）
id := h.GetQueryInt64("id", 0)
if id == 0 {
h.WriteJSON(http.StatusBadRequest, 400, "用户ID不能为空", nil)
return
}
// 模拟查询用户
if id == 1 {
user := User{ID: 1, Name: "User1", Email: "user1@example.com"}
h.Success(user)
} else {
h.Error(1002, "用户不存在")
}
}
func main() {
// 方式1：使用HandleFunc包装器（推荐，最简洁）
http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
switch h.Request().Method {
case http.MethodGet:
GetUserList(h)
case http.MethodPost:
CreateUser(h)
default:
h.WriteJSON(http.StatusMethodNotAllowed, 405, "方法不支持", nil)
}
}))
// 方式2：手动创建Handler（需要更多控制时）
http.HandleFunc("/user", func(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
GetUser(h)
})
log.Println("Server started on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}

56
examples/http_pagination_example.go
View File

@@ -1,61 +1,57 @@
//go:build example
// +build example
package main
import (
"log"
"net/http"
"git.toowon.com/jimmy/go-common/factory"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
// ListUserRequest 用户列表请求（包含分页字段）
type ListUserRequest struct {
Keyword string `json:"keyword"`
commonhttp.PaginationRequest // 嵌入分页请求结构
commonhttp.PaginationRequest
}
// User 用户结构
type User struct {
ID int64 `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
}
// 获取用户列表（使用Handler和PaginationRequest）
func GetUserList(h *commonhttp.Handler) {
var req ListUserRequest
func main() {
if err := factory.Init("config.json"); err != nil {
log.Fatal(err)
}
app := factory.Default()
chain := app.MiddlewareChain()
http.Handle("/users", chain.ThenFunc(listUsers))
log.Fatal(http.ListenAndServe(":8080", nil))
}
// 方式1：从JSON请求体解析（分页字段会自动解析）
if h.Request().Method == http.MethodPost {
func listUsers(w http.ResponseWriter, r *http.Request) {
app := factory.Default()
i18n, _ := app.I18n()
h := commonhttp.NewHandler(w, r, commonhttp.WithI18n(i18n))
var req ListUserRequest
if r.Method == http.MethodPost {
if err := h.ParseJSON(&req); err != nil {
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
h.Error("common.invalid_request")
return
}
} else {
// 方式2：从查询参数解析分页
pagination := h.ParsePaginationRequest()
req.PaginationRequest = *pagination
req.Keyword = h.GetQuery("keyword", "")
p := h.Pagination()
req.PaginationRequest = *p
req.Keyword = r.URL.Query().Get("keyword")
}
// 使用分页方法
page := req.GetPage() // 获取页码（默认1）
size := req.GetSize() // 获取每页数量（默认20，最大100）
_ = req.GetOffset() // 计算偏移量
// 模拟查询数据
users := []User{
{ID: 1, Name: "User1", Email: "user1@example.com"},
{ID: 2, Name: "User2", Email: "user2@example.com"},
}
total := int64(100)
// 返回分页响应
h.SuccessPage(users, total, page, size)
}
func main() {
http.HandleFunc("/users", commonhttp.HandleFunc(GetUserList))
log.Println("Server started on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
h.SuccessPage(users, 100)
}

32
examples/i18n_example.go Normal file
View File

@@ -0,0 +1,32 @@
//go:build example
// +build example
package main
import (
"fmt"
"log"
"git.toowon.com/jimmy/go-common/factory"
)
func main() {
if err := factory.Init("config.json"); err != nil {
log.Fatal(err)
}
app := factory.Default()
i18n, err := app.I18n()
if err != nil {
log.Fatal(err)
}
if err := i18n.LoadFromDir("locales"); err != nil {
log.Fatal(err)
}
fmt.Println("zh-CN:", i18n.GetMessage("zh-CN", "user.not_found"))
fmt.Println("en-US:", i18n.GetMessage("en-US", "user.not_found"))
fmt.Println("welcome:", i18n.GetMessage("zh-CN", "user.welcome", "Alice"))
fmt.Println("langs:", i18n.GetSupportedLangs())
}

38
examples/locales/en-US.json Normal file
View File

@@ -0,0 +1,38 @@
{
"user.not_found": {
"code": 100002,
"message": "User not found"
},
"user.login_success": {
"code": 0,
"message": "Login successful"
},
"user.welcome": {
"code": 0,
"message": "Welcome, %s"
},
"user.logout": {
"code": 0,
"message": "Logout"
},
"error.invalid_params": {
"code": 100001,
"message": "Invalid parameters"
},
"error.server_error": {
"code": 100003,
"message": "Server error"
},
"order.created": {
"code": 0,
"message": "Order created successfully"
},
"order.paid": {
"code": 0,
"message": "Order paid successfully"
},
"message.count": {
"code": 0,
"message": "You have %d new messages"
}
}

38
examples/locales/zh-CN.json Normal file
View File

@@ -0,0 +1,38 @@
{
"user.not_found": {
"code": 100002,
"message": "用户不存在"
},
"user.login_success": {
"code": 0,
"message": "登录成功"
},
"user.welcome": {
"code": 0,
"message": "欢迎，%s"
},
"user.logout": {
"code": 0,
"message": "退出登录"
},
"error.invalid_params": {
"code": 100001,
"message": "参数无效"
},
"error.server_error": {
"code": 100003,
"message": "服务器错误"
},
"order.created": {
"code": 0,
"message": "订单创建成功"
},
"order.paid": {
"code": 0,
"message": "订单支付成功"
},
"message.count": {
"code": 0,
"message": "您有 %d 条新消息"
}
}

46
examples/logger_example.go
View File

@@ -1,3 +1,6 @@
//go:build example
// +build example
package main
import (
@@ -8,45 +11,24 @@ import (
)
func main() {
// 加载配置
cfg, err := config.LoadFromFile("./config/example.json")
if err != nil {
log.Fatal("Failed to load config:", err)
log.Fatal(err)
}
// 使用工厂创建日志记录器（推荐方式）
fac := factory.NewFactory(cfg)
logger, err := fac.GetLogger()
app := factory.New(cfg)
logInst, err := app.Logger()
if err != nil {
log.Fatal("Failed to create logger:", err)
log.Fatal(err)
}
defer logInst.Close()
// 示例1：基本日志记录
logger.Info("Application started")
logger.Debug("Debug message: %s", "This is a debug message")
logger.Warn("Warning message: %s", "This is a warning")
logger.Error("Error message: %s", "This is an error")
// 示例2：带字段的日志记录
logger.Infof(map[string]interface{}{
logInst.Info("Application started", nil)
logInst.Info("User logged in", map[string]any{
"user_id": 123,
"action": "login",
"ip": "192.168.1.1",
}, "User logged in successfully")
logger.Errorf(map[string]interface{}{
"error_code": 1001,
"module": "database",
}, "Failed to connect to database: %v", "connection timeout")
// 示例3：不同级别的日志
logger.Debug("This is a debug log")
logger.Info("This is an info log")
logger.Warn("This is a warn log")
logger.Error("This is an error log")
// 注意：Fatal和Panic会终止程序，示例中不执行
// logger.Fatal("This would exit the program")
// logger.Panic("This would panic")
})
logInst.Error("Failed to connect to database", map[string]any{
"error": "connection timeout",
})
}

66
examples/middleware_example.go
View File

@@ -1,66 +0,0 @@
package main
import (
"log"
"net/http"
"git.toowon.com/jimmy/go-common/datetime"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/middleware"
)
// 示例：使用CORS和时区中间件
func main() {
// 配置CORS
corsConfig := &middleware.CORSConfig{
AllowedOrigins: []string{"*"},
AllowedMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
AllowedHeaders: []string{
"Content-Type",
"Authorization",
"X-Requested-With",
"X-Timezone",
},
AllowCredentials: false,
MaxAge: 3600,
}
// 创建中间件链
chain := middleware.NewChain(
middleware.CORS(corsConfig),
middleware.Timezone,
)
// 定义处理器（使用Handler模式）
handler := chain.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
apiHandler(h)
})
// 注册路由
http.Handle("/api", handler)
log.Println("Server started on :8080")
log.Println("Try: curl -H 'X-Timezone: America/New_York' http://localhost:8080/api")
log.Fatal(http.ListenAndServe(":8080", nil))
}
// apiHandler 处理API请求（使用Handler模式）
func apiHandler(h *commonhttp.Handler) {
// 从Handler获取时区
timezone := h.GetTimezone()
// 使用时区进行时间处理
now := datetime.Now(timezone)
startOfDay := datetime.StartOfDay(now, timezone)
endOfDay := datetime.EndOfDay(now, timezone)
// 返回响应
h.Success(map[string]interface{}{
"message": "Hello from API",
"timezone": timezone,
"currentTime": datetime.FormatDateTime(now),
"startOfDay": datetime.FormatDateTime(startOfDay),
"endOfDay": datetime.FormatDateTime(endOfDay),
})
}

30
examples/middleware_simple_example.go Normal file
View File

@@ -0,0 +1,30 @@
//go:build example
// +build example
package main
import (
"log"
"net/http"
"git.toowon.com/jimmy/go-common/factory"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
func main() {
if err := factory.Init("config.json"); err != nil {
log.Fatal(err)
}
app := factory.Default()
chain := app.MiddlewareChain()
http.Handle("/api/hello", chain.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
h.Success(map[string]any{
"message": "Hello, World!",
"timezone": h.GetTimezone(),
})
}))
log.Fatal(http.ListenAndServe(":8080", nil))
}

58
examples/migration_example.go
View File

@@ -1,58 +0,0 @@
package main
import (
"fmt"
"log"
"gorm.io/driver/mysql"
"gorm.io/gorm"
"git.toowon.com/jimmy/go-common/migration"
)
func main() {
// 初始化数据库连接
dsn := "user:password@tcp(localhost:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local"
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
if err != nil {
log.Fatal(err)
}
// 创建迁移器
migrator := migration.NewMigrator(db)
// 添加迁移
migrator.AddMigration(migration.Migration{
Version: "20240101000001",
Description: "create_users_table",
Up: func(db *gorm.DB) error {
return db.Exec(`
CREATE TABLE IF NOT EXISTS users (
id INT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(255) NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
`).Error
},
Down: func(db *gorm.DB) error {
return db.Exec("DROP TABLE IF EXISTS users").Error
},
})
// 执行迁移
if err := migrator.Up(); err != nil {
log.Fatal(err)
}
// 查看迁移状态
status, err := migrator.Status()
if err != nil {
log.Fatal(err)
}
for _, s := range status {
fmt.Printf("Version: %s, Description: %s, Applied: %v\n",
s.Version, s.Description, s.Applied)
}
}

105
examples/migration_reset_example.go
View File

@@ -1,105 +0,0 @@
package main
import (
"fmt"
"log"
"git.toowon.com/jimmy/go-common/migration"
"gorm.io/driver/sqlite"
"gorm.io/gorm"
)
func main() {
// 初始化数据库连接（使用SQLite作为示例）
db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
if err != nil {
log.Fatal("Failed to connect to database:", err)
}
// 创建迁移器
migrator := migration.NewMigrator(db)
// 添加一些迁移
migrator.AddMigrations(
migration.Migration{
Version: "20240101000001",
Description: "create_users_table",
Up: func(db *gorm.DB) error {
return db.Exec(`
CREATE TABLE users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name VARCHAR(255) NOT NULL,
email VARCHAR(255) UNIQUE NOT NULL
)
`).Error
},
Down: func(db *gorm.DB) error {
return db.Exec("DROP TABLE IF EXISTS users").Error
},
},
migration.Migration{
Version: "20240101000002",
Description: "add_created_at_to_users",
Up: func(db *gorm.DB) error {
return db.Exec("ALTER TABLE users ADD COLUMN created_at DATETIME").Error
},
Down: func(db *gorm.DB) error {
return db.Exec("ALTER TABLE users DROP COLUMN created_at").Error
},
},
)
// 执行迁移
fmt.Println("=== Executing migrations ===")
err = migrator.Up()
if err != nil {
log.Fatal("Failed to run migrations:", err)
}
// 查看状态
fmt.Println("\n=== Migration status ===")
status, err := migrator.Status()
if err != nil {
log.Fatal("Failed to get status:", err)
}
for _, s := range status {
fmt.Printf("Version: %s, Description: %s, Applied: %v\n",
s.Version, s.Description, s.Applied)
}
// 示例1：仅清空迁移记录（不回滚数据库变更）
fmt.Println("\n=== Example 1: Reset migration records only ===")
fmt.Println("Note: This only clears records, not database changes")
// 直接调用（需要确认标志）
// err = migrator.Reset(true)
// if err != nil {
// log.Fatal("Failed to reset:", err)
// }
// 交互式确认（推荐）
// 取消注释下面的代码来测试交互式重置
// err = migrator.ResetWithConfirm()
// if err != nil {
// log.Fatal("Failed to reset with confirm:", err)
// }
// 示例2：回滚所有迁移并清空记录
fmt.Println("\n=== Example 2: Reset all migrations (rollback + clear records) ===")
fmt.Println("Note: This will rollback all migrations and clear records")
// 直接调用（需要确认标志）
// err = migrator.ResetAll(true)
// if err != nil {
// log.Fatal("Failed to reset all:", err)
// }
// 交互式确认（推荐）
// 取消注释下面的代码来测试交互式重置
// err = migrator.ResetAllWithConfirm()
// if err != nil {
// log.Fatal("Failed to reset all with confirm:", err)
// }
fmt.Println("\nNote: Reset functions are commented out for safety.")
fmt.Println("Uncomment the code above to test reset functionality.")
}

4
examples/migrations/migrations/20240101000001_create_users_table.down.sql Normal file
View File

@@ -0,0 +1,4 @@
-- Rollback: Drop users table
DROP TABLE IF EXISTS users;

14
examples/migrations/migrations/20240101000001_create_users_table.sql Normal file
View File

@@ -0,0 +1,14 @@
-- Create users table
-- Created at: 2024-01-01 00:00:01
CREATE TABLE IF NOT EXISTS users (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(255) NOT NULL UNIQUE,
email VARCHAR(255) NOT NULL UNIQUE,
password_hash VARCHAR(255) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_username (username),
INDEX idx_email (email)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

95
examples/sms_example.go
View File

@@ -1,3 +1,6 @@
//go:build example
// +build example
package main
import (
@@ -5,98 +8,30 @@ import (
"log"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/sms"
"git.toowon.com/jimmy/go-common/factory"
)
func main() {
// 加载配置
cfg, err := config.LoadFromFile("./config/example.json")
if err != nil {
log.Fatal("Failed to load config:", err)
log.Fatal(err)
}
// 创建短信发送器
smsConfig := cfg.GetSMS()
if smsConfig == nil {
log.Fatal("SMS config is nil")
}
smsClient, err := sms.NewSMS(smsConfig)
app := factory.New(cfg)
smsClient, err := app.SMS()
if err != nil {
log.Fatal("Failed to create SMS client:", err)
log.Fatal(err)
}
defer smsClient.Close()
// 示例1：发送原始请求（推荐，最灵活）
fmt.Println("=== Example 1: Send Raw SMS Request ===")
// 外部构建完整的请求参数
params := map[string]string{
"PhoneNumbers": "13800138000",
"SignName": smsConfig.SignName,
"TemplateCode": smsConfig.TemplateCode,
"TemplateParam": `{"code":"123456","expire":"5"}`,
}
resp, err := smsClient.SendRaw(params)
params := map[string]string{"code": "123456"}
resp, err := smsClient.SendSMS([]string{"13800138000"}, params)
if err != nil {
log.Printf("Failed to send raw SMS: %v", err)
log.Printf("sync send failed: %v", err)
} else {
fmt.Printf("Raw SMS sent successfully, RequestID: %s\n", resp.RequestID)
fmt.Printf("sync sms sent, RequestID: %s\n", resp.RequestID)
}
// 示例2：发送简单短信（使用配置中的模板代码）
fmt.Println("\n=== Example 2: Send Simple SMS ===")
templateParam := map[string]string{
"code": "123456",
"expire": "5",
}
resp2, err := smsClient.SendSimple(
[]string{"13800138000"},
templateParam,
)
if err != nil {
log.Printf("Failed to send SMS: %v", err)
} else {
fmt.Printf("SMS sent successfully, RequestID: %s\n", resp2.RequestID)
}
// 示例3：使用指定模板发送短信
fmt.Println("\n=== Example 3: Send SMS with Template ===")
templateParam3 := map[string]string{
"code": "654321",
"expire": "10",
}
resp3, err := smsClient.SendWithTemplate(
[]string{"13800138000"},
"SMS_123456789", // 使用指定的模板代码
templateParam3,
)
if err != nil {
log.Printf("Failed to send SMS: %v", err)
} else {
fmt.Printf("SMS sent successfully, RequestID: %s\n", resp3.RequestID)
}
// 示例4：使用JSON字符串作为模板参数
fmt.Println("\n=== Example 4: Send SMS with JSON String Template Param ===")
req := &sms.SendRequest{
PhoneNumbers: []string{"13800138000"},
TemplateCode: smsConfig.TemplateCode,
TemplateParam: `{"code":"888888","expire":"15"}`, // 直接使用JSON字符串
}
resp4, err := smsClient.Send(req)
if err != nil {
log.Printf("Failed to send SMS: %v", err)
} else {
fmt.Printf("SMS sent successfully, RequestID: %s\n", resp4.RequestID)
}
fmt.Println("\nNote: Make sure your Aliyun SMS service is configured correctly:")
fmt.Println("1. AccessKey ID and Secret are valid")
fmt.Println("2. Sign name is approved")
fmt.Println("3. Template code is approved")
fmt.Println("4. Template parameters match the template definition")
smsClient.SendSMSAsync(nil, []string{"13800138000"}, params)
fmt.Println("async sms enqueued")
}

47
examples/storage_example.go
View File

@@ -1,3 +1,6 @@
//go:build example
// +build example
package main
import (
@@ -16,28 +19,36 @@ func main() {
log.Fatal("Failed to load config:", err)
}
// 创建存储实例（使用OSS）
// 注意：需要先实现OSS SDK集成
ossStorage, err := storage.NewStorage(storage.StorageTypeOSS, cfg)
// 优先演示本地存储（可直接运行）
localStorage, err := storage.NewStorage(storage.StorageTypeLocal, cfg)
if err != nil {
log.Printf("Failed to create OSS storage: %v", err)
log.Println("Note: OSS SDK integration is required")
// 继续演示其他功能
} else {
// 创建上传处理器
log.Fatal("Failed to create Local storage:", err)
}
uploadHandler := storage.NewUploadHandler(storage.UploadHandlerConfig{
Storage: ossStorage,
Storage: localStorage,
MaxFileSize: 10 * 1024 * 1024, // 10MB
AllowedExts: []string{".jpg", ".jpeg", ".png", ".gif", ".pdf"},
ObjectPrefix: "uploads/",
})
// 创建代理查看处理器
proxyHandler := storage.NewProxyHandler(ossStorage)
proxyHandler := storage.NewProxyHandler(localStorage)
// 创建中间件链
var corsConfig *middleware.CORSConfig
if cfg.GetCORS() != nil {
c := cfg.GetCORS()
corsConfig = middleware.NewCORSConfig(
c.AllowedOrigins,
c.AllowedMethods,
c.AllowedHeaders,
c.ExposedHeaders,
c.AllowCredentials,
c.MaxAge,
)
}
chain := middleware.NewChain(
middleware.CORS(cfg.GetCORS()),
middleware.CORS(corsConfig),
middleware.Timezone,
)
@@ -46,10 +57,13 @@ func main() {
mux.Handle("/upload", chain.Then(uploadHandler))
mux.Handle("/file", chain.Then(proxyHandler))
log.Println("Storage server started on :8080")
log.Println("Local storage server started on :8080")
log.Println("Upload: POST /upload")
log.Println("View: GET /file?key=images/test.jpg")
log.Fatal(http.ListenAndServe(":8080", mux))
log.Println("View: GET /file?key=uploads/xxx.jpg")
// 提示：OSS 需要你自行集成对应 SDK（当前 go-common 中仅提供接口框架）
if _, err := storage.NewStorage(storage.StorageTypeOSS, cfg); err != nil {
log.Printf("OSS storage not ready: %v", err)
}
// 演示MinIO存储
@@ -67,5 +81,6 @@ func main() {
objectKey2 := storage.GenerateObjectKeyWithDate("images", "test.jpg")
log.Printf("Object key 2: %s", objectKey2)
}
log.Fatal(http.ListenAndServe(":8080", mux))
}

443
excel/excel.go Normal file
View File

@@ -0,0 +1,443 @@
package excel
import (
"fmt"
"io"
"os"
"reflect"
"time"
"git.toowon.com/jimmy/go-common/tools"
"github.com/xuri/excelize/v2"
)
// Excel Excel导出器
type Excel struct {
file *excelize.File
}
// NewExcel 创建Excel导出器
func NewExcel() *Excel {
return &Excel{
file: excelize.NewFile(),
}
}
// ExportColumn 导出列定义
type ExportColumn struct {
// Header 表头名称
Header string
// Field 数据字段名（支持嵌套字段，如 "User.Name"）
Field string
// Width 列宽（可选，0表示自动）
Width float64
// Format 格式化函数（可选，用于自定义字段值的格式化）
Format func(value interface{}) string
}
// ExportData 导出数据接口
// 实现此接口的结构体可以直接导出
type ExportData interface {
// GetExportColumns 获取导出列定义
GetExportColumns() []ExportColumn
// GetExportRows 获取导出数据行
GetExportRows() [][]interface{}
}
// ExportToWriter 导出数据到Writer（黑盒模式，推荐使用）
// sheetName: 工作表名称（可选，默认为"Sheet1"）
// columns: 列定义
// data: 数据列表（可以是结构体切片或实现了ExportData接口的对象）
// 返回错误信息
//
// 示例1：导出结构体切片
//
// type User struct {
// ID int `json:"id"`
// Name string `json:"name"`
// Email string `json:"email"`
// }
//
// users := []User{
// {ID: 1, Name: "Alice", Email: "alice@example.com"},
// {ID: 2, Name: "Bob", Email: "bob@example.com"},
// }
//
// columns := []ExportColumn{
// {Header: "ID", Field: "ID"},
// {Header: "姓名", Field: "Name"},
// {Header: "邮箱", Field: "Email"},
// }
//
// excel := excel.NewExcel()
// err := excel.ExportToWriter(w, "用户列表", columns, users)
//
// 示例2：使用格式化函数
//
// columns := []ExportColumn{
// {Header: "ID", Field: "ID"},
// {Header: "姓名", Field: "Name"},
// {Header: "创建时间", Field: "CreatedAt", Format: func(v interface{}) string {
// if t, ok := v.(time.Time); ok {
// return t.Format("2006-01-02 15:04:05")
// }
// return ""
// }},
// }
//
// excel.ExportToWriter(w, "用户列表", columns, users)
func (e *Excel) ExportToWriter(w io.Writer, sheetName string, columns []ExportColumn, data interface{}) error {
if e.file == nil {
e.file = excelize.NewFile()
}
// 设置工作表名称
if sheetName == "" {
sheetName = "Sheet1"
}
// 检查工作表是否已存在
sheetIndex, err := e.file.GetSheetIndex(sheetName)
if err != nil || sheetIndex == 0 {
// 工作表不存在，需要创建
// 如果sheetName不是"Sheet1"，且默认"Sheet1"存在，则删除它
if sheetName != "Sheet1" {
defaultIndex, _ := e.file.GetSheetIndex("Sheet1")
if defaultIndex > 0 {
e.file.DeleteSheet("Sheet1")
}
}
// 创建新工作表
_, err = e.file.NewSheet(sheetName)
if err != nil {
return fmt.Errorf("failed to create sheet: %w", err)
}
// 重新获取工作表索引
sheetIndex, err = e.file.GetSheetIndex(sheetName)
if err != nil {
return fmt.Errorf("failed to get sheet index: %w", err)
}
}
// 设置活动工作表
if sheetIndex > 0 {
e.file.SetActiveSheet(sheetIndex)
}
// 写入表头
headerStyle, _ := e.file.NewStyle(&excelize.Style{
Font: &excelize.Font{
Bold: true,
Size: 12,
},
Fill: excelize.Fill{
Type: "pattern",
Color: []string{"#E0E0E0"},
Pattern: 1,
},
Alignment: &excelize.Alignment{
Horizontal: "center",
Vertical: "center",
},
})
for i, col := range columns {
cell := fmt.Sprintf("%c1", 'A'+i)
e.file.SetCellValue(sheetName, cell, col.Header)
// 设置表头样式
e.file.SetCellStyle(sheetName, cell, cell, headerStyle)
// 设置列宽
if col.Width > 0 {
colName, _ := excelize.ColumnNumberToName(i + 1)
e.file.SetColWidth(sheetName, colName, colName, col.Width)
}
}
// 处理数据
var rows [][]interface{}
// 检查数据是否实现了ExportData接口
if exportData, ok := data.(ExportData); ok {
// 使用接口方法获取数据
rows = exportData.GetExportRows()
// 如果接口返回nil，初始化为空切片
if rows == nil {
rows = [][]interface{}{}
}
} else {
// 处理结构体切片（包括nil和空切片的情况）
rows, err = e.convertDataToRows(data, columns)
if err != nil {
return fmt.Errorf("failed to convert data to rows: %w", err)
}
// 确保rows不为nil
if rows == nil {
rows = [][]interface{}{}
}
}
// 写入数据行
for rowIndex, row := range rows {
for colIndex, value := range row {
cell := fmt.Sprintf("%c%d", 'A'+colIndex, rowIndex+2) // +2 因为第一行是表头
// 应用格式化函数
var cellValue interface{} = value
if colIndex < len(columns) && columns[colIndex].Format != nil {
cellValue = columns[colIndex].Format(value)
}
e.file.SetCellValue(sheetName, cell, cellValue)
}
}
// 自动调整列宽（如果未设置宽度）
for i, col := range columns {
if col.Width == 0 {
colName, _ := excelize.ColumnNumberToName(i + 1)
// 获取列的最大宽度
maxWidth := e.getColumnMaxWidth(sheetName, i+1, len(rows)+1)
if maxWidth > 0 {
e.file.SetColWidth(sheetName, colName, colName, maxWidth)
}
}
}
// 写入到Writer
return e.file.Write(w)
}
// ExportToFile 导出数据到文件
func (e *Excel) ExportToFile(filePath, sheetName string, columns []ExportColumn, data interface{}) error {
f, err := os.Create(filePath)
if err != nil {
return fmt.Errorf("failed to create file: %w", err)
}
defer f.Close()
return e.ExportToWriter(f, sheetName, columns, data)
}
// GetFile 获取Excel文件对象（高级功能时使用）
// 返回excelize.File对象，可用于高级操作
//
// ℹ️ 推荐使用黑盒方法：
// - ExportToWriter()：导出到Writer（可用于文件、HTTP响应等）
//
// 仅在需要使用高级功能时获取对象：
// - 多工作表操作
// - 自定义样式
// - 图表、公式等高级功能
//
// 示例（常用操作，推荐）：
//
// excel := excel.NewExcel()
// file, _ := os.Create("users.xlsx")
// defer file.Close()
// excel.ExportToWriter(file, "用户列表", columns, users)
//
// 示例（高级功能）：
//
// file := excel.GetFile()
// file.NewSheet("Sheet2")
// file.SetCellValue("Sheet2", "A1", "数据")
func (e *Excel) GetFile() *excelize.File {
if e.file == nil {
e.file = excelize.NewFile()
}
return e.file
}
// convertDataToRows 将数据转换为行数据
// 支持nil、空切片等情况，返回空切片而不是错误
func (e *Excel) convertDataToRows(data interface{}, columns []ExportColumn) ([][]interface{}, error) {
// 如果data为nil，返回空切片
if data == nil {
return [][]interface{}{}, nil
}
// 使用反射处理数据
val := reflect.ValueOf(data)
if val.Kind() == reflect.Ptr {
// 如果是指针且指向nil，返回空切片
if val.IsNil() {
return [][]interface{}{}, nil
}
val = val.Elem()
}
// 如果解引用后仍然是无效值，返回空切片
if !val.IsValid() {
return [][]interface{}{}, nil
}
// 必须是切片类型
if val.Kind() != reflect.Slice {
return nil, fmt.Errorf("data must be a slice, got %v", val.Kind())
}
// 如果是空切片，返回空切片（不返回错误）
if val.Len() == 0 {
return [][]interface{}{}, nil
}
rows := make([][]interface{}, 0, val.Len())
for i := 0; i < val.Len(); i++ {
item := val.Index(i)
if item.Kind() == reflect.Ptr {
// 如果指针指向nil，跳过该行或使用空值
if item.IsNil() {
row := make([]interface{}, len(columns))
rows = append(rows, row)
continue
}
item = item.Elem()
}
row := make([]interface{}, len(columns))
for j, col := range columns {
value := e.getFieldValue(item, col.Field)
row[j] = value
}
rows = append(rows, row)
}
return rows, nil
}
// getFieldValue 获取字段值（支持嵌套字段）
func (e *Excel) getFieldValue(v reflect.Value, fieldPath string) interface{} {
if v.Kind() == reflect.Ptr {
v = v.Elem()
}
if v.Kind() != reflect.Struct {
return nil
}
// 处理嵌套字段（如 "User.Name"）
fields := splitFieldPath(fieldPath)
current := v
for i, fieldName := range fields {
if current.Kind() == reflect.Ptr {
current = current.Elem()
}
if current.Kind() != reflect.Struct {
return nil
}
field := current.FieldByName(fieldName)
if !field.IsValid() {
return nil
}
// 如果是最后一个字段，返回值
if i == len(fields)-1 {
if field.CanInterface() {
return field.Interface()
}
return nil
}
// 继续嵌套查找
current = field
}
return nil
}
// splitFieldPath 分割字段路径（如 "User.Name" -> ["User", "Name"]）
func splitFieldPath(path string) []string {
result := make([]string, 0)
current := ""
for _, char := range path {
if char == '.' {
if current != "" {
result = append(result, current)
current = ""
}
} else {
current += string(char)
}
}
if current != "" {
result = append(result, current)
}
return result
}
// getColumnMaxWidth 获取列的最大宽度（用于自动调整列宽）
func (e *Excel) getColumnMaxWidth(sheetName string, colIndex int, maxRow int) float64 {
maxWidth := 10.0 // 默认最小宽度
for row := 1; row <= maxRow; row++ {
cell, _ := excelize.CoordinatesToCellName(colIndex, row)
value, err := e.file.GetCellValue(sheetName, cell)
if err == nil {
width := float64(len(value)) + 2 // 加2作为边距
if width > maxWidth {
maxWidth = width
}
}
}
// 限制最大宽度
if maxWidth > 50 {
maxWidth = 50
}
return maxWidth
}
// AdaptTimeFormatter 适配器函数：将tools包的格式化函数转换为Excel Format字段需要的函数类型
// 允许直接使用tools包的任何格式化函数
//
// 示例：
//
// // 直接使用tools.FormatDate
// Format: excel.AdaptTimeFormatter(tools.FormatDate)
//
// // 使用自定义格式化函数
// Format: excel.AdaptTimeFormatter(func(t time.Time) string {
// return tools.Format(t, "2006-01-02 15:04:05", "Asia/Shanghai")
// })
func AdaptTimeFormatter(fn func(time.Time, ...string) string) func(interface{}) string {
return func(value interface{}) string {
if t, ok := value.(time.Time); ok {
return fn(t)
}
return ""
}
}
// formatDateTime 格式化日期时间（内部便捷函数）
// 用于ExportColumn的Format字段
// layout: 时间格式，如 "2006-01-02 15:04:05"
// timezone: 可选时区，如果为空则使用时间对象本身的时区
// 直接调用 tools.Format() 方法
func formatDateTime(layout string, timezone ...string) func(interface{}) string {
return AdaptTimeFormatter(func(t time.Time, _ ...string) string {
return tools.Format(t, layout, timezone...)
})
}
// formatDate 格式化日期（内部便捷函数）
// 用于ExportColumn的Format字段，格式：2006-01-02
// 直接调用 tools.FormatDate() 方法
var formatDate = AdaptTimeFormatter(tools.FormatDate)
// formatDateTimeDefault 格式化日期时间（内部便捷函数）
// 用于ExportColumn的Format字段，格式：2006-01-02 15:04:05
// 直接调用 tools.FormatDateTime() 方法
var formatDateTimeDefault = AdaptTimeFormatter(tools.FormatDateTime)
// formatTime 格式化时间（内部便捷函数）
// 用于ExportColumn的Format字段，格式：15:04:05
// 直接调用 tools.FormatTime() 方法
var formatTime = AdaptTimeFormatter(tools.FormatTime)

728
factory/factory.go
View File

@@ -3,12 +3,17 @@ package factory
import (
"context"
"fmt"
"io"
"net/http"
"sync"
"time"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/email"
"git.toowon.com/jimmy/go-common/excel"
"git.toowon.com/jimmy/go-common/i18n"
"git.toowon.com/jimmy/go-common/logger"
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/migration"
"git.toowon.com/jimmy/go-common/sms"
"git.toowon.com/jimmy/go-common/storage"
"github.com/redis/go-redis/v9"
@@ -18,314 +23,111 @@ import (
"gorm.io/gorm"
)
// Factory 工厂类，用于从配置创建各种客户端对象
var (
defaultFactory *Factory
)
// Factory 工具库入口：配置加载 + lazy getter
type Factory struct {
cfg *config.Config
storage storage.Storage // 存储实例（延迟初始化）
logger *logger.Logger // 日志实例（延迟初始化）
email *email.Email // 邮件客户端（延迟初始化）
sms *sms.SMS // 短信客户端（延迟初始化）
db *gorm.DB // 数据库连接（延迟初始化）
redis *redis.Client // Redis客户端（延迟初始化）
storage storage.Storage
logger *logger.Logger
email *email.Email
sms *sms.SMS
db *gorm.DB
redis *redis.Client
i18n *i18n.I18n
excel *excel.Excel
chain *middleware.Chain
mu sync.Mutex
}
// NewFactory 创建工厂实例
func NewFactory(cfg *config.Config) *Factory {
return &Factory{
cfg: cfg,
// Option Factory 可选项（支持重载模块实现）
type Option func(*Factory)
// WithStorage 注入自定义存储实现
func WithStorage(s storage.Storage) Option {
return func(f *Factory) {
f.storage = s
}
}
// NewFactoryFromFile 从配置文件创建工厂实例（便捷方法）
// filePath: 配置文件路径
func NewFactoryFromFile(filePath string) (*Factory, error) {
// Init 从配置文件初始化全局 Factory（启动时调用一次）
func Init(filePath string, opts ...Option) error {
cfg, err := config.LoadFromFile(filePath)
if err != nil {
return nil, fmt.Errorf("failed to load config: %w", err)
}
return NewFactory(cfg), nil
}
// getEmailClient 获取邮件客户端（内部方法，延迟初始化）
func (f *Factory) getEmailClient() (*email.Email, error) {
if f.email != nil {
return f.email, nil
}
if f.cfg.Email == nil {
return nil, fmt.Errorf("email config is nil")
}
e, err := email.NewEmail(f.cfg.Email)
if err != nil {
return nil, fmt.Errorf("failed to create email client: %w", err)
}
f.email = e
return e, nil
}
// SendEmail 发送邮件（黑盒模式）
// to: 收件人列表
// subject: 邮件主题
// body: 邮件正文（纯文本）
// htmlBody: HTML正文（可选，如果设置了会优先使用）
func (f *Factory) SendEmail(to []string, subject, body string, htmlBody ...string) error {
e, err := f.getEmailClient()
if err != nil {
return err
}
msg := &email.Message{
To: to,
Subject: subject,
Body: body,
defaultFactory = New(cfg, opts...)
if l, err := defaultFactory.Logger(); err == nil {
logger.SetDefaultLogger(l)
}
if len(htmlBody) > 0 && htmlBody[0] != "" {
msg.HTMLBody = htmlBody[0]
}
return e.Send(msg)
return nil
}
// getSMSClient 获取短信客户端（内部方法，延迟初始化）
func (f *Factory) getSMSClient() (*sms.SMS, error) {
if f.sms != nil {
return f.sms, nil
}
if f.cfg.SMS == nil {
return nil, fmt.Errorf("SMS config is nil")
}
s, err := sms.NewSMS(f.cfg.SMS)
if err != nil {
return nil, fmt.Errorf("failed to create SMS client: %w", err)
}
f.sms = s
return s, nil
// Default 获取全局 Factory
func Default() *Factory {
return defaultFactory
}
// SendSMS 发送短信（黑盒模式）
// phoneNumbers: 手机号列表
// templateParam: 模板参数（map或JSON字符串）
// templateCode: 模板代码（可选，如果为空使用配置中的模板代码）
func (f *Factory) SendSMS(phoneNumbers []string, templateParam interface{}, templateCode ...string) (*sms.SendResponse, error) {
s, err := f.getSMSClient()
if err != nil {
return nil, err
// New 从配置创建 Factory
func New(cfg *config.Config, opts ...Option) *Factory {
f := &Factory{cfg: cfg}
for _, opt := range opts {
opt(f)
}
req := &sms.SendRequest{
PhoneNumbers: phoneNumbers,
TemplateParam: templateParam,
}
if len(templateCode) > 0 && templateCode[0] != "" {
req.TemplateCode = templateCode[0]
}
return s.Send(req)
return f
}
// Config 获取配置
func (f *Factory) Config() *config.Config {
return f.cfg
}
// getLogger 获取日志记录器（内部方法，延迟初始化）
func (f *Factory) getLogger() (*logger.Logger, error) {
if f.logger != nil {
return f.logger, nil
}
var l *logger.Logger
var err error
if f.cfg.Logger == nil {
// 如果没有配置，使用默认配置创建
l, err = logger.NewLogger(nil)
} else {
l, err = logger.NewLogger(f.cfg.Logger)
f.mu.Lock()
defer f.mu.Unlock()
if f.logger != nil {
return f.logger, nil
}
var cfg *config.LoggerConfig
if f.cfg != nil {
cfg = f.cfg.Logger
}
l, err := logger.NewLogger(cfg)
if err != nil {
return nil, fmt.Errorf("failed to create logger: %w", err)
}
f.logger = l
return l, nil
}
// LogDebug 记录调试日志
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogDebug(message string, args ...interface{}) {
l, err := f.getLogger()
if err != nil {
// 如果日志初始化失败，使用标准输出
if len(args) > 0 {
fmt.Printf("[DEBUG] "+message+"\n", args...)
} else {
fmt.Printf("[DEBUG] %s\n", message)
}
return
}
if len(args) > 0 {
l.Debug(message, args...)
} else {
l.Debug(message)
}
// Logger 获取日志对象
func (f *Factory) Logger() (*logger.Logger, error) {
return f.getLogger()
}
// LogDebugf 记录调试日志（带字段）
// fields: 日志字段
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogDebugf(fields map[string]interface{}, message string, args ...interface{}) {
l, err := f.getLogger()
if err != nil {
// 如果日志初始化失败，使用标准输出
if len(args) > 0 {
fmt.Printf("[DEBUG] "+message+"\n", args...)
} else {
fmt.Printf("[DEBUG] %s\n", message)
}
return
}
l.Debugf(fields, message, args...)
}
// LogInfo 记录信息日志
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogInfo(message string, args ...interface{}) {
l, err := f.getLogger()
if err != nil {
// 如果日志初始化失败，使用标准输出
if len(args) > 0 {
fmt.Printf("[INFO] "+message+"\n", args...)
} else {
fmt.Printf("[INFO] %s\n", message)
}
return
}
if len(args) > 0 {
l.Info(message, args...)
} else {
l.Info(message)
}
}
// LogInfof 记录信息日志（带字段）
// fields: 日志字段
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogInfof(fields map[string]interface{}, message string, args ...interface{}) {
l, err := f.getLogger()
if err != nil {
// 如果日志初始化失败，使用标准输出
if len(args) > 0 {
fmt.Printf("[INFO] "+message+"\n", args...)
} else {
fmt.Printf("[INFO] %s\n", message)
}
return
}
l.Infof(fields, message, args...)
}
// LogWarn 记录警告日志
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogWarn(message string, args ...interface{}) {
l, err := f.getLogger()
if err != nil {
// 如果日志初始化失败，使用标准输出
if len(args) > 0 {
fmt.Printf("[WARN] "+message+"\n", args...)
} else {
fmt.Printf("[WARN] %s\n", message)
}
return
}
if len(args) > 0 {
l.Warn(message, args...)
} else {
l.Warn(message)
}
}
// LogWarnf 记录警告日志（带字段）
// fields: 日志字段
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogWarnf(fields map[string]interface{}, message string, args ...interface{}) {
l, err := f.getLogger()
if err != nil {
// 如果日志初始化失败，使用标准输出
if len(args) > 0 {
fmt.Printf("[WARN] "+message+"\n", args...)
} else {
fmt.Printf("[WARN] %s\n", message)
}
return
}
l.Warnf(fields, message, args...)
}
// LogError 记录错误日志
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogError(message string, args ...interface{}) {
l, err := f.getLogger()
if err != nil {
// 如果日志初始化失败，使用标准输出
if len(args) > 0 {
fmt.Printf("[ERROR] "+message+"\n", args...)
} else {
fmt.Printf("[ERROR] %s\n", message)
}
return
}
if len(args) > 0 {
l.Error(message, args...)
} else {
l.Error(message)
}
}
// LogErrorf 记录错误日志（带字段）
// fields: 日志字段
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogErrorf(fields map[string]interface{}, message string, args ...interface{}) {
l, err := f.getLogger()
if err != nil {
// 如果日志初始化失败，使用标准输出
if len(args) > 0 {
fmt.Printf("[ERROR] "+message+"\n", args...)
} else {
fmt.Printf("[ERROR] %s\n", message)
}
return
}
l.Errorf(fields, message, args...)
}
// getDatabase 获取数据库连接对象（内部方法，延迟初始化）
func (f *Factory) getDatabase() (*gorm.DB, error) {
if f.db != nil {
return f.db, nil
}
if f.cfg.Database == nil {
f.mu.Lock()
defer f.mu.Unlock()
if f.db != nil {
return f.db, nil
}
if f.cfg == nil || f.cfg.Database == nil {
return nil, fmt.Errorf("database config is nil")
}
// 获取DSN
dsn, err := f.cfg.GetDatabaseDSN()
if err != nil {
return nil, fmt.Errorf("failed to get DSN: %w", err)
return nil, err
}
// 根据数据库类型创建连接
var db *gorm.DB
switch f.cfg.Database.Type {
case "mysql":
@@ -337,17 +139,13 @@ func (f *Factory) getDatabase() (*gorm.DB, error) {
default:
return nil, fmt.Errorf("unsupported database type: %s", f.cfg.Database.Type)
}
if err != nil {
return nil, fmt.Errorf("failed to connect to database: %w", err)
}
// 配置连接池
sqlDB, err := db.DB()
if err != nil {
return nil, fmt.Errorf("failed to get sql.DB: %w", err)
return nil, err
}
if f.cfg.Database.MaxOpenConns > 0 {
sqlDB.SetMaxOpenConns(f.cfg.Database.MaxOpenConns)
}
@@ -357,232 +155,250 @@ func (f *Factory) getDatabase() (*gorm.DB, error) {
if f.cfg.Database.ConnMaxLifetime > 0 {
sqlDB.SetConnMaxLifetime(time.Duration(f.cfg.Database.ConnMaxLifetime) * time.Second)
}
f.db = db
return db, nil
}
// GetDatabase 获取数据库连接对象（已初始化）
// 返回已初始化的GORM数据库对象，可直接使用
// 注意：数据库保持返回GORM对象，因为GORM已经提供了很好的抽象
func (f *Factory) GetDatabase() (*gorm.DB, error) {
// Database 获取 GORM 数据库连接
func (f *Factory) Database() (*gorm.DB, error) {
return f.getDatabase()
}
// getRedisClient 获取Redis客户端对象（内部方法，延迟初始化）
func (f *Factory) getRedisClient() (*redis.Client, error) {
func (f *Factory) getRedis() (*redis.Client, error) {
if f.redis != nil {
return f.redis, nil
}
if f.cfg.Redis == nil {
f.mu.Lock()
defer f.mu.Unlock()
if f.redis != nil {
return f.redis, nil
}
if f.cfg == nil || f.cfg.Redis == nil {
return nil, fmt.Errorf("redis config is nil")
}
// 获取Redis地址
addr := f.cfg.GetRedisAddr()
if addr == "" {
return nil, fmt.Errorf("redis address is empty")
}
// 设置默认值
redisConfig := f.cfg.Redis
if redisConfig.PoolSize == 0 {
redisConfig.PoolSize = 10 // 默认连接池大小
}
if redisConfig.MinIdleConns == 0 {
redisConfig.MinIdleConns = 5 // 默认最小空闲连接数
}
if redisConfig.DialTimeout == 0 {
redisConfig.DialTimeout = 5 // 默认连接超时5秒
}
if redisConfig.ReadTimeout == 0 {
redisConfig.ReadTimeout = 3 // 默认读取超时3秒
}
if redisConfig.WriteTimeout == 0 {
redisConfig.WriteTimeout = 3 // 默认写入超时3秒
}
// 创建Redis客户端
rc := f.cfg.Redis
client := redis.NewClient(&redis.Options{
Addr: addr,
Password: redisConfig.Password,
DB: redisConfig.Database,
PoolSize: redisConfig.PoolSize,
MinIdleConns: redisConfig.MinIdleConns,
MaxRetries: redisConfig.MaxRetries,
DialTimeout: time.Duration(redisConfig.DialTimeout) * time.Second,
ReadTimeout: time.Duration(redisConfig.ReadTimeout) * time.Second,
WriteTimeout: time.Duration(redisConfig.WriteTimeout) * time.Second,
Password: rc.Password,
DB: rc.Database,
PoolSize: rc.PoolSize,
MinIdleConns: rc.MinIdleConns,
MaxRetries: rc.MaxRetries,
DialTimeout: time.Duration(rc.DialTimeout) * time.Second,
ReadTimeout: time.Duration(rc.ReadTimeout) * time.Second,
WriteTimeout: time.Duration(rc.WriteTimeout) * time.Second,
})
// 测试连接
ctx, cancel := context.WithTimeout(context.Background(), time.Duration(redisConfig.DialTimeout)*time.Second)
ctx, cancel := context.WithTimeout(context.Background(), time.Duration(rc.DialTimeout)*time.Second)
defer cancel()
_, err := client.Ping(ctx).Result()
if err != nil {
client.Close() // 连接失败时关闭客户端
if _, err := client.Ping(ctx).Result(); err != nil {
_ = client.Close()
return nil, fmt.Errorf("failed to connect to redis: %w", err)
}
f.redis = client
return client, nil
}
// GetRedisClient 获取Redis客户端对象（已初始化）
// 返回已初始化的Redis客户端对象，可直接使用
// 注意：推荐使用 RedisGet、RedisSet、RedisDelete 等方法直接操作Redis
// 如果需要使用Redis的高级功能（如Hash、List、Set等），可以使用此方法获取客户端对象
func (f *Factory) GetRedisClient() (*redis.Client, error) {
return f.getRedisClient()
// Redis 获取 Redis 客户端
func (f *Factory) Redis() (*redis.Client, error) {
return f.getRedis()
}
// RedisGet 获取Redis值（黑盒模式）
// key: Redis键
func (f *Factory) RedisGet(ctx context.Context, key string) (string, error) {
client, err := f.getRedisClient()
if err != nil {
return "", err
}
result, err := client.Get(ctx, key).Result()
if err == redis.Nil {
return "", nil // key不存在，返回空字符串
}
if err != nil {
return "", fmt.Errorf("failed to get redis key: %w", err)
}
return result, nil
}
// RedisSet 设置Redis值（黑盒模式）
// key: Redis键
// value: Redis值
// expiration: 过期时间（可选，0表示不过期）
func (f *Factory) RedisSet(ctx context.Context, key string, value interface{}, expiration ...time.Duration) error {
client, err := f.getRedisClient()
if err != nil {
return err
}
var exp time.Duration
if len(expiration) > 0 {
exp = expiration[0]
}
err = client.Set(ctx, key, value, exp).Err()
if err != nil {
return fmt.Errorf("failed to set redis key: %w", err)
}
return nil
}
// RedisDelete 删除Redis键（黑盒模式）
// keys: Redis键列表
func (f *Factory) RedisDelete(ctx context.Context, keys ...string) error {
if len(keys) == 0 {
return nil
}
client, err := f.getRedisClient()
if err != nil {
return err
}
err = client.Del(ctx, keys...).Err()
if err != nil {
return fmt.Errorf("failed to delete redis keys: %w", err)
}
return nil
}
// RedisExists 检查Redis键是否存在（黑盒模式）
// key: Redis键
func (f *Factory) RedisExists(ctx context.Context, key string) (bool, error) {
client, err := f.getRedisClient()
if err != nil {
return false, err
}
count, err := client.Exists(ctx, key).Result()
if err != nil {
return false, fmt.Errorf("failed to check redis key existence: %w", err)
}
return count > 0, nil
}
// GetConfig 获取配置对象
func (f *Factory) GetConfig() *config.Config {
return f.cfg
}
// getStorage 获取存储实例（内部方法，延迟初始化）
func (f *Factory) getStorage() (storage.Storage, error) {
if f.storage != nil {
return f.storage, nil
}
// 根据配置自动选择存储类型
// 优先级：MinIO > OSS
var storageType storage.StorageType
if f.cfg.MinIO != nil {
storageType = storage.StorageTypeMinIO
} else if f.cfg.OSS != nil {
storageType = storage.StorageTypeOSS
} else {
return nil, fmt.Errorf("no storage config found (OSS or MinIO)")
f.mu.Lock()
defer f.mu.Unlock()
if f.storage != nil {
return f.storage, nil
}
if f.cfg == nil {
return nil, fmt.Errorf("config is nil")
}
var storageType storage.StorageType
switch {
case f.cfg.GetLocalStorage() != nil:
storageType = storage.StorageTypeLocal
case f.cfg.MinIO != nil:
storageType = storage.StorageTypeMinIO
case f.cfg.OSS != nil:
storageType = storage.StorageTypeOSS
default:
return nil, fmt.Errorf("no storage config found (LocalStorage, OSS or MinIO)")
}
// 创建存储实例
s, err := storage.NewStorage(storageType, f.cfg)
if err != nil {
return nil, fmt.Errorf("failed to create storage: %w", err)
return nil, err
}
f.storage = s
return s, nil
}
// UploadFile 上传文件
// ctx: 上下文
// objectKey: 对象键（文件路径）
// reader: 文件内容
// contentType: 文件类型（可选）
// 返回文件访问URL和错误
func (f *Factory) UploadFile(ctx context.Context, objectKey string, reader io.Reader, contentType ...string) (string, error) {
s, err := f.getStorage()
if err != nil {
return "", err
}
// 上传文件
err = s.Upload(ctx, objectKey, reader, contentType...)
if err != nil {
return "", fmt.Errorf("failed to upload file: %w", err)
}
// 获取文件URL
url, err := s.GetURL(objectKey, 0)
if err != nil {
return "", fmt.Errorf("failed to get file URL: %w", err)
}
return url, nil
// Storage 获取存储对象
func (f *Factory) Storage() (storage.Storage, error) {
return f.getStorage()
}
// GetFileURL 获取文件访问URL（Show方法）
// objectKey: 对象键
// expires: 过期时间（秒），0表示永久有效
func (f *Factory) GetFileURL(objectKey string, expires int64) (string, error) {
s, err := f.getStorage()
if err != nil {
return "", err
func (f *Factory) getEmail() (*email.Email, error) {
if f.email != nil {
return f.email, nil
}
f.mu.Lock()
defer f.mu.Unlock()
if f.email != nil {
return f.email, nil
}
if f.cfg == nil || f.cfg.Email == nil {
return nil, fmt.Errorf("email config is nil")
}
f.email = email.NewEmail(f.cfg)
return f.email, nil
}
// Email 获取邮件客户端
func (f *Factory) Email() (*email.Email, error) {
return f.getEmail()
}
func (f *Factory) getSMS() (*sms.SMS, error) {
if f.sms != nil {
return f.sms, nil
}
f.mu.Lock()
defer f.mu.Unlock()
if f.sms != nil {
return f.sms, nil
}
if f.cfg == nil || f.cfg.SMS == nil {
return nil, fmt.Errorf("sms config is nil")
}
f.sms = sms.NewSMS(f.cfg)
return f.sms, nil
}
// SMS 获取短信客户端
func (f *Factory) SMS() (*sms.SMS, error) {
return f.getSMS()
}
func (f *Factory) getI18n() (*i18n.I18n, error) {
if f.i18n != nil {
return f.i18n, nil
}
f.mu.Lock()
defer f.mu.Unlock()
if f.i18n != nil {
return f.i18n, nil
}
if f.cfg == nil || f.cfg.I18n == nil {
return nil, fmt.Errorf("i18n config is nil")
}
i := i18n.NewI18n(f.cfg.I18n.DefaultLang)
if f.cfg.I18n.LocalesDir != "" {
if err := i.LoadFromDir(f.cfg.I18n.LocalesDir); err != nil {
return nil, err
}
}
f.i18n = i
return i, nil
}
// I18n 获取国际化对象
func (f *Factory) I18n() (*i18n.I18n, error) {
return f.getI18n()
}
func (f *Factory) getExcel() *excel.Excel {
if f.excel != nil {
return f.excel
}
f.mu.Lock()
defer f.mu.Unlock()
if f.excel == nil {
f.excel = excel.NewExcel()
}
return f.excel
}
// Excel 获取 Excel 导出器
func (f *Factory) Excel() *excel.Excel {
return f.getExcel()
}
// MiddlewareChain 获取默认中间件链
func (f *Factory) MiddlewareChain() *middleware.Chain {
if f.chain != nil {
return f.chain
}
f.mu.Lock()
defer f.mu.Unlock()
if f.chain != nil {
return f.chain
}
return s.GetURL(objectKey, expires)
var mws []func(http.Handler) http.Handler
l, _ := f.getLogger()
i18nInst, _ := f.getI18n()
mws = append(mws, middleware.Recovery(&middleware.RecoveryConfig{
Logger: l,
I18n: i18nInst,
}))
mws = append(mws, middleware.RequestID())
mws = append(mws, middleware.Logging(&middleware.LoggingConfig{Logger: l}))
if f.cfg != nil && f.cfg.RateLimit != nil && f.cfg.RateLimit.Enable {
limiter := middleware.NewTokenBucketLimiter(
f.cfg.RateLimit.Rate,
time.Duration(f.cfg.RateLimit.Period)*time.Second,
)
var keyFunc func(r *http.Request) string
if f.cfg.RateLimit.ByIP {
keyFunc = func(r *http.Request) string { return middleware.GetClientIP(r) }
} else if f.cfg.RateLimit.ByUserID {
keyFunc = func(r *http.Request) string { return r.Header.Get("X-User-ID") }
}
mws = append(mws, middleware.RateLimit(&middleware.RateLimitConfig{
Limiter: limiter,
KeyFunc: keyFunc,
}))
}
if f.cfg != nil && f.cfg.CORS != nil {
mws = append(mws, middleware.CORS(&middleware.CORSConfig{
AllowedOrigins: f.cfg.CORS.AllowedOrigins,
AllowedMethods: f.cfg.CORS.AllowedMethods,
AllowedHeaders: f.cfg.CORS.AllowedHeaders,
ExposedHeaders: f.cfg.CORS.ExposedHeaders,
AllowCredentials: f.cfg.CORS.AllowCredentials,
MaxAge: f.cfg.CORS.MaxAge,
}))
}
mws = append(mws, middleware.Language, middleware.Timezone)
f.chain = middleware.NewChain(mws...)
return f.chain
}
// Migrator 创建迁移器并加载指定目录下的 SQL 文件
func (f *Factory) Migrator(migrationsDir string) (*migration.Migrator, error) {
db, err := f.getDatabase()
if err != nil {
return nil, err
}
dbType := "mysql"
if f.cfg.Database != nil && f.cfg.Database.Type != "" {
dbType = f.cfg.Database.Type
}
m := migration.NewMigratorWithType(db, dbType)
migrations, err := migration.LoadMigrationsFromFiles(migrationsDir, "*.sql")
if err != nil {
return nil, err
}
m.AddMigrations(migrations...)
return m, nil
}

20
go.mod
View File

@@ -1,12 +1,15 @@
module git.toowon.com/jimmy/go-common
go 1.23.0
go 1.24.0
toolchain go1.24.10
require (
github.com/google/uuid v1.6.0
github.com/minio/minio-go/v7 v7.0.97
github.com/redis/go-redis/v9 v9.17.1
github.com/xuri/excelize/v2 v2.10.0
golang.org/x/crypto v0.43.0
gorm.io/driver/mysql v1.5.2
gorm.io/driver/postgres v1.6.0
gorm.io/driver/sqlite v1.6.0
@@ -19,7 +22,6 @@ require (
github.com/dustin/go-humanize v1.0.1 // indirect
github.com/go-ini/ini v1.67.0 // indirect
github.com/go-sql-driver/mysql v1.7.1 // indirect
github.com/google/uuid v1.6.0 // indirect
github.com/jackc/pgpassfile v1.0.0 // indirect
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
github.com/jackc/pgx/v5 v5.6.0 // indirect
@@ -34,13 +36,17 @@ require (
github.com/minio/crc64nvme v1.1.0 // indirect
github.com/minio/md5-simd v1.1.2 // indirect
github.com/philhofer/fwd v1.2.0 // indirect
github.com/richardlehane/mscfb v1.0.4 // indirect
github.com/richardlehane/msoleps v1.0.4 // indirect
github.com/rogpeppe/go-internal v1.14.1 // indirect
github.com/rs/xid v1.6.0 // indirect
github.com/tiendc/go-deepcopy v1.7.1 // indirect
github.com/tinylib/msgp v1.3.0 // indirect
golang.org/x/crypto v0.36.0 // indirect
golang.org/x/net v0.38.0 // indirect
golang.org/x/sync v0.15.0 // indirect
golang.org/x/sys v0.34.0 // indirect
golang.org/x/text v0.26.0 // indirect
github.com/xuri/efp v0.0.1 // indirect
github.com/xuri/nfp v0.0.2-0.20250530014748-2ddeb826f9a9 // indirect
golang.org/x/net v0.46.0 // indirect
golang.org/x/sync v0.17.0 // indirect
golang.org/x/sys v0.37.0 // indirect
golang.org/x/text v0.30.0 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
)

39
go.sum
View File

@@ -56,6 +56,11 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/redis/go-redis/v9 v9.17.1 h1:7tl732FjYPRT9H9aNfyTwKg9iTETjWjGKEJ2t/5iWTs=
github.com/redis/go-redis/v9 v9.17.1/go.mod h1:u410H11HMLoB+TP67dz8rL9s6QW2j76l0//kSOd3370=
github.com/richardlehane/mscfb v1.0.4 h1:WULscsljNPConisD5hR0+OyZjwK46Pfyr6mPu5ZawpM=
github.com/richardlehane/mscfb v1.0.4/go.mod h1:YzVpcZg9czvAuhk9T+a3avCpcFPMUWm7gK3DypaEsUk=
github.com/richardlehane/msoleps v1.0.1/go.mod h1:BWev5JBpU9Ko2WAgmZEuiz4/u3ZYTKbjLycmwiWUfWg=
github.com/richardlehane/msoleps v1.0.4 h1:WuESlvhX3gH2IHcd8UqyCuFY5yiq/GR/yqaSM/9/g00=
github.com/richardlehane/msoleps v1.0.4/go.mod h1:BWev5JBpU9Ko2WAgmZEuiz4/u3ZYTKbjLycmwiWUfWg=
github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
github.com/rs/xid v1.6.0 h1:fV591PaemRlL6JfRxGDEPl69wICngIQ3shQtzfy2gxU=
@@ -63,20 +68,30 @@ github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
github.com/tiendc/go-deepcopy v1.7.1 h1:LnubftI6nYaaMOcaz0LphzwraqN8jiWTwm416sitff4=
github.com/tiendc/go-deepcopy v1.7.1/go.mod h1:4bKjNC2r7boYOkD2IOuZpYjmlDdzjbpTRyCx+goBCJQ=
github.com/tinylib/msgp v1.3.0 h1:ULuf7GPooDaIlbyvgAxBV/FI7ynli6LZ1/nVUNu+0ww=
github.com/tinylib/msgp v1.3.0/go.mod h1:ykjzy2wzgrlvpDCRc4LA8UXy6D8bzMSuAF3WD57Gok0=
golang.org/x/crypto v0.36.0 h1:AnAEvhDddvBdpY+uR+MyHmuZzzNqXSe/GvuDeob5L34=
golang.org/x/crypto v0.36.0/go.mod h1:Y4J0ReaxCR1IMaabaSMugxJES1EpwhBHhv2bDHklZvc=
golang.org/x/net v0.38.0 h1:vRMAPTMaeGqVhG5QyLJHqNDwecKTomGeqbnfZyKlBI8=
golang.org/x/net v0.38.0/go.mod h1:ivrbrMbzFq5J41QOQh0siUuly180yBYtLp+CKbEaFx8=
golang.org/x/sync v0.15.0 h1:KWH3jNZsfyT6xfAfKiz6MRNmd46ByHDYaZ7KSkCtdW8=
golang.org/x/sync v0.15.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
golang.org/x/sys v0.34.0 h1:H5Y5sJ2L2JRdyv7ROF1he/lPdvFsd0mJHFw2ThKHxLA=
golang.org/x/sys v0.34.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
golang.org/x/text v0.26.0 h1:P42AVeLghgTYr4+xUnTRKDMqpar+PtX7KWuNQL21L8M=
golang.org/x/text v0.26.0/go.mod h1:QK15LZJUUQVJxhz7wXgxSy/CJaTFjd0G+YLonydOVQA=
github.com/xuri/efp v0.0.1 h1:fws5Rv3myXyYni8uwj2qKjVaRP30PdjeYe2Y6FDsCL8=
github.com/xuri/efp v0.0.1/go.mod h1:ybY/Jr0T0GTCnYjKqmdwxyxn2BQf2RcQIIvex5QldPI=
github.com/xuri/excelize/v2 v2.10.0 h1:8aKsP7JD39iKLc6dH5Tw3dgV3sPRh8uRVXu/fMstfW4=
github.com/xuri/excelize/v2 v2.10.0/go.mod h1:SC5TzhQkaOsTWpANfm+7bJCldzcnU/jrhqkTi/iBHBU=
github.com/xuri/nfp v0.0.2-0.20250530014748-2ddeb826f9a9 h1:+C0TIdyyYmzadGaL/HBLbf3WdLgC29pgyhTjAT/0nuE=
github.com/xuri/nfp v0.0.2-0.20250530014748-2ddeb826f9a9/go.mod h1:WwHg+CVyzlv/TX9xqBFXEZAuxOPxn2k1GNHwG41IIUQ=
golang.org/x/crypto v0.43.0 h1:dduJYIi3A3KOfdGOHX8AVZ/jGiyPa3IbBozJ5kNuE04=
golang.org/x/crypto v0.43.0/go.mod h1:BFbav4mRNlXJL4wNeejLpWxB7wMbc79PdRGhWKncxR0=
golang.org/x/image v0.25.0 h1:Y6uW6rH1y5y/LK1J8BPWZtr6yZ7hrsy6hFrXjgsc2fQ=
golang.org/x/image v0.25.0/go.mod h1:tCAmOEGthTtkalusGp1g3xa2gke8J6c2N565dTyl9Rs=
golang.org/x/net v0.46.0 h1:giFlY12I07fugqwPuWJi68oOnpfqFnJIJzaIIm2JVV4=
golang.org/x/net v0.46.0/go.mod h1:Q9BGdFy1y4nkUwiLvT5qtyhAnEHgnQ/zd8PfU6nc210=
golang.org/x/sync v0.17.0 h1:l60nONMj9l5drqw6jlhIELNv9I0A4OFgRsG9k2oT9Ug=
golang.org/x/sync v0.17.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
golang.org/x/sys v0.37.0 h1:fdNQudmxPjkdUTPnLn5mdQv7Zwvbvpaxqs831goi9kQ=
golang.org/x/sys v0.37.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
golang.org/x/text v0.30.0 h1:yznKA/E9zq54KzlzBEAWn1NXSQ8DIp/NYMy88xJjl4k=
golang.org/x/text v0.30.0/go.mod h1:yDdHFIX9t+tORqspjENWgzaCVXgk0yYnYuSZ8UzzBVM=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=

304
http/handler.go
View File

@@ -1,279 +1,95 @@
package http
import (
"context"
"encoding/json"
"io"
"net/http"
"strconv"
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/i18n"
)
// Handler HTTP处理器包装器，封装ResponseWriter和Request，提供简洁的API
// Handler HTTP 出参处理器（唯一对外出参方式）
type Handler struct {
w http.ResponseWriter
r *http.Request
i18n *i18n.I18n
pagination *PaginationRequest
}
// NewHandler 创建Handler实例
func NewHandler(w http.ResponseWriter, r *http.Request) *Handler {
return &Handler{
w: w,
r: r,
// HandlerOption Handler 配置项
type HandlerOption func(*Handler)
// WithI18n 注入 i18n
func WithI18n(i *i18n.I18n) HandlerOption {
return func(h *Handler) {
h.i18n = i
}
}
// ResponseWriter 获取原始的ResponseWriter（需要时使用）
func (h *Handler) ResponseWriter() http.ResponseWriter {
return h.w
// NewHandler 创建 HTTP 出参处理器
func NewHandler(w http.ResponseWriter, r *http.Request, opts ...HandlerOption) *Handler {
h := &Handler{w: w, r: r}
for _, opt := range opts {
opt(h)
}
return h
}
// Request 获取原始的Request（需要时使用）
func (h *Handler) Request() *http.Request {
return h.r
// ParseJSON 解析 JSON 请求体
func (h *Handler) ParseJSON(v interface{}) error {
return ParseJSON(h.r, v)
}
// Context 获取请求的Context
func (h *Handler) Context() context.Context {
return h.r.Context()
// Pagination 解析并缓存分页参数
func (h *Handler) Pagination() *PaginationRequest {
if h.pagination == nil {
h.pagination = ParsePaginationRequest(h.r)
}
return h.pagination
}
// ========== 响应方法（黑盒模式） ==========
// GetLanguage 从 context 获取语言
func (h *Handler) GetLanguage() string {
return GetLanguage(h.r)
}
// GetTimezone 从 context 获取时区
func (h *Handler) GetTimezone() string {
return GetTimezone(h.r)
}
// Success 成功响应
// data: 响应数据，可以为nil
func (h *Handler) Success(data interface{}) {
writeJSON(h.w, http.StatusOK, 0, "success", data)
}
// SuccessWithMessage 带消息的成功响应
func (h *Handler) SuccessWithMessage(message string, data interface{}) {
writeJSON(h.w, http.StatusOK, 0, message, data)
}
// Error 错误响应
// code: 业务错误码，非0表示业务错误
// message: 错误消息
func (h *Handler) Error(code int, message string) {
writeJSON(h.w, http.StatusOK, code, message, nil)
}
// SystemError 系统错误响应（返回HTTP 500）
// message: 错误消息
func (h *Handler) SystemError(message string) {
writeJSON(h.w, http.StatusInternalServerError, 500, message, nil)
}
// WriteJSON 写入JSON响应（自定义HTTP状态码和业务状态码）
// httpCode: HTTP状态码（200表示正常，500表示系统错误等）
// code: 业务状态码（0表示成功，非0表示业务错误）
// message: 响应消息
// data: 响应数据
func (h *Handler) WriteJSON(httpCode, code int, message string, data interface{}) {
writeJSON(h.w, httpCode, code, message, data)
message := "success"
code := 0
if h.i18n != nil {
info := h.i18n.GetMessageInfo(h.GetLanguage(), "common.success")
if info.Message != "common.success" {
message = info.Message
code = info.Code
}
}
writeResponse(h.w, code, message, data)
}
// SuccessPage 分页成功响应
// list: 数据列表
// total: 总记录数
// page: 当前页码
// pageSize: 每页大小
// message: 响应消息（可选，如果为空则使用默认消息 "success"）
func (h *Handler) SuccessPage(list interface{}, total int64, page, pageSize int, message ...string) {
msg := "success"
if len(message) > 0 && message[0] != "" {
msg = message[0]
}
func (h *Handler) SuccessPage(list interface{}, total int64) {
p := h.Pagination()
pageData := &PageData{
List: list,
Total: total,
Page: page,
PageSize: pageSize,
Page: p.GetPage(),
PageSize: p.GetPageSize(),
}
writeJSON(h.w, http.StatusOK, 0, msg, pageData)
h.Success(pageData)
}
// ========== 请求解析方法（黑盒模式） ==========
// ParseJSON 解析JSON请求体
// v: 目标结构体指针
func (h *Handler) ParseJSON(v interface{}) error {
body, err := io.ReadAll(h.r.Body)
if err != nil {
return err
}
defer h.r.Body.Close()
if len(body) == 0 {
return nil
}
return json.Unmarshal(body, v)
}
// GetQuery 获取查询参数
// key: 参数名
// defaultValue: 默认值
func (h *Handler) GetQuery(key, defaultValue string) string {
value := h.r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
return value
}
// GetQueryInt 获取整数查询参数
// key: 参数名
// defaultValue: 默认值
func (h *Handler) GetQueryInt(key string, defaultValue int) int {
value := h.r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.Atoi(value)
if err != nil {
return defaultValue
}
return intValue
}
// GetQueryInt64 获取int64查询参数
func (h *Handler) GetQueryInt64(key string, defaultValue int64) int64 {
value := h.r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.ParseInt(value, 10, 64)
if err != nil {
return defaultValue
}
return intValue
}
// GetQueryBool 获取布尔查询参数
func (h *Handler) GetQueryBool(key string, defaultValue bool) bool {
value := h.r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
boolValue, err := strconv.ParseBool(value)
if err != nil {
return defaultValue
}
return boolValue
}
// GetQueryFloat64 获取float64查询参数
func (h *Handler) GetQueryFloat64(key string, defaultValue float64) float64 {
value := h.r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
floatValue, err := strconv.ParseFloat(value, 64)
if err != nil {
return defaultValue
}
return floatValue
}
// GetFormValue 获取表单值
func (h *Handler) GetFormValue(key, defaultValue string) string {
value := h.r.FormValue(key)
if value == "" {
return defaultValue
}
return value
}
// GetFormInt 获取表单整数
func (h *Handler) GetFormInt(key string, defaultValue int) int {
value := h.r.FormValue(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.Atoi(value)
if err != nil {
return defaultValue
}
return intValue
}
// GetFormInt64 获取表单int64
func (h *Handler) GetFormInt64(key string, defaultValue int64) int64 {
value := h.r.FormValue(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.ParseInt(value, 10, 64)
if err != nil {
return defaultValue
}
return intValue
}
// GetFormBool 获取表单布尔值
func (h *Handler) GetFormBool(key string, defaultValue bool) bool {
value := h.r.FormValue(key)
if value == "" {
return defaultValue
}
boolValue, err := strconv.ParseBool(value)
if err != nil {
return defaultValue
}
return boolValue
}
// GetHeader 获取请求头
func (h *Handler) GetHeader(key, defaultValue string) string {
value := h.r.Header.Get(key)
if value == "" {
return defaultValue
}
return value
}
// ParsePaginationRequest 从请求中解析分页参数
// 支持从查询参数和form表单中解析
// 优先级：查询参数 > form表单
func (h *Handler) ParsePaginationRequest() *PaginationRequest {
return ParsePaginationRequest(h.r)
}
// GetTimezone 从请求的context中获取时区
// 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
// 如果未设置，返回默认时区 AsiaShanghai
func (h *Handler) GetTimezone() string {
return middleware.GetTimezoneFromContext(h.r.Context())
}
// HandleFunc 将Handler函数转换为标准的http.HandlerFunc
// 这样可以将Handler函数直接用于http.HandleFunc
// 示例：
//
// http.HandleFunc("/users", http.HandleFunc(func(h *http.Handler) {
// h.Success(data)
// }))
func HandleFunc(fn func(*Handler)) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
h := NewHandler(w, r)
fn(h)
// Error 失败响应（messageCode 为 i18n 消息码）
func (h *Handler) Error(messageCode string, args ...interface{}) {
code := 0
message := messageCode
if h.i18n != nil {
info := h.i18n.GetMessageInfo(h.GetLanguage(), messageCode, args...)
code = info.Code
message = info.Message
}
writeResponse(h.w, code, message, nil)
}

100
http/request.go
View File

@@ -1,46 +1,20 @@
package http
import (
"encoding/json"
"io"
"net/http"
"strconv"
"git.toowon.com/jimmy/go-common/requestctx"
"git.toowon.com/jimmy/go-common/tools"
)
// getQueryInt 获取整数查询参数（内部方法，供ParsePaginationRequest使用）
func getQueryInt(r *http.Request, key string, defaultValue int) int {
value := r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.Atoi(value)
if err != nil {
return defaultValue
}
return intValue
}
// getFormInt 获取表单整数（内部方法，供ParsePaginationRequest使用）
func getFormInt(r *http.Request, key string, defaultValue int) int {
value := r.FormValue(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.Atoi(value)
if err != nil {
return defaultValue
}
return intValue
}
// PaginationRequest 分页请求结构
// 支持从JSON和form中解析分页参数
type PaginationRequest struct {
Page int `json:"page" form:"page"` // 页码，默认1
Size int `json:"size" form:"size"` // 每页数量（兼容旧版本）
PageSize int `json:"page_size" form:"page_size"` // 每页数量（推荐使用）
PageSize int `json:"page_size" form:"page_size"` // 每页数量
Keyword string `json:"keyword" form:"keyword"` // 关键字
}
// GetPage 获取页码，如果未设置则返回默认值1
@@ -51,13 +25,9 @@ func (p *PaginationRequest) GetPage() int {
return p.Page
}
// GetSize 获取每页数量，如果未设置则返回默认值20，最大限制100
// 优先使用 PageSize 字段，如果未设置则使用 Size 字段（兼容旧版本）
func (p *PaginationRequest) GetSize() int {
// GetPageSize 获取每页数量，如果未设置则返回默认值20，最大限制100
func (p *PaginationRequest) GetPageSize() int {
size := p.PageSize
if size <= 0 {
size = p.Size // 兼容旧版本的 Size 字段
}
if size <= 0 {
return 20 // 默认20条
}
@@ -69,22 +39,20 @@ func (p *PaginationRequest) GetSize() int {
// GetOffset 计算数据库查询的偏移量
func (p *PaginationRequest) GetOffset() int {
return (p.GetPage() - 1) * p.GetSize()
return (p.GetPage() - 1) * p.GetPageSize()
}
// getPaginationFromQuery 从查询参数获取分页参数（内部辅助方法）
func getPaginationFromQuery(r *http.Request) (page, size, pageSize int) {
page = getQueryInt(r, "page", 0)
size = getQueryInt(r, "size", 0)
pageSize = getQueryInt(r, "page_size", 0)
func getPaginationFromQuery(r *http.Request) (page, pageSize int) {
page = tools.ConvertInt(r.URL.Query().Get("page"), 0)
pageSize = tools.ConvertInt(r.URL.Query().Get("page_size"), 0)
return
}
// getPaginationFromForm 从form表单获取分页参数（内部辅助方法）
func getPaginationFromForm(r *http.Request) (page, size, pageSize int) {
page = getFormInt(r, "page", 0)
size = getFormInt(r, "size", 0)
pageSize = getFormInt(r, "page_size", 0)
func getPaginationFromForm(r *http.Request) (page, pageSize int) {
page = tools.ConvertInt(r.FormValue("page"), 0)
pageSize = tools.ConvertInt(r.FormValue("page_size"), 0)
return
}
@@ -96,17 +64,14 @@ func ParsePaginationRequest(r *http.Request) *PaginationRequest {
req := &PaginationRequest{}
// 1. 从查询参数解析（优先级最高）
req.Page, req.Size, req.PageSize = getPaginationFromQuery(r)
req.Page, req.PageSize = getPaginationFromQuery(r)
// 2. 如果查询参数中没有，尝试从form表单解析
if req.Page == 0 || (req.Size == 0 && req.PageSize == 0) {
page, size, pageSize := getPaginationFromForm(r)
if req.Page == 0 || req.PageSize == 0 {
page, pageSize := getPaginationFromForm(r)
if req.Page == 0 && page != 0 {
req.Page = page
}
if req.Size == 0 && size != 0 {
req.Size = size
}
if req.PageSize == 0 && pageSize != 0 {
req.PageSize = pageSize
}
@@ -114,3 +79,30 @@ func ParsePaginationRequest(r *http.Request) *PaginationRequest {
return req
}
// ParseJSON 解析JSON请求体（公共方法）
// r: HTTP请求
// v: 目标结构体指针
func ParseJSON(r *http.Request, v interface{}) error {
body, err := io.ReadAll(r.Body)
if err != nil {
return err
}
defer r.Body.Close()
if len(body) == 0 {
return nil
}
return json.Unmarshal(body, v)
}
// GetTimezone 从请求的 context 中获取时区
func GetTimezone(r *http.Request) string {
return requestctx.Timezone(r.Context())
}
// GetLanguage 从请求的 context 中获取语言
func GetLanguage(r *http.Request) string {
return requestctx.Language(r.Context())
}

30
http/response.go
View File

@@ -8,36 +8,24 @@ import (
// Response 标准响应结构
type Response struct {
Code int `json:"code"` // 业务状态码，0表示成功
Message string `json:"message"` // 响应消息
Timestamp int64 `json:"timestamp"` // 时间戳
Data interface{} `json:"data"` // 响应数据
}
// PageResponse 分页响应结构
type PageResponse struct {
Code int `json:"code"`
Message string `json:"message"`
Timestamp int64 `json:"timestamp"`
Data *PageData `json:"data"`
Data interface{} `json:"data"`
}
// PageData 分页数据
type PageData struct {
List interface{} `json:"list"` // 数据列表
Total int64 `json:"total"` // 总记录数
Page int `json:"page"` // 当前页码
PageSize int `json:"pageSize"` // 每页大小
List interface{} `json:"list"`
Total int64 `json:"total"`
Page int `json:"page"`
PageSize int `json:"pageSize"`
}
// writeJSON 写入JSON响应（内部方法）
// httpCode: HTTP状态码（200表示正常，500表示系统错误等）
// code: 业务状态码（0表示成功，非0表示业务错误）
// message: 响应消息
// data: 响应数据
func writeJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{}) {
// writeResponse 统一 JSON 出参（HTTP 恒 200）
func writeResponse(w http.ResponseWriter, code int, message string, data interface{}) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(httpCode)
w.WriteHeader(http.StatusOK)
response := Response{
Code: code,
@@ -46,5 +34,5 @@ func writeJSON(w http.ResponseWriter, httpCode, code int, message string, data i
Data: data,
}
json.NewEncoder(w).Encode(response)
_ = json.NewEncoder(w).Encode(response)
}

286
i18n/i18n.go Normal file
View File

@@ -0,0 +1,286 @@
package i18n
import (
"encoding/json"
"fmt"
"os"
"path/filepath"
"strings"
"sync"
)
// MessageInfo 消息信息结构
// 包含业务错误码和消息内容
type MessageInfo struct {
Code int `json:"code"` // 业务错误码
Message string `json:"message"` // 消息内容
}
// I18n 国际化工具
// 支持多语言内容管理，通过语言代码和消息代码获取对应语言的内容
type I18n struct {
messages map[string]map[string]MessageInfo // 存储格式：messages[语言][code] = MessageInfo
defaultLang string // 默认语言代码
mu sync.RWMutex // 读写锁，保证并发安全
}
// NewI18n 创建国际化工具实例
// defaultLang: 默认语言代码（如 "zh-CN", "en-US"），当指定语言不存在时使用
func NewI18n(defaultLang string) *I18n {
return &I18n{
messages: make(map[string]map[string]MessageInfo),
defaultLang: defaultLang,
}
}
// LoadFromFile 从单个语言文件加载内容
// filePath: 语言文件路径（JSON格式）
// lang: 语言代码（如 "zh-CN", "en-US"）
//
// 文件格式示例（zh-CN.json）：
//
// {
// "user.not_found": {
// "code": 1001,
// "message": "用户不存在"
// },
// "user.login_success": {
// "code": 0,
// "message": "登录成功"
// },
// "user.welcome": {
// "code": 0,
// "message": "欢迎，%s"
// }
// }
func (i *I18n) LoadFromFile(filePath, lang string) error {
data, err := os.ReadFile(filePath)
if err != nil {
return fmt.Errorf("failed to read file %s: %w", filePath, err)
}
var messages map[string]MessageInfo
if err := json.Unmarshal(data, &messages); err != nil {
return fmt.Errorf("failed to parse JSON file %s: %w", filePath, err)
}
i.mu.Lock()
defer i.mu.Unlock()
if i.messages[lang] == nil {
i.messages[lang] = make(map[string]MessageInfo)
}
// 合并到现有消息中（如果key已存在会被覆盖）
for k, v := range messages {
i.messages[lang][k] = v
}
return nil
}
// LoadFromDir 从目录加载多个语言文件
// dirPath: 语言文件目录路径
// 文件命名规则：{语言代码}.json（如 zh-CN.json, en-US.json）
//
// 示例目录结构：
//
// locales/
// zh-CN.json
// en-US.json
// ja-JP.json
func (i *I18n) LoadFromDir(dirPath string) error {
entries, err := os.ReadDir(dirPath)
if err != nil {
return fmt.Errorf("failed to read directory %s: %w", dirPath, err)
}
for _, entry := range entries {
if entry.IsDir() {
continue
}
// 只处理 .json 文件
if !strings.HasSuffix(entry.Name(), ".json") {
continue
}
// 从文件名提取语言代码（去掉 .json 后缀）
lang := strings.TrimSuffix(entry.Name(), ".json")
filePath := filepath.Join(dirPath, entry.Name())
if err := i.LoadFromFile(filePath, lang); err != nil {
return fmt.Errorf("failed to load language file %s: %w", filePath, err)
}
}
return nil
}
// LoadFromMap 从map加载语言内容（用于测试或动态加载）
// lang: 语言代码
// messages: 消息map，key为消息代码，value为消息信息
//
// 示例：
//
// i18n.LoadFromMap("zh-CN", map[string]MessageInfo{
// "user.not_found": {Code: 1001, Message: "用户不存在"},
// "user.login_success": {Code: 0, Message: "登录成功"},
// })
func (i *I18n) LoadFromMap(lang string, messages map[string]MessageInfo) {
i.mu.Lock()
defer i.mu.Unlock()
if i.messages[lang] == nil {
i.messages[lang] = make(map[string]MessageInfo)
}
// 合并到现有消息中
for k, v := range messages {
i.messages[lang][k] = v
}
}
// GetMessage 获取指定语言和代码的消息内容
// lang: 语言代码（如 "zh-CN", "en-US"）
// code: 消息代码（如 "user.not_found"）
// args: 可选参数，用于格式化消息（类似 fmt.Sprintf）
//
// 返回逻辑：
// 1. 如果指定语言存在该code，返回对应内容
// 2. 如果指定语言不存在，尝试使用默认语言
// 3. 如果默认语言也不存在，返回code本身（作为fallback）
//
// 示例：
//
// msg := i18n.GetMessage("zh-CN", "user.not_found")
// // 返回: "用户不存在"
//
// msg := i18n.GetMessage("zh-CN", "user.welcome", "Alice")
// // 如果消息内容是 "欢迎，%s"，返回: "欢迎，Alice"
func (i *I18n) GetMessage(lang, code string, args ...interface{}) string {
info := i.GetMessageInfo(lang, code, args...)
return info.Message
}
// GetMessageInfo 获取指定语言和代码的完整消息信息（包含业务code）
// lang: 语言代码（如 "zh-CN", "en-US"）
// code: 消息代码（如 "user.not_found"）
// args: 可选参数，用于格式化消息（类似 fmt.Sprintf）
//
// 返回逻辑：
// 1. 如果指定语言存在该code，返回对应的MessageInfo
// 2. 如果指定语言不存在，尝试使用默认语言
// 3. 如果默认语言也不存在，返回code本身作为message，code为0
//
// 示例：
//
// info := i18n.GetMessageInfo("zh-CN", "user.not_found")
// // 返回: MessageInfo{Code: 1001, Message: "用户不存在"}
func (i *I18n) GetMessageInfo(lang, code string, args ...interface{}) MessageInfo {
i.mu.RLock()
defer i.mu.RUnlock()
// 尝试从指定语言获取
if messages, ok := i.messages[lang]; ok {
if msgInfo, ok := messages[code]; ok {
// 格式化消息内容
msgInfo.Message = i.formatMessage(msgInfo.Message, args...)
return msgInfo
}
}
// 如果指定语言不存在该code，尝试使用默认语言
if i.defaultLang != "" && i.defaultLang != lang {
if messages, ok := i.messages[i.defaultLang]; ok {
if msgInfo, ok := messages[code]; ok {
// 格式化消息内容
msgInfo.Message = i.formatMessage(msgInfo.Message, args...)
return msgInfo
}
}
}
// 如果都不存在，返回code本身作为message，code为0（作为fallback）
return MessageInfo{
Code: 0,
Message: code,
}
}
// formatMessage 格式化消息（支持参数替换）
// 如果消息中包含 %s, %d 等格式化占位符，使用 args 进行替换
func (i *I18n) formatMessage(msg string, args ...interface{}) string {
if len(args) == 0 {
return msg
}
// 检查消息中是否包含格式化占位符
if strings.Contains(msg, "%") {
return fmt.Sprintf(msg, args...)
}
return msg
}
// SetDefaultLang 设置默认语言
// lang: 默认语言代码
func (i *I18n) SetDefaultLang(lang string) {
i.mu.Lock()
defer i.mu.Unlock()
i.defaultLang = lang
}
// GetDefaultLang 获取默认语言代码
func (i *I18n) GetDefaultLang() string {
i.mu.RLock()
defer i.mu.RUnlock()
return i.defaultLang
}
// HasLang 检查是否已加载指定语言
// lang: 语言代码
func (i *I18n) HasLang(lang string) bool {
i.mu.RLock()
defer i.mu.RUnlock()
_, ok := i.messages[lang]
return ok
}
// GetSupportedLangs 获取所有已加载的语言代码列表
func (i *I18n) GetSupportedLangs() []string {
i.mu.RLock()
defer i.mu.RUnlock()
langs := make([]string, 0, len(i.messages))
for lang := range i.messages {
langs = append(langs, lang)
}
return langs
}
// ReloadFromFile 重新加载指定语言文件
// filePath: 语言文件路径
// lang: 语言代码
func (i *I18n) ReloadFromFile(filePath, lang string) error {
// 先清除该语言的所有消息
i.mu.Lock()
delete(i.messages, lang)
i.mu.Unlock()
// 重新加载
return i.LoadFromFile(filePath, lang)
}
// ReloadFromDir 重新加载目录中的所有语言文件
// dirPath: 语言文件目录路径
func (i *I18n) ReloadFromDir(dirPath string) error {
// 先清除所有消息
i.mu.Lock()
i.messages = make(map[string]map[string]MessageInfo)
i.mu.Unlock()
// 重新加载
return i.LoadFromDir(dirPath)
}

384
logger/logger.go
View File

@@ -1,44 +1,138 @@
package logger
import (
"context"
"encoding/json"
"fmt"
"io"
"log"
"os"
"path/filepath"
"sync"
"sync/atomic"
"time"
"git.toowon.com/jimmy/go-common/config"
)
type ctxKey int
const requestIDKey ctxKey = iota
// WithRequestID 将 Request ID 写入 context
func WithRequestID(ctx context.Context, id string) context.Context {
return context.WithValue(ctx, requestIDKey, id)
}
// RequestIDFromContext 从 context 读取 Request ID
func RequestIDFromContext(ctx context.Context) string {
if ctx == nil {
return ""
}
if id, ok := ctx.Value(requestIDKey).(string); ok {
return id
}
return ""
}
var (
defaultLogger *Logger
defaultMux sync.RWMutex
)
func init() {
l, err := NewLogger(nil)
if err != nil {
defaultLogger = nil
return
}
defaultLogger = l
}
// SetDefaultLogger 设置全局默认 logger
func SetDefaultLogger(l *Logger) {
defaultMux.Lock()
defer defaultMux.Unlock()
if defaultLogger != nil && defaultLogger != l {
_ = defaultLogger.Close()
}
defaultLogger = l
}
func getDefaultLogger() *Logger {
defaultMux.RLock()
defer defaultMux.RUnlock()
return defaultLogger
}
type logEntry struct {
level string
message string
fields map[string]any
}
// Logger 日志记录器
type Logger struct {
infoLog *log.Logger
errorLog *log.Logger
warnLog *log.Logger
debugLog *log.Logger
config *config.LoggerConfig
level string
writers []io.Writer
prefix string
async bool
logChan chan logEntry
done chan struct{}
wg sync.WaitGroup
closed bool
mu sync.RWMutex
dropped atomic.Uint64
}
// NewLogger 创建日志记录器
func NewLogger(cfg *config.LoggerConfig) (*Logger, error) {
if cfg == nil {
// 使用默认配置
cfg = &config.LoggerConfig{
Level: "info",
Output: "stdout",
FilePath: "",
Async: config.BoolPtr(true),
BufferSize: 1000,
}
}
// 设置默认值
if cfg.Level == "" {
cfg.Level = "info"
}
if cfg.Output == "" {
cfg.Output = "stdout"
}
if cfg.BufferSize <= 0 {
cfg.BufferSize = 1000
}
// 创建输出目标
writers, err := createWriters(cfg)
if err != nil {
return nil, err
}
prefix := ""
if cfg.Prefix != "" {
prefix = cfg.Prefix + " "
}
l := &Logger{
level: cfg.Level,
writers: writers,
prefix: prefix,
async: cfg.IsAsync(),
}
if cfg.IsAsync() {
l.logChan = make(chan logEntry, cfg.BufferSize)
l.done = make(chan struct{})
l.wg.Add(1)
go l.processLogs()
}
return l, nil
}
func createWriters(cfg *config.LoggerConfig) ([]io.Writer, error) {
var writers []io.Writer
switch cfg.Output {
case "stdout":
@@ -49,159 +143,219 @@ func NewLogger(cfg *config.LoggerConfig) (*Logger, error) {
if cfg.FilePath == "" {
return nil, fmt.Errorf("file path is required when output is file")
}
// 确保目录存在
dir := filepath.Dir(cfg.FilePath)
if err := os.MkdirAll(dir, 0755); err != nil {
return nil, fmt.Errorf("failed to create log directory: %w", err)
}
file, err := os.OpenFile(cfg.FilePath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
w, err := openLogFile(cfg.FilePath)
if err != nil {
return nil, fmt.Errorf("failed to open log file: %w", err)
return nil, err
}
writers = append(writers, file)
writers = append(writers, w)
case "both":
writers = append(writers, os.Stdout)
if cfg.FilePath == "" {
return nil, fmt.Errorf("file path is required when output is both")
}
dir := filepath.Dir(cfg.FilePath)
if err := os.MkdirAll(dir, 0755); err != nil {
return nil, fmt.Errorf("failed to create log directory: %w", err)
}
file, err := os.OpenFile(cfg.FilePath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
w, err := openLogFile(cfg.FilePath)
if err != nil {
return nil, fmt.Errorf("failed to open log file: %w", err)
return nil, err
}
writers = append(writers, file)
writers = append(writers, w)
default:
return nil, fmt.Errorf("invalid output type: %s", cfg.Output)
}
return writers, nil
}
// 创建多写入器
multiWriter := io.MultiWriter(writers...)
// 创建日志前缀
prefix := ""
if cfg.Prefix != "" {
prefix = cfg.Prefix + " "
func openLogFile(path string) (io.Writer, error) {
dir := filepath.Dir(path)
if err := os.MkdirAll(dir, 0o755); err != nil {
return nil, fmt.Errorf("failed to create log directory: %w", err)
}
// 创建日志记录器
logger := &Logger{
config: cfg,
f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o666)
if err != nil {
return nil, fmt.Errorf("failed to open log file: %w", err)
}
return f, nil
}
// 根据日志级别创建不同的logger
flags := log.LstdFlags
if cfg.DisableTimestamp {
flags = 0
func (l *Logger) processLogs() {
defer l.wg.Done()
for {
select {
case msg, ok := <-l.logChan:
if !ok {
return
}
if cfg.Level == "debug" || cfg.Level == "info" || cfg.Level == "warn" || cfg.Level == "error" {
logger.infoLog = log.New(multiWriter, prefix+"[INFO] ", flags)
logger.warnLog = log.New(multiWriter, prefix+"[WARN] ", flags)
logger.errorLog = log.New(multiWriter, prefix+"[ERROR] ", flags)
if cfg.Level == "debug" {
logger.debugLog = log.New(multiWriter, prefix+"[DEBUG] ", flags)
l.writeEntry(msg)
case <-l.done:
for {
select {
case msg, ok := <-l.logChan:
if !ok {
return
}
l.writeEntry(msg)
default:
return
}
}
}
}
}
return logger, nil
func (l *Logger) isClosed() bool {
l.mu.RLock()
defer l.mu.RUnlock()
return l.closed
}
func (l *Logger) shouldLog(level string) bool {
switch l.level {
case "debug":
return true
case "info":
return level != "debug"
case "error":
return level == "error"
default:
return level != "debug"
}
}
func (l *Logger) emit(level, message string, fields map[string]any) {
if l.isClosed() || !l.shouldLog(level) {
return
}
entry := logEntry{level: level, message: message, fields: fields}
if l.async {
select {
case l.logChan <- entry:
default:
l.dropped.Add(1)
}
return
}
l.writeEntry(entry)
}
func (l *Logger) writeEntry(entry logEntry) {
line := l.formatLine(entry.level, entry.message, entry.fields)
for _, w := range l.writers {
_, _ = fmt.Fprintln(w, line)
}
}
func (l *Logger) formatLine(level, message string, fields map[string]any) string {
ts := time.Now().Format("2006-01-02 15:04:05")
payload := map[string]any{
"time": ts,
"level": level,
"message": message,
}
for k, v := range fields {
payload[k] = v
}
b, err := json.Marshal(payload)
if err != nil {
return fmt.Sprintf("%s[%s] %s %v", l.prefix, level, message, fields)
}
return l.prefix + string(b)
}
// Debug 记录调试日志
func (l *Logger) Debug(format string, v ...interface{}) {
if l.debugLog != nil {
l.debugLog.Printf(format, v...)
}
func (l *Logger) Debug(message string, fields map[string]any) {
l.emit("debug", message, fields)
}
// Info 记录信息日志
func (l *Logger) Info(format string, v ...interface{}) {
if l.infoLog != nil {
l.infoLog.Printf(format, v...)
}
}
// Warn 记录警告日志
func (l *Logger) Warn(format string, v ...interface{}) {
if l.warnLog != nil {
l.warnLog.Printf(format, v...)
}
func (l *Logger) Info(message string, fields map[string]any) {
l.emit("info", message, fields)
}
// Error 记录错误日志
func (l *Logger) Error(format string, v ...interface{}) {
if l.errorLog != nil {
l.errorLog.Printf(format, v...)
}
func (l *Logger) Error(message string, fields map[string]any) {
l.emit("error", message, fields)
}
// Fatal 记录致命错误日志并退出程序
func (l *Logger) Fatal(format string, v ...interface{}) {
if l.errorLog != nil {
l.errorLog.Fatalf(format, v...)
} else {
log.Fatalf(format, v...)
// Close 刷盘并关闭异步队列
func (l *Logger) Close() error {
if !l.async {
return nil
}
l.mu.Lock()
if l.closed {
l.mu.Unlock()
return nil
}
l.closed = true
l.mu.Unlock()
close(l.done)
close(l.logChan)
l.wg.Wait()
return nil
}
// Panic 记录恐慌日志并触发panic
func (l *Logger) Panic(format string, v ...interface{}) {
if l.errorLog != nil {
l.errorLog.Panicf(format, v...)
} else {
log.Panicf(format, v...)
}
// DroppedCount 返回因队列满而丢弃的日志条数
func (l *Logger) DroppedCount() uint64 {
return l.dropped.Load()
}
// WithFields 创建带字段的日志记录器（简化版，返回格式化字符串）
func (l *Logger) WithFields(fields map[string]interface{}) *Logger {
// 返回自身，实际使用时可以在format中包含fields
return l
// ContextLogger 带 context 的 logger（自动附加 request_id）
type ContextLogger struct {
base *Logger
ctx context.Context
}
// formatFields 格式化字段
func formatFields(fields map[string]interface{}) string {
if len(fields) == 0 {
return ""
// FromContext 从 context 获取 logger，自动附加 request_id
func FromContext(ctx context.Context) *ContextLogger {
base := getDefaultLogger()
if base == nil {
if l, err := NewLogger(nil); err == nil {
base = l
}
result := ""
}
return &ContextLogger{base: base, ctx: ctx}
}
// FromContextWithLogger 使用指定 logger 并从 context 附加 request_id
func FromContextWithLogger(ctx context.Context, base *Logger) *ContextLogger {
if base == nil {
base = getDefaultLogger()
}
return &ContextLogger{base: base, ctx: ctx}
}
func (c *ContextLogger) mergeFields(fields map[string]any) map[string]any {
out := make(map[string]any, len(fields)+1)
for k, v := range fields {
result += fmt.Sprintf("%s=%v ", k, v)
out[k] = v
}
return result
if id := RequestIDFromContext(c.ctx); id != "" {
out["request_id"] = id
}
return out
}
// Debugf 记录调试日志（带字段）
func (l *Logger) Debugf(fields map[string]interface{}, format string, v ...interface{}) {
if l.debugLog != nil {
fieldStr := formatFields(fields)
l.debugLog.Printf(fieldStr+format, v...)
// Debug 记录调试日志
func (c *ContextLogger) Debug(message string, fields map[string]any) {
if c.base == nil {
return
}
c.base.Debug(message, c.mergeFields(fields))
}
// Infof 记录信息日志（带字段）
func (l *Logger) Infof(fields map[string]interface{}, format string, v ...interface{}) {
if l.infoLog != nil {
fieldStr := formatFields(fields)
l.infoLog.Printf(fieldStr+format, v...)
// Info 记录信息日志
func (c *ContextLogger) Info(message string, fields map[string]any) {
if c.base == nil {
return
}
c.base.Info(message, c.mergeFields(fields))
}
// Warnf 记录警告日志（带字段）
func (l *Logger) Warnf(fields map[string]interface{}, format string, v ...interface{}) {
if l.warnLog != nil {
fieldStr := formatFields(fields)
l.warnLog.Printf(fieldStr+format, v...)
// Error 记录错误日志
func (c *ContextLogger) Error(message string, fields map[string]any) {
if c.base == nil {
return
}
c.base.Error(message, c.mergeFields(fields))
}
// Errorf 记录错误日志（带字段）
func (l *Logger) Errorf(fields map[string]interface{}, format string, v ...interface{}) {
if l.errorLog != nil {
fieldStr := formatFields(fields)
l.errorLog.Printf(fieldStr+format, v...)
}
}

26
middleware/clientip.go Normal file
View File

@@ -0,0 +1,26 @@
package middleware
import "net/http"
// GetClientIP 获取客户端真实 IP
func GetClientIP(r *http.Request) string {
xff := r.Header.Get("X-Forwarded-For")
if xff != "" {
for i := 0; i < len(xff); i++ {
if xff[i] == ',' {
return xff[:i]
}
}
return xff
}
if xri := r.Header.Get("X-Real-IP"); xri != "" {
return xri
}
remoteAddr := r.RemoteAddr
for i := len(remoteAddr) - 1; i >= 0; i-- {
if remoteAddr[i] == ':' {
return remoteAddr[:i]
}
}
return remoteAddr
}

30
middleware/cors.go
View File

@@ -43,6 +43,36 @@ func DefaultCORSConfig() *CORSConfig {
}
}
// NewCORSConfig 从配置参数创建 CORSConfig
// 用于从 config 包的 CORSConfig 转换为 middleware 的 CORSConfig
// 避免循环依赖
func NewCORSConfig(allowedOrigins, allowedMethods, allowedHeaders, exposedHeaders []string, allowCredentials bool, maxAge int) *CORSConfig {
cfg := &CORSConfig{
AllowedOrigins: allowedOrigins,
AllowedMethods: allowedMethods,
AllowedHeaders: allowedHeaders,
ExposedHeaders: exposedHeaders,
AllowCredentials: allowCredentials,
MaxAge: maxAge,
}
// 设置默认值（如果为空）
if len(cfg.AllowedOrigins) == 0 {
cfg.AllowedOrigins = []string{"*"}
}
if len(cfg.AllowedMethods) == 0 {
cfg.AllowedMethods = []string{"GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"}
}
if len(cfg.AllowedHeaders) == 0 {
cfg.AllowedHeaders = []string{"Content-Type", "Authorization", "X-Requested-With", "X-Timezone"}
}
if cfg.MaxAge == 0 {
cfg.MaxAge = 86400
}
return cfg
}
// CORS CORS中间件
func CORS(config ...*CORSConfig) func(http.Handler) http.Handler {
var cfg *CORSConfig

93
middleware/language.go Normal file
View File

@@ -0,0 +1,93 @@
package middleware
import (
"context"
"net/http"
"strings"
"git.toowon.com/jimmy/go-common/requestctx"
)
// LanguageHeaderName 语言请求头名称
const LanguageHeaderName = "X-Language"
// AcceptLanguageHeaderName Accept-Language 请求头名称
const AcceptLanguageHeaderName = "Accept-Language"
// GetLanguageFromContext 从 context 中获取语言
func GetLanguageFromContext(ctx context.Context) string {
return requestctx.Language(ctx)
}
// Language 语言处理中间件
// 从请求头 X-Language 或 Accept-Language 读取语言信息，如果未传递则使用默认语言 zh-CN
// 语言信息会存储到context中，可以通过 GetLanguageFromContext 获取
func Language(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 1. 优先从 X-Language 请求头获取（显式指定）
lang := r.Header.Get(LanguageHeaderName)
// 2. 如果未设置，从 Accept-Language 请求头解析
if lang == "" {
acceptLang := r.Header.Get(AcceptLanguageHeaderName)
if acceptLang != "" {
lang = parseAcceptLanguage(acceptLang)
}
}
// 3. 如果都未设置，使用默认语言
if lang == "" {
lang = requestctx.DefaultLanguage
}
ctx := requestctx.WithLanguage(r.Context(), lang)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
// LanguageWithDefault 语言处理中间件（可自定义默认语言）
// defaultLanguage: 默认语言，如果未指定则使用 zh-CN
func LanguageWithDefault(defaultLanguage string) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 1. 优先从 X-Language 请求头获取（显式指定）
lang := r.Header.Get(LanguageHeaderName)
// 2. 如果未设置，从 Accept-Language 请求头解析
if lang == "" {
acceptLang := r.Header.Get(AcceptLanguageHeaderName)
if acceptLang != "" {
lang = parseAcceptLanguage(acceptLang)
}
}
// 3. 如果都未设置，使用指定的默认语言
if lang == "" {
lang = defaultLanguage
}
ctx := requestctx.WithLanguage(r.Context(), lang)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
}
// parseAcceptLanguage 解析 Accept-Language 请求头
// 返回第一个语言代码（去掉权重信息）
func parseAcceptLanguage(acceptLang string) string {
if acceptLang == "" {
return ""
}
// 分割语言列表
parts := strings.Split(acceptLang, ",")
if len(parts) == 0 {
return ""
}
// 取第一个语言代码，去掉权重信息（如 ";q=0.9"）
firstLang := strings.Split(parts[0], ";")[0]
firstLang = strings.TrimSpace(firstLang)
return firstLang
}

66
middleware/logging.go Normal file
View File

@@ -0,0 +1,66 @@
package middleware
import (
"net/http"
"time"
"git.toowon.com/jimmy/go-common/logger"
)
// responseWriter 包装 ResponseWriter 以捕获状态码
type responseWriter struct {
http.ResponseWriter
statusCode int
}
func (rw *responseWriter) WriteHeader(statusCode int) {
rw.statusCode = statusCode
rw.ResponseWriter.WriteHeader(statusCode)
}
// LoggingConfig 日志中间件配置
type LoggingConfig struct {
Logger *logger.Logger
SkipPaths []string
}
// Logging HTTP 访问日志（固定 Info 级别）
func Logging(config *LoggingConfig) func(http.Handler) http.Handler {
if config == nil {
config = &LoggingConfig{}
}
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if shouldSkipPath(r.URL.Path, config.SkipPaths) {
next.ServeHTTP(w, r)
return
}
start := time.Now()
rw := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK}
next.ServeHTTP(rw, r)
fields := map[string]any{
"method": r.Method,
"path": r.URL.Path,
"duration": time.Since(start).Milliseconds(),
}
log := logger.FromContext(r.Context())
if config.Logger != nil {
log = logger.FromContextWithLogger(r.Context(), config.Logger)
}
log.Info("HTTP Request", fields)
})
}
}
func shouldSkipPath(path string, skipPaths []string) bool {
for _, skip := range skipPaths {
if path == skip {
return true
}
}
return false
}

286
middleware/ratelimit.go Normal file
View File

@@ -0,0 +1,286 @@
package middleware
import (
"net/http"
"sync"
"time"
)
// RateLimiter 限流器接口
type RateLimiter interface {
// Allow 检查是否允许请求
// key: 限流键（如IP地址、用户ID等）
// 返回: 是否允许, 剩余配额, 重置时间
Allow(key string) (allowed bool, remaining int, resetTime time.Time)
}
// tokenBucketLimiter 令牌桶限流器
type tokenBucketLimiter struct {
rate int // 每个窗口期允许的请求数
windowSize time.Duration // 窗口大小
buckets map[string]*bucket
mu sync.RWMutex
cleanupTicker *time.Ticker
stopCleanup chan struct{}
}
// bucket 令牌桶
type bucket struct {
tokens int // 当前令牌数
lastRefill time.Time // 上次填充时间
mu sync.Mutex
}
// NewTokenBucketLimiter 创建令牌桶限流器
func NewTokenBucketLimiter(rate int, windowSize time.Duration) RateLimiter {
limiter := &tokenBucketLimiter{
rate: rate,
windowSize: windowSize,
buckets: make(map[string]*bucket),
stopCleanup: make(chan struct{}),
}
// 启动清理goroutine，定期清理过期的bucket
limiter.cleanupTicker = time.NewTicker(windowSize * 2)
go limiter.cleanup()
return limiter
}
// cleanup 定期清理过期的bucket
func (l *tokenBucketLimiter) cleanup() {
for {
select {
case <-l.cleanupTicker.C:
l.mu.Lock()
now := time.Now()
for key, bkt := range l.buckets {
bkt.mu.Lock()
// 如果bucket超过2个窗口期没有使用，删除它
if now.Sub(bkt.lastRefill) > l.windowSize*2 {
delete(l.buckets, key)
}
bkt.mu.Unlock()
}
l.mu.Unlock()
case <-l.stopCleanup:
l.cleanupTicker.Stop()
return
}
}
}
// Allow 检查是否允许请求
func (l *tokenBucketLimiter) Allow(key string) (bool, int, time.Time) {
now := time.Now()
// 获取或创建bucket
l.mu.Lock()
bkt, exists := l.buckets[key]
if !exists {
bkt = &bucket{
tokens: l.rate,
lastRefill: now,
}
l.buckets[key] = bkt
}
l.mu.Unlock()
// 尝试消费令牌
bkt.mu.Lock()
defer bkt.mu.Unlock()
// 计算需要填充的令牌数
elapsed := now.Sub(bkt.lastRefill)
if elapsed >= l.windowSize {
// 窗口期已过，重新填充
bkt.tokens = l.rate
bkt.lastRefill = now
}
// 检查是否有可用令牌
if bkt.tokens > 0 {
bkt.tokens--
resetTime := bkt.lastRefill.Add(l.windowSize)
return true, bkt.tokens, resetTime
}
// 没有可用令牌
resetTime := bkt.lastRefill.Add(l.windowSize)
return false, 0, resetTime
}
// RateLimitConfig 限流中间件配置
type RateLimitConfig struct {
// Limiter 限流器（必需）
// 如果为nil，会使用默认的令牌桶限流器（100请求/分钟）
Limiter RateLimiter
// KeyFunc 生成限流键的函数（可选）
// 默认使用客户端IP作为键
// 可以自定义为用户ID、API Key等
KeyFunc func(r *http.Request) string
// OnRateLimitExceeded 当限流被触发时的回调（可选）
// 可以用于记录日志、发送告警等
OnRateLimitExceeded func(w http.ResponseWriter, r *http.Request, key string)
}
// RateLimit 限流中间件
// 实现基于令牌桶算法的请求限流
//
// 使用方式1：使用默认配置（100请求/分钟，按IP限流）
//
// chain := middleware.NewChain(
// middleware.RateLimit(nil),
// )
//
// 使用方式2：自定义限流规则
//
// limiter := middleware.NewTokenBucketLimiter(10, time.Minute) // 10请求/分钟
// chain := middleware.NewChain(
// middleware.RateLimit(&middleware.RateLimitConfig{
// Limiter: limiter,
// }),
// )
//
// 使用方式3：按用户ID限流
//
// chain := middleware.NewChain(
// middleware.RateLimit(&middleware.RateLimitConfig{
// Limiter: limiter,
// KeyFunc: func(r *http.Request) string {
// // 从请求头或token中获取用户ID
// return r.Header.Get("X-User-ID")
// },
// }),
// )
func RateLimit(config *RateLimitConfig) func(http.Handler) http.Handler {
// 如果没有配置，使用默认配置
if config == nil {
config = &RateLimitConfig{}
}
// 如果没有提供限流器，创建默认的（100请求/分钟）
if config.Limiter == nil {
config.Limiter = NewTokenBucketLimiter(100, time.Minute)
}
// 如果没有提供KeyFunc，使用默认的（客户端IP）
if config.KeyFunc == nil {
config.KeyFunc = func(r *http.Request) string {
return GetClientIP(r)
}
}
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 生成限流键
key := config.KeyFunc(r)
if key == "" {
// 如果无法生成键，允许请求通过
next.ServeHTTP(w, r)
return
}
// 检查是否允许请求
allowed, remaining, resetTime := config.Limiter.Allow(key)
// 设置限流相关的响应头
w.Header().Set("X-RateLimit-Limit", formatInt(config.Limiter.(*tokenBucketLimiter).rate))
w.Header().Set("X-RateLimit-Remaining", formatInt(remaining))
w.Header().Set("X-RateLimit-Reset", formatInt64(resetTime.Unix()))
if !allowed {
// 触发限流回调
if config.OnRateLimitExceeded != nil {
config.OnRateLimitExceeded(w, r, key)
}
// 返回429错误
w.Header().Set("Retry-After", formatInt64(int64(time.Until(resetTime).Seconds())))
http.Error(w, "Too Many Requests", http.StatusTooManyRequests)
return
}
// 允许请求通过
next.ServeHTTP(w, r)
})
}
}
// RateLimitWithRate 使用指定速率创建限流中间件（便捷函数）
// rate: 每个窗口期允许的请求数
// windowSize: 窗口大小
func RateLimitWithRate(rate int, windowSize time.Duration) func(http.Handler) http.Handler {
return RateLimit(&RateLimitConfig{
Limiter: NewTokenBucketLimiter(rate, windowSize),
})
}
// RateLimitByIP 按IP限流（便捷函数）
func RateLimitByIP(rate int, windowSize time.Duration) func(http.Handler) http.Handler {
return RateLimit(&RateLimitConfig{
Limiter: NewTokenBucketLimiter(rate, windowSize),
KeyFunc: func(r *http.Request) string {
return GetClientIP(r)
},
})
}
// formatInt 格式化int为字符串
func formatInt(n int) string {
if n == 0 {
return "0"
}
// 简单的int转字符串
var buf [20]byte
i := len(buf) - 1
negative := n < 0
if negative {
n = -n
}
for n > 0 {
buf[i] = byte('0' + n%10)
n /= 10
i--
}
if negative {
buf[i] = '-'
i--
}
return string(buf[i+1:])
}
// formatInt64 格式化int64为字符串
func formatInt64(n int64) string {
if n == 0 {
return "0"
}
// 简单的int64转字符串
var buf [20]byte
i := len(buf) - 1
negative := n < 0
if negative {
n = -n
}
for n > 0 {
buf[i] = byte('0' + n%10)
n /= 10
i--
}
if negative {
buf[i] = '-'
i--
}
return string(buf[i+1:])
}

47
middleware/recovery.go Normal file
View File

@@ -0,0 +1,47 @@
package middleware
import (
"fmt"
"net/http"
"runtime/debug"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/i18n"
"git.toowon.com/jimmy/go-common/logger"
)
// RecoveryConfig Recovery 中间件配置
type RecoveryConfig struct {
Logger *logger.Logger
I18n *i18n.I18n
}
// Recovery Panic 恢复中间件，响应统一 JSON 200 + system.internal_error
func Recovery(config *RecoveryConfig) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if err := recover(); err != nil {
fields := map[string]any{
"method": r.Method,
"path": r.URL.Path,
"error": fmt.Sprintf("%v", err),
"stack": string(debug.Stack()),
}
log := logger.FromContextWithLogger(r.Context(), nil)
if config != nil && config.Logger != nil {
log = logger.FromContextWithLogger(r.Context(), config.Logger)
}
log.Error("panic recovered", fields)
h := commonhttp.NewHandler(w, r)
if config != nil && config.I18n != nil {
h = commonhttp.NewHandler(w, r, commonhttp.WithI18n(config.I18n))
}
h.Error("system.internal_error")
}
}()
next.ServeHTTP(w, r)
})
}
}

23
middleware/requestid.go Normal file
View File

@@ -0,0 +1,23 @@
package middleware
import (
"net/http"
"git.toowon.com/jimmy/go-common/logger"
"github.com/google/uuid"
)
// RequestID 为每个请求生成或透传 Request ID，写入 context 与响应头
func RequestID() func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
id := r.Header.Get("X-Request-ID")
if id == "" {
id = uuid.NewString()
}
w.Header().Set("X-Request-ID", id)
ctx := logger.WithRequestID(r.Context(), id)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
}

54
middleware/timezone.go
View File

@@ -4,79 +4,49 @@ import (
"context"
"net/http"
"git.toowon.com/jimmy/go-common/datetime"
"git.toowon.com/jimmy/go-common/requestctx"
"git.toowon.com/jimmy/go-common/tools"
)
// TimezoneKey context中存储时区的key
type timezoneKey struct{}
// TimezoneHeaderName 时区请求头名称
const TimezoneHeaderName = "X-Timezone"
// DefaultTimezone 默认时区
const DefaultTimezone = datetime.AsiaShanghai
// GetTimezoneFromContext 从context中获取时区
// GetTimezoneFromContext 从 context 中获取时区
func GetTimezoneFromContext(ctx context.Context) string {
if tz, ok := ctx.Value(timezoneKey{}).(string); ok && tz != "" {
return tz
}
return DefaultTimezone
return requestctx.Timezone(ctx)
}
// Timezone 时区处理中间件
// 从请求头 X-Timezone 读取时区信息，如果未传递则使用默认时区 AsiaShanghai
// 时区信息会存储到context中，可以通过 GetTimezoneFromContext 获取
func Timezone(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 从请求头获取时区
timezone := r.Header.Get(TimezoneHeaderName)
// 如果未传递时区信息，使用默认时区
if timezone == "" {
timezone = DefaultTimezone
timezone = requestctx.DefaultTimezone
}
// 验证时区是否有效
if _, err := datetime.GetLocation(timezone); err != nil {
// 如果时区无效，使用默认时区
timezone = DefaultTimezone
if _, err := tools.GetLocation(timezone); err != nil {
timezone = requestctx.DefaultTimezone
}
// 将时区存储到context中
ctx := context.WithValue(r.Context(), timezoneKey{}, timezone)
ctx := requestctx.WithTimezone(r.Context(), timezone)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
// TimezoneWithDefault 时区处理中间件（可自定义默认时区）
// defaultTimezone: 默认时区，如果未指定则使用 AsiaShanghai
func TimezoneWithDefault(defaultTimezone string) func(http.Handler) http.Handler {
// 验证默认时区是否有效
if _, err := datetime.GetLocation(defaultTimezone); err != nil {
defaultTimezone = DefaultTimezone
if _, err := tools.GetLocation(defaultTimezone); err != nil {
defaultTimezone = requestctx.DefaultTimezone
}
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 从请求头获取时区
timezone := r.Header.Get(TimezoneHeaderName)
// 如果未传递时区信息，使用指定的默认时区
if timezone == "" {
timezone = defaultTimezone
}
// 验证时区是否有效
if _, err := datetime.GetLocation(timezone); err != nil {
// 如果时区无效，使用默认时区
if _, err := tools.GetLocation(timezone); err != nil {
timezone = defaultTimezone
}
// 将时区存储到context中
ctx := context.WithValue(r.Context(), timezoneKey{}, timezone)
ctx := requestctx.WithTimezone(r.Context(), timezone)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
}

222
migration/helper.go Normal file
View File

@@ -0,0 +1,222 @@
package migration
import (
"fmt"
"os"
"time"
"git.toowon.com/jimmy/go-common/config"
"gorm.io/driver/mysql"
"gorm.io/driver/postgres"
"gorm.io/driver/sqlite"
"gorm.io/gorm"
)
// RunMigrationsFromConfig 从配置文件运行迁移（便捷方法）
//
// 注意：推荐使用独立的迁移工具（templates/migrate/main.go），而不是在应用代码中直接调用。
// 独立工具可以实现零耦合、独立部署。
//
// 此方法主要用于：
// 1. 独立迁移工具内部调用（推荐）
// 2. 简单场景下在应用启动时调用（不推荐，会导致耦合）
//
// 用法：
//
// import "git.toowon.com/jimmy/go-common/migration"
// migration.RunMigrationsFromConfig("config.json", "migrations")
// // 或使用默认迁移目录
// migration.RunMigrationsFromConfig("config.json", "")
func RunMigrationsFromConfig(configFile, migrationsDir string) error {
return RunMigrationsFromConfigWithCommand(configFile, migrationsDir, "up")
}
// RunMigrationsFromConfigWithCommand 从配置文件运行迁移（支持命令，黑盒模式）
//
// 这是最简单的迁移方式，内部自动处理：
// - 配置加载（支持配置文件、默认路径）
// - 数据库连接（自动识别数据库类型）
// - 迁移文件加载和执行
//
// 参数：
// - configFile: 配置文件路径，支持：
// - 空字符串：自动查找（config.json, ../config.json）
// - 相对路径或绝对路径：指定配置文件路径
// - migrationsDir: 迁移文件目录，支持：
// - 空字符串：使用默认目录 "migrations"
// - 相对路径或绝对路径
// - command: 命令，支持 "up", "down", "status"
//
// 使用示例：
//
// // 最简单：使用默认配置和默认迁移目录
// migration.RunMigrationsFromConfigWithCommand("", "", "up")
//
// // 指定配置文件，使用默认迁移目录
// migration.RunMigrationsFromConfigWithCommand("config.json", "", "up")
//
// // 指定配置和迁移目录
// migration.RunMigrationsFromConfigWithCommand("config.json", "scripts/sql", "up")
func RunMigrationsFromConfigWithCommand(configFile, migrationsDir, command string) error {
// 加载配置
cfg, err := loadConfigFromFileOrEnv(configFile)
if err != nil {
return fmt.Errorf("加载配置失败: %w", err)
}
// 连接数据库
db, err := connectDB(cfg)
if err != nil {
return fmt.Errorf("连接数据库失败: %w", err)
}
// 使用默认迁移目录（如果未指定）
if migrationsDir == "" {
migrationsDir = "migrations"
}
// 创建迁移器（传入数据库类型，性能更好）
migrator := NewMigratorWithType(db, cfg.Database.Type)
// 加载迁移文件
migrations, err := LoadMigrationsFromFiles(migrationsDir, "*.sql")
if err != nil {
return fmt.Errorf("加载迁移文件失败: %w", err)
}
if len(migrations) == 0 {
fmt.Printf("在目录 '%s' 中没有找到迁移文件\n", migrationsDir)
return nil
}
migrator.AddMigrations(migrations...)
// 执行命令
switch command {
case "up":
if err := migrator.Up(); err != nil {
return fmt.Errorf("执行迁移失败: %w", err)
}
fmt.Println("✓ 迁移执行成功")
case "down":
if err := migrator.Down(); err != nil {
return fmt.Errorf("回滚迁移失败: %w", err)
}
fmt.Println("✓ 迁移回滚成功")
case "status":
status, err := migrator.Status()
if err != nil {
return fmt.Errorf("获取迁移状态失败: %w", err)
}
printMigrationStatus(status)
default:
return fmt.Errorf("未知命令: %s (支持: up, down, status)", command)
}
return nil
}
// loadConfigFromFileOrEnv 从配置文件加载配置
// 支持指定配置文件路径，或自动查找默认路径
func loadConfigFromFileOrEnv(configFile string) (*config.Config, error) {
// 如果指定了配置文件路径，优先使用
if configFile != "" {
if _, err := os.Stat(configFile); err == nil {
return config.LoadFromFile(configFile)
}
// 如果指定的文件不存在，返回错误
return nil, fmt.Errorf("配置文件不存在: %s", configFile)
}
// 尝试默认路径
defaultPaths := []string{"config.json", "../config.json"}
for _, path := range defaultPaths {
if _, err := os.Stat(path); err == nil {
return config.LoadFromFile(path)
}
}
return nil, fmt.Errorf("未找到配置文件，请指定配置文件路径或确保存在以下文件之一: %v", defaultPaths)
}
// connectDB 连接数据库
// 与 factory.getDatabase 保持一致的实现，避免代码重复
func connectDB(cfg *config.Config) (*gorm.DB, error) {
if cfg.Database == nil {
return nil, fmt.Errorf("数据库配置为空")
}
dsn, err := cfg.GetDatabaseDSN()
if err != nil {
return nil, err
}
var db *gorm.DB
switch cfg.Database.Type {
case "mysql":
db, err = gorm.Open(mysql.Open(dsn), &gorm.Config{})
case "postgres":
db, err = gorm.Open(postgres.Open(dsn), &gorm.Config{})
case "sqlite":
db, err = gorm.Open(sqlite.Open(dsn), &gorm.Config{})
default:
return nil, fmt.Errorf("不支持的数据库类型: %s", cfg.Database.Type)
}
if err != nil {
return nil, err
}
// 配置连接池（与 factory.getDatabase 保持一致）
sqlDB, err := db.DB()
if err != nil {
return nil, err
}
// 使用配置文件中的连接池参数，如果没有配置则使用默认值
if cfg.Database.MaxOpenConns > 0 {
sqlDB.SetMaxOpenConns(cfg.Database.MaxOpenConns)
} else {
sqlDB.SetMaxOpenConns(10) // 默认值
}
if cfg.Database.MaxIdleConns > 0 {
sqlDB.SetMaxIdleConns(cfg.Database.MaxIdleConns)
} else {
sqlDB.SetMaxIdleConns(5) // 默认值
}
if cfg.Database.ConnMaxLifetime > 0 {
sqlDB.SetConnMaxLifetime(time.Duration(cfg.Database.ConnMaxLifetime) * time.Second)
} else {
sqlDB.SetConnMaxLifetime(time.Hour) // 默认值
}
return db, nil
}
// printMigrationStatus 打印迁移状态
func printMigrationStatus(status []MigrationStatus) {
if len(status) == 0 {
fmt.Println("没有找到迁移")
return
}
fmt.Println("\n迁移状态:")
fmt.Println("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
fmt.Printf("%-20s %-40s %-10s\n", "版本", "描述", "状态")
fmt.Println("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
for _, s := range status {
statusText := "待执行"
if s.Applied {
statusText = "✓ 已应用"
}
fmt.Printf("%-20s %-40s %-10s\n", s.Version, s.Description, statusText)
}
fmt.Println("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━")
fmt.Println()
}

376
migration/migration.go
View File

@@ -26,6 +26,7 @@ type Migrator struct {
db *gorm.DB
migrations []Migration
tableName string
dbType string // 数据库类型: mysql, postgres, sqlite
}
// NewMigrator 创建新的迁移器
@@ -41,6 +42,25 @@ func NewMigrator(db *gorm.DB, tableName ...string) *Migrator {
db: db,
migrations: make([]Migration, 0),
tableName: table,
dbType: "", // 未指定时为空，会使用兼容模式
}
}
// NewMigratorWithType 创建新的迁移器（指定数据库类型，性能更好）
// db: GORM数据库连接
// dbType: 数据库类型 ("mysql", "postgres", "sqlite")
// tableName: 存储迁移记录的表名，默认为 "schema_migrations"
func NewMigratorWithType(db *gorm.DB, dbType string, tableName ...string) *Migrator {
table := "schema_migrations"
if len(tableName) > 0 && tableName[0] != "" {
table = tableName[0]
}
return &Migrator{
db: db,
migrations: make([]Migration, 0),
tableName: table,
dbType: dbType,
}
}
@@ -56,33 +76,152 @@ func (m *Migrator) AddMigrations(migrations ...Migration) {
// initTable 初始化迁移记录表
func (m *Migrator) initTable() error {
// 检查表是否存在
// 检查表是否存在（根据数据库类型使用对应的SQL，性能更好）
var exists bool
err := m.db.Raw(fmt.Sprintf(`
var err error
switch m.dbType {
case "mysql":
// MySQL/MariaDB语法
var count int64
err = m.db.Raw(fmt.Sprintf(`
SELECT COUNT(*) FROM information_schema.tables
WHERE table_schema = DATABASE()
AND table_name = '%s'
`, m.tableName)).Scan(&count).Error
if err == nil {
exists = count > 0
}
case "postgres":
// PostgreSQL语法
err = m.db.Raw(fmt.Sprintf(`
SELECT EXISTS (
SELECT FROM information_schema.tables
SELECT 1 FROM information_schema.tables
WHERE table_schema = CURRENT_SCHEMA()
AND table_name = '%s'
)
`, m.tableName)).Scan(&exists).Error
case "sqlite":
// SQLite语法
var count int64
err = m.db.Raw(fmt.Sprintf(`
SELECT COUNT(*) FROM sqlite_master
WHERE type='table' AND name='%s'
`, m.tableName)).Scan(&count).Error
if err == nil {
exists = count > 0
}
default:
// 未指定数据库类型时，使用兼容模式（向后兼容）
// 按顺序尝试不同数据库的语法
var count int64
err = m.db.Raw(fmt.Sprintf(`
SELECT COUNT(*) FROM information_schema.tables
WHERE table_schema = DATABASE()
AND table_name = '%s'
`, m.tableName)).Scan(&count).Error
if err == nil && count > 0 {
exists = true
} else {
var pgExists bool
err = m.db.Raw(fmt.Sprintf(`
SELECT EXISTS (
SELECT 1 FROM information_schema.tables
WHERE table_schema = CURRENT_SCHEMA()
AND table_name = '%s'
)
`, m.tableName)).Scan(&pgExists).Error
if err == nil {
exists = pgExists
} else {
var sqliteCount int64
err = m.db.Raw(fmt.Sprintf(`
SELECT COUNT(*) FROM sqlite_master
WHERE type='table' AND name='%s'
`, m.tableName)).Scan(&sqliteCount).Error
if err == nil && sqliteCount > 0 {
exists = true
}
}
}
}
// 如果查询失败，假设表不存在，尝试创建
if err != nil {
// 如果查询失败，可能是SQLite或其他数据库，尝试直接创建
exists = false
}
if !exists {
// 创建迁移记录表
// 创建迁移记录表（包含执行时间字段）
err = m.db.Exec(fmt.Sprintf(`
CREATE TABLE IF NOT EXISTS %s (
version VARCHAR(255) PRIMARY KEY,
description VARCHAR(255),
applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
execution_time INT COMMENT '执行耗时(ms)'
)
`, m.tableName)).Error
if err != nil {
return fmt.Errorf("failed to create migration table: %w", err)
}
} else {
// 表已存在，检查是否有 execution_time 字段（向后兼容）
// 注意：这个检查可能在某些数据库中失败，但不影响功能
// 如果字段不存在，记录执行时间时会失败，但不影响迁移执行
var hasExecutionTime bool
var columnCount int64
var checkErr error
switch m.dbType {
case "mysql":
// MySQL/MariaDB语法
checkErr = m.db.Raw(fmt.Sprintf(`
SELECT COUNT(*)
FROM information_schema.columns
WHERE table_schema = DATABASE()
AND table_name = '%s'
AND column_name = 'execution_time'
`, m.tableName)).Scan(&columnCount).Error
if checkErr == nil {
hasExecutionTime = columnCount > 0
}
case "postgres":
// PostgreSQL语法
checkErr = m.db.Raw(fmt.Sprintf(`
SELECT COUNT(*)
FROM information_schema.columns
WHERE table_schema = CURRENT_SCHEMA()
AND table_name = '%s'
AND column_name = 'execution_time'
`, m.tableName)).Scan(&columnCount).Error
if checkErr == nil {
hasExecutionTime = columnCount > 0
}
case "sqlite":
// SQLite不支持information_schema，跳过检查
hasExecutionTime = false
default:
// 兼容模式：尝试MySQL语法
checkErr = m.db.Raw(fmt.Sprintf(`
SELECT COUNT(*)
FROM information_schema.columns
WHERE table_schema = DATABASE()
AND table_name = '%s'
AND column_name = 'execution_time'
`, m.tableName)).Scan(&columnCount).Error
if checkErr == nil {
hasExecutionTime = columnCount > 0
}
}
if !hasExecutionTime {
// 尝试添加字段（如果失败不影响功能）
// 注意：SQLite的ALTER TABLE ADD COLUMN语法略有不同，但GORM会处理
_ = m.db.Exec(fmt.Sprintf(`
ALTER TABLE %s
ADD COLUMN execution_time INT
`, m.tableName))
}
}
return nil
@@ -109,17 +248,34 @@ func (m *Migrator) getAppliedMigrations() (map[string]bool, error) {
}
// recordMigration 记录迁移
func (m *Migrator) recordMigration(version, description string, isUp bool) error {
func (m *Migrator) recordMigration(version, description string, isUp bool, executionTime ...int) error {
if err := m.initTable(); err != nil {
return err
}
if isUp {
// 记录迁移
err := m.db.Exec(fmt.Sprintf(`
// 记录迁移（包含执行时间，如果提供了）
var err error
if len(executionTime) > 0 && executionTime[0] > 0 {
// 尝试插入执行时间（如果字段存在）
err = m.db.Exec(fmt.Sprintf(`
INSERT INTO %s (version, description, applied_at, execution_time)
VALUES (?, ?, ?, ?)
`, m.tableName), version, description, time.Now(), executionTime[0]).Error
if err != nil {
// 如果失败（可能是字段不存在），尝试不包含执行时间
err = m.db.Exec(fmt.Sprintf(`
INSERT INTO %s (version, description, applied_at)
VALUES (?, ?, ?)
`, m.tableName), version, description, time.Now()).Error
}
} else {
// 不包含执行时间
err = m.db.Exec(fmt.Sprintf(`
INSERT INTO %s (version, description, applied_at)
VALUES (?, ?, ?)
`, m.tableName), version, description, time.Now()).Error
}
if err != nil {
return fmt.Errorf("failed to record migration: %w", err)
}
@@ -160,6 +316,9 @@ func (m *Migrator) Up() error {
return fmt.Errorf("migration %s has no Up function", migration.Version)
}
// 记录开始时间
startTime := time.Now()
// 开始事务
tx := m.db.Begin()
if tx.Error != nil {
@@ -172,8 +331,11 @@ func (m *Migrator) Up() error {
return fmt.Errorf("failed to apply migration %s: %w", migration.Version, err)
}
// 记录迁移
if err := m.recordMigrationWithDB(tx, migration.Version, migration.Description, true); err != nil {
// 计算执行时间（毫秒）
executionTime := int(time.Since(startTime).Milliseconds())
// 记录迁移（包含执行时间）
if err := m.recordMigrationWithDB(tx, migration.Version, migration.Description, true, executionTime); err != nil {
tx.Rollback()
return err
}
@@ -183,7 +345,7 @@ func (m *Migrator) Up() error {
return fmt.Errorf("failed to commit migration %s: %w", migration.Version, err)
}
fmt.Printf("Applied migration: %s - %s\n", migration.Version, migration.Description)
fmt.Printf("Applied migration: %s - %s (耗时: %dms)\n", migration.Version, migration.Description, executionTime)
}
return nil
@@ -246,12 +408,29 @@ func (m *Migrator) Down() error {
}
// recordMigrationWithDB 使用指定的数据库连接记录迁移
func (m *Migrator) recordMigrationWithDB(db *gorm.DB, version, description string, isUp bool) error {
func (m *Migrator) recordMigrationWithDB(db *gorm.DB, version, description string, isUp bool, executionTime ...int) error {
if isUp {
err := db.Exec(fmt.Sprintf(`
var err error
if len(executionTime) > 0 && executionTime[0] > 0 {
// 尝试插入执行时间（如果字段存在）
err = db.Exec(fmt.Sprintf(`
INSERT INTO %s (version, description, applied_at, execution_time)
VALUES (?, ?, ?, ?)
`, m.tableName), version, description, time.Now(), executionTime[0]).Error
if err != nil {
// 如果失败（可能是字段不存在），尝试不包含执行时间
err = db.Exec(fmt.Sprintf(`
INSERT INTO %s (version, description, applied_at)
VALUES (?, ?, ?)
`, m.tableName), version, description, time.Now()).Error
}
} else {
// 不包含执行时间
err = db.Exec(fmt.Sprintf(`
INSERT INTO %s (version, description, applied_at)
VALUES (?, ?, ?)
`, m.tableName), version, description, time.Now()).Error
}
if err != nil {
return fmt.Errorf("failed to record migration: %w", err)
}
@@ -300,10 +479,96 @@ type MigrationStatus struct {
Applied bool
}
// splitSQL 分割SQL语句，处理多行SQL、注释等
// 支持单行注释（--）、多行注释（/* */）、按分号分割语句
func splitSQL(content string) []string {
var statements []string
var current strings.Builder
lines := strings.Split(content, "\n")
inMultiLineComment := false
for _, line := range lines {
trimmedLine := strings.TrimSpace(line)
// 跳过空行
if trimmedLine == "" {
continue
}
// 处理多行注释
if strings.HasPrefix(trimmedLine, "/*") {
inMultiLineComment = true
}
if strings.HasSuffix(trimmedLine, "*/") {
inMultiLineComment = false
continue
}
if inMultiLineComment {
continue
}
// 跳过单行注释
if strings.HasPrefix(trimmedLine, "--") {
continue
}
// 添加到当前语句
current.WriteString(line)
current.WriteString("\n")
// 检查是否是完整语句（以分号结尾）
if strings.HasSuffix(trimmedLine, ";") {
stmt := strings.TrimSpace(current.String())
if stmt != "" && !strings.HasPrefix(stmt, "--") {
statements = append(statements, stmt)
}
current.Reset()
}
}
// 添加最后一个语句（如果没有分号结尾）
if current.Len() > 0 {
stmt := strings.TrimSpace(current.String())
if stmt != "" && !strings.HasPrefix(stmt, "--") {
statements = append(statements, stmt)
}
}
return statements
}
// parseMigrationFileName 解析迁移文件名，支持多种格式
// 格式1: 数字前缀 - 01_init_schema.sql
// 格式2: 时间戳 - 20240101000001_create_users.sql
// 格式3: 带.up后缀 - 20240101000001_create_users.up.sql
// 返回: (version, description, error)
func parseMigrationFileName(baseName string) (string, string, error) {
// 移除扩展名
nameWithoutExt := strings.TrimSuffix(baseName, filepath.Ext(baseName))
// 移除 .up 后缀（如果存在）
nameWithoutExt = strings.TrimSuffix(nameWithoutExt, ".up")
// 解析版本号和描述
parts := strings.SplitN(nameWithoutExt, "_", 2)
if len(parts) < 2 {
// 如果只有一个部分，尝试作为版本号（向后兼容）
return nameWithoutExt, baseName, nil
}
version := parts[0]
description := strings.Join(parts[1:], "_")
return version, description, nil
}
// LoadMigrationsFromFiles 从文件系统加载迁移文件
// dir: 迁移文件目录
// pattern: 文件命名模式，例如 "*.sql" 或 "*.up.sql"
// 文件命名格式: {version}_{description}.sql 或 {version}_{description}.up.sql
// 文件命名格式支持:
// - 数字前缀: 01_init_schema.sql
// - 时间戳: 20240101000001_create_users.sql
// - 带.up后缀: 20240101000001_create_users.up.sql
func LoadMigrationsFromFiles(dir string, pattern string) ([]Migration, error) {
files, err := filepath.Glob(filepath.Join(dir, pattern))
if err != nil {
@@ -313,19 +578,17 @@ func LoadMigrationsFromFiles(dir string, pattern string) ([]Migration, error) {
migrations := make([]Migration, 0)
for _, file := range files {
baseName := filepath.Base(file)
// 移除扩展名
nameWithoutExt := strings.TrimSuffix(baseName, filepath.Ext(baseName))
// 移除 .up 后缀（如果存在）
nameWithoutExt = strings.TrimSuffix(nameWithoutExt, ".up")
// 解析版本号和描述
parts := strings.SplitN(nameWithoutExt, "_", 2)
if len(parts) < 2 {
return nil, fmt.Errorf("invalid migration file name format: %s (expected: {version}_{description})", baseName)
// 跳过 .down.sql 文件（会在处理 .up.sql 或 .sql 时自动加载）
if strings.HasSuffix(baseName, ".down.sql") {
continue
}
version := parts[0]
description := strings.Join(parts[1:], "_")
// 解析版本号和描述
version, description, err := parseMigrationFileName(baseName)
if err != nil {
return nil, fmt.Errorf("invalid migration file name format: %s: %w", baseName, err)
}
// 读取文件内容
content, err := os.ReadFile(file)
@@ -343,26 +606,81 @@ func LoadMigrationsFromFiles(dir string, pattern string) ([]Migration, error) {
downSQL = string(downContent)
}
// 创建迁移，使用 SQL 分割功能
migration := Migration{
Version: version,
Description: description,
Up: func(db *gorm.DB) error {
return db.Exec(sqlContent).Error
// 分割 SQL 语句
statements := splitSQL(sqlContent)
if len(statements) == 0 {
return nil // 空文件，跳过
}
// 执行每个 SQL 语句
// 注意：某些 DDL 语句（如 CREATE TABLE）在某些数据库中会隐式提交事务
// 因此这里不使用事务，而是逐个执行
for i, stmt := range statements {
stmt = strings.TrimSpace(stmt)
if stmt == "" {
continue
}
if err := db.Exec(stmt).Error; err != nil {
// 如果是表已存在的错误，记录警告但继续执行（向后兼容）
errStr := err.Error()
if strings.Contains(errStr, "already exists") ||
strings.Contains(errStr, "Duplicate") ||
strings.Contains(errStr, "duplicate") {
fmt.Printf("Warning: SQL statement %d in migration %s: %v\n", i+1, version, err)
continue
}
return fmt.Errorf("failed to execute SQL statement %d in migration %s: %w\nSQL: %s", i+1, version, err, stmt)
}
}
return nil
},
}
if downSQL != "" {
migration.Down = func(db *gorm.DB) error {
return db.Exec(downSQL).Error
// 分割 SQL 语句
statements := splitSQL(downSQL)
if len(statements) == 0 {
return nil
}
// 执行每个 SQL 语句
for i, stmt := range statements {
stmt = strings.TrimSpace(stmt)
if stmt == "" {
continue
}
if err := db.Exec(stmt).Error; err != nil {
return fmt.Errorf("failed to execute SQL statement %d in rollback %s: %w\nSQL: %s", i+1, version, err, stmt)
}
}
return nil
}
}
migrations = append(migrations, migration)
}
// 按版本号排序
// 按版本号排序（支持数字和时间戳混合排序）
sort.Slice(migrations, func(i, j int) bool {
return migrations[i].Version < migrations[j].Version
vi, vj := migrations[i].Version, migrations[j].Version
// 尝试按数字排序（如果是数字前缀）
if viNum, err1 := strconv.Atoi(vi); err1 == nil {
if vjNum, err2 := strconv.Atoi(vj); err2 == nil {
return viNum < vjNum
}
}
// 否则按字符串排序
return vi < vj
})
return migrations, nil

41
requestctx/requestctx.go Normal file
View File

@@ -0,0 +1,41 @@
package requestctx
import (
"context"
"git.toowon.com/jimmy/go-common/tools"
)
type languageKey struct{}
type timezoneKey struct{}
const (
DefaultLanguage = "zh-CN"
DefaultTimezone = tools.AsiaShanghai
)
// WithLanguage 写入语言到 context
func WithLanguage(ctx context.Context, lang string) context.Context {
return context.WithValue(ctx, languageKey{}, lang)
}
// Language 从 context 读取语言
func Language(ctx context.Context) string {
if lang, ok := ctx.Value(languageKey{}).(string); ok && lang != "" {
return lang
}
return DefaultLanguage
}
// WithTimezone 写入时区到 context
func WithTimezone(ctx context.Context, tz string) context.Context {
return context.WithValue(ctx, timezoneKey{}, tz)
}
// Timezone 从 context 读取时区
func Timezone(ctx context.Context) string {
if tz, ok := ctx.Value(timezoneKey{}).(string); ok && tz != "" {
return tz
}
return DefaultTimezone
}

401
sms/sms.go
View File

@@ -1,6 +1,7 @@
package sms
import (
"context"
"crypto/hmac"
"crypto/sha1"
"encoding/base64"
@@ -11,210 +12,128 @@ import (
"net/url"
"sort"
"strings"
"sync"
"sync/atomic"
"time"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/logger"
)
// SendResponse 发送短信响应
type SendResponse struct {
RequestID string `json:"RequestId"`
Code string `json:"Code"`
Message string `json:"Message"`
BizID string `json:"BizId"`
}
// SMS 短信发送器
type SMS struct {
config *config.SMSConfig
async bool
queue chan smsTask
workers int
wg sync.WaitGroup
closed bool
mu sync.Mutex
dropped atomic.Uint64
}
type smsTask struct {
phones []string
templateParam interface{}
templateCode string
requestID string
}
// NewSMS 创建短信发送器
func NewSMS(cfg *config.SMSConfig) (*SMS, error) {
if cfg == nil {
func NewSMS(cfg *config.Config) *SMS {
if cfg == nil || cfg.SMS == nil {
return &SMS{config: nil}
}
s := &SMS{
config: cfg.SMS,
async: cfg.SMS.IsAsync(),
workers: cfg.SMS.Workers,
}
if s.workers <= 0 {
s.workers = 2
}
queueSize := cfg.SMS.QueueSize
if queueSize <= 0 {
queueSize = 1000
}
if s.async {
s.queue = make(chan smsTask, queueSize)
for i := 0; i < s.workers; i++ {
s.wg.Add(1)
go s.worker()
}
}
return s
}
func (s *SMS) worker() {
defer s.wg.Done()
for task := range s.queue {
if _, err := s.SendSMS(task.phones, task.templateParam, task.templateCode); err != nil {
logger.FromContext(context.Background()).Error("async sms send failed", map[string]any{
"error": err.Error(),
"request_id": task.requestID,
"phones": task.phones,
})
}
}
}
func (s *SMS) getSMSConfig() (*config.SMSConfig, error) {
if s.config == nil {
return nil, fmt.Errorf("SMS config is nil")
}
if cfg.AccessKeyID == "" {
if s.config.AccessKeyID == "" {
return nil, fmt.Errorf("AccessKeyID is required")
}
if cfg.AccessKeySecret == "" {
if s.config.AccessKeySecret == "" {
return nil, fmt.Errorf("AccessKeySecret is required")
}
if cfg.SignName == "" {
if s.config.SignName == "" {
return nil, fmt.Errorf("SignName is required")
}
// 设置默认值
if cfg.Region == "" {
cfg.Region = "cn-hangzhou"
if s.config.Region == "" {
s.config.Region = "cn-hangzhou"
}
if cfg.Timeout == 0 {
cfg.Timeout = 10
if s.config.Timeout == 0 {
s.config.Timeout = 5
}
return &SMS{
config: cfg,
}, nil
return s.config, nil
}
// SendRequest 发送短信请求
type SendRequest struct {
// PhoneNumbers 手机号列表
PhoneNumbers []string
// TemplateCode 模板代码（如果为空，使用配置中的模板代码）
TemplateCode string
// TemplateParam 模板参数（可以是map或JSON字符串）
// 如果是map，会自动转换为JSON字符串
// 如果是string，直接使用（必须是有效的JSON字符串）
TemplateParam interface{}
// SignName 签名（如果为空，使用配置中的签名）
SignName string
}
// SendResponse 发送短信响应
type SendResponse struct {
// RequestID 请求ID
RequestID string `json:"RequestId"`
// Code 响应码
Code string `json:"Code"`
// Message 响应消息
Message string `json:"Message"`
// BizID 业务ID
BizID string `json:"BizId"`
}
// SendRaw 发送原始请求（允许外部完全控制请求参数）
// params: 请求参数map，工具只负责添加必要的系统参数（如签名、时间戳等）并发送
func (s *SMS) SendRaw(params map[string]string) (*SendResponse, error) {
if params == nil {
params = make(map[string]string)
}
// 确保必要的系统参数存在
if params["Action"] == "" {
params["Action"] = "SendSms"
}
if params["Version"] == "" {
params["Version"] = "2017-05-25"
}
if params["RegionId"] == "" {
params["RegionId"] = s.config.Region
}
if params["AccessKeyId"] == "" {
params["AccessKeyId"] = s.config.AccessKeyID
}
if params["Format"] == "" {
params["Format"] = "JSON"
}
if params["SignatureMethod"] == "" {
params["SignatureMethod"] = "HMAC-SHA1"
}
if params["SignatureVersion"] == "" {
params["SignatureVersion"] = "1.0"
}
if params["SignatureNonce"] == "" {
params["SignatureNonce"] = fmt.Sprint(time.Now().UnixNano())
}
if params["Timestamp"] == "" {
params["Timestamp"] = time.Now().UTC().Format("2006-01-02T15:04:05Z")
}
// 计算签名
signature := s.calculateSignature(params, "POST")
params["Signature"] = signature
// 构建请求URL
endpoint := s.config.Endpoint
if endpoint == "" {
endpoint = "https://dysmsapi.aliyuncs.com"
}
// 发送HTTP请求
formData := url.Values{}
for k, v := range params {
formData.Set(k, v)
}
httpReq, err := http.NewRequest("POST", endpoint, strings.NewReader(formData.Encode()))
// SendSMS 同步发送短信
func (s *SMS) SendSMS(phoneNumbers []string, templateParam interface{}, templateCode ...string) (*SendResponse, error) {
cfg, err := s.getSMSConfig()
if err != nil {
return nil, fmt.Errorf("failed to create request: %w", err)
return nil, err
}
httpReq.Header.Set("Content-Type", "application/x-www-form-urlencoded")
httpReq.Header.Set("Accept", "application/json")
client := &http.Client{
Timeout: time.Duration(s.config.Timeout) * time.Second,
}
resp, err := client.Do(httpReq)
if err != nil {
return nil, fmt.Errorf("failed to send request: %w", err)
}
defer resp.Body.Close()
// 读取响应
body, err := io.ReadAll(resp.Body)
if err != nil {
return nil, fmt.Errorf("failed to read response: %w", err)
}
// 解析响应
var sendResp SendResponse
if err := json.Unmarshal(body, &sendResp); err != nil {
return nil, fmt.Errorf("failed to parse response: %w", err)
}
// 检查响应码
if sendResp.Code != "OK" {
return &sendResp, fmt.Errorf("SMS send failed: Code=%s, Message=%s", sendResp.Code, sendResp.Message)
}
return &sendResp, nil
}
// Send 发送短信（使用SendRequest结构）
// 注意：如果需要完全控制请求参数，请使用SendRaw方法
func (s *SMS) Send(req *SendRequest) (*SendResponse, error) {
if req == nil {
return nil, fmt.Errorf("request is nil")
}
if len(req.PhoneNumbers) == 0 {
if len(phoneNumbers) == 0 {
return nil, fmt.Errorf("phone numbers are required")
}
// 使用配置中的模板代码和签名（如果请求中未指定）
templateCode := req.TemplateCode
if templateCode == "" {
templateCode = s.config.TemplateCode
templateCodeValue := cfg.TemplateCode
if len(templateCode) > 0 && templateCode[0] != "" {
templateCodeValue = templateCode[0]
}
if templateCode == "" {
if templateCodeValue == "" {
return nil, fmt.Errorf("template code is required")
}
signName := req.SignName
if signName == "" {
signName = s.config.SignName
}
// 处理模板参数
var templateParamJSON string
if req.TemplateParam != nil {
switch v := req.TemplateParam.(type) {
if templateParam != nil {
switch v := templateParam.(type) {
case string:
// 直接使用字符串（必须是有效的JSON）
templateParamJSON = v
case map[string]string:
// 转换为JSON字符串
paramBytes, err := json.Marshal(v)
if err != nil {
return nil, fmt.Errorf("failed to marshal template param: %w", err)
}
templateParamJSON = string(paramBytes)
default:
// 尝试JSON序列化
paramBytes, err := json.Marshal(v)
if err != nil {
return nil, fmt.Errorf("failed to marshal template param: %w", err)
@@ -225,66 +144,120 @@ func (s *SMS) Send(req *SendRequest) (*SendResponse, error) {
templateParamJSON = "{}"
}
// 构建请求参数
params := make(map[string]string)
params["PhoneNumbers"] = strings.Join(req.PhoneNumbers, ",")
params["SignName"] = signName
params["TemplateCode"] = templateCode
params["TemplateParam"] = templateParamJSON
params := map[string]string{
"Action": "SendSms",
"Version": "2017-05-25",
"RegionId": cfg.Region,
"AccessKeyId": cfg.AccessKeyID,
"Format": "JSON",
"SignatureMethod": "HMAC-SHA1",
"SignatureVersion": "1.0",
"SignatureNonce": fmt.Sprint(time.Now().UnixNano()),
"Timestamp": time.Now().UTC().Format("2006-01-02T15:04:05Z"),
"PhoneNumbers": strings.Join(phoneNumbers, ","),
"SignName": cfg.SignName,
"TemplateCode": templateCodeValue,
"TemplateParam": templateParamJSON,
}
params["Signature"] = s.calculateSignature(params, "POST", cfg.AccessKeySecret)
// 使用SendRaw发送
return s.SendRaw(params)
endpoint := cfg.Endpoint
if endpoint == "" {
endpoint = "https://dysmsapi.aliyuncs.com"
}
formData := url.Values{}
for k, v := range params {
formData.Set(k, v)
}
httpReq, err := http.NewRequest(http.MethodPost, endpoint, strings.NewReader(formData.Encode()))
if err != nil {
return nil, fmt.Errorf("failed to create request: %w", err)
}
httpReq.Header.Set("Content-Type", "application/x-www-form-urlencoded")
httpReq.Header.Set("Accept", "application/json")
client := &http.Client{Timeout: time.Duration(cfg.Timeout) * time.Second}
resp, err := client.Do(httpReq)
if err != nil {
return nil, fmt.Errorf("failed to send request: %w", err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
return nil, fmt.Errorf("failed to read response: %w", err)
}
var sendResp SendResponse
if err := json.Unmarshal(body, &sendResp); err != nil {
return nil, fmt.Errorf("failed to parse response: %w", err)
}
if sendResp.Code != "OK" {
return &sendResp, fmt.Errorf("SMS send failed: Code=%s, Message=%s", sendResp.Code, sendResp.Message)
}
return &sendResp, nil
}
// calculateSignature 计算签名
func (s *SMS) calculateSignature(params map[string]string, method string) string {
// 对参数进行排序
// SendSMSAsync 异步发送短信
func (s *SMS) SendSMSAsync(ctx context.Context, phoneNumbers []string, templateParam interface{}, templateCode ...string) {
code := ""
if len(templateCode) > 0 {
code = templateCode[0]
}
task := smsTask{
phones: append([]string(nil), phoneNumbers...),
templateParam: templateParam,
templateCode: code,
requestID: logger.RequestIDFromContext(ctx),
}
if !s.async {
_, _ = s.SendSMS(task.phones, task.templateParam, task.templateCode)
return
}
select {
case s.queue <- task:
default:
s.dropped.Add(1)
logger.FromContext(ctx).Error("sms queue full, task dropped", map[string]any{
"phones": phoneNumbers,
})
}
}
// Close 关闭异步 worker
func (s *SMS) Close() error {
if !s.async {
return nil
}
s.mu.Lock()
if s.closed {
s.mu.Unlock()
return nil
}
s.closed = true
s.mu.Unlock()
close(s.queue)
s.wg.Wait()
return nil
}
func (s *SMS) calculateSignature(params map[string]string, method, accessKeySecret string) string {
keys := make([]string, 0, len(params))
for k := range params {
keys = append(keys, k)
}
sort.Strings(keys)
// 构建查询字符串
var queryParts []string
for _, k := range keys {
v := params[k]
// URL编码
encodedKey := url.QueryEscape(k)
encodedValue := url.QueryEscape(v)
queryParts = append(queryParts, encodedKey+"="+encodedValue)
queryParts = append(queryParts, url.QueryEscape(k)+"="+url.QueryEscape(params[k]))
}
queryString := strings.Join(queryParts, "&")
// 构建待签名字符串
stringToSign := method + "&" + url.QueryEscape("/") + "&" + url.QueryEscape(queryString)
// 计算HMAC-SHA1签名
mac := hmac.New(sha1.New, []byte(s.config.AccessKeySecret+"&"))
mac := hmac.New(sha1.New, []byte(accessKeySecret+"&"))
mac.Write([]byte(stringToSign))
signature := base64.StdEncoding.EncodeToString(mac.Sum(nil))
return signature
}
// SendSimple 发送简单短信（便捷方法）
// phoneNumbers: 手机号列表
// templateParam: 模板参数
func (s *SMS) SendSimple(phoneNumbers []string, templateParam map[string]string) (*SendResponse, error) {
return s.Send(&SendRequest{
PhoneNumbers: phoneNumbers,
TemplateParam: templateParam,
})
}
// SendWithTemplate 使用指定模板发送短信（便捷方法）
// phoneNumbers: 手机号列表
// templateCode: 模板代码
// templateParam: 模板参数
func (s *SMS) SendWithTemplate(phoneNumbers []string, templateCode string, templateParam map[string]string) (*SendResponse, error) {
return s.Send(&SendRequest{
PhoneNumbers: phoneNumbers,
TemplateCode: templateCode,
TemplateParam: templateParam,
})
return base64.StdEncoding.EncodeToString(mac.Sum(nil))
}

51
storage/handler.go
View File

@@ -39,39 +39,32 @@ func NewUploadHandler(cfg UploadHandlerConfig) *UploadHandler {
}
// ServeHTTP 处理文件上传请求
// 请求方式: POST
// 表单字段: file (文件)
// 可选字段: prefix (对象键前缀，会覆盖配置中的前缀)
func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
handler := commonhttp.NewHandler(w, r)
if r.Method != http.MethodPost {
handler.Error(4001, "Method not allowed")
handler.Error("common.method_not_allowed")
return
}
// 解析multipart表单
err := r.ParseMultipartForm(h.maxFileSize)
if err != nil {
handler.Error(4002, fmt.Sprintf("Failed to parse form: %v", err))
handler.Error("common.invalid_request")
return
}
// 获取文件
file, header, err := r.FormFile("file")
if err != nil {
handler.Error(4003, fmt.Sprintf("Failed to get file: %v", err))
handler.Error("common.invalid_request")
return
}
defer file.Close()
// 检查文件大小
if h.maxFileSize > 0 && header.Size > h.maxFileSize {
handler.Error(1001, fmt.Sprintf("File size exceeds limit: %d bytes", h.maxFileSize))
handler.Error("storage.file_too_large")
return
}
// 检查文件扩展名
if len(h.allowedExts) > 0 {
ext := strings.ToLower(filepath.Ext(header.Filename))
allowed := false
@@ -82,22 +75,19 @@ func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
}
}
if !allowed {
handler.Error(1002, fmt.Sprintf("File extension not allowed. Allowed: %v", h.allowedExts))
handler.Error("storage.invalid_extension")
return
}
}
// 生成对象键
prefix := h.objectPrefix
if r.FormValue("prefix") != "" {
prefix = r.FormValue("prefix")
}
// 生成唯一文件名
filename := generateUniqueFilename(header.Filename)
objectKey := GenerateObjectKey(prefix, filename)
// 获取文件类型
contentType := header.Header.Get("Content-Type")
if contentType == "" {
contentType = mime.TypeByExtension(filepath.Ext(header.Filename))
@@ -106,22 +96,18 @@ func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
}
}
// 上传文件
ctx := r.Context()
err = h.storage.Upload(ctx, objectKey, file, contentType)
if err != nil {
handler.SystemError(fmt.Sprintf("Failed to upload file: %v", err))
if err = h.storage.Upload(ctx, objectKey, file, contentType); err != nil {
handler.Error("system.internal_error")
return
}
// 获取文件URL
fileURL, err := h.storage.GetURL(objectKey, 0)
if err != nil {
handler.SystemError(fmt.Sprintf("Failed to get file URL: %v", err))
handler.Error("system.internal_error")
return
}
// 返回结果
result := UploadResult{
ObjectKey: objectKey,
URL: fileURL,
@@ -129,8 +115,7 @@ func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
ContentType: contentType,
UploadTime: time.Now(),
}
handler.SuccessWithMessage("Upload successful", result)
handler.Success(result)
}
// generateUniqueFilename 生成唯一文件名
@@ -155,18 +140,17 @@ func NewProxyHandler(storage Storage) *ProxyHandler {
// ServeHTTP 处理文件查看请求
// URL参数: key (对象键)
// 注意：此方法直接返回文件内容（二进制），错误时返回标准HTTP错误状态码
func (h *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
handler := commonhttp.NewHandler(w, r)
if r.Method != http.MethodGet {
handler.Error(4001, "Method not allowed")
http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
return
}
// 获取对象键
objectKey := handler.GetQuery("key", "")
objectKey := r.URL.Query().Get("key")
if objectKey == "" {
handler.Error(4004, "Missing parameter: key")
http.Error(w, "Missing parameter: key", http.StatusBadRequest)
return
}
@@ -174,19 +158,19 @@ func (h *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
exists, err := h.storage.Exists(ctx, objectKey)
if err != nil {
handler.SystemError(fmt.Sprintf("Failed to check file existence: %v", err))
http.Error(w, fmt.Sprintf("Failed to check file existence: %v", err), http.StatusInternalServerError)
return
}
if !exists {
handler.Error(4005, "File not found")
http.Error(w, "File not found", http.StatusNotFound)
return
}
// 获取文件内容
reader, err := h.storage.GetObject(ctx, objectKey)
if err != nil {
handler.SystemError(fmt.Sprintf("Failed to get file: %v", err))
http.Error(w, fmt.Sprintf("Failed to get file: %v", err), http.StatusInternalServerError)
return
}
defer reader.Close()
@@ -210,7 +194,8 @@ func (h *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
// 复制文件内容到响应
_, err = io.Copy(w, reader)
if err != nil {
handler.SystemError(fmt.Sprintf("Failed to write response: %v", err))
// 如果已经开始写入响应，无法再设置错误状态码
// 这里只能记录错误，无法返回错误响应
return
}
}

222
storage/local.go Normal file
View File

@@ -0,0 +1,222 @@
package storage
import (
"context"
"fmt"
"io"
"net/url"
"os"
"path"
"path/filepath"
"strings"
"git.toowon.com/jimmy/go-common/config"
)
// LocalStorage 本地存储实现
// 将对象写入本地文件夹（BaseDir），对象键 objectKey 作为相对路径使用。
//
// 典型用法：
// - 上传：Upload(ctx, "uploads/2026/01/01/a.png", reader)
// - 查看：配合 ProxyHandler 或 http.FileServer 对外提供访问
type LocalStorage struct {
baseDir string
publicURL string
}
// NewLocalStorage 创建本地存储实例
func NewLocalStorage(cfg *config.LocalStorageConfig) (*LocalStorage, error) {
if cfg == nil {
return nil, fmt.Errorf("LocalStorage config is nil")
}
if strings.TrimSpace(cfg.BaseDir) == "" {
return nil, fmt.Errorf("LocalStorage baseDir is empty")
}
absBase, err := filepath.Abs(cfg.BaseDir)
if err != nil {
return nil, fmt.Errorf("failed to get absolute baseDir: %w", err)
}
// 确保根目录存在
if err := os.MkdirAll(absBase, 0o755); err != nil {
return nil, fmt.Errorf("failed to create baseDir: %w", err)
}
return &LocalStorage{
baseDir: absBase,
publicURL: strings.TrimSpace(cfg.PublicURL),
}, nil
}
// Upload 上传文件到本地文件夹
func (s *LocalStorage) Upload(ctx context.Context, objectKey string, reader io.Reader, contentType ...string) error {
_ = ctx
_ = contentType // 本地写文件不依赖 contentType；可由上层自行记录
dstPath, err := s.resolvePath(objectKey)
if err != nil {
return err
}
// 确保目录存在
if err := os.MkdirAll(filepath.Dir(dstPath), 0o755); err != nil {
return fmt.Errorf("failed to create directory: %w", err)
}
// 原子写入：先写临时文件，再 rename
tmp, err := os.CreateTemp(filepath.Dir(dstPath), ".upload-*")
if err != nil {
return fmt.Errorf("failed to create temp file: %w", err)
}
tmpName := tmp.Name()
defer func() {
_ = tmp.Close()
_ = os.Remove(tmpName)
}()
if _, err := io.Copy(tmp, reader); err != nil {
return fmt.Errorf("failed to write temp file: %w", err)
}
if err := tmp.Close(); err != nil {
return fmt.Errorf("failed to close temp file: %w", err)
}
// 如果目标文件已存在，先删除（保证跨平台兼容 rename 行为）
_ = os.Remove(dstPath)
if err := os.Rename(tmpName, dstPath); err != nil {
return fmt.Errorf("failed to move temp file to destination: %w", err)
}
return nil
}
// GetURL 获取本地文件访问URL
// - 若配置了 publicURL：
// - 包含 "{objectKey}" 占位符：替换为 url.QueryEscape(objectKey)
// - 否则认为是 URL 前缀：自动拼接 objectKey（用 path.Join 处理斜杠）
//
// - 未配置 publicURL：返回 objectKey（相对路径）
func (s *LocalStorage) GetURL(objectKey string, expires int64) (string, error) {
_ = expires // 本地存储不提供签名URL，忽略 expires
cleanKey, err := normalizeObjectKey(objectKey)
if err != nil {
return "", err
}
if s.publicURL == "" {
return cleanKey, nil
}
if strings.Contains(s.publicURL, "{objectKey}") {
return strings.ReplaceAll(s.publicURL, "{objectKey}", url.QueryEscape(cleanKey)), nil
}
// 作为前缀拼接
trimmed := strings.TrimRight(s.publicURL, "/")
return trimmed + "/" + path.Clean("/" + cleanKey)[1:], nil
}
// Delete 删除本地文件
func (s *LocalStorage) Delete(ctx context.Context, objectKey string) error {
_ = ctx
dstPath, err := s.resolvePath(objectKey)
if err != nil {
return err
}
if err := os.Remove(dstPath); err != nil {
if os.IsNotExist(err) {
return nil
}
return fmt.Errorf("failed to delete file: %w", err)
}
return nil
}
// Exists 检查本地文件是否存在
func (s *LocalStorage) Exists(ctx context.Context, objectKey string) (bool, error) {
_ = ctx
dstPath, err := s.resolvePath(objectKey)
if err != nil {
return false, err
}
info, err := os.Stat(dstPath)
if err != nil {
if os.IsNotExist(err) {
return false, nil
}
return false, fmt.Errorf("failed to stat file: %w", err)
}
if info.IsDir() {
return false, nil
}
return true, nil
}
// GetObject 获取本地文件内容
func (s *LocalStorage) GetObject(ctx context.Context, objectKey string) (io.ReadCloser, error) {
_ = ctx
dstPath, err := s.resolvePath(objectKey)
if err != nil {
return nil, err
}
f, err := os.Open(dstPath)
if err != nil {
return nil, fmt.Errorf("failed to open file: %w", err)
}
return f, nil
}
func (s *LocalStorage) resolvePath(objectKey string) (string, error) {
cleanKey, err := normalizeObjectKey(objectKey)
if err != nil {
return "", err
}
// 将 URL 风格路径转换为 OS 路径
full := filepath.Join(s.baseDir, filepath.FromSlash(cleanKey))
// 防御：确保仍在 baseDir 下
rel, err := filepath.Rel(s.baseDir, full)
if err != nil {
return "", fmt.Errorf("failed to resolve path: %w", err)
}
if rel == "." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) || rel == ".." {
return "", fmt.Errorf("invalid objectKey: %s", objectKey)
}
return full, nil
}
func normalizeObjectKey(objectKey string) (string, error) {
key := strings.TrimSpace(objectKey)
if key == "" {
return "", fmt.Errorf("objectKey is empty")
}
// 兼容 Windows 风格路径，统一为 URL 风格
key = strings.ReplaceAll(key, "\\", "/")
// 清洗路径，去除多余的 . / ..
// 加前缀 "/" 让 Clean 以绝对路径方式处理，避免出现空结果
clean := path.Clean("/" + key)
clean = strings.TrimPrefix(clean, "/")
if clean == "" || clean == "." {
return "", fmt.Errorf("invalid objectKey: %s", objectKey)
}
// 不允许以 "/" 结尾（必须指向文件）
if strings.HasSuffix(clean, "/") {
return "", fmt.Errorf("objectKey cannot be a directory: %s", objectKey)
}
return clean, nil
}

102
storage/local_test.go Normal file
View File

@@ -0,0 +1,102 @@
package storage
import (
"bytes"
"context"
"io"
"testing"
"git.toowon.com/jimmy/go-common/config"
)
func TestLocalStorage_UploadGetExistsDelete(t *testing.T) {
t.Parallel()
cfg := &config.LocalStorageConfig{
BaseDir: t.TempDir(),
PublicURL: "http://localhost:8080/file?key={objectKey}",
}
s, err := NewLocalStorage(cfg)
if err != nil {
t.Fatalf("NewLocalStorage error: %v", err)
}
ctx := context.Background()
objectKey := "uploads/2026/01/30/hello.txt"
body := []byte("hello local storage")
if err := s.Upload(ctx, objectKey, bytes.NewReader(body), "text/plain"); err != nil {
t.Fatalf("Upload error: %v", err)
}
exists, err := s.Exists(ctx, objectKey)
if err != nil {
t.Fatalf("Exists error: %v", err)
}
if !exists {
t.Fatalf("expected exists=true")
}
rc, err := s.GetObject(ctx, objectKey)
if err != nil {
t.Fatalf("GetObject error: %v", err)
}
defer rc.Close()
got, err := io.ReadAll(rc)
if err != nil {
t.Fatalf("ReadAll error: %v", err)
}
if !bytes.Equal(got, body) {
t.Fatalf("content mismatch: got=%q want=%q", string(got), string(body))
}
u, err := s.GetURL(objectKey, 0)
if err != nil {
t.Fatalf("GetURL error: %v", err)
}
if u == "" {
t.Fatalf("expected non-empty url")
}
if err := s.Delete(ctx, objectKey); err != nil {
t.Fatalf("Delete error: %v", err)
}
exists, err = s.Exists(ctx, objectKey)
if err != nil {
t.Fatalf("Exists error: %v", err)
}
if exists {
t.Fatalf("expected exists=false after delete")
}
}
func TestNormalizeObjectKey(t *testing.T) {
t.Parallel()
if _, err := normalizeObjectKey(""); err == nil {
t.Fatalf("expected error for empty objectKey")
}
if _, err := normalizeObjectKey(" "); err == nil {
t.Fatalf("expected error for blank objectKey")
}
if _, err := normalizeObjectKey("."); err == nil {
t.Fatalf("expected error for '.'")
}
clean1, err := normalizeObjectKey("a/b/")
if err != nil {
t.Fatalf("normalizeObjectKey error: %v", err)
}
if clean1 != "a/b" {
t.Fatalf("unexpected clean key: %q", clean1)
}
clean, err := normalizeObjectKey(`\a\..\b\c.txt`)
if err != nil {
t.Fatalf("normalizeObjectKey error: %v", err)
}
if clean != "b/c.txt" {
t.Fatalf("unexpected clean key: %q", clean)
}
}

9
storage/storage.go
View File

@@ -39,10 +39,11 @@ type StorageType string
const (
StorageTypeOSS StorageType = "oss"
StorageTypeMinIO StorageType = "minio"
StorageTypeLocal StorageType = "local"
)
// NewStorage 创建存储实例
// storageType: 存储类型（oss或minio）
// storageType: 存储类型（oss/minio/local）
// cfg: 配置对象
func NewStorage(storageType StorageType, cfg *config.Config) (Storage, error) {
switch storageType {
@@ -58,6 +59,12 @@ func NewStorage(storageType StorageType, cfg *config.Config) (Storage, error) {
return nil, fmt.Errorf("MinIO config is nil")
}
return NewMinIOStorage(minioConfig)
case StorageTypeLocal:
localCfg := cfg.GetLocalStorage()
if localCfg == nil {
return nil, fmt.Errorf("LocalStorage config is nil")
}
return NewLocalStorage(localCfg)
default:
return nil, fmt.Errorf("unsupported storage type: %s", storageType)
}

39
templates/Dockerfile.example Normal file
View File

@@ -0,0 +1,39 @@
# Dockerfile 示例
# 展示如何构建包含迁移工具的 Go 应用
# ===== 构建阶段 =====
FROM golang:1.21 as builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
# 编译应用和迁移工具
RUN go build -o bin/server cmd/server/main.go
RUN go build -o bin/migrate cmd/migrate/main.go
# ===== 运行阶段 =====
FROM debian:bookworm-slim
WORKDIR /app
# 安装运行时依赖
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
# 复制二进制文件和迁移文件
COPY --from=builder /app/bin/server .
COPY --from=builder /app/bin/migrate .
COPY --from=builder /app/migrations ./migrations
EXPOSE 8080
# 启动：先执行迁移，再启动应用
CMD ["sh", "-c", "./migrate up && ./server"]
# 注意：
# 1. 配置文件通过 docker-compose volumes 挂载，不打包进镜像
# 2. 镜像只包含二进制文件和迁移SQL文件
# 3. 配置文件在运行时提供，更安全、更灵活

78
templates/Makefile.example Normal file
View File

@@ -0,0 +1,78 @@
# 示例 Makefile
# 提供常用的开发和部署命令
.PHONY: help build run migrate-up migrate-down migrate-status docker-build docker-up clean
# 默认目标：显示帮助
help:
@echo "可用命令："
@echo " make build - 编译应用和迁移工具"
@echo " make run - 运行应用（先执行迁移）"
@echo " make migrate-up - 执行数据库迁移"
@echo " make migrate-down - 回滚数据库迁移"
@echo " make migrate-status - 查看迁移状态"
@echo " make docker-build - 构建 Docker 镜像"
@echo " make docker-up - 启动 Docker 服务"
@echo " make clean - 清理编译文件"
# 编译
build:
@echo "编译应用..."
@mkdir -p bin
@go build -o bin/server cmd/server/main.go
@go build -o bin/migrate cmd/migrate/main.go
@echo "✓ 编译完成"
# 运行应用
run: migrate-up
@echo "启动应用..."
@./bin/server
# 执行迁移
migrate-up: build
@echo "执行数据库迁移..."
@./bin/migrate up
# 回滚迁移
migrate-down: build
@echo "回滚数据库迁移..."
@./bin/migrate down
# 查看迁移状态
migrate-status: build
@./bin/migrate status
# 构建 Docker 镜像
docker-build:
@echo "构建 Docker 镜像..."
@docker build -t myapp:latest .
# 启动 Docker 服务
docker-up:
@echo "启动 Docker 服务..."
@docker-compose up --build
# 清理
clean:
@echo "清理编译文件..."
@rm -rf bin
@echo "✓ 清理完成"
# 开发环境：直接运行（不编译）
dev-migrate-up:
@go run cmd/migrate/main.go up
dev-migrate-down:
@go run cmd/migrate/main.go down
dev-migrate-status:
@go run cmd/migrate/main.go status
# 交叉编译（Linux）
build-linux:
@echo "交叉编译 Linux 版本..."
@mkdir -p bin
@GOOS=linux GOARCH=amd64 go build -o bin/server-linux cmd/server/main.go
@GOOS=linux GOARCH=amd64 go build -o bin/migrate-linux cmd/migrate/main.go
@echo "✓ Linux 版本编译完成"

40
templates/README.md Normal file
View File

@@ -0,0 +1,40 @@
# 模板文件
这个目录包含了可以直接复制到你项目中使用的模板文件。
## 包含的模板
- `migrate/main.go` - 数据库迁移工具模板 ⭐
- `Dockerfile.example` - Docker 构建示例
- `docker-compose.example.yml` - Docker Compose 示例
- `Makefile.example` - Makefile 常用命令示例
## 快速使用
### 迁移工具模板
```bash
# 1. 复制到你的项目
mkdir -p cmd/migrate
cp templates/migrate/main.go cmd/migrate/
# 2. 编译
go build -o bin/migrate cmd/migrate/main.go
# 3. 使用
./bin/migrate up
./bin/migrate -help
```
### Docker 模板
```bash
# 复制到你的项目根目录
cp templates/Dockerfile.example Dockerfile
cp templates/docker-compose.example.yml docker-compose.yml
cp templates/Makefile.example Makefile
```
## 完整文档
详细使用说明请查看：[INTEGRATION.md](../INTEGRATION.md) 第 7 节「数据库迁移」

22
templates/docker-compose.example.yml Normal file
View File

@@ -0,0 +1,22 @@
# docker-compose.yml 示例
# 展示如何在 docker-compose 中使用迁移工具
version: '3.8'
services:
app:
build: .
ports:
- "8080:8080"
volumes:
# 挂载配置文件（推荐：修改配置无需重启容器）
- ./config.json:/app/config.json:ro
# 启动时先执行迁移，再启动应用
command: sh -c "./migrate up && ./server"
# 使用说明：
# 1. 将此配置添加到你的 docker-compose.yml 中
# 2. 确保你的配置文件（config.json）包含数据库连接信息
# 3. 修改配置后，手动执行迁移：docker-compose exec app ./migrate up
# 4. 无需重启容器！

149
templates/migrate/main.go Normal file
View File

@@ -0,0 +1,149 @@
package main
import (
"flag"
"fmt"
"os"
"git.toowon.com/jimmy/go-common/migration"
)
// 数据库迁移工具（黑盒模式）
//
// 工作原理：
// 此工具调用 migration.RunMigrationsFromConfigWithCommand() 方法，
// 内部自动处理配置加载、数据库连接、迁移执行等所有细节。
// 你只需要提供配置文件和SQL迁移文件即可。
//
// 使用方式：
// 基本用法：
// ./migrate up # 使用默认配置
// ./migrate up -config /path/to/config.json # 指定配置文件
// ./migrate up -config config.json -dir db/migrations # 指定配置和迁移目录
// ./migrate status # 查看迁移状态
// ./migrate down # 回滚最后一个迁移
//
// Docker 中使用：
// # 方式1：挂载配置文件（推荐）
// docker run -v /host/config.json:/app/config.json myapp ./migrate up
//
// # 方式2：使用环境变量指定配置文件路径
// docker run -e CONFIG_FILE=/etc/app/config.json myapp ./migrate up
//
// # 方式3：指定容器内的配置文件路径
// docker run myapp ./migrate up -config /etc/app/config.json
//
// 支持的命令：
// up - 执行所有待执行的迁移
// down - 回滚最后一个迁移
// status - 查看迁移状态
//
// 配置优先级（从高到低）：
// 1. 命令行参数 -config 和 -dir
// 2. 环境变量 CONFIG_FILE 和 MIGRATIONS_DIR
// 3. 默认值（config.json 和 migrations）
var (
configFile string
migrationsDir string
showHelp bool
)
func init() {
flag.StringVar(&configFile, "config", "", "配置文件路径（默认：config.json 或环境变量 CONFIG_FILE）")
flag.StringVar(&configFile, "c", "", "配置文件路径（简写）")
flag.StringVar(&migrationsDir, "dir", "", "迁移文件目录（默认：migrations 或环境变量 MIGRATIONS_DIR）")
flag.StringVar(&migrationsDir, "d", "", "迁移文件目录（简写）")
flag.BoolVar(&showHelp, "help", false, "显示帮助信息")
flag.BoolVar(&showHelp, "h", false, "显示帮助信息（简写）")
}
func main() {
flag.Parse()
// 显示帮助
if showHelp {
printHelp()
os.Exit(0)
}
// 获取命令（默认up）
// 支持两种方式：
// 1. 位置参数：./migrate up
// 2. 标志参数：./migrate -cmd=up（向后兼容）
command := "up"
args := flag.Args()
if len(args) > 0 {
command = args[0]
}
// 验证命令
if command != "up" && command != "down" && command != "status" {
fmt.Fprintf(os.Stderr, "错误：未知命令 '%s'\n\n", command)
printHelp()
os.Exit(1)
}
// 获取配置文件路径（优先级：命令行 > 环境变量 > 默认值）
// 如果未指定，RunMigrationsFromConfigWithCommand 会自动查找
if configFile == "" {
configFile = getEnv("CONFIG_FILE", "")
}
// 获取迁移目录（优先级：命令行 > 环境变量 > 默认值）
// 如果未指定，RunMigrationsFromConfigWithCommand 会使用默认值 "migrations"
if migrationsDir == "" {
migrationsDir = getEnv("MIGRATIONS_DIR", "")
}
// 执行迁移（黑盒模式：内部自动处理所有细节）
if err := migration.RunMigrationsFromConfigWithCommand(configFile, migrationsDir, command); err != nil {
fmt.Fprintf(os.Stderr, "错误: %v\n", err)
os.Exit(1)
}
}
func getEnv(key, defaultValue string) string {
if value := os.Getenv(key); value != "" {
return value
}
return defaultValue
}
func printHelp() {
fmt.Println("数据库迁移工具")
fmt.Println()
fmt.Println("用法:")
fmt.Println(" migrate [命令] [选项]")
fmt.Println()
fmt.Println("命令:")
fmt.Println(" up 执行所有待执行的迁移（默认）")
fmt.Println(" down 回滚最后一个迁移")
fmt.Println(" status 查看迁移状态")
fmt.Println()
fmt.Println("选项:")
fmt.Println(" -config, -c 配置文件路径（默认: config.json）")
fmt.Println(" -dir, -d 迁移文件目录（默认: migrations）")
fmt.Println(" -help, -h 显示帮助信息")
fmt.Println()
fmt.Println("示例:")
fmt.Println(" # 使用默认配置")
fmt.Println(" migrate up")
fmt.Println()
fmt.Println(" # 指定配置文件")
fmt.Println(" migrate up -config /etc/app/config.json")
fmt.Println()
fmt.Println(" # 指定配置和迁移目录")
fmt.Println(" migrate up -c config.json -d db/migrations")
fmt.Println()
fmt.Println(" # 使用环境变量指定配置文件路径")
fmt.Println(" CONFIG_FILE=/etc/app/config.json migrate up")
fmt.Println()
fmt.Println(" # Docker 中使用（挂载配置文件）")
fmt.Println(" docker run -v /host/config.json:/app/config.json myapp migrate up")
fmt.Println()
fmt.Println("配置优先级（从高到低）:")
fmt.Println(" 1. 命令行参数 -config 和 -dir")
fmt.Println(" 2. 环境变量 CONFIG_FILE 和 MIGRATIONS_DIR")
fmt.Println(" 3. 默认值（config.json 和 migrations）")
}

99
tools/convertor.go Normal file
View File

@@ -0,0 +1,99 @@
package tools
import "strconv"
// ConvertInt 将字符串转换为int类型
// value: 待转换的字符串
// defaultValue: 转换失败或字符串为空时返回的默认值
func ConvertInt(value string, defaultValue int) int {
if value == "" {
return defaultValue
}
intValue, err := strconv.Atoi(value)
if err != nil {
return defaultValue
}
return intValue
}
// ConvertInt64 将字符串转换为int64类型
// value: 待转换的字符串
// defaultValue: 转换失败或字符串为空时返回的默认值
func ConvertInt64(value string, defaultValue int64) int64 {
if value == "" {
return defaultValue
}
intValue, err := strconv.ParseInt(value, 10, 64)
if err != nil {
return defaultValue
}
return intValue
}
// ConvertUint64 将字符串转换为uint64类型
// value: 待转换的字符串
// defaultValue: 转换失败或字符串为空时返回的默认值
func ConvertUint64(value string, defaultValue uint64) uint64 {
if value == "" {
return defaultValue
}
uintValue, err := strconv.ParseUint(value, 10, 64)
if err != nil {
return defaultValue
}
return uintValue
}
// ConvertUint32 将字符串转换为uint32类型
// value: 待转换的字符串
// defaultValue: 转换失败或字符串为空时返回的默认值
func ConvertUint32(value string, defaultValue uint32) uint32 {
if value == "" {
return defaultValue
}
uintValue, err := strconv.ParseUint(value, 10, 32)
if err != nil {
return defaultValue
}
return uint32(uintValue)
}
// ConvertBool 将字符串转换为bool类型
// value: 待转换的字符串
// defaultValue: 转换失败或字符串为空时返回的默认值
func ConvertBool(value string, defaultValue bool) bool {
if value == "" {
return defaultValue
}
boolValue, err := strconv.ParseBool(value)
if err != nil {
return defaultValue
}
return boolValue
}
// ConvertFloat64 将字符串转换为float64类型
// value: 待转换的字符串
// defaultValue: 转换失败或字符串为空时返回的默认值
func ConvertFloat64(value string, defaultValue float64) float64 {
if value == "" {
return defaultValue
}
floatValue, err := strconv.ParseFloat(value, 64)
if err != nil {
return defaultValue
}
return floatValue
}

85
tools/crypto.go Normal file
View File

@@ -0,0 +1,85 @@
package tools
import (
"crypto/md5"
"crypto/rand"
"crypto/sha256"
"encoding/hex"
"fmt"
"math/big"
"golang.org/x/crypto/bcrypt"
)
// HashPassword 使用bcrypt加密密码
func HashPassword(password string) (string, error) {
bytes, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
return string(bytes), err
}
// CheckPassword 验证密码
func CheckPassword(password, hash string) bool {
err := bcrypt.CompareHashAndPassword([]byte(hash), []byte(password))
return err == nil
}
// MD5 计算MD5哈希值
func MD5(text string) string {
hash := md5.Sum([]byte(text))
return hex.EncodeToString(hash[:])
}
// SHA256 计算SHA256哈希值
func SHA256(text string) string {
hash := sha256.Sum256([]byte(text))
return hex.EncodeToString(hash[:])
}
// GenerateRandomString 生成指定长度的随机字符串
func GenerateRandomString(length int) string {
const charset = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
b := make([]byte, length)
for i := range b {
num, _ := rand.Int(rand.Reader, big.NewInt(int64(len(charset))))
b[i] = charset[num.Int64()]
}
return string(b)
}
// GenerateRandomNumber 生成指定长度的随机数字字符串
func GenerateRandomNumber(length int) string {
const charset = "0123456789"
b := make([]byte, length)
for i := range b {
num, _ := rand.Int(rand.Reader, big.NewInt(int64(len(charset))))
b[i] = charset[num.Int64()]
}
return string(b)
}
// GenerateSMSCode 生成短信验证码
func GenerateSMSCode() string {
return GenerateRandomNumber(6)
}
// GenerateOrderNo 生成订单号
func GenerateOrderNo(prefix string) string {
timestamp := GetTimestamp()
random := GenerateRandomNumber(6)
return fmt.Sprintf("%s%d%s", prefix, timestamp, random)
}
// GeneratePaymentNo 生成支付单号
func GeneratePaymentNo() string {
return GenerateOrderNo("PAY")
}
// GenerateRefundNo 生成退款单号
func GenerateRefundNo() string {
return GenerateOrderNo("RF")
}
// GenerateTransferNo 生成调拨单号
func GenerateTransferNo() string {
return GenerateOrderNo("TF")
}

2
datetime/datetime.go → tools/datetime.go
View File

@@ -1,4 +1,4 @@
package datetime
package tools
import (
"fmt"

173
tools/money.go Normal file
View File

@@ -0,0 +1,173 @@
package tools
import (
"fmt"
"math"
)
// MoneyCalculator 金额计算工具（以分为单位）
type MoneyCalculator struct{}
// NewMoneyCalculator 创建金额计算器
func NewMoneyCalculator() *MoneyCalculator {
return &MoneyCalculator{}
}
// YuanToCents 元转分
func (m *MoneyCalculator) YuanToCents(yuan float64) int64 {
return int64(math.Round(yuan * 100))
}
// CentsToYuan 分转元
func (m *MoneyCalculator) CentsToYuan(cents int64) float64 {
return float64(cents) / 100
}
// FormatYuan 格式化显示金额（分转元，保留2位小数）
func (m *MoneyCalculator) FormatYuan(cents int64) string {
return fmt.Sprintf("%.2f", m.CentsToYuan(cents))
}
// Add 金额相加
func (m *MoneyCalculator) Add(amount1, amount2 int64) int64 {
return amount1 + amount2
}
// Subtract 金额相减
func (m *MoneyCalculator) Subtract(amount1, amount2 int64) int64 {
return amount1 - amount2
}
// Multiply 金额乘法（金额 * 数量）
func (m *MoneyCalculator) Multiply(amount int64, quantity int) int64 {
return amount * int64(quantity)
}
// MultiplyFloat 金额乘法（金额 * 浮点数，如折扣）
func (m *MoneyCalculator) MultiplyFloat(amount int64, rate float64) int64 {
return int64(math.Round(float64(amount) * rate))
}
// Divide 金额除法（平均分配）
func (m *MoneyCalculator) Divide(amount int64, count int) int64 {
if count <= 0 {
return 0
}
return amount / int64(count)
}
// CalculateDiscount 计算折扣金额
func (m *MoneyCalculator) CalculateDiscount(originalAmount int64, discountRate float64) int64 {
if discountRate <= 0 || discountRate >= 1 {
return 0
}
return int64(math.Round(float64(originalAmount) * discountRate))
}
// CalculatePercentage 计算百分比金额
func (m *MoneyCalculator) CalculatePercentage(amount int64, percentage float64) int64 {
return int64(math.Round(float64(amount) * percentage / 100))
}
// Max 取最大金额
func (m *MoneyCalculator) Max(amounts ...int64) int64 {
if len(amounts) == 0 {
return 0
}
max := amounts[0]
for _, amount := range amounts[1:] {
if amount > max {
max = amount
}
}
return max
}
// Min 取最小金额
func (m *MoneyCalculator) Min(amounts ...int64) int64 {
if len(amounts) == 0 {
return 0
}
min := amounts[0]
for _, amount := range amounts[1:] {
if amount < min {
min = amount
}
}
return min
}
// IsPositive 判断是否为正数
func (m *MoneyCalculator) IsPositive(amount int64) bool {
return amount > 0
}
// IsZero 判断是否为零
func (m *MoneyCalculator) IsZero(amount int64) bool {
return amount == 0
}
// IsNegative 判断是否为负数
func (m *MoneyCalculator) IsNegative(amount int64) bool {
return amount < 0
}
// Equal 判断金额是否相等
func (m *MoneyCalculator) Equal(amount1, amount2 int64) bool {
return amount1 == amount2
}
// Greater 判断第一个金额是否大于第二个
func (m *MoneyCalculator) Greater(amount1, amount2 int64) bool {
return amount1 > amount2
}
// Less 判断第一个金额是否小于第二个
func (m *MoneyCalculator) Less(amount1, amount2 int64) bool {
return amount1 < amount2
}
// Sum 计算金额总和
func (m *MoneyCalculator) Sum(amounts ...int64) int64 {
var total int64
for _, amount := range amounts {
total += amount
}
return total
}
// SplitAmount 金额分摊（处理分摊不均的情况）
func (m *MoneyCalculator) SplitAmount(totalAmount int64, count int) []int64 {
if count <= 0 {
return []int64{}
}
baseAmount := totalAmount / int64(count)
remainder := totalAmount % int64(count)
amounts := make([]int64, count)
for i := 0; i < count; i++ {
amounts[i] = baseAmount
if int64(i) < remainder {
amounts[i]++
}
}
return amounts
}
// 全局金额计算器实例
var Money = NewMoneyCalculator()
// 便捷函数
func YuanToCents(yuan float64) int64 {
return Money.YuanToCents(yuan)
}
func CentsToYuan(cents int64) float64 {
return Money.CentsToYuan(cents)
}
func FormatYuan(cents int64) string {
return Money.FormatYuan(cents)
}

186
tools/time.go Normal file
View File

@@ -0,0 +1,186 @@
package tools
import (
"time"
)
// TimeInfo 详细时间信息结构
type TimeInfo struct {
UTC string `json:"utc"` // UTC时间
Local string `json:"local"` // 用户时区时间
Unix int64 `json:"unix"` // Unix时间戳
Timezone string `json:"timezone"` // 时区名称
Offset int `json:"offset"` // 时区偏移量（小时）
RFC3339 string `json:"rfc3339"` // RFC3339格式
DateTime string `json:"datetime"` // 日期时间格式
Date string `json:"date"` // 日期格式
Time string `json:"time"` // 时间格式
}
// GetTimestamp 获取当前时间戳（秒）
func GetTimestamp() int64 {
return time.Now().Unix()
}
// GetMillisTimestamp 获取当前时间戳（毫秒）
func GetMillisTimestamp() int64 {
return time.Now().UnixMilli()
}
// FormatTimeWithLayout 格式化时间（自定义格式）
func FormatTimeWithLayout(t time.Time, layout string) string {
if layout == "" {
layout = "2006-01-02 15:04:05"
}
return t.Format(layout)
}
// ParseTime 解析时间字符串
func ParseTime(timeStr, layout string) (time.Time, error) {
if layout == "" {
layout = "2006-01-02 15:04:05"
}
return time.Parse(layout, timeStr)
}
// GetCurrentTime 获取当前时间字符串
func GetCurrentTime() string {
return FormatTimeWithLayout(time.Now(), "")
}
// 注意：GetBeginOfDay、GetEndOfDay 已在 datetime.go 中实现为 StartOfDay、EndOfDay
// datetime.go 中的方法支持时区参数，功能更强大，建议使用 datetime.go 中的方法
// GetBeginOfWeek 获取某周的开始时间（周一）
func GetBeginOfWeek(t time.Time) time.Time {
weekday := t.Weekday()
if weekday == time.Sunday {
weekday = 7
}
// 使用 datetime.go 中的 StartOfDay 方法（需要时区，这里使用时间对象本身的时区）
beginDay := t.AddDate(0, 0, int(1-weekday))
return time.Date(beginDay.Year(), beginDay.Month(), beginDay.Day(), 0, 0, 0, 0, beginDay.Location())
}
// GetEndOfWeek 获取某周的结束时间（周日）
func GetEndOfWeek(t time.Time) time.Time {
beginOfWeek := GetBeginOfWeek(t)
endDay := beginOfWeek.AddDate(0, 0, 6)
return time.Date(endDay.Year(), endDay.Month(), endDay.Day(), 23, 59, 59, 999999999, endDay.Location())
}
// 注意：GetBeginOfMonth、GetEndOfMonth、GetBeginOfYear、GetEndOfYear 已在 datetime.go 中实现
// datetime.go 中的方法（StartOfMonth、EndOfMonth、StartOfYear、EndOfYear）支持时区参数，功能更强大
// 建议使用 datetime.go 中的方法
// AddHours 增加小时数
func AddHours(t time.Time, hours int) time.Time {
return t.Add(time.Duration(hours) * time.Hour)
}
// AddMinutes 增加分钟数
func AddMinutes(t time.Time, minutes int) time.Time {
return t.Add(time.Duration(minutes) * time.Minute)
}
// 注意：DiffDays、DiffHours、DiffMinutes、DiffSeconds 方法已在 datetime.go 中实现
// 请使用 datetime.go 中的方法，它们支持更精确的计算和统一的返回类型
// IsToday 判断是否为今天
func IsToday(t time.Time) bool {
now := time.Now()
tBegin := time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, t.Location())
nowBegin := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, now.Location())
return tBegin.Equal(nowBegin)
}
// GenerateTimeInfoWithTimezone 生成详细时间信息（指定时区）
func GenerateTimeInfoWithTimezone(t time.Time, timezone string) TimeInfo {
// 加载时区
loc, err := time.LoadLocation(timezone)
if err != nil {
loc = time.UTC
timezone = "UTC"
}
// 转换为指定时区时间
localTime := t.In(loc)
// 计算时区偏移量
_, offset := localTime.Zone()
offsetHours := offset / 3600
// 预先计算格式化结果，避免重复调用
utcRFC3339 := t.UTC().Format(time.RFC3339)
localRFC3339 := localTime.Format(time.RFC3339)
localDateTime := localTime.Format("2006-01-02 15:04:05")
localDate := localTime.Format("2006-01-02")
localTimeOnly := localTime.Format("15:04:05")
return TimeInfo{
UTC: utcRFC3339,
Local: localRFC3339,
Unix: t.Unix(),
Timezone: timezone,
Offset: offsetHours,
RFC3339: localRFC3339,
DateTime: localDateTime,
Date: localDate,
Time: localTimeOnly,
}
}
// GetUTCTimestamp 获取UTC时间戳
func GetUTCTimestamp() int64 {
return time.Now().UTC().Unix()
}
// GetUTCTimestampFromTime 从指定时间获取UTC时间戳
func GetUTCTimestampFromTime(t time.Time) int64 {
return t.UTC().Unix()
}
// FormatTimeUTC 格式化时间为UTC字符串（ISO 8601格式）
func FormatTimeUTC(t time.Time) string {
return t.UTC().Format(time.RFC3339)
}
// IsYesterday 判断是否为昨天
func IsYesterday(t time.Time) bool {
yesterday := time.Now().AddDate(0, 0, -1)
tBegin := time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, t.Location())
yesterdayBegin := time.Date(yesterday.Year(), yesterday.Month(), yesterday.Day(), 0, 0, 0, 0, yesterday.Location())
return tBegin.Equal(yesterdayBegin)
}
// IsTomorrow 判断是否为明天
func IsTomorrow(t time.Time) bool {
tomorrow := time.Now().AddDate(0, 0, 1)
tBegin := time.Date(t.Year(), t.Month(), t.Day(), 0, 0, 0, 0, t.Location())
tomorrowBegin := time.Date(tomorrow.Year(), tomorrow.Month(), tomorrow.Day(), 0, 0, 0, 0, tomorrow.Location())
return tBegin.Equal(tomorrowBegin)
}
// GenerateTimeInfoFromContext 从gin.Context中获取用户时区并生成时间信息
func GenerateTimeInfoFromContext(t time.Time, c interface{}) TimeInfo {
// 尝试从context中获取时区
timezone := ""
// 如果传入的是gin.Context，尝试获取时区
if ginCtx, ok := c.(interface {
Get(key string) (value interface{}, exists bool)
}); ok {
if tz, exists := ginCtx.Get("user_timezone"); exists {
if tzStr, ok := tz.(string); ok && tzStr != "" {
timezone = tzStr
}
}
}
// 如果没有获取到时区，使用默认时区（东8区）
if timezone == "" {
timezone = "Asia/Shanghai"
}
return GenerateTimeInfoWithTimezone(t, timezone)
}

26
tools/version.go Normal file
View File

@@ -0,0 +1,26 @@
package tools
import (
"os"
)
// Version 版本号 - 在这里修改版本号（默认值）
const DefaultVersion = "1.0.1"
// GetVersion 获取版本号
// 优先从环境变量 DOCKER_TAG 或 VERSION 中读取
// 如果没有设置环境变量，则使用默认版本号
func GetVersion() string {
// 优先从 Docker 标签环境变量读取
if dockerTag := os.Getenv("DOCKER_TAG"); dockerTag != "" {
return dockerTag
}
// 从通用版本环境变量读取
if version := os.Getenv("VERSION"); version != "" {
return version
}
// 使用默认版本号
return DefaultVersion
}