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

Compare commits

base: jimmy:a6e8101e098a5f66bdd3383126fe3842d1fbc7b4
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:987b16fd41fa420aad27acddf17f0f9d9323ada1
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

2 Commits
a6e8101e09 ... 987b16fd41

Author SHA1 Message Date
Jimmy Xue
987b16fd41 调整版本统一为1.0.0 2026-06-25 00:41:24 +08:00
Jimmy Xue
6072ec57e8 重构项目的实现,优化使用方法与使用逻辑 2026-06-25 00:03:59 +08:00
49 changed files with 1657 additions and 12535 deletions
Expand all files Collapse all files

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@v1.0.0
```
在 `go.mod` 中：
```go
require git.toowon.com/jimmy/go-common v1.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)。

580
MIGRATION.md
View File

@@ -1,580 +0,0 @@
# 数据库迁移工具 - 完整指南
## 📌 核心特点
- ✅ **独立工具，零耦合** - 与应用代码完全分离
- ✅ **生产就绪** - 编译成二进制，无需Go环境
- ✅ **灵活配置** - 支持命令行参数、环境变量、配置文件
- ✅ **Docker友好** - 挂载配置，修改无需重启容器
---
## 🚀 快速开始（3步）
> **黑盒模式**：迁移工具内部调用 `migration.RunMigrationsFromConfig()` 方法，自动处理配置加载、数据库连接、迁移执行等所有细节。你只需要提供配置文件和SQL文件即可。
### 1. 复制迁移工具模板
```bash
mkdir -p cmd/migrate
cp /path/to/go-common/templates/migrate/main.go cmd/migrate/
```
### 2. 创建迁移文件
```bash
mkdir -p migrations
```
创建 `migrations/20240101000001_create_users.sql`：
```sql
CREATE TABLE users (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(255) NOT NULL,
email VARCHAR(255) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
### 3. 编译和使用
```bash
# 编译（生产环境推荐）
go build -o bin/migrate cmd/migrate/main.go
# 使用
./bin/migrate up # 使用默认配置
./bin/migrate up -config /path/to/config.json # 指定配置
./bin/migrate status # 查看状态
./bin/migrate -help # 查看帮助
```
---
## 💻 本地使用
### 开发环境
```bash
# 直接运行（需要Go环境）
go run cmd/migrate/main.go up
go run cmd/migrate/main.go up -config dev.json
# 编译后运行（推荐）
go build -o bin/migrate cmd/migrate/main.go
./bin/migrate up
./bin/migrate up -config config.prod.json
./bin/migrate up -c prod.json -d db/migrations
```
### 命令说明
```bash
./bin/migrate -help
# 输出：
# 用法: migrate [命令] [选项]
#
# 命令:
# up 执行所有待执行的迁移（默认）
# down 回滚最后一个迁移
# status 查看迁移状态
#
# 选项:
# -config, -c 配置文件路径（默认: config.json）
# -dir, -d 迁移文件目录（默认: migrations）
# -help, -h 显示帮助信息
```
### 配置方式
#### 方式1：配置文件（推荐开发环境）
`config.json`:
```json
{
"database": {
"type": "mysql",
"host": "localhost",
"port": 3306,
"user": "root",
"password": "password",
"database": "mydb"
}
}
```
#### 方式2：环境变量指定配置文件路径（推荐生产环境）
```bash
# 使用环境变量指定配置文件路径
export CONFIG_FILE="/etc/app/config.json"
export MIGRATIONS_DIR="/opt/app/migrations"
./bin/migrate up
```
#### 配置优先级（从高到低）
1. 命令行参数 `-config` 和 `-dir`（最高）
2. 环境变量 `CONFIG_FILE` 和 `MIGRATIONS_DIR`
3. 默认值 `config.json` 和 `migrations`
---
## 🐳 Docker 使用
### 方式1：挂载配置文件（推荐）⭐
**优势**：修改配置无需重启容器！
#### docker-compose.yml
```yaml
version: '3.8'
services:
app:
build: .
ports:
- "8080:8080"
volumes:
# 挂载配置文件（推荐：修改配置无需重启容器）
- ./config.json:/app/config.json:ro
# 启动时先执行迁移，再启动应用
command: sh -c "./migrate up && ./server"
```
#### 使用方式
```bash
# 1. 启动服务
docker-compose up -d
# 2. 修改配置文件
vim config.json
# 3. 手动执行迁移（无需重启容器！）
docker-compose exec app ./migrate up
# 4. 查看状态
docker-compose exec app ./migrate status
```
### 方式2：指定配置文件路径
适用于多环境部署：
```yaml
services:
app:
build: .
volumes:
# 挂载不同环境的配置文件
- ./config.prod.json:/app/config.json:ro
command: sh -c "./migrate up -config /app/config.json && ./server"
```
```bash
# 手动切换环境（修改挂载的配置文件后）
docker-compose exec app ./migrate up
```
### 方式3：使用环境变量指定配置文件路径
适用于多环境部署，通过环境变量指定不同环境的配置文件：
```yaml
services:
app:
build: .
environment:
CONFIG_FILE: /app/config.prod.json
MIGRATIONS_DIR: /app/migrations
volumes:
- ./config.prod.json:/app/config.prod.json:ro
command: sh -c "./migrate up && ./server"
```
### Dockerfile
```dockerfile
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/migrate .
COPY --from=builder /app/bin/server .
COPY --from=builder /app/migrations ./migrations
EXPOSE 8080
# 启动：先迁移，再启动应用
CMD ["sh", "-c", "./migrate up && ./server"]
# 注意：配置文件通过 volumes 挂载，不打包进镜像
```
---
## ☸️ Kubernetes 部署
### 使用 Job 执行迁移
```yaml
# k8s-job-migrate.yaml
apiVersion: batch/v1
kind: Job
metadata:
name: db-migrate
spec:
template:
spec:
containers:
- name: migrate
image: myapp:latest
command: ["./migrate", "up", "-config", "/etc/config/database.json"]
volumeMounts:
- name: config
mountPath: /etc/config
readOnly: true
volumes:
- name: config
configMap:
name: app-config
restartPolicy: OnFailure
```
### 部署流程
```bash
# 1. 创建 ConfigMap
kubectl create configmap app-config --from-file=config.json
# 2. 执行迁移
kubectl apply -f k8s-job-migrate.yaml
kubectl wait --for=condition=complete job/db-migrate
# 3. 部署应用
kubectl apply -f k8s-deployment.yaml
```
---
## 🔧 CI/CD 集成
### GitLab CI
```yaml
# .gitlab-ci.yml
stages:
- build
- migrate
- deploy
build:
stage: build
script:
- go build -o bin/migrate cmd/migrate/main.go
- go build -o bin/server cmd/server/main.go
artifacts:
paths:
- bin/
migrate:
stage: migrate
script:
- ./bin/migrate up -config config.prod.json
environment:
name: production
deploy:
stage: deploy
script:
- ./bin/server
```
### GitHub Actions
```yaml
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Go
uses: actions/setup-go@v4
with:
go-version: '1.21'
- name: Build
run: |
go build -o bin/migrate cmd/migrate/main.go
go build -o bin/server cmd/server/main.go
- name: Create Config File
run: |
echo '${{ secrets.CONFIG_JSON }}' > config.json
- name: Run Migrations
run: ./bin/migrate up -config config.json
- name: Deploy
run: ./bin/server
```
---
## 📁 迁移文件管理
### 文件命名规则
```
migrations/
├── 20240101000001_create_users.sql # Up 迁移
├── 20240101000001_create_users.down.sql # Down 回滚（可选）
├── 20240102000001_add_posts.sql
└── 20240102000001_add_posts.down.sql
```
格式：`{时间戳}_{描述}.sql`
### 创建迁移文件
```bash
# 获取时间戳
date +%Y%m%d%H%M%S
# 输出：20240101120000
# 创建迁移文件
vim migrations/20240101120000_create_posts.sql
```
### 迁移文件示例
**Up 文件**：
```sql
-- migrations/20240101000001_create_users.sql
CREATE TABLE users (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(255) NOT NULL UNIQUE,
email VARCHAR(255) NOT NULL UNIQUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE INDEX idx_users_email ON users(email);
```
**Down 文件**（可选）：
```sql
-- migrations/20240101000001_create_users.down.sql
DROP INDEX idx_users_email ON users;
DROP TABLE IF EXISTS users;
```
### 兼容性建议
使用条件语句确保迁移可重复执行：
```sql
-- 创建表
CREATE TABLE IF NOT EXISTS users (...);
-- 添加列
ALTER TABLE posts ADD COLUMN IF NOT EXISTS author_id BIGINT;
-- 创建索引
CREATE INDEX IF NOT EXISTS idx_posts_author ON posts(author_id);
```
---
## 🔍 常见问题
### Q: 为什么不直接在应用代码中调用？
**A**: **耦合度太高！** 独立工具的优势：
- ✅ 应用和迁移完全解耦
- ✅ 可以独立部署和执行
- ✅ 更灵活的部署策略
- ✅ 符合单一职责原则
### Q: 生产环境没有Go怎么办？
**A**: **编译成二进制文件**！
```bash
# 本地或CI中编译
go build -o bin/migrate cmd/migrate/main.go
# 部署二进制文件（不需要Go环境）
scp bin/migrate server:/app/
ssh server "/app/migrate up"
```
### Q: Docker中修改配置需要重启吗？
**A**: **不需要！** 使用挂载方式：
```yaml
volumes:
- ./config.json:/app/config.json:ro
```
修改后直接执行：
```bash
docker-compose exec app ./migrate up
```
### Q: 如何指定不同的配置文件？
**A**: 使用命令行参数：
```bash
# 开发环境
./migrate up -config config.dev.json
# 测试环境
./migrate up -config config.test.json
# 生产环境
./migrate up -config /etc/app/config.prod.json
```
### Q: 多个实例同时启动会有问题吗？
**A**: 不会。数据库会保证只有一个实例能执行迁移（通过版本号主键）。
### Q: Docker连不上数据库？
**A**: 注意主机名：
- ❌ `localhost`（容器内无法访问宿主机）
- ✅ `db`（docker-compose 服务名）
- ✅ `host.docker.internal`（Mac/Windows 访问宿主机）
---
## 💡 最佳实践
### 1. 开发环境
- 使用 `go run` 快速迭代
- 使用配置文件管理不同环境
```bash
go run cmd/migrate/main.go up -config config.dev.json
```
### 2. 测试环境
- 编译后部署，模拟生产环境
- 使用独立的数据库
```bash
go build -o bin/migrate cmd/migrate/main.go
./bin/migrate up -config config.test.json
```
### 3. 生产环境
- 编译后部署，先执行迁移再启动应用
- 使用配置文件管理敏感信息
```bash
go build -o bin/migrate cmd/migrate/main.go
./bin/migrate up -config config.json
./bin/server
```
### 4. Docker 部署
- 多阶段构建，只包含二进制文件
- 挂载配置文件，灵活修改
```dockerfile
FROM golang:1.21 as builder
RUN go build -o bin/migrate cmd/migrate/main.go
FROM debian:bookworm-slim
COPY --from=builder /app/bin/migrate .
CMD ["sh", "-c", "./migrate up && ./server"]
```
### 5. CI/CD
- 在构建阶段编译
- 部署前执行迁移
```yaml
- build: go build -o bin/migrate cmd/migrate/main.go
- migrate: ./bin/migrate up
- deploy: ./bin/server
```
---
## 📊 推荐的项目结构
```
your-project/
├── cmd/
│ ├── migrate/
│ │ └── main.go # 迁移工具（独立）
│ └── server/
│ └── main.go # 应用主程序
├── migrations/ # 迁移SQL文件
│ ├── 20240101000001_create_users.sql
│ └── 20240101000001_create_users.down.sql
├── config.json # 配置文件
├── Dockerfile
├── docker-compose.yml
├── Makefile # 常用命令
└── go.mod
```
---
## 📚 更多资源
- [模板文件](./templates/) - 可直接复制的模板
- [完整文档](./docs/migration.md) - 详细功能文档
- [配置文档](./docs/config.md) - 配置说明
---
## 🎯 总结
使用 GoCommon 的迁移工具，你可以：
1. ✅ 复制一个模板文件到 `cmd/migrate/main.go`
2. ✅ 创建 SQL 迁移文件到 `migrations/`
3. ✅ 编译：`go build -o bin/migrate cmd/migrate/main.go`
4. ✅ 使用：`./bin/migrate up`
**核心优势**：
- 独立工具，零耦合
- 生产就绪，无需Go环境
- 灵活配置，支持多环境
- Docker友好，修改配置无需重启
**开箱即用，灵活强大！** 🎉

346
QUICKSTART.md
View File

@@ -1,346 +0,0 @@
# 快速开始指南
5分钟快速上手 GoCommon 工具库。
## 1. 安装
```bash
# 配置私有仓库
go env -w GOPRIVATE=git.toowon.com
# 安装最新版本
go get git.toowon.com/jimmy/go-common@latest
```
## 2. 创建配置文件
创建 `config.json`：
```json
{
"database": {
"type": "mysql",
"host": "localhost",
"port": 3306,
"user": "root",
"password": "password",
"database": "mydb"
},
"redis": {
"host": "localhost",
"port": 6379
},
"logger": {
"level": "info",
"output": "stdout",
"async": true
},
"rateLimit": {
"enable": true,
"rate": 100,
"period": 60,
"byIP": true
}
}
```
## 3. 创建主程序
创建 `main.go`：
```go
package main
import (
"net/http"
"time"
"git.toowon.com/jimmy/go-common/factory"
"git.toowon.com/jimmy/go-common/middleware"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
func main() {
// 从配置文件创建工厂（黑盒模式）
fac, err := factory.NewFactoryFromFile("./config.json")
if err != nil {
panic(err)
}
// 使用factory的黑盒方法获取中间件链
// 自动从配置文件读取并配置所有中间件
chain := fac.GetMiddlewareChain()
// （可选）如果项目需要额外的中间件，可以继续添加
// chain.Append(yourAuthMiddleware, yourMetricsMiddleware)
// 注册路由
http.Handle("/api/hello", chain.ThenFunc(handleHello))
http.Handle("/api/users", chain.ThenFunc(handleUsers))
// 启动服务
logger.Info("Server started on :8080")
http.ListenAndServe(":8080", nil)
}
// API处理器 - 问候接口
func handleHello(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
h.Success(map[string]interface{}{
"message": "Hello, World!",
"timezone": h.GetTimezone(),
})
}
// API处理器 - 用户列表（带分页）
func handleUsers(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
// 解析分页参数
pagination := h.ParsePaginationRequest()
page := pagination.GetPage()
size := pagination.GetSize()
// 模拟数据
users := []map[string]interface{}{
{"id": 1, "name": "Alice"},
{"id": 2, "name": "Bob"},
}
total := int64(100)
// 返回分页数据
h.SuccessPage(users, total, page, size)
}
```
## 4. 运行
```bash
go run main.go
```
## 5. 测试
```bash
# 测试问候接口
curl http://localhost:8080/api/hello
# 测试分页接口
curl "http://localhost:8080/api/users?page=1&page_size=10"
# 测试时区
curl -H "X-Timezone: America/New_York" http://localhost:8080/api/hello
# 测试限流（快速请求多次）
for i in {1..150}; do curl http://localhost:8080/api/hello; done
```
## 6. 常见使用场景
### 场景1：使用数据库
```go
// 获取数据库连接
db, _ := fac.GetDatabase()
// 使用GORM查询
var users []User
db.Find(&users)
```
### 场景2：使用Redis
```go
ctx := context.Background()
// 设置值
fac.RedisSet(ctx, "key", "value", time.Hour)
// 获取值
value, _ := fac.RedisGet(ctx, "key")
// 删除值
fac.RedisDelete(ctx, "key")
```
### 场景3：发送邮件
```go
// 发送简单邮件
fac.SendEmail(
[]string{"user@example.com"},
"测试邮件",
"这是邮件正文",
)
// 发送HTML邮件
fac.SendEmail(
[]string{"user@example.com"},
"测试邮件",
"纯文本内容",
"<h1>HTML内容</h1>",
)
```
### 场景4：上传文件
```go
ctx := context.Background()
// 打开文件
file, _ := os.Open("test.jpg")
defer file.Close()
// 上传文件（自动选择OSS或MinIO）
url, _ := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")
// 获取文件URL
url, _ := fac.GetFileURL("images/test.jpg", 3600) // 1小时后过期
```
### 场景5：记录日志
```go
// 简单日志
fac.LogInfo("用户登录成功")
fac.LogError("登录失败: %v", err)
// 带字段的日志
fac.LogInfof(map[string]interface{}{
"user_id": 123,
"action": "login",
}, "用户操作")
```
### 场景6：时间处理
```go
import "git.toowon.com/jimmy/go-common/datetime"
// 获取当前时间（带时区）
timezone := h.GetTimezone()
now := datetime.Now(timezone)
// 格式化时间
str := datetime.FormatDateTime(now)
// 解析时间
t, _ := datetime.ParseDateTime("2024-01-01 00:00:00", timezone)
// 时间计算
tomorrow := datetime.AddDays(now, 1)
startOfDay := datetime.StartOfDay(now, timezone)
```
### 场景7：数据库迁移（独立工具）⭐
```bash
# 1. 复制模板到项目
cp templates/migrate/main.go cmd/migrate/
# 2. 创建迁移文件 migrations/20240101000001_create_users.sql
# 3. 编译并使用
go build -o bin/migrate cmd/migrate/main.go
./bin/migrate up # 执行迁移
./bin/migrate status # 查看状态
```
**特点**：独立工具，零耦合，生产就绪
完整指南：[MIGRATION.md](./MIGRATION.md)
## 7. 更多文档
- [完整文档](./docs/README.md)
- [中间件文档](./docs/middleware.md)
- [工厂模式文档](./docs/factory.md)
- [HTTP工具文档](./docs/http.md)
- [配置文档](./docs/config.md)
## 常见问题
### Q: 如何自定义中间件配置？
查看 [中间件文档](./docs/middleware.md) 了解详细配置选项。
### Q: 如何使用数据库迁移？
查看 [迁移工具文档](./docs/migration.md) 了解数据库版本管理。
### Q: 支持哪些数据库？
支持 MySQL、PostgreSQL、SQLite。
### Q: 日志如何配置异步模式？
在配置文件中设置 `"async": true`，或通过代码配置：
```go
loggerConfig := &config.LoggerConfig{
Async: true,
BufferSize: 1000,
}
```
### Q: 如何添加自定义中间件？
```go
// 获取基础中间件链
chain := fac.GetMiddlewareChain()
// 添加自定义中间件
chain.Append(
yourAuthMiddleware, // 认证中间件
yourMetricsMiddleware, // 指标中间件
// 更多自定义中间件...
)
// 使用扩展后的中间件链
http.Handle("/api/secure", chain.ThenFunc(yourHandler))
```
自定义中间件示例：
```go
func authMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
token := r.Header.Get("Authorization")
if token == "" {
http.Error(w, "Unauthorized", 401)
return
}
// 验证token...
next.ServeHTTP(w, r)
})
}
```
### Q: 如何按用户ID限流？
在配置文件中设置：
```json
{
"rateLimit": {
"enable": true,
"rate": 100,
"period": 60,
"byUserID": true,
"byIP": false
}
}
```
中间件会自动从 `X-User-ID` header 中获取用户ID进行限流。
## 下一步
恭喜！你已经掌握了 GoCommon 的基本使用。
建议阅读：
1. [中间件文档](./docs/middleware.md) - 了解更多中间件配置
2. [工厂模式文档](./docs/factory.md) - 深入了解黑盒模式
3. [示例代码](./examples/) - 查看更多实际示例

434
README.md
View File

@@ -1,424 +1,56 @@
# GoCommon - Go 通用工具类库 # GoCommon - Go 通用工具类库
这是一个Go语言开发的通用工具类库，为其他Go项目提供常用的工具方法集合。 供其他 Go 项目引用的通用工具集合。业务项目对接请直接阅读：
**📖 快速链接**： **[业务项目对接操作手册（INTEGRATION.md）](./INTEGRATION.md)**
- [5分钟快速开始](./QUICKSTART.md)
- [数据库迁移指南](./MIGRATION.md) ⭐ 独立工具，零耦合，Docker友好
- [完整文档](./docs/README.md)
## 🌟 核心特性 ## 模块路径
### 🎯 **极简调用，减少80%重复代码**
- **工厂黑盒模式**：一个配置文件，搞定所有服务初始化
- **Handler黑盒模式**：统一的HTTP请求处理，无需重复传递 `w` 和 `r`
- **中间件链式调用**：一行代码组合多个中间件
### 🚀 **生产级特性，开箱即用**
- **异步日志**：不阻塞请求，高并发性能
- **Panic恢复**：自动捕获panic，防止服务崩溃
- **令牌桶限流**：保护API，防止滥用
- **时区自动处理**：统一管理时区，避免时间错乱
### 🔧 **灵活可扩展**
- **默认配置即可用**：传 `nil` 使用默认配置
- **完全可定制**：每个功能都支持自定义配置
- **无侵入设计**：可以独立使用任何模块
### 📦 **零外部依赖（核心功能）**
- email、sms 使用 Go 标准库实现
- 可选依赖：gorm（数据库）、redis、minio
## 功能模块
### 1. 数据库迁移工具 (migration)
提供数据库迁移功能，支持MySQL、PostgreSQL、SQLite等数据库。
**🎯 独立工具，零耦合**：
- ✅ 编译成独立二进制：`go build -o bin/migrate cmd/migrate/main.go`
- ✅ 生产环境无需Go环境，只需二进制文件
- ✅ 与应用代码完全解耦，可独立部署和执行
- ✅ 支持宿主机和Docker，零额外配置
### 2. 日期转换工具 (datetime)
提供日期时间转换功能，支持时区设定和多种格式转换。
### 3. HTTP Restful工具 (http)
提供HTTP请求/响应处理工具，包含标准化的响应结构、分页支持和HTTP状态码与业务状态码的分离。
### 4. 中间件工具 (middleware)
提供生产级HTTP中间件，包括：
- **CORS** - 跨域资源共享
- **Timezone** - 时区处理
- **Logging** - 请求日志记录（支持异步）
- **Recovery** - Panic恢复，防止服务崩溃
- **RateLimit** - 请求限流（令牌桶算法）
- **Chain** - 中间件链式组合
### 5. 配置工具 (config)
提供从外部文件加载配置的功能，支持数据库、OSS、Redis、CORS、MinIO等配置。
### 6. 存储工具 (storage)
提供文件上传和查看功能，支持本地文件夹（Local）、OSS 和 MinIO 三种存储方式，并提供HTTP处理器。
### 7. 邮件工具 (email)
提供SMTP邮件发送功能，支持纯文本和HTML邮件，使用Go标准库实现。
### 8. 短信工具 (sms)
提供阿里云短信发送功能，支持模板短信和批量发送，使用Go标准库实现。
### 9. Excel导出工具 (excel)
提供数据导出到Excel文件的功能，支持结构体切片、自定义格式化、多工作表等特性。
**功能特性**：
- 支持结构体切片自动导出
- 支持嵌套字段访问（如 "User.Name"）
- 支持自定义格式化函数
- 自动调整列宽和表头样式
- 支持导出到文件或HTTP响应
### 10. 工厂工具 (factory)
提供从配置文件直接创建已初始化客户端对象的功能，包括数据库、Redis、邮件、短信、日志、Excel等，避免调用方重复实现创建逻辑。
### 11. 日志工具 (logger)
提供统一的日志记录功能，支持多种日志级别和输出方式，使用Go标准库实现。
---
## 🎯 Factory 黑盒模式（核心设计）
**理念**：外部项目只需传递一个配置文件路径，直接使用黑盒方法，无需获取内部对象。
### 方法分类
| 类型 | 方法 | 使用方式 | 推荐度 |
|------|------|----------|--------|
| **黑盒方法（推荐）** | | | |
| 中间件 | `GetMiddlewareChain()` | 直接使用，可Append自定义中间件 | ⭐⭐⭐ |
| 日志 | `LogInfo()`, `LogError()` 等 | 直接调用，无需获取logger对象 | ⭐⭐⭐ |
| Redis | `RedisSet()`, `RedisGet()` 等 | 直接调用，覆盖常用操作 | ⭐⭐⭐ |
| 邮件 | `SendEmail()` | 直接调用 | ⭐⭐⭐ |
| 短信 | `SendSMS()` | 直接调用 | ⭐⭐⭐ |
| 存储 | `UploadFile()`, `GetFileURL()` | 直接调用 | ⭐⭐⭐ |
| Excel导出 | `ExportToExcel()`, `ExportToExcelFile()` | 直接调用 | ⭐⭐⭐ |
| **Get方法（高级功能）** | | | |
| 数据库 | `GetDatabase()` | 返回GORM对象，用于复杂查询 | ⭐⭐ |
| Redis高级 | `GetRedisClient()` | 返回Redis客户端，用于Hash/List/Set等 | ⭐ |
| Logger高级 | `GetLogger()` | 返回Logger对象，用于Close等 | ⭐ |
| 存储高级 | `GetStorage()` | 返回Storage对象，用于Delete/Exists/GetObject等 | ⭐ |
### 使用示例
```go
// 创建工厂（只需配置文件路径）
fac, _ := factory.NewFactoryFromFile("config.json")
// ====== 推荐使用黑盒方法 ======
fac.LogInfo("用户登录")
fac.RedisSet(ctx, "key", "value", time.Hour)
fac.SendEmail([]string{"user@example.com"}, "主题", "内容")
chain := fac.GetMiddlewareChain()
// ====== 仅在需要高级功能时获取对象 ======
db, _ := fac.GetDatabase() // 数据库操作复杂，使用GORM
db.Find(&users)
client, _ := fac.GetRedisClient() // Redis高级操作
client.HSet(ctx, "user:1", "name", "Alice")
``` ```
git.toowon.com/jimmy/go-common
--- ```
## 安装 ## 安装
### 1. 配置私有仓库（重要）
由于本项目使用私有 Git 仓库，需要先配置 `GOPRIVATE` 环境变量：
```bash ```bash
# 使用 go env 命令配置（推荐，永久生效）
go env -w GOPRIVATE=git.toowon.com go env -w GOPRIVATE=git.toowon.com
# 验证配置
go env GOPRIVATE
```
**详细配置说明请参考 [SETUP.md](./SETUP.md)**
**遇到问题？请查看 [故障排除指南](./TROUBLESHOOTING.md)**
### 2. 安装模块
```bash
# 安装最新版本（推荐用于开发）
go get git.toowon.com/jimmy/go-common@latest
# 安装特定版本（推荐用于生产）
go get git.toowon.com/jimmy/go-common@v1.0.0 go get git.toowon.com/jimmy/go-common@v1.0.0
``` ```
**版本管理说明请参考 [VERSION.md](./VERSION.md)** ## 设计概要
--- - **Factory**：入口，启动时初始化一次，按需 getter 获取模块对象（DB、Redis、Logger 等）
- **各模块包**：能力在对象方法上（`log.Info()`、`store.Upload()`）
- **http 包**：统一 HTTP 出参（Response / PageData / Handler）
- **migration**：独立 CLI 或 Factory 执行 SQL 迁移
- **tools**：无状态工具函数，直接 import
## 📚 文档导航 ## 功能模块
- **[快速开始指南](./QUICKSTART.md)** ⭐ - 5分钟快速上手 | 模块 | 包路径 | 说明 |
- [完整文档](./docs/README.md) - 所有模块详细文档 |------|--------|------|
- [故障排除](./TROUBLESHOOTING.md) - 常见问题解决 | 配置 | `config` | JSON 配置加载 |
- [版本管理](./VERSION.md) - 版本发布说明 | 工厂 | `factory` | 统一入口与 lazy getter |
| HTTP | `http` | 请求解析、统一响应 |
| 中间件 | `middleware` | CORS、日志、Recovery、限流、语种、时区 |
| 工具 | `tools` | 时间、加密、金额、类型转换 |
| 日志 | `logger` | 异步日志 |
| 存储 | `storage` | Local / OSS / MinIO |
| 邮件 / 短信 | `email` / `sms` | SMTP、阿里云短信 |
| Excel | `excel` | 数据导出 |
| 国际化 | `i18n` | 多语言消息 |
| 迁移 | `migration` | SQL 版本管理 |
--- ## 文档
## 快速开始 | 文档 | 说明 |
|------|------|
### 1. 创建配置文件 `config.json` | [INTEGRATION.md](./INTEGRATION.md) | 业务项目对接操作手册 |
| [VERSION.md](./VERSION.md) | 版本管理与发布 |
```json | [templates/](./templates/) | migrate 等脚手架模板 |
{ | [config/example.json](./config/example.json) | 配置文件示例 |
"database": { | [examples/](./examples/) | 代码示例 |
"type": "mysql",
"host": "localhost",
"port": 3306,
"user": "root",
"password": "password",
"database": "mydb"
},
"redis": {
"host": "localhost",
"port": 6379
},
"logger": {
"level": "info",
"output": "both",
"filePath": "./logs/app.log",
"async": true
}
}
```
### 2. 使用工厂黑盒模式（最简单，推荐）⭐
```go
package main
import (
"context"
"net/http"
"time"
"git.toowon.com/jimmy/go-common/factory"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
func main() {
// 只需传入配置文件路径
fac, _ := factory.NewFactoryFromFile("config.json")
// 获取配置好的中间件链（黑盒）
chain := fac.GetMiddlewareChain()
// （可选）添加自定义中间件
chain.Append(yourAuthMiddleware)
// 注册路由
http.Handle("/api/hello", chain.ThenFunc(handleHello))
http.ListenAndServe(":8080", nil)
}
func handleHello(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
fac, _ := factory.NewFactoryFromFile("config.json")
ctx := context.Background()
// 使用黑盒方法（无需获取对象）
fac.LogInfo("处理请求: /api/hello")
fac.RedisSet(ctx, "last_visit", time.Now().String(), time.Hour)
h.Success(map[string]interface{}{
"message": "Hello!",
"timezone": h.GetTimezone(),
})
}
```
### 3. 运行项目
```bash
go run main.go
# 访问 http://localhost:8080/api/hello
```
## 核心功能示例
详细文档请参考：[完整文档](./docs/README.md) | [快速开始](./QUICKSTART.md)
### 数据库迁移
```bash
# 编译独立工具
go build -o bin/migrate cmd/migrate/main.go
# 执行迁移
./bin/migrate up # 默认配置
./bin/migrate up -config /path/to/config.json # 指定配置
./bin/migrate status # 查看状态
```
**详细说明**：[数据库迁移指南](./MIGRATION.md) ⭐
### 工厂黑盒模式（推荐）
```go
import "git.toowon.com/jimmy/go-common/factory"
fac, _ := factory.NewFactoryFromFile("config.json")
// 中间件
chain := fac.GetMiddlewareChain()
chain.Append(yourAuthMiddleware) // 添加自定义中间件
// 日志
fac.LogInfo("用户登录成功")
// Redis
fac.RedisSet(ctx, "key", "value", time.Hour)
// 邮件/短信
fac.SendEmail([]string{"user@example.com"}, "主题", "内容")
fac.SendSMS([]string{"13800138000"}, map[string]string{"code": "123456"})
// 文件上传
url, _ := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")
// Excel导出
columns := []factory.ExportColumn{
{Header: "ID", Field: "ID", Width: 10},
{Header: "姓名", Field: "Name", Width: 20},
{Header: "邮箱", Field: "Email", Width: 30},
}
fac.ExportToExcelFile("users.xlsx", "用户列表", columns, users)
// 数据库（高级功能）
db, _ := fac.GetDatabase()
db.Find(&users)
```
### HTTP处理器
```go
import 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))
```
### 日期时间
**推荐方式：通过 factory 使用（黑盒模式）**
```go
import "git.toowon.com/jimmy/go-common/factory"
fac, _ := factory.NewFactoryFromFile("config.json")
now := fac.Now("Asia/Shanghai")
str := fac.FormatDateTime(now)
```
**或者直接使用 tools 包：**
```go
import "git.toowon.com/jimmy/go-common/tools"
tools.SetDefaultTimeZone(tools.AsiaShanghai)
now := tools.Now()
str := tools.FormatDateTime(now)
```
更多示例：[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)**
## 最佳实践
### 生产环境配置
```json
{
"logger": {
"async": true, // 开启异步日志
"bufferSize": 1000
},
"database": {
"maxOpenConns": 100, // 连接池配置
"maxIdleConns": 10,
"connMaxLifetime": 3600
},
"rateLimit": {
"enable": true, // 开启限流
"rate": 100,
"period": 60,
"byIP": true
}
}
```
### 使用建议
- ✅ 使用工厂黑盒模式，减少重复代码
- ✅ 生产环境开启异步日志和限流
- ✅ 配置Recovery中间件防止panic
- ✅ 明确指定CORS允许的源
- ❌ 避免在循环中创建logger
- ❌ 避免使用同步日志记录大量日志
## 故障排除
常见问题请查看 [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
## 贡献指南
欢迎贡献代码！请遵循以下步骤：
1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request
## 许可证 ## 许可证
MIT License MIT License
## 联系方式
- 作者：Jimmy
- 邮箱：jimmy@toowon.com
- 项目地址：git.toowon.com/jimmy/go-common
---
⭐ 如果这个项目对你有帮助，请给个 Star！

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. 联系项目维护者

14
VERSION.md
View File

@@ -126,11 +126,11 @@ go get -u=minor git.toowon.com/jimmy/go-common
## 版本历史 ## 版本历史
- **v1.0.0** (当前版本) - **v1.0.0** (当前版本)
- 初始版本 - 初始发布
- 包含所有基础工具类：migration、datetime、http、middleware、config、storage、email、sms、factory、logger - Factory：`Init` / `Default()` + lazy getter（`Logger`、`Database`、`Redis`、`Storage` 等）
- HTTP 出参统一由 `http.Handler` 负责
- **v1.1.0** (未发布) - Logger：`Debug/Info/Error(msg, fields)`，Request ID + `FromContext`，异步默认开启
- storage：新增本地文件夹存储（LocalStorage），支持将文件/图片上传到本地目录 - email / sms：异步队列 + `Close()`
- config：新增 `localStorage` 配置段（`baseDir` / `publicURL`） - 中间件链：Recovery → RequestID → Logging → RateLimit → CORS → Language → Timezone
- factory：新增 `GetStorage()`，并支持 Local/MinIO/OSS 自动选择（优先级：Local > MinIO > OSS） - 模块：migration、tools、middleware、config、storage（Local/MinIO/OSS）、email、sms、excel、i18n

94
config/config.go
View File

@@ -18,9 +18,16 @@ type Config struct {
Email *EmailConfig `json:"email"` Email *EmailConfig `json:"email"`
SMS *SMSConfig `json:"sms"` SMS *SMSConfig `json:"sms"`
Logger *LoggerConfig `json:"logger"` Logger *LoggerConfig `json:"logger"`
I18n *I18nConfig `json:"i18n"`
RateLimit *RateLimitConfig `json:"rateLimit"` RateLimit *RateLimitConfig `json:"rateLimit"`
} }
// I18nConfig 国际化配置
type I18nConfig struct {
DefaultLang string `json:"defaultLang"`
LocalesDir string `json:"localesDir"`
}
// LocalStorageConfig 本地存储配置 // LocalStorageConfig 本地存储配置
// 用于将文件保存到本地文件夹（适合开发环境、单机部署等场景） // 用于将文件保存到本地文件夹（适合开发环境、单机部署等场景）
type LocalStorageConfig struct { type LocalStorageConfig struct {
@@ -208,6 +215,23 @@ type EmailConfig struct {
// Timeout 连接超时时间（秒） // Timeout 连接超时时间（秒）
Timeout int `json:"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 短信配置（阿里云短信） // SMSConfig 短信配置（阿里云短信）
@@ -232,11 +256,28 @@ type SMSConfig struct {
// Timeout 请求超时时间（秒） // Timeout 请求超时时间（秒）
Timeout int `json:"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 日志配置 // LoggerConfig 日志配置
type LoggerConfig struct { type LoggerConfig struct {
// Level 日志级别: debug, info, warn, error // Level 日志级别: debug, info, error
Level string `json:"level"` Level string `json:"level"`
// Output 输出方式: stdout, stderr, file, both // Output 输出方式: stdout, stderr, file, both
@@ -251,16 +292,21 @@ type LoggerConfig struct {
// DisableTimestamp 禁用时间戳 // DisableTimestamp 禁用时间戳
DisableTimestamp bool `json:"disableTimestamp"` DisableTimestamp bool `json:"disableTimestamp"`
// Async 是否使用异步模式（默认false，即同步模式） // Async 是否使用异步模式（默认 true，省略时启用）
// 异步模式：日志写入通过channel异步处理，不阻塞调用方 Async *bool `json:"async"`
// 同步模式：日志直接写入，会阻塞调用方直到写入完成
Async bool `json:"async"`
// BufferSize 异步模式下的缓冲区大小（默认1000） // BufferSize 异步模式下的缓冲区大小（默认1000）
// 当缓冲区满时，新的日志会阻塞直到有空间
BufferSize int `json:"bufferSize"` BufferSize int `json:"bufferSize"`
} }
// IsAsync 是否启用异步（默认 true）
func (c *LoggerConfig) IsAsync() bool {
if c == nil || c.Async == nil {
return true
}
return *c.Async
}
// RateLimitConfig 限流配置 // RateLimitConfig 限流配置
type RateLimitConfig struct { type RateLimitConfig struct {
// Enable 是否启用限流 // Enable 是否启用限流
@@ -384,13 +430,19 @@ func (c *Config) setDefaults() {
// 邮件默认值 // 邮件默认值
if c.Email != nil { if c.Email != nil {
if c.Email.Port == 0 { if c.Email.Port == 0 {
c.Email.Port = 587 // 默认使用587端口（TLS） c.Email.Port = 587
} }
if c.Email.From == "" { if c.Email.From == "" {
c.Email.From = c.Email.Username c.Email.From = c.Email.Username
} }
if c.Email.Timeout == 0 { 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
} }
} }
@@ -400,7 +452,13 @@ func (c *Config) setDefaults() {
c.SMS.Region = "cn-hangzhou" c.SMS.Region = "cn-hangzhou"
} }
if c.SMS.Timeout == 0 { 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
} }
} }
@@ -412,6 +470,14 @@ func (c *Config) setDefaults() {
if c.Logger.Output == "" { if c.Logger.Output == "" {
c.Logger.Output = "stdout" 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"
} }
// 限流默认值 // 限流默认值
@@ -475,6 +541,11 @@ func (c *Config) GetLogger() *LoggerConfig {
return c.Logger return c.Logger
} }
// GetI18n 获取国际化配置
func (c *Config) GetI18n() *I18nConfig {
return c.I18n
}
// GetDatabaseDSN 获取数据库连接字符串 // GetDatabaseDSN 获取数据库连接字符串
func (c *Config) GetDatabaseDSN() (string, error) { func (c *Config) GetDatabaseDSN() (string, error) {
if c.Database == nil { if c.Database == nil {
@@ -549,3 +620,8 @@ func (c *Config) GetRedisAddr() string {
// 构建地址 // 构建地址
return fmt.Sprintf("%s:%d", c.Redis.Host, c.Redis.Port) return fmt.Sprintf("%s:%d", c.Redis.Host, c.Redis.Port)
} }
// BoolPtr 返回 bool 指针（用于配置默认值）
func BoolPtr(v bool) *bool {
return &v
}

150
docs/README.md
View File

@@ -1,150 +0,0 @@
# GoCommon 工具类库文档
## 目录
- [数据库迁移工具](./migration.md) - 数据库版本管理和迁移
- [完整使用指南](../MIGRATION.md) ⭐ - 独立工具，零耦合，Docker友好
- [日期转换工具](./datetime.md) - 日期时间处理和时区转换
- [HTTP Restful工具](./http.md) - HTTP请求响应处理和分页
- [中间件工具](./middleware.md) - 生产级HTTP中间件（CORS、时区、日志、Recovery、限流）
- [配置工具](./config.md) - 外部配置文件加载和管理
- [存储工具](./storage.md) - 文件上传和查看（OSS、MinIO）
- [邮件工具](./email.md) - SMTP邮件发送
- [短信工具](./sms.md) - 阿里云短信发送
- [Excel导出工具](./excel.md) - 数据导出到Excel文件
- [工厂工具](./factory.md) - 从配置直接创建已初始化客户端对象
- [日志工具](./logger.md) - 统一的日志记录功能
- [国际化工具](./i18n.md) - 多语言内容管理和国际化支持
## 快速开始
### 安装
```bash
go get git.toowon.com/jimmy/go-common
```
### 使用示例
#### 数据库迁移（独立工具，零耦合）
```bash
# 1. 复制模板：templates/migrate/main.go -> cmd/migrate/main.go
# 2. 创建迁移文件：migrations/20240101000001_create_users.sql
# 3. 开发环境
go run cmd/migrate/main.go up
# 4. 生产环境（编译后使用，推荐）
go build -o bin/migrate cmd/migrate/main.go
./bin/migrate up # 使用默认配置
./bin/migrate up -config /path/to/config.json # 指定配置
./bin/migrate status # 查看状态
# 5. Docker（挂载配置，修改无需重启）
# docker-compose.yml:
# volumes:
# - ./config.json:/app/config.json:ro
# command: sh -c "./migrate up && ./server"
```
**迁移文件示例**（`migrations/20240101000001_create_users.sql`）：
```sql
CREATE TABLE users (id BIGINT PRIMARY KEY AUTO_INCREMENT, ...);
```
**优势**：独立工具，零耦合，支持命令行参数，Docker友好
详细说明：[MIGRATION.md](../MIGRATION.md)
#### 日期转换
**推荐方式：通过 factory 使用（黑盒模式）**
```go
import "git.toowon.com/jimmy/go-common/factory"
fac, _ := factory.NewFactoryFromFile("config.json")
now := fac.Now("Asia/Shanghai")
str := fac.FormatDateTime(now)
```
**或者直接使用 tools 包：**
```go
import "git.toowon.com/jimmy/go-common/tools"
tools.SetDefaultTimeZone(tools.AsiaShanghai)
now := tools.Now()
str := tools.FormatDateTime(now)
```
#### HTTP响应（Factory黑盒模式，推荐）
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/factory"
"git.toowon.com/jimmy/go-common/tools"
)
func GetUser(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 获取查询参数（使用类型转换方法）
id := tools.ConvertInt64(r.URL.Query().Get("id"), 0)
// 返回成功响应
fac.Success(w, data)
}
http.HandleFunc("/user", GetUser)
```
#### 中间件（生产级配置）
```go
import (
"time"
"git.toowon.com/jimmy/go-common/middleware"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
// 完整的中间件链
chain := middleware.NewChain(
middleware.Recovery(nil), // Panic恢复
middleware.Logging(nil), // 请求日志
middleware.RateLimitByIP(100, time.Minute), // 限流
middleware.CORS(nil), // CORS
middleware.Timezone, // 时区
)
handler := chain.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
timezone := h.GetTimezone()
h.Success(data)
})
```
#### 配置管理
```go
import "git.toowon.com/jimmy/go-common/config"
// 从文件加载配置
cfg, err := config.LoadFromFile("./config.json")
// 获取各种配置
dsn, _ := cfg.GetDatabaseDSN()
redisAddr := cfg.GetRedisAddr()
corsConfig := cfg.GetCORS()
```
## 版本
v1.0.0
## 许可证
MIT

562
docs/config.md
View File

@@ -1,562 +0,0 @@
# 配置工具文档
## 概述
配置工具提供了从外部文件加载和管理应用配置的功能，支持数据库、LocalStorage、OSS、Redis、CORS、MinIO、邮件、短信等常用服务的配置。
## 功能特性
- 支持从外部JSON文件加载配置
- 支持数据库配置（MySQL、PostgreSQL、SQLite）
- 支持本地存储配置（LocalStorage，文件上传保存到本地文件夹）
- 支持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"
},
"localStorage": {
"baseDir": "./uploads",
"publicURL": "http://localhost:8080/file?key={objectKey}"
},
"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配置（返回config.CORSConfig类型）
configCORS := config.GetCORS()
// 转换为middleware.CORSConfig并使用CORS中间件
import "git.toowon.com/jimmy/go-common/middleware"
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(middlewareCORS),
)
```
### 6. 获取MinIO配置
```go
minioConfig := config.GetMinIO()
if minioConfig != nil {
fmt.Printf("MinIO Endpoint: %s\n", minioConfig.Endpoint)
fmt.Printf("Bucket: %s\n", minioConfig.Bucket)
}
```
### 6.1 获取本地存储配置（LocalStorage）
```go
localCfg := config.GetLocalStorage()
if localCfg != nil {
fmt.Printf("Local baseDir: %s\n", localCfg.BaseDir)
fmt.Printf("Local publicURL: %s\n", localCfg.PublicURL)
}
```
## 配置项说明
### 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 | 自定义域名 |
### LocalStorageConfig 本地存储配置
| 字段 | 类型 | 说明 |
|------|------|------|
| BaseDir | string | 本地文件保存根目录（必填） |
| PublicURL | string | 对外访问 URL（可选）。包含 `{objectKey}` 占位符时会替换为 `url.QueryEscape(objectKey)`；不包含时作为 URL 前缀拼接 |
### 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配置
configCORS := cfg.GetCORS()
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(middlewareCORS),
)
// 使用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`

596
docs/datetime.md
View File

@@ -1,596 +0,0 @@
# 日期转换工具文档
## 概述
日期转换工具提供了丰富的日期时间处理功能，支持时区设定、格式转换、时间计算等常用操作。
**重要说明**：日期时间功能位于 `tools` 包中，推荐通过 `factory` 包使用（黑盒模式），也可以直接使用 `tools` 包。
## 功能特性
- 支持时区设定和转换
- 支持多种时间格式的解析和格式化
- 提供常用时间格式常量
- 支持Unix时间戳转换
- 提供时间计算功能（添加天数、月数、年数等）
- 提供时间范围获取功能（开始/结束时间）
- 支持将任意时区时间转换为UTC时间（用于数据库存储）
## 使用方法
### 方式1：通过 factory 使用（推荐，黑盒模式）
```go
import "git.toowon.com/jimmy/go-common/factory"
// 创建工厂
fac, _ := factory.NewFactoryFromFile("config.json")
// 获取当前时间
now := fac.Now("Asia/Shanghai")
// 格式化时间
str := fac.FormatDateTime(now)
// 解析时间
t, _ := fac.ParseDateTime("2024-01-01 12:00:00", "Asia/Shanghai")
// 时间计算
tomorrow := fac.AddDays(now, 1)
```
### 方式2：直接使用 tools 包
```go
import "git.toowon.com/jimmy/go-common/tools"
// 设置默认时区为上海时区
err := tools.SetDefaultTimeZone(tools.AsiaShanghai)
if err != nil {
log.Fatal(err)
}
```
### 2. 获取当前时间
**通过 factory：**
```go
// 使用默认时区
now := fac.Now()
// 使用指定时区
now := fac.Now("Asia/Shanghai")
now := fac.Now("America/New_York")
```
**直接使用 tools：**
```go
// 使用默认时区
now := tools.Now()
// 使用指定时区
now := tools.Now(tools.AsiaShanghai)
now := tools.Now("America/New_York")
```
### 3. 解析时间字符串
**通过 factory：**
```go
// 使用默认时区解析
t, err := fac.ParseDateTime("2024-01-01 12:00:00")
// 使用指定时区解析
t, err := fac.ParseDateTime("2024-01-01 12:00:00", "Asia/Shanghai")
// 解析日期
t, err := fac.ParseDate("2024-01-01")
```
**直接使用 tools：**
```go
// 使用默认时区解析
t, err := tools.Parse("2006-01-02 15:04:05", "2024-01-01 12:00:00")
// 使用指定时区解析
t, err := tools.Parse("2006-01-02 15:04:05", "2024-01-01 12:00:00", tools.AsiaShanghai)
// 使用常用格式解析
t, err := tools.ParseDateTime("2024-01-01 12:00:00")
t, err := tools.ParseDate("2024-01-01")
```
### 4. 格式化时间
**通过 factory：**
```go
t := time.Now()
// 使用默认时区格式化
str := fac.FormatDateTime(t)
str := fac.FormatDate(t)
str := fac.FormatTime(t)
// 使用指定时区格式化
str := fac.FormatDateTime(t, "Asia/Shanghai")
```
**直接使用 tools：**
```go
t := time.Now()
// 使用默认时区格式化
str := tools.Format(t, "2006-01-02 15:04:05")
// 使用指定时区格式化
str := tools.Format(t, "2006-01-02 15:04:05", tools.AsiaShanghai)
// 使用常用格式
str := tools.FormatDateTime(t) // "2006-01-02 15:04:05"
str := tools.FormatDate(t) // "2006-01-02"
str := tools.FormatTime(t) // "15:04:05"
```
### 5. 时区转换
**通过 factory：**
```go
t := time.Now()
t2, err := tools.ToTimezone(t, "Asia/Shanghai")
```
**直接使用 tools：**
```go
t := time.Now()
t2, err := tools.ToTimezone(t, tools.AsiaShanghai)
```
### 6. Unix时间戳转换
**通过 factory：**
```go
t := time.Now()
// 转换为Unix时间戳（秒）
unix := fac.ToUnix(t)
// 从Unix时间戳创建时间
t2 := fac.FromUnix(unix)
// 转换为Unix毫秒时间戳
unixMilli := fac.ToUnixMilli(t)
// 从Unix毫秒时间戳创建时间
t3 := fac.FromUnixMilli(unixMilli)
```
**直接使用 tools：**
```go
t := time.Now()
// 转换为Unix时间戳（秒）
unix := tools.ToUnix(t)
// 从Unix时间戳创建时间
t2 := tools.FromUnix(unix)
// 转换为Unix毫秒时间戳
unixMilli := tools.ToUnixMilli(t)
// 从Unix毫秒时间戳创建时间
t3 := tools.FromUnixMilli(unixMilli)
```
### 7. 时间计算
**通过 factory：**
```go
t := time.Now()
// 添加天数
t1 := fac.AddDays(t, 7)
// 添加月数
t2 := fac.AddMonths(t, 1)
// 添加年数
t3 := fac.AddYears(t, 1)
```
**直接使用 tools：**
```go
t := time.Now()
// 添加天数
t1 := tools.AddDays(t, 7)
// 添加月数
t2 := tools.AddMonths(t, 1)
// 添加年数
t3 := tools.AddYears(t, 1)
```
### 8. 时间范围获取
**通过 factory：**
```go
t := time.Now()
// 获取一天的开始时间（00:00:00）
start := fac.StartOfDay(t)
// 获取一天的结束时间（23:59:59.999999999）
end := fac.EndOfDay(t)
// 获取月份的开始时间
monthStart := fac.StartOfMonth(t)
// 获取月份的结束时间
monthEnd := fac.EndOfMonth(t)
// 获取年份的开始时间
yearStart := fac.StartOfYear(t)
// 获取年份的结束时间
yearEnd := fac.EndOfYear(t)
```
**直接使用 tools：**
```go
t := time.Now()
// 获取一天的开始时间（00:00:00）
start := tools.StartOfDay(t)
// 获取一天的结束时间（23:59:59.999999999）
end := tools.EndOfDay(t)
// 获取月份的开始时间
monthStart := tools.StartOfMonth(t)
// 获取月份的结束时间
monthEnd := tools.EndOfMonth(t)
// 获取年份的开始时间
yearStart := tools.StartOfYear(t)
// 获取年份的结束时间
yearEnd := tools.EndOfYear(t)
```
### 9. 时间差计算
**通过 factory：**
```go
t1 := time.Now()
t2 := time.Now().Add(24 * time.Hour)
// 计算天数差
days := fac.DiffDays(t1, t2)
// 计算小时差
hours := fac.DiffHours(t1, t2)
// 计算分钟差
minutes := fac.DiffMinutes(t1, t2)
// 计算秒数差
seconds := fac.DiffSeconds(t1, t2)
```
**直接使用 tools：**
```go
t1 := time.Now()
t2 := time.Now().Add(24 * time.Hour)
// 计算天数差
days := tools.DiffDays(t1, t2)
// 计算小时差
hours := tools.DiffHours(t1, t2)
// 计算分钟差
minutes := tools.DiffMinutes(t1, t2)
// 计算秒数差
seconds := tools.DiffSeconds(t1, t2)
```
### 10. 转换为UTC时间（用于数据库存储）
**直接使用 tools（factory 暂未提供）：**
```go
// 将任意时区的时间转换为UTC
t := time.Now() // 当前时区的时间
utcTime := tools.ToUTC(t)
// 从指定时区转换为UTC
t, _ := tools.ParseDateTime("2024-01-01 12:00:00", tools.AsiaShanghai)
utcTime, err := tools.ToUTCFromTimezone(t, tools.AsiaShanghai)
// 解析时间字符串并直接转换为UTC
utcTime, err := tools.ParseDateTimeToUTC("2024-01-01 12:00:00", tools.AsiaShanghai)
// 解析日期并转换为UTC（当天的00:00:00 UTC）
utcTime, err := tools.ParseDateToUTC("2024-01-01", tools.AsiaShanghai)
```
## API 参考
### 时区常量
**通过 tools 包使用：**
```go
import "git.toowon.com/jimmy/go-common/tools"
const (
tools.UTC = "UTC"
tools.AsiaShanghai = "Asia/Shanghai"
tools.AmericaNewYork = "America/New_York"
tools.EuropeLondon = "Europe/London"
tools.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
```
### 主要函数
**注意**：以下函数可以通过 `factory` 或 `tools` 包调用。推荐使用 `factory` 的黑盒模式。
#### SetDefaultTimeZone(timezone string) error
设置默认时区（仅 tools 包提供）。
**参数：**
- `timezone`: 时区字符串，如 "Asia/Shanghai"
**返回：** 错误信息
**使用方式：**
```go
tools.SetDefaultTimeZone(tools.AsiaShanghai)
```
#### Now(timezone ...string) time.Time
获取当前时间。
**参数：**
- `timezone`: 可选，时区字符串，不指定则使用默认时区
**返回：** 时间对象
**使用方式：**
```go
// 通过 factory
now := fac.Now("Asia/Shanghai")
// 直接使用 tools
now := tools.Now(tools.AsiaShanghai)
```
#### ParseDateTime(value string, timezone ...string) (time.Time, error)
解析日期时间字符串（2006-01-02 15:04:05）。
**参数：**
- `value`: 时间字符串
- `timezone`: 可选，时区字符串
**返回：** 时间对象和错误信息
**使用方式：**
```go
// 通过 factory
t, err := fac.ParseDateTime("2024-01-01 12:00:00", "Asia/Shanghai")
// 直接使用 tools
t, err := tools.ParseDateTime("2024-01-01 12:00:00", tools.AsiaShanghai)
```
#### FormatDateTime(t time.Time, timezone ...string) string
格式化日期时间（2006-01-02 15:04:05）。
**参数：**
- `t`: 时间对象
- `timezone`: 可选，时区字符串
**返回：** 格式化后的时间字符串
**使用方式：**
```go
// 通过 factory
str := fac.FormatDateTime(t, "Asia/Shanghai")
// 直接使用 tools
str := tools.FormatDateTime(t, tools.AsiaShanghai)
```
更多函数请参考 `factory` 包或 `tools` 包的 API 文档。
### 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：通过 factory 使用（推荐）
```go
package main
import (
"fmt"
"log"
"git.toowon.com/jimmy/go-common/factory"
)
func main() {
// 创建工厂
fac, err := factory.NewFactoryFromFile("config.json")
if err != nil {
log.Fatal(err)
}
// 获取当前时间
now := fac.Now("Asia/Shanghai")
fmt.Printf("Current time: %s\n", fac.FormatDateTime(now))
// 解析时间
t, err := fac.ParseDateTime("2024-01-01 12:00:00", "Asia/Shanghai")
if err != nil {
log.Fatal(err)
}
// 格式化时间
fmt.Printf("Parsed time: %s\n", fac.FormatDateTime(t))
// 时间计算
tomorrow := fac.AddDays(now, 1)
fmt.Printf("Tomorrow: %s\n", fac.FormatDate(tomorrow))
}
```
### 示例2：直接使用 tools 包
```go
package main
import (
"fmt"
"log"
"git.toowon.com/jimmy/go-common/tools"
)
func main() {
// 设置默认时区
err := tools.SetDefaultTimeZone(tools.AsiaShanghai)
if err != nil {
log.Fatal(err)
}
// 获取当前时间
now := tools.Now()
fmt.Printf("Current time: %s\n", tools.FormatDateTime(now))
// 时区转换
t, _ := tools.ParseDateTime("2024-01-01 12:00:00")
t2, _ := tools.ToTimezone(t, tools.AmericaNewYork)
fmt.Printf("Time in New York: %s\n", tools.FormatDateTime(t2))
}
```
### 示例3：UTC转换（数据库存储场景）
```go
package main
import (
"fmt"
"log"
"git.toowon.com/jimmy/go-common/tools"
)
func main() {
// 从请求中获取时间（假设是上海时区）
requestTimeStr := "2024-01-01 12:00:00"
requestTimezone := tools.AsiaShanghai
// 转换为UTC时间（用于数据库存储）
dbTime, err := tools.ParseDateTimeToUTC(requestTimeStr, requestTimezone)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Request time (Shanghai): %s\n", requestTimeStr)
fmt.Printf("Database time (UTC): %s\n", tools.FormatDateTime(dbTime, tools.UTC))
// 从数据库读取UTC时间，转换为用户时区显示
userTimezone := tools.AsiaShanghai
displayTime, err := tools.ToTimezone(dbTime, userTimezone)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Display time (Shanghai): %s\n", tools.FormatDateTime(displayTime, userTimezone))
}
```
完整示例请参考 `factory` 包中的 datetime 相关方法，通过 `factory` 调用 `tools` 包中的 datetime 功能。

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`

447
docs/excel.md
View File

@@ -1,447 +0,0 @@
# Excel导出工具文档
## 概述
Excel导出工具提供了将数据导出到Excel文件的功能，支持结构体切片、自定义格式化、多工作表等特性。通过工厂模式，外部项目可以方便地使用Excel导出功能。
## 功能特性
- **黑盒模式**：提供直接调用的方法，无需获取Excel对象
- **延迟初始化**：Excel导出器在首次使用时才创建
- **支持结构体切片**：自动将结构体切片转换为Excel行数据
- **支持嵌套字段**：支持访问嵌套结构体字段（如 "User.Name"）
- **自定义格式化**：支持自定义字段值的格式化函数
- **自动列宽**：自动调整列宽以适应内容
- **表头样式**：自动应用表头样式（加粗、背景色等）
- **智能工作表管理**：自动处理工作表的创建和删除，避免产生空sheet
- **ExportData接口**：支持实现ExportData接口进行高级定制
- **空数据处理**：即使数据为空（nil或空切片），也会正常生成表头
- **统一接口**：只暴露 `ExportToWriter` 一个核心方法
## 使用方法
### 1. 创建工厂
```go
import "git.toowon.com/jimmy/go-common/factory"
// 从配置文件创建
fac, err := factory.NewFactoryFromFile("./config.json")
// 或Excel导出不需要配置，可以传nil
fac := factory.NewFactory(nil)
```
### 2. 导出结构体切片到文件
```go
// 定义结构体
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"`
}
// 准备数据
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: 1},
}
// 定义导出列
columns := []factory.ExportColumn{
{Header: "ID", Field: "ID", Width: 10},
{Header: "姓名", Field: "Name", Width: 20},
{Header: "邮箱", Field: "Email", Width: 30},
{Header: "创建时间", Field: "CreatedAt", Width: 20},
{Header: "状态", Field: "Status", Width: 10},
}
// 导出到文件
err := fac.ExportToExcelFile("users.xlsx", "用户列表", columns, users)
if err != nil {
log.Fatal(err)
}
```
### 3. 导出到HTTP响应
```go
import "net/http"
func exportUsersHandler(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("./config.json")
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: 1},
}
columns := []factory.ExportColumn{
{Header: "ID", Field: "ID"},
{Header: "姓名", Field: "Name"},
{Header: "邮箱", Field: "Email"},
}
// 设置HTTP响应头
w.Header().Set("Content-Type", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
w.Header().Set("Content-Disposition", "attachment; filename=users.xlsx")
// 导出到响应
err := fac.ExportToExcel(w, "用户列表", columns, users)
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
}
```
### 4. 使用格式化函数
```go
import "git.toowon.com/jimmy/go-common/excel"
columns := []factory.ExportColumn{
{Header: "ID", Field: "ID", Width: 10},
{Header: "姓名", Field: "Name", Width: 20},
{
Header: "创建时间",
Field: "CreatedAt",
Width: 20,
Format: excel.AdaptTimeFormatter(tools.FormatDateTime), // 使用适配器直接调用tools函数
},
{
Header: "状态",
Field: "Status",
Width: 10,
Format: func(value interface{}) string {
// 自定义格式化函数
if status, ok := value.(int); ok {
if status == 1 {
return "启用"
}
return "禁用"
}
return ""
},
},
}
err := fac.ExportToExcelFile("users.xlsx", "用户列表", columns, users)
```
### 5. 使用ExportData接口（高级功能）
```go
// 实现ExportData接口
type UserExportData struct {
users []User
}
// GetExportColumns 获取导出列定义
func (d *UserExportData) GetExportColumns() []excel.ExportColumn {
return []excel.ExportColumn{
{Header: "ID", Field: "ID", Width: 10},
{Header: "姓名", Field: "Name", Width: 20},
{Header: "邮箱", Field: "Email", Width: 30},
}
}
// GetExportRows 获取导出数据行
func (d *UserExportData) GetExportRows() [][]interface{} {
rows := make([][]interface{}, 0, len(d.users))
for _, user := range d.users {
row := []interface{}{
user.ID,
user.Name,
user.Email,
}
rows = append(rows, row)
}
return rows
}
// 使用
exportData := &UserExportData{users: users}
columns := exportData.GetExportColumns()
err := fac.ExportToExcelFile("users.xlsx", "用户列表", columns, exportData)
```
### 6. 获取Excel对象（高级功能）
```go
// 获取Excel导出器对象（仅在需要高级功能时使用）
excel, err := fac.GetExcel()
if err != nil {
log.Fatal(err)
}
// 获取excelize.File对象，用于高级操作
file := excel.GetFile()
// 创建多个工作表
file.NewSheet("Sheet2")
file.SetCellValue("Sheet2", "A1", "数据")
// 自定义样式
style, _ := file.NewStyle(&excelize.Style{
Font: &excelize.Font{
Bold: true,
Size: 14,
},
})
file.SetCellStyle("Sheet2", "A1", "A1", style)
```
## API 参考
### 工厂方法
#### ExportToExcel(w io.Writer, sheetName string, columns []ExportColumn, data interface{}) error
导出数据到Writer。
**参数：**
- `w`: Writer对象（如http.ResponseWriter）
- `sheetName`: 工作表名称（可选，默认为"Sheet1"）
- `columns`: 列定义
- `data`: 数据列表（可以是结构体切片或实现了ExportData接口的对象）
**返回：** 错误信息
**数据为空处理：**
- 支持 `nil`、空切片、指针类型等空数据情况
- 即使数据为空，表头也会正常生成
**工作表处理逻辑：**
- 如果 `sheetName` 为空，默认使用 "Sheet1"
- 如果指定的工作表不存在，会自动创建
- 使用自定义名称时会自动删除默认的"Sheet1"，避免产生空sheet
**示例：**
```go
fac.ExportToExcel(w, "用户列表", columns, users)
fac.ExportToExcel(w, "空数据", columns, []User{}) // 空数据也会生成表头
```
#### ExportToExcelFile(filePath string, sheetName string, columns []ExportColumn, data interface{}) error
导出数据到文件。
**参数：**
- `filePath`: 文件路径
- `sheetName`: 工作表名称（可选，默认为"Sheet1"）
- `columns`: 列定义
- `data`: 数据列表（可以是结构体切片或实现了ExportData接口的对象）
**返回：** 错误信息
**实现说明：**
- 此方法内部创建文件并调用 `ExportToWriter`
- 文件相关的封装由工厂方法处理
**工作表处理逻辑：**
- 如果 `sheetName` 为空，默认使用 "Sheet1"
- 如果指定的工作表不存在，会自动创建
- 使用自定义名称时会自动删除默认的"Sheet1"，避免产生空sheet
**示例：**
```go
fac.ExportToExcelFile("users.xlsx", "用户列表", columns, users)
fac.ExportToExcelFile("empty.xlsx", "空数据", columns, []User{}) // 空数据也会生成表头
```
### 高级方法
#### GetExcel() (*excel.Excel, error)
获取Excel导出器对象。
**返回：** Excel导出器对象和错误信息
**说明：** 仅在需要使用高级功能时使用，推荐使用黑盒方法
### 结构体类型
#### ExportColumn
导出列定义。
```go
type ExportColumn struct {
Header string // 表头名称
Field string // 数据字段名（支持嵌套字段，如 "User.Name"）
Width float64 // 列宽（可选，0表示自动）
Format func(interface{}) string // 格式化函数（可选）
}
```
**字段说明：**
- `Header`: 表头显示的名称
- `Field`: 数据字段名，支持嵌套字段（如 "User.Name"）
- `Width`: 列宽，0表示自动调整
- `Format`: 格式化函数，用于自定义字段值的显示格式
### 格式化函数适配器
#### excel.AdaptTimeFormatter(fn func(time.Time, ...string) string) func(interface{}) string
适配器函数：将tools包的格式化函数转换为Excel Format字段需要的函数类型。
**参数：**
- `fn`: tools包的格式化函数（如 `tools.FormatDate`、`tools.FormatDateTime` 等）
**返回：** Excel Format字段需要的格式化函数
**说明：**
- 允许直接使用tools包的任何格式化函数
**示例：**
```go
import (
"git.toowon.com/jimmy/go-common/excel"
"git.toowon.com/jimmy/go-common/tools"
)
// 使用tools.FormatDate
Format: excel.AdaptTimeFormatter(tools.FormatDate)
// 使用tools.FormatDateTime
Format: excel.AdaptTimeFormatter(tools.FormatDateTime)
// 使用tools.FormatTime
Format: excel.AdaptTimeFormatter(tools.FormatTime)
// 使用自定义格式化函数
Format: excel.AdaptTimeFormatter(func(t time.Time) string {
return tools.Format(t, "2006-01-02 15:04:05", "Asia/Shanghai")
})
```
### ExportData接口
实现此接口的结构体可以直接导出。
```go
type ExportData interface {
// GetExportColumns 获取导出列定义
GetExportColumns() []ExportColumn
// GetExportRows 获取导出数据行
GetExportRows() [][]interface{}
}
```
## 完整示例
```go
package main
import (
"net/http"
"time"
"git.toowon.com/jimmy/go-common/excel"
"git.toowon.com/jimmy/go-common/factory"
)
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 exportUsersHandler(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("./config.json")
// 从数据库或其他数据源获取数据
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: 1},
}
// 定义导出列
columns := []factory.ExportColumn{
{Header: "ID", Field: "ID", Width: 10},
{Header: "姓名", Field: "Name", Width: 20},
{Header: "邮箱", Field: "Email", Width: 30},
{
Header: "创建时间",
Field: "CreatedAt",
Width: 20,
Format: excel.AdaptTimeFormatter(tools.FormatDateTime),
},
{
Header: "状态",
Field: "Status",
Width: 10,
Format: func(value interface{}) string {
if status, ok := value.(int); ok {
if status == 1 {
return "启用"
}
return "禁用"
}
return ""
},
},
}
// 设置HTTP响应头
w.Header().Set("Content-Type", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
w.Header().Set("Content-Disposition", "attachment; filename=users.xlsx")
// 导出到响应
err := fac.ExportToExcel(w, "用户列表", columns, users)
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
}
func main() {
http.HandleFunc("/export/users", exportUsersHandler)
http.ListenAndServe(":8080", nil)
}
```
## 设计优势
1. **降低复杂度**：调用方无需关心Excel文件对象的创建和管理
2. **延迟初始化**：Excel导出器在首次使用时才创建
3. **统一接口**：所有操作通过工厂方法调用
4. **灵活扩展**：支持结构体切片、自定义格式化、ExportData接口等多种方式
5. **自动优化**：自动调整列宽、应用表头样式等
## 注意事项
1. **配置**：Excel导出不需要配置，可以传nil创建工厂
2. **错误处理**：所有方法都可能返回错误，需要正确处理
3. **延迟初始化**：Excel导出器在首次使用时才创建，首次调用可能稍慢
4. **字段名匹配**：Field字段名必须与结构体字段名匹配（区分大小写）
5. **嵌套字段**：支持嵌套字段访问（如 "User.Name"），但需要确保字段路径正确
6. **格式化函数**：格式化函数返回的字符串会直接写入Excel单元格
7. **列宽设置**：Width为0时会自动调整列宽，但可能影响性能（大数据量时建议设置固定宽度）
8. **工作表处理**：工具会自动处理工作表的创建和删除，确保不会产生空sheet
9. **空数据处理**：即使数据为 `nil` 或空切片，表头也会正常生成
10. **方法设计**：
- `excel` 包只暴露 `ExportToWriter` 一个核心方法
- 文件相关的封装由工厂方法 `ExportToExcelFile` 处理
## 最佳实践
1. **使用工厂方法**：推荐使用 `ExportToExcel()` 和 `ExportToExcelFile()`
2. **设置列宽**：对于大数据量，建议设置固定列宽以提高性能
3. **使用格式化函数**：对于日期时间、状态等字段，使用格式化函数提高可读性
4. **错误处理**：始终检查导出方法的返回值
5. **HTTP响应**：导出到HTTP响应时，记得设置正确的Content-Type和Content-Disposition头
6. **工作表命名**：推荐使用有意义的工作表名称，工具会自动处理工作表的创建和删除
7. **空数据场景**：即使查询结果为空，也可以导出包含表头的Excel文件
## 示例
完整示例请参考 `examples/excel_example.go`

1251
docs/factory.md
View File

File diff suppressed because it is too large Load Diff

765
docs/http.md
View File

@@ -1,765 +0,0 @@
# HTTP Restful工具文档
## 概述
HTTP Restful工具提供了标准化的HTTP请求和响应处理功能，提供公共方法供外部调用，保持低耦合。
## 功能特性
- **低耦合设计**：提供公共方法，不封装Handler结构
- **标准化的响应结构**：`{code, message, timestamp, data}`
- **分离HTTP状态码和业务状态码**
- **支持分页响应**
- **提供便捷的请求参数解析方法**
- **支持JSON请求体解析**
- **Factory黑盒模式**：推荐使用 `factory.Success()` 等方法
## 响应结构
### 标准响应结构
```json
{
"code": 0,
"message": "success",
"timestamp": 1704067200,
"data": {}
}
```
**结构体类型（暴露在 factory 中）：**
```go
// 在 factory 包中可以直接使用
type Response struct {
Code int `json:"code"` // 业务状态码，0表示成功
Message string `json:"message"` // 响应消息
Timestamp int64 `json:"timestamp"` // 时间戳
Data interface{} `json:"data"` // 响应数据
}
```
### 分页响应结构
```json
{
"code": 0,
"message": "success",
"timestamp": 1704067200,
"data": {
"list": [],
"total": 100,
"page": 1,
"pageSize": 10
}
}
```
**结构体类型（暴露在 factory 中）：**
```go
// 在 factory 包中可以直接使用
type PageData struct {
List interface{} `json:"list"` // 数据列表
Total int64 `json:"total"` // 总记录数
Page int `json:"page"` // 当前页码
PageSize int `json:"pageSize"` // 每页大小
}
type PageResponse struct {
Code int `json:"code"`
Message string `json:"message"`
Timestamp int64 `json:"timestamp"`
Data *PageData `json:"data"`
}
```
### 使用暴露的结构体
外部项目可以直接使用 `factory.Response`、`factory.PageData` 等类型：
```go
import "git.toowon.com/jimmy/go-common/factory"
// 创建标准响应对象
response := factory.Response{
Code: 0,
Message: "success",
Data: userData,
}
// 创建分页数据对象
pageData := &factory.PageData{
List: users,
Total: 100,
Page: 1,
PageSize: 20,
}
// 传递给 Success 方法
fac.Success(w, pageData)
```
## 使用方法
### 方式一：使用Factory黑盒方法（推荐）⭐
这是最简单的方式，直接使用 `factory.Success()` 等方法：
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/factory"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/tools"
)
func GetUser(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 获取查询参数（使用类型转换方法）
id := tools.ConvertInt64(r.URL.Query().Get("id"), 0)
// 返回成功响应（使用factory方法）
fac.Success(w, data)
}
func CreateUser(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 解析JSON（使用公共方法）
var req struct {
Name string `json:"name"`
}
if err := commonhttp.ParseJSON(r, &req); err != nil {
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
// 返回成功响应（使用factory方法）
fac.Success(w, data, "创建成功")
}
func GetUserList(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 获取分页参数（使用factory方法，推荐）
pagination := fac.ParsePaginationRequest(r)
page := pagination.GetPage()
pageSize := pagination.GetPageSize()
// 获取查询参数（直接使用HTTP原生方法）
keyword := r.URL.Query().Get("keyword")
// 查询数据
list, total := getDataList(keyword, page, pageSize)
// 返回分页响应（使用factory方法）
fac.SuccessPage(w, list, total, page, pageSize)
}
// 注册路由
http.HandleFunc("/user", GetUser)
http.HandleFunc("/users", GetUserList)
```
### 方式二：直接使用公共方法
如果不想使用Factory，可以直接使用 `http` 包的公共方法：
```go
import (
"net/http"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/tools"
)
func GetUser(w http.ResponseWriter, r *http.Request) {
// 获取查询参数
id := tools.ConvertInt64(r.URL.Query().Get("id"), 0)
// 返回成功响应
commonhttp.Success(w, data)
}
func CreateUser(w http.ResponseWriter, r *http.Request) {
// 解析JSON
var req struct {
Name string `json:"name"`
}
if err := commonhttp.ParseJSON(r, &req); err != nil {
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
// 返回成功响应
commonhttp.Success(w, data, "创建成功")
}
```
### 成功响应
```go
// 使用Factory（推荐）
fac.Success(w, data) // 只有数据，使用默认消息 "success"
fac.Success(w, data, "操作成功") // 数据+消息
// 或直接使用公共方法
commonhttp.Success(w, data) // 只有数据
commonhttp.Success(w, data, "操作成功") // 数据+消息
```
### 错误响应
```go
// 使用Factory（推荐）
fac.Error(w, 1001, "用户不存在") // 业务错误（HTTP 200，业务code非0）
fac.SystemError(w, "服务器内部错误") // 系统错误（HTTP 500）
// 或直接使用公共方法
commonhttp.Error(w, 1001, "用户不存在")
commonhttp.SystemError(w, "服务器内部错误")
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数错误", nil) // 自定义HTTP状态码（仅公共方法）
```
### 分页响应
```go
// 使用Factory（推荐）
fac.SuccessPage(w, list, total, page, pageSize)
fac.SuccessPage(w, list, total, page, pageSize, "查询成功")
// 或直接使用公共方法
commonhttp.SuccessPage(w, list, total, page, pageSize)
commonhttp.SuccessPage(w, list, total, page, pageSize, "查询成功")
```
### 解析请求
#### 解析JSON请求体
```go
// 使用公共方法
var req struct {
Name string `json:"name"`
Email string `json:"email"`
}
if err := commonhttp.ParseJSON(r, &req); err != nil {
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
```
#### 获取查询参数
```go
import "git.toowon.com/jimmy/go-common/tools"
// 字符串直接获取
name := r.URL.Query().Get("name")
// 使用类型转换方法
id := tools.ConvertInt(r.URL.Query().Get("id"), 0)
userId := tools.ConvertInt64(r.URL.Query().Get("userId"), 0)
isActive := tools.ConvertBool(r.URL.Query().Get("isActive"), false)
price := tools.ConvertFloat64(r.URL.Query().Get("price"), 0.0)
```
#### 获取表单参数
```go
import "git.toowon.com/jimmy/go-common/tools"
// 字符串直接获取
name := r.FormValue("name")
// 使用类型转换方法
age := tools.ConvertInt(r.FormValue("age"), 0)
userId := tools.ConvertInt64(r.FormValue("userId"), 0)
isActive := tools.ConvertBool(r.FormValue("isActive"), false)
```
#### 获取请求头
```go
// 直接使用HTTP原生方法
token := r.Header.Get("Authorization")
contentType := r.Header.Get("Content-Type")
if contentType == "" {
contentType = "application/json" // 设置默认值
}
```
#### 获取分页参数
**方式1：使用 PaginationRequest 结构（推荐）**
```go
// 定义请求结构（包含分页字段）
type ListUserRequest struct {
Keyword string `json:"keyword"`
commonhttp.PaginationRequest // 嵌入分页请求结构
}
// 从JSON请求体解析（分页字段会自动解析）
var req ListUserRequest
if err := commonhttp.ParseJSON(r, &req); err != nil {
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
// 使用分页方法
page := req.GetPage() // 获取页码（默认1）
pageSize := req.GetPageSize() // 获取每页数量（默认20，最大100）
offset := req.GetOffset() // 计算偏移量
```
**方式2：从查询参数/form解析分页**
```go
// 使用公共方法
pagination := commonhttp.ParsePaginationRequest(r)
page := pagination.GetPage()
pageSize := pagination.GetPageSize()
offset := pagination.GetOffset()
```
#### 获取时区
```go
// 使用公共方法
// 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
// 如果未设置，返回默认时区 AsiaShanghai
timezone := commonhttp.GetTimezone(r)
```
## 完整示例
### 使用Factory（推荐）
```go
package main
import (
"log"
"net/http"
"git.toowon.com/jimmy/go-common/factory"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/tools"
)
// 用户结构
type User struct {
ID int64 `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
}
// 用户列表接口
func GetUserList(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 获取分页参数（使用公共方法）
pagination := commonhttp.ParsePaginationRequest(r)
page := pagination.GetPage()
pageSize := pagination.GetPageSize()
// 获取查询参数（直接使用HTTP原生方法）
keyword := r.URL.Query().Get("keyword")
// 查询数据
users, total := queryUsers(keyword, page, pageSize)
// 返回分页响应（使用factory方法）
fac.SuccessPage(w, users, total, page, pageSize)
}
// 创建用户接口
func CreateUser(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 解析请求体（使用公共方法）
var req struct {
Name string `json:"name"`
Email string `json:"email"`
}
if err := commonhttp.ParseJSON(r, &req); err != nil {
fac.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
// 参数验证
if req.Name == "" {
fac.Error(w, 1001, "用户名不能为空")
return
}
// 创建用户
user, err := createUser(req.Name, req.Email)
if err != nil {
fac.SystemError(w, "创建用户失败")
return
}
// 返回成功响应（使用factory方法）
fac.Success(w, user, "创建成功")
}
// 获取用户详情接口
func GetUser(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 获取查询参数（使用类型转换方法）
id := tools.ConvertInt64(r.URL.Query().Get("id"), 0)
if id == 0 {
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "用户ID不能为空", nil)
return
}
// 查询用户
user, err := getUserByID(id)
if err != nil {
fac.SystemError(w, "查询用户失败")
return
}
if user == nil {
fac.Error(w, 1002, "用户不存在")
return
}
// 返回成功响应（使用factory方法）
fac.Success(w, user)
}
func main() {
http.HandleFunc("/users", func(w http.ResponseWriter, r *http.Request) {
switch r.Method {
case http.MethodGet:
GetUserList(w, r)
case http.MethodPost:
CreateUser(w, r)
default:
commonhttp.WriteJSON(w, http.StatusMethodNotAllowed, 405, "方法不支持", nil)
}
})
http.HandleFunc("/user", GetUser)
log.Println("Server started on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}
```
## API 参考
### Factory HTTP响应结构体（暴露给外部项目使用）
#### Response
标准响应结构体，外部项目可以直接使用 `factory.Response`。
**字段：**
- `Code`: 业务状态码，0表示成功
- `Message`: 响应消息
- `Timestamp`: 时间戳（Unix时间戳，秒）
- `Data`: 响应数据
**示例：**
```go
response := factory.Response{
Code: 0,
Message: "success",
Data: userData,
}
```
#### PageData
分页数据结构体，外部项目可以直接使用 `factory.PageData`。
**字段：**
- `List`: 数据列表
- `Total`: 总记录数
- `Page`: 当前页码
- `PageSize`: 每页大小
**示例：**
```go
pageData := &factory.PageData{
List: users,
Total: 100,
Page: 1,
PageSize: 20,
}
fac.Success(w, pageData)
```
#### PageResponse
分页响应结构体，外部项目可以直接使用 `factory.PageResponse`。
**字段：**
- `Code`: 业务状态码
- `Message`: 响应消息
- `Timestamp`: 时间戳
- `Data`: 分页数据（*PageData）
### Factory HTTP响应方法（推荐使用）
#### (f *Factory) Success(w http.ResponseWriter, data interface{}, message ...string)
成功响应，HTTP 200，业务code 0。
**参数：**
- `data`: 响应数据，可以为nil
- `message`: 响应消息（可选），如果为空则使用默认消息 "success"
**示例：**
```go
fac.Success(w, data) // 只有数据，使用默认消息 "success"
fac.Success(w, data, "操作成功") // 数据+消息
```
#### (f *Factory) Error(w http.ResponseWriter, code int, message string)
业务错误响应，HTTP 200，业务code非0。
**示例：**
```go
fac.Error(w, 1001, "用户不存在")
```
#### (f *Factory) SystemError(w http.ResponseWriter, message string)
系统错误响应，HTTP 500，业务code 500。
**示例：**
```go
fac.SystemError(w, "服务器内部错误")
```
#### (f *Factory) WriteJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{})
写入JSON响应（自定义）。
**参数：**
- `httpCode`: HTTP状态码
- `code`: 业务状态码
- `message`: 响应消息
- `data`: 响应数据
**说明：**
- 此方法不在 Factory 中，直接使用 `commonhttp.WriteJSON()`
- 用于需要自定义HTTP状态码的场景（如 400, 401, 403, 404 等）
**示例：**
```go
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数错误", nil)
commonhttp.WriteJSON(w, http.StatusUnauthorized, 401, "未登录", nil)
```
#### (f *Factory) SuccessPage(w http.ResponseWriter, list interface{}, total int64, page, pageSize int, message ...string)
分页成功响应。
**参数：**
- `list`: 数据列表
- `total`: 总记录数
- `page`: 当前页码
- `pageSize`: 每页大小
- `message`: 响应消息（可选，如果为空则使用默认消息 "success"）
**示例：**
```go
fac.SuccessPage(w, users, total, page, pageSize)
fac.SuccessPage(w, users, total, page, pageSize, "查询成功")
```
### HTTP公共方法（直接使用）
#### WriteJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{})
写入JSON响应（自定义HTTP状态码和业务状态码）。
**说明：**
- 此方法不在 Factory 中，直接使用 `commonhttp.WriteJSON()`
- 用于需要自定义HTTP状态码的场景（如 400, 401, 403, 404 等）
**示例：**
```go
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数错误", nil)
commonhttp.WriteJSON(w, http.StatusUnauthorized, 401, "未登录", nil)
```
#### ParseJSON(r *http.Request, v interface{}) error
解析JSON请求体。
**示例：**
```go
var req CreateUserRequest
if err := commonhttp.ParseJSON(r, &req); err != nil {
// 处理错误
}
```
#### 获取查询参数和表单参数
**推荐方式：使用类型转换工具**
```go
import "git.toowon.com/jimmy/go-common/tools"
// 字符串直接使用HTTP原生方法
name := r.URL.Query().Get("name")
if name == "" {
name = "default" // 设置默认值
}
// 类型转换使用tools包
id := tools.ConvertInt(r.URL.Query().Get("id"), 0)
userId := tools.ConvertInt64(r.URL.Query().Get("userId"), 0)
isActive := tools.ConvertBool(r.URL.Query().Get("isActive"), false)
price := tools.ConvertFloat64(r.URL.Query().Get("price"), 0.0)
// 表单参数类似
age := tools.ConvertInt(r.FormValue("age"), 0)
```
**类型转换方法说明：**
- `tools.ConvertInt(value string, defaultValue int) int` - 转换为int
- `tools.ConvertInt64(value string, defaultValue int64) int64` - 转换为int64
- `tools.ConvertUint64(value string, defaultValue uint64) uint64` - 转换为uint64
- `tools.ConvertUint32(value string, defaultValue uint32) uint32` - 转换为uint32
- `tools.ConvertBool(value string, defaultValue bool) bool` - 转换为bool
- `tools.ConvertFloat64(value string, defaultValue float64) float64` - 转换为float64
**获取请求头：**
```go
// 直接使用HTTP原生方法
token := r.Header.Get("Authorization")
contentType := r.Header.Get("Content-Type")
```
#### ParsePaginationRequest(r *http.Request) *PaginationRequest
从请求中解析分页参数。
**说明：**
- 支持从查询参数和form表单中解析
- 优先级：查询参数 > form表单
- 如果请求体是JSON格式且包含分页字段，建议先使用`ParseJSON`解析完整请求体到包含`PaginationRequest`的结构体中
#### GetTimezone(r *http.Request) string
从请求的context中获取时区。
**说明：**
- 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
- 如果未设置，返回默认时区 AsiaShanghai
#### Success(w http.ResponseWriter, data interface{}, message ...string)
成功响应（公共方法）。
**参数：**
- `data`: 响应数据，可以为nil
- `message`: 响应消息（可选），如果为空则使用默认消息 "success"
**示例：**
```go
commonhttp.Success(w, data) // 只有数据
commonhttp.Success(w, data, "操作成功") // 数据+消息
```
#### Error(w http.ResponseWriter, code int, message string)
错误响应（公共方法）。
#### SystemError(w http.ResponseWriter, message string)
系统错误响应（公共方法）。
#### WriteJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{})
写入JSON响应（公共方法，不在Factory中）。
**说明：**
- 用于需要自定义HTTP状态码的场景
- 直接使用 `commonhttp.WriteJSON()`，不在 Factory 中
#### SuccessPage(w http.ResponseWriter, list interface{}, total int64, page, pageSize int, message ...string)
分页成功响应（公共方法）。
### 分页请求结构
#### PaginationRequest
分页请求结构，支持从JSON和form中解析分页参数。
**字段：**
- `Page`: 页码（默认1）
- `PageSize`: 每页数量
**方法：**
- `GetPage() int`: 获取页码，如果未设置则返回默认值1
- `GetPageSize() int`: 获取每页数量，如果未设置则返回默认值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. **推荐使用Factory**：
- 使用 `factory.Success()` 等方法，代码更简洁
- 直接使用 `http` 包的公共方法，保持低耦合
- 不需要Handler结构，减少不必要的封装
## 示例
完整示例请参考：
- `examples/http_handler_example.go` - 使用Factory和公共方法
- `examples/http_pagination_example.go` - 分页示例
- `examples/factory_blackbox_example.go` - Factory黑盒模式示例

510
docs/i18n.md
View File

@@ -1,510 +0,0 @@
# 国际化工具文档
## 概述
国际化工具（i18n）提供多语言内容管理功能，支持从文件加载语言内容，通过语言代码和消息代码获取对应语言的内容。
## 功能特性
- **多语言支持**：支持加载多个语言文件
- **文件加载**：支持从目录或单个文件加载语言内容
- **语言回退**：当指定语言不存在时，自动回退到默认语言
- **参数替换**：支持在消息中使用格式化参数（类似 fmt.Sprintf）
- **并发安全**：使用读写锁保证并发安全
- **动态加载**：支持重新加载语言文件
## 快速开始
### 1. 创建语言文件
创建语言文件目录 `locales/`，并创建对应的语言文件：
**locales/zh-CN.json**：
```json
{
"user.not_found": {
"code": 100002,
"message": "用户不存在"
},
"user.login_success": {
"code": 0,
"message": "登录成功"
},
"user.welcome": {
"code": 0,
"message": "欢迎，%s"
},
"error.invalid_params": {
"code": 100001,
"message": "参数无效"
}
}
```
**locales/en-US.json**：
```json
{
"user.not_found": {
"code": 100002,
"message": "User not found"
},
"user.login_success": {
"code": 0,
"message": "Login successful"
},
"user.welcome": {
"code": 0,
"message": "Welcome, %s"
},
"error.invalid_params": {
"code": 100001,
"message": "Invalid parameters"
}
}
```
### 2. 初始化并使用
```go
package main
import (
"git.toowon.com/jimmy/go-common/factory"
)
func main() {
// 创建工厂实例
fac, _ := factory.NewFactoryFromFile("config.json")
// 初始化国际化工具，设置默认语言为中文
fac.InitI18n("zh-CN")
// 从目录加载所有语言文件
fac.LoadI18nFromDir("locales")
// 获取消息
msg := fac.GetMessage("zh-CN", "user.not_found")
// 返回: "用户不存在"
// 带参数的消息
msg = fac.GetMessage("zh-CN", "user.welcome", "Alice")
// 返回: "欢迎，Alice"
// 在HTTP handler中使用Error方法（推荐）
// fac.Error(w, r, 0, "user.not_found")
// 会自动从语言文件获取业务code和国际化消息
// 返回: {"code": 100002, "message": "用户不存在"}
}
```
## API 文档
### 初始化方法
#### InitI18n
初始化国际化工具，设置默认语言。
```go
fac.InitI18n(defaultLang string)
```
**参数**：
- `defaultLang`: 默认语言代码（如 "zh-CN", "en-US"）
**示例**：
```go
fac.InitI18n("zh-CN")
```
### 加载方法
#### LoadI18nFromDir
从目录加载多个语言文件（推荐方式）。
```go
fac.LoadI18nFromDir(dirPath string) error
```
**参数**：
- `dirPath`: 语言文件目录路径
**文件命名规则**：
- 文件必须以 `.json` 结尾
- 文件名（去掉 `.json` 后缀）作为语言代码
- 例如：`zh-CN.json` 对应语言代码 `zh-CN`
**示例**：
```go
fac.LoadI18nFromDir("locales")
```
#### LoadI18nFromFile
从单个语言文件加载内容。
```go
fac.LoadI18nFromFile(filePath, lang string) error
```
**参数**：
- `filePath`: 语言文件路径（JSON格式）
- `lang`: 语言代码（如 "zh-CN", "en-US"）
**示例**：
```go
fac.LoadI18nFromFile("locales/zh-CN.json", "zh-CN")
fac.LoadI18nFromFile("locales/en-US.json", "en-US")
```
### 错误响应方法
#### Error
错误响应（自动国际化，推荐使用）。
```go
fac.Error(w, r, code int, message string, args ...interface{})
```
**参数**：
- `w`: ResponseWriter
- `r`: HTTP请求（用于获取语言信息）
- `code`: 业务错误码（如果message是消息代码，此参数会被语言文件中的code覆盖）
- `message`: 错误消息或消息代码（如果i18n已初始化且message是消息代码格式，会自动获取国际化消息和业务code）
- `args`: 可选参数，用于格式化消息（类似 fmt.Sprintf，仅在message是消息代码时使用）
**使用逻辑**：
1. 如果i18n已初始化，且message看起来是消息代码（包含点号，如 "user.not_found"），
则从请求context中获取语言，并尝试从语言文件中获取国际化消息和业务code
2. 如果获取到国际化消息，使用语言文件中的code作为响应code，使用国际化消息作为响应message
3. 如果未获取到或i18n未初始化，使用传入的code和message
**示例**：
```go
// 方式1：传入消息代码（推荐，自动获取业务code和国际化消息）
fac.Error(w, r, 0, "user.not_found")
// 如果请求语言是 zh-CN，且语言文件中 "user.not_found" 的 code 是 100002，
// 返回: {"code": 100002, "message": "用户不存在"}
// 如果请求语言是 en-US，返回: {"code": 100002, "message": "User not found"}
// 注意：业务code在所有语言中保持一致
// 方式2：带参数的消息代码
fac.Error(w, r, 0, "user.welcome", "Alice")
// 如果消息内容是 "欢迎，%s"，返回: {"code": 0, "message": "欢迎，Alice"}
// 方式3：直接传入消息文本（不使用国际化）
fac.Error(w, r, 500, "系统错误")
// 返回: {"code": 500, "message": "系统错误"}
```
### 获取消息方法
#### GetMessage
获取指定语言和代码的消息内容（推荐使用）。
```go
fac.GetMessage(lang, code string, args ...interface{}) string
```
**参数**：
- `lang`: 语言代码（如 "zh-CN", "en-US"）
- `code`: 消息代码（如 "user.not_found"）
- `args`: 可选参数，用于格式化消息（类似 fmt.Sprintf）
**返回逻辑**：
1. 如果指定语言存在该code，返回对应内容
2. 如果指定语言不存在，尝试使用默认语言
3. 如果默认语言也不存在，返回code本身（作为fallback）
**示例**：
```go
// 简单消息
msg := fac.GetMessage("zh-CN", "user.not_found")
// 返回: "用户不存在"
// 带参数的消息
msg := fac.GetMessage("zh-CN", "user.welcome", "Alice")
// 如果消息内容是 "欢迎，%s"，返回: "欢迎，Alice"
```
### GetLanguage
从请求的context中获取语言代码（推荐使用）。
```go
fac.GetLanguage(r *http.Request) string
```
**参数**：
- `r`: HTTP请求
**返回逻辑**：
1. 从请求context中获取语言（由middleware.Language中间件设置）
2. 如果未设置，返回默认语言 zh-CN
**示例**：
```go
lang := fac.GetLanguage(r)
// 可能返回: "zh-CN", "en-US" 等
```
### 高级功能
#### GetI18n
获取国际化工具对象（仅在需要高级功能时使用）。
```go
fac.GetI18n() (*i18n.I18n, error)
```
**返回**：国际化工具对象
**高级功能示例**：
```go
i18n, _ := fac.GetI18n()
// 检查语言是否存在
hasLang := i18n.HasLang("en-US")
// 获取所有支持的语言
langs := i18n.GetSupportedLangs()
// 重新加载语言文件
i18n.ReloadFromFile("locales/zh-CN.json", "zh-CN")
// 动态设置默认语言
i18n.SetDefaultLang("en-US")
```
## 使用场景
### 场景1：HTTP API 响应消息（推荐使用 Error 方法）
**推荐方式**：使用 `Error` 方法，自动从请求中获取语言并返回国际化消息和业务code：
```go
func handleLogin(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 验证用户
user, err := validateUser(r)
if err != nil {
// 直接传入消息代码，自动获取业务code和国际化消息（推荐）
// 会自动从请求context获取语言（由middleware.Language中间件设置）
fac.Error(w, r, 0, "user.not_found")
// 返回: {"code": 100002, "message": "用户不存在"} 或 {"code": 100002, "message": "User not found"}
return
}
// 成功消息
lang := fac.GetLanguage(r)
msg := fac.GetMessage(lang, "user.login_success")
fac.Success(w, user, msg)
}
```
### 场景2：带参数的消息
```go
func handleWelcome(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
lang := getLangFromRequest(r)
username := "Alice"
// 消息内容: "欢迎，%s"
msg := fac.GetMessage(lang, "user.welcome", username)
// 返回: "欢迎，Alice" 或 "Welcome, Alice"
fac.Success(w, nil, msg)
}
```
### 场景3：错误消息国际化（推荐使用 Error 方法）
**推荐方式**：使用 `Error` 方法，自动获取业务code和国际化消息：
```go
func handleError(w http.ResponseWriter, r *http.Request, messageCode string) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 直接传入消息代码，自动获取业务code和国际化消息（推荐）
// 会自动从请求context获取语言并查找对应的国际化消息和业务code
fac.Error(w, r, 0, "error."+messageCode)
// 例如：fac.Error(w, r, 0, "error.invalid_params")
// 返回: {"code": 100001, "message": "参数无效"} 或 {"code": 100001, "message": "Invalid parameters"}
}
```
## 语言文件格式
语言文件必须是 JSON 格式，每个消息包含业务code和消息内容：
```json
{
"user.not_found": {
"code": 100002,
"message": "用户不存在"
},
"user.login_success": {
"code": 0,
"message": "登录成功"
},
"user.welcome": {
"code": 0,
"message": "欢迎，%s"
},
"error.invalid_params": {
"code": 100001,
"message": "参数无效"
}
}
```
**注意事项**：
- key（消息代码）建议使用点号分隔的层级结构（如 `user.not_found`）
- value 是一个对象，包含：
- `code`: 业务错误码（整数），用于业务逻辑判断，所有语言的同一消息代码应使用相同的code
- `message`: 消息内容（字符串），支持格式化占位符（如 `%s`, `%d`）
- 所有语言文件应该包含相同的 key，确保所有语言都有对应的翻译
- **重要**：同一消息代码在所有语言文件中的 `code` 必须保持一致，只有 `message` 会根据语言变化
## 最佳实践
### 1. 消息代码命名规范
建议使用层级结构，便于管理和查找：
```
模块.功能.状态
例如：
- user.not_found
- user.login_success
- order.created
- order.paid
- error.invalid_params
- error.server_error
```
### 2. 默认语言设置
建议将最常用的语言设置为默认语言，确保在语言不存在时有合理的回退：
```go
fac.InitI18n("zh-CN") // 中文作为默认语言
```
### 3. 语言代码规范
建议使用标准的语言代码格式：
- `zh-CN`: 简体中文
- `zh-TW`: 繁体中文
- `en-US`: 美式英语
- `en-GB`: 英式英语
- `ja-JP`: 日语
- `ko-KR`: 韩语
### 4. 文件组织
建议将所有语言文件放在统一的目录下：
```
project/
locales/
zh-CN.json
en-US.json
ja-JP.json
```
### 5. 参数使用
对于需要动态内容的消息，使用格式化参数：
```json
{
"user.welcome": {
"code": 0,
"message": "欢迎，%s"
},
"order.total": {
"code": 0,
"message": "订单总额：%.2f 元"
},
"message.count": {
"code": 0,
"message": "您有 %d 条新消息"
}
}
```
使用方式：
```go
// 使用 GetMessage
msg := fac.GetMessage("zh-CN", "user.welcome", "Alice")
msg := fac.GetMessage("zh-CN", "order.total", 99.99)
msg := fac.GetMessage("zh-CN", "message.count", 5)
// 使用 Error 方法（推荐）
fac.Error(w, r, 0, "user.welcome", "Alice")
fac.Error(w, r, 0, "message.count", 5)
```
### 6. 业务Code管理
**重要原则**：同一消息代码在所有语言文件中的业务code必须保持一致。
```json
// zh-CN.json
{
"user.not_found": {
"code": 100002, // 业务code
"message": "用户不存在"
}
}
// en-US.json
{
"user.not_found": {
"code": 100002, // 必须与zh-CN.json中的code相同
"message": "User not found" // 只有message会根据语言变化
}
}
```
这样设计的好处：
- 调用端可以根据返回的 `code` 进行业务逻辑判断，不受语言影响
- 所有语言的同一错误使用相同的业务code，便于统一管理
## 常见问题
### Q1: 如果语言文件不存在会怎样？
A: 如果语言文件不存在，`LoadI18nFromFile` 或 `LoadI18nFromDir` 会返回错误。建议在初始化时检查错误。
### Q2: 如果消息代码不存在会怎样？
A: `GetMessage` 和 `Error` 会按以下顺序查找：
1. 指定语言的消息
2. 默认语言的消息
3. 如果都不存在：
- `GetMessage` 返回消息代码本身（作为fallback）
- `Error` 使用传入的code参数和消息代码作为message
### Q5: 业务code在不同语言中必须相同吗？
A: **是的，必须相同**。同一消息代码在所有语言文件中的业务code必须保持一致，只有message内容会根据语言变化。这样调用端可以根据code进行业务逻辑判断，不受语言影响。
### Q3: 如何支持动态加载语言文件？
A: 可以使用 `GetI18n()` 获取对象，然后调用 `ReloadFromFile()` 或 `ReloadFromDir()` 方法。
### Q4: 是否支持嵌套的消息结构？
A: 当前版本只支持扁平结构（key-value），不支持嵌套。如果需要嵌套结构，建议使用点号分隔的层级命名（如 `user.profile.name`）。
## 完整示例
参考 [examples/i18n_example.go](../examples/i18n_example.go)

341
docs/logger.md
View File

@@ -1,341 +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")
```
### 5. 异步/同步模式
#### 同步模式（默认）
```go
// 配置中不设置async或设置为false，使用同步模式
// 同步模式：日志直接写入，会阻塞调用方直到写入完成
logger.Info("This is a synchronous log")
```
#### 异步模式
```go
// 配置中设置async为true，使用异步模式
// 异步模式：日志写入通过channel异步处理，不阻塞调用方
// 配置文件示例：
// {
// "logger": {
// "async": true,
// "bufferSize": 1000
// }
// }
// 使用异步模式时，程序退出前需要调用Close()确保所有日志写入完成
defer logger.Close()
logger.Info("This is an asynchronous log")
```
**注意：**
- `Fatal` 和 `Panic` 方法始终使用同步模式，确保日志写入后再退出/panic
- 异步模式下，程序退出前应调用 `Close()` 方法，确保所有日志写入完成
- 如果channel已满，会自动降级为同步写入，避免丢失日志
## 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{})
记录错误日志（带字段）。
### (l *Logger) Close() error
优雅关闭logger（仅异步模式需要）。
**说明：**
- 等待所有日志写入完成后再返回
- 同步模式下调用此方法会立即返回，无需等待
- 程序退出前应调用此方法，确保所有日志写入完成
## 配置说明
日志配置通过 `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 |
| Async | bool | 是否使用异步模式 | false（同步） |
| BufferSize | int | 异步模式下的缓冲区大小 | 1000 |
## 配置示例
### 输出到标准输出
```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
}
}
```
### 异步模式配置
```json
{
"logger": {
"level": "info",
"output": "file",
"filePath": "./logs/app.log",
"prefix": "app",
"async": true,
"bufferSize": 1000
}
}
```
**说明：**
- `async`: 设置为 `true` 启用异步模式，`false` 或不设置则使用同步模式（默认）
- `bufferSize`: 异步模式下的channel缓冲区大小，默认1000。当缓冲区满时，新的日志会阻塞直到有空间，或降级为同步写入
## 日志级别说明
- **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包，性能较好
- 文件输出使用追加模式，不会覆盖已有日志
- 异步模式适合高并发场景，减少日志写入对业务代码的阻塞
- 同步模式适合需要确保日志立即写入的场景（如调试）
5. **异步模式注意事项**：
- 异步模式下，程序退出前必须调用 `Close()` 方法，确保所有日志写入完成
- 如果channel缓冲区已满，会自动降级为同步写入，避免丢失日志
- `Fatal` 和 `Panic` 方法始终使用同步模式，确保日志写入后再退出/panic
## 完整示例
```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)
// 如果使用异步模式，程序退出前需要关闭logger
// defer logger.Close()
}
```
## 示例
完整示例请参考 `examples/logger_example.go`

1039
docs/middleware.md
View File

File diff suppressed because it is too large Load Diff

442
docs/migration.md
View File

@@ -1,442 +0,0 @@
# 数据库迁移工具文档
## 概述
数据库迁移工具提供了数据库版本管理和迁移功能，支持MySQL、PostgreSQL、SQLite等数据库。使用GORM作为数据库操作库，可以方便地进行数据库结构的版本控制。
## 功能特性
- 支持迁移版本管理
- 支持迁移和回滚操作
- 支持从文件系统加载迁移文件
- 支持迁移状态查询
- 自动创建迁移记录表
- 事务支持，确保迁移的原子性
## 🚀 最简单的使用方式（黑盒模式，推荐）
这是最简单的迁移方式，内部自动处理配置加载、数据库连接、迁移执行等所有细节。
### 方式一：使用独立迁移工具（推荐）
1. **复制迁移工具模板到你的项目**：
```bash
mkdir -p cmd/migrate
cp /path/to/go-common/templates/migrate/main.go cmd/migrate/
```
2. **创建迁移文件**：
```bash
mkdir -p migrations
# 或使用其他目录，如 scripts/sql
```
创建 `migrations/01_init_schema.sql`：
```sql
CREATE TABLE users (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(255) NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
3. **编译和使用**：
```bash
# 编译
go build -o bin/migrate cmd/migrate/main.go
# 使用（最简单，使用默认配置和默认迁移目录）
./bin/migrate up
# 指定配置文件
./bin/migrate up -config config.json
# 指定配置和迁移目录
./bin/migrate up -config config.json -dir scripts/sql
# 查看状态
./bin/migrate status
# 回滚
./bin/migrate down
```
**特点**：
- ✅ 零配置：使用默认值即可运行
- ✅ 自动查找配置：支持环境变量、默认路径
- ✅ 自动处理：配置加载、数据库连接、迁移执行全自动
### 方式二：在代码中直接调用（简单场景）
```go
import "git.toowon.com/jimmy/go-common/migration"
// 最简单：使用默认配置和默认迁移目录
err := migration.RunMigrationsFromConfigWithCommand("", "", "up")
// 指定配置文件，使用默认迁移目录
err := migration.RunMigrationsFromConfigWithCommand("config.json", "", "up")
// 指定配置和迁移目录
err := migration.RunMigrationsFromConfigWithCommand("config.json", "scripts/sql", "up")
// 查看状态
err := migration.RunMigrationsFromConfigWithCommand("config.json", "migrations", "status")
```
**参数说明**：
- `configFile`: 配置文件路径，空字符串时自动查找（config.json, ../config.json）
- `migrationsDir`: 迁移文件目录，空字符串时使用默认值 "migrations"
- `command`: 命令，支持 "up", "down", "status"
### 方式三：使用Factory（如果项目已使用Factory）
```go
import "git.toowon.com/jimmy/go-common/factory"
fac, _ := factory.NewFactoryFromFile("config.json")
// 使用默认目录 "migrations"
err := fac.RunMigrations()
// 或指定目录
err := fac.RunMigrations("scripts/sql")
```
---
## 详细使用方法（高级功能）
### 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
// 支持的文件命名格式：
// 1. 数字前缀: 01_init_schema.sql
// 2. 时间戳: 20240101000001_create_users.sql
// 3. 带.up后缀: 20240101000001_create_users.up.sql
// 对应的回滚文件: 20240101000001_create_users.down.sql
migrations, err := migration.LoadMigrationsFromFiles("./migrations", "*.sql")
if err != nil {
log.Fatal(err)
}
migrator.AddMigrations(migrations...)
```
**新特性：**
- ✅ 支持数字前缀命名（如 `01_init_schema.sql`）
- ✅ 自动分割多行 SQL 语句
- ✅ 自动处理注释（单行 `--` 和多行 `/* */`）
- ✅ 记录执行时间（毫秒）
### 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`: 文件匹配模式，如 "*.sql" 或 "*.up.sql"
**返回：** 迁移列表和错误信息
**支持的文件命名格式：**
1. **数字前缀格式**（新支持）：
- `01_init_schema.sql`
- `02_init_data.sql`
- `03_add_log_schema.sql`
2. **时间戳格式**（现有）：
- `20240101000001_create_users.sql`
- `20240101000002_add_index.sql`
3. **带.up后缀格式**（现有）：
- `20240101000001_create_users.up.sql` - 升级文件
- `20240101000001_create_users.down.sql` - 回滚文件（可选）
**新特性：**
- ✅ 自动识别文件命名格式（数字前缀或时间戳）
- ✅ 自动分割多行 SQL 语句（按分号分割）
- ✅ 自动处理注释（单行 `--` 和多行 `/* */`）
- ✅ 自动跳过空行和空白字符
- ✅ 支持一个文件包含多个 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`

571
docs/storage.md
View File

@@ -1,571 +0,0 @@
# 存储工具文档
## 概述
存储工具提供了文件上传和查看功能，支持 **本地文件夹(Local)**、OSS 和 MinIO 三种存储方式，并提供HTTP处理器用于文件上传和代理查看。
## 功能特性
- 支持本地文件夹存储（Local）
- 支持OSS对象存储（阿里云、腾讯云、AWS、七牛云等）
- 支持MinIO对象存储
- 提供统一的存储接口
- 支持文件上传HTTP处理器
- 支持文件代理查看HTTP处理器
- 支持文件大小和扩展名限制
- 自动生成唯一文件名
- 支持自定义对象键前缀
## 使用方法
### 0. 工厂调用方式（推荐）
当你使用 `factory` 黑盒模式时，外部项目无需关心底层是 Local/MinIO/OSS：
```go
import (
"context"
"os"
"git.toowon.com/jimmy/go-common/factory"
"git.toowon.com/jimmy/go-common/storage"
)
fac, _ := factory.NewFactoryFromFile("./config.json")
f, _ := os.Open("test.jpg")
defer f.Close()
objectKey := storage.GenerateObjectKeyWithDate("uploads/images", "test.jpg")
url, err := fac.UploadFile(context.Background(), objectKey, f, "image/jpeg")
if err != nil {
panic(err)
}
_ = url
```
### 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)
}
// 创建本地存储实例
localStorage, err := storage.NewStorage(storage.StorageTypeLocal, 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)
```
### 2.1 本地存储配置示例
`config.json` 增加 `localStorage` 配置段：
```json
{
"localStorage": {
"baseDir": "./uploads",
"publicURL": "http://localhost:8080/file?key={objectKey}"
}
}
```
说明：
- **baseDir**：文件保存根目录
- **publicURL**：用于 `GetURL()` 返回对外可访问的 URL
- 推荐配合本文的 `ProxyHandler`，示例 `http://localhost:8080/file?key={objectKey}`
- `{objectKey}` 会自动做 `url.QueryEscape` 处理
### 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)
```
**本地存储建议搭配：**
- `POST /upload` 上传文件（返回 `url`）
- `GET /file?key=...` 通过代理读取本地文件并返回二进制内容
**查看请求示例：**
```
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
- **错误**：返回标准HTTP错误状态码和错误消息（文本格式）
- `400 Bad Request`: 缺少必需参数
- `404 Not Found`: 文件不存在
- `405 Method Not Allowed`: 请求方法不正确
- `500 Internal Server Error`: 系统错误
**注意**：`ProxyHandler` 返回的是文件内容（二进制），而不是JSON响应。错误时使用标准HTTP状态码，保持与文件响应的一致性。
### 辅助函数
#### 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)
// 创建中间件链
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(corsConfig),
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`

223
email/email.go
View File

@@ -2,18 +2,38 @@ package email
import ( import (
"bytes" "bytes"
"context"
"crypto/tls" "crypto/tls"
"fmt" "fmt"
"net" "net"
"net/smtp" "net/smtp"
"sync"
"sync/atomic"
"time" "time"
"git.toowon.com/jimmy/go-common/config" "git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/logger"
) )
// Email 邮件发送器 // Email 邮件发送器
type Email struct { type Email struct {
config *config.EmailConfig 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 创建邮件发送器 // NewEmail 创建邮件发送器
@@ -21,28 +41,55 @@ func NewEmail(cfg *config.Config) *Email {
if cfg == nil || cfg.Email == nil { if cfg == nil || cfg.Email == nil {
return &Email{config: nil} return &Email{config: nil}
} }
return &Email{config: cfg.Email} 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)
}
}
} }
// getEmailConfig 获取邮件配置（内部方法）
func (e *Email) getEmailConfig() (*config.EmailConfig, error) { func (e *Email) getEmailConfig() (*config.EmailConfig, error) {
if e.config == nil { if e.config == nil {
return nil, fmt.Errorf("email config is nil") return nil, fmt.Errorf("email config is nil")
} }
if e.config.Host == "" { if e.config.Host == "" {
return nil, fmt.Errorf("email host is required") return nil, fmt.Errorf("email host is required")
} }
if e.config.Username == "" { if e.config.Username == "" {
return nil, fmt.Errorf("email username is required") return nil, fmt.Errorf("email username is required")
} }
if e.config.Password == "" { if e.config.Password == "" {
return nil, fmt.Errorf("email password is required") return nil, fmt.Errorf("email password is required")
} }
// 设置默认值
if e.config.Port == 0 { if e.config.Port == 0 {
e.config.Port = 587 e.config.Port = 587
} }
@@ -50,224 +97,177 @@ func (e *Email) getEmailConfig() (*config.EmailConfig, error) {
e.config.From = e.config.Username e.config.From = e.config.Username
} }
if e.config.Timeout == 0 { if e.config.Timeout == 0 {
e.config.Timeout = 30 e.config.Timeout = 5
} }
return e.config, nil return e.config, nil
} }
// Message 邮件消息 // Message 邮件消息
type Message struct { type Message struct {
// To 收件人列表
To []string To []string
// Cc 抄送列表（可选）
Cc []string Cc []string
// Bcc 密送列表（可选）
Bcc []string Bcc []string
// Subject 主题
Subject string Subject string
// Body 正文（纯文本）
Body string Body string
// HTMLBody HTML正文（可选，如果设置了会优先使用）
HTMLBody string HTMLBody string
} }
// SendEmail 发送邮件 // SendEmail 同步发送邮件（验证码等需等待结果的场景）
// to: 收件人列表
// subject: 邮件主题
// body: 邮件正文（纯文本）
// htmlBody: HTML正文（可选，如果设置了会优先使用）
func (e *Email) SendEmail(to []string, subject, body string, htmlBody ...string) error { func (e *Email) SendEmail(to []string, subject, body string, htmlBody ...string) error {
cfg, err := e.getEmailConfig() cfg, err := e.getEmailConfig()
if err != nil { if err != nil {
return err return err
} }
msg := &Message{To: to, Subject: subject, Body: body}
msg := &Message{
To: to,
Subject: subject,
Body: body,
}
if len(htmlBody) > 0 && htmlBody[0] != "" { if len(htmlBody) > 0 && htmlBody[0] != "" {
msg.HTMLBody = htmlBody[0] msg.HTMLBody = htmlBody[0]
} }
return e.send(msg, cfg) return e.send(msg, cfg)
} }
// send 发送邮件（内部方法） // 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 { func (e *Email) send(msg *Message, cfg *config.EmailConfig) error {
if msg == nil { if msg == nil {
return fmt.Errorf("message is nil") return fmt.Errorf("message is nil")
} }
if len(msg.To) == 0 { if len(msg.To) == 0 {
return fmt.Errorf("recipients are required") return fmt.Errorf("recipients are required")
} }
if msg.Subject == "" { if msg.Subject == "" {
return fmt.Errorf("subject is required") return fmt.Errorf("subject is required")
} }
if msg.Body == "" && msg.HTMLBody == "" { if msg.Body == "" && msg.HTMLBody == "" {
return fmt.Errorf("body or HTMLBody is required") return fmt.Errorf("body or HTMLBody is required")
} }
// 构建邮件内容
emailBody, err := e.buildEmailBody(msg, cfg) emailBody, err := e.buildEmailBody(msg, cfg)
if err != nil { if err != nil {
return fmt.Errorf("failed to build email body: %w", err) return fmt.Errorf("failed to build email body: %w", err)
} }
// 合并收件人列表
recipients := append(msg.To, msg.Cc...) recipients := append(msg.To, msg.Cc...)
recipients = append(recipients, msg.Bcc...) recipients = append(recipients, msg.Bcc...)
// 连接SMTP服务器
addr := net.JoinHostPort(cfg.Host, fmt.Sprintf("%d", cfg.Port)) addr := net.JoinHostPort(cfg.Host, fmt.Sprintf("%d", cfg.Port))
auth := smtp.PlainAuth("", cfg.Username, cfg.Password, cfg.Host) auth := smtp.PlainAuth("", cfg.Username, cfg.Password, cfg.Host)
// 创建连接
conn, err := net.DialTimeout("tcp", addr, time.Duration(cfg.Timeout)*time.Second) conn, err := net.DialTimeout("tcp", addr, time.Duration(cfg.Timeout)*time.Second)
if err != nil { if err != nil {
return fmt.Errorf("failed to connect to SMTP server: %w", err) return fmt.Errorf("failed to connect to SMTP server: %w", err)
} }
defer conn.Close() defer conn.Close()
// 创建SMTP客户端
client, err := smtp.NewClient(conn, cfg.Host) client, err := smtp.NewClient(conn, cfg.Host)
if err != nil { if err != nil {
return fmt.Errorf("failed to create SMTP client: %w", err) return fmt.Errorf("failed to create SMTP client: %w", err)
} }
defer client.Close() defer client.Close()
// TLS/SSL处理 if cfg.UseSSL || cfg.UseTLS {
if cfg.UseSSL { tlsConfig := &tls.Config{ServerName: cfg.Host}
// SSL模式（端口通常是465）
tlsConfig := &tls.Config{
ServerName: cfg.Host,
}
if err := client.StartTLS(tlsConfig); err != nil {
return fmt.Errorf("failed to start TLS: %w", err)
}
} else if cfg.UseTLS {
// TLS模式（STARTTLS，端口通常是587）
tlsConfig := &tls.Config{
ServerName: cfg.Host,
}
if err := client.StartTLS(tlsConfig); err != nil { if err := client.StartTLS(tlsConfig); err != nil {
return fmt.Errorf("failed to start TLS: %w", err) return fmt.Errorf("failed to start TLS: %w", err)
} }
} }
// 认证
if err := client.Auth(auth); err != nil { if err := client.Auth(auth); err != nil {
return fmt.Errorf("failed to authenticate: %w", err) return fmt.Errorf("failed to authenticate: %w", err)
} }
// 设置发件人
if err := client.Mail(cfg.From); err != nil { if err := client.Mail(cfg.From); err != nil {
return fmt.Errorf("failed to set sender: %w", err) return fmt.Errorf("failed to set sender: %w", err)
} }
// 设置收件人
for _, to := range recipients { for _, to := range recipients {
if err := client.Rcpt(to); err != nil { if err := client.Rcpt(to); err != nil {
return fmt.Errorf("failed to set recipient %s: %w", to, err) return fmt.Errorf("failed to set recipient %s: %w", to, err)
} }
} }
// 发送邮件内容
writer, err := client.Data() writer, err := client.Data()
if err != nil { if err != nil {
return fmt.Errorf("failed to get data writer: %w", err) return fmt.Errorf("failed to get data writer: %w", err)
} }
if _, err = writer.Write(emailBody); err != nil {
_, err = writer.Write(emailBody) _ = writer.Close()
if err != nil {
writer.Close()
return fmt.Errorf("failed to write email body: %w", err) return fmt.Errorf("failed to write email body: %w", err)
} }
if err = writer.Close(); err != nil {
err = writer.Close()
if err != nil {
return fmt.Errorf("failed to close writer: %w", err) return fmt.Errorf("failed to close writer: %w", err)
} }
// 退出
if err := client.Quit(); err != nil { if err := client.Quit(); err != nil {
return fmt.Errorf("failed to quit: %w", err) return fmt.Errorf("failed to quit: %w", err)
} }
return nil return nil
} }
// buildEmailBody 构建邮件内容
func (e *Email) buildEmailBody(msg *Message, cfg *config.EmailConfig) ([]byte, error) { func (e *Email) buildEmailBody(msg *Message, cfg *config.EmailConfig) ([]byte, error) {
var buf bytes.Buffer var buf bytes.Buffer
// 邮件头
from := cfg.From from := cfg.From
if cfg.FromName != "" { if cfg.FromName != "" {
from = fmt.Sprintf("%s <%s>", cfg.FromName, cfg.From) from = fmt.Sprintf("%s <%s>", cfg.FromName, cfg.From)
} }
buf.WriteString(fmt.Sprintf("From: %s\r\n", from)) buf.WriteString(fmt.Sprintf("From: %s\r\n", from))
// 收件人
buf.WriteString(fmt.Sprintf("To: %s\r\n", joinEmails(msg.To))) buf.WriteString(fmt.Sprintf("To: %s\r\n", joinEmails(msg.To)))
// 抄送
if len(msg.Cc) > 0 { if len(msg.Cc) > 0 {
buf.WriteString(fmt.Sprintf("Cc: %s\r\n", joinEmails(msg.Cc))) buf.WriteString(fmt.Sprintf("Cc: %s\r\n", joinEmails(msg.Cc)))
} }
// 主题
buf.WriteString(fmt.Sprintf("Subject: %s\r\n", msg.Subject)) buf.WriteString(fmt.Sprintf("Subject: %s\r\n", msg.Subject))
// 内容类型
if msg.HTMLBody != "" { if msg.HTMLBody != "" {
// 多部分邮件（HTML + 纯文本）
boundary := "----=_Part_" + fmt.Sprint(time.Now().UnixNano()) boundary := "----=_Part_" + fmt.Sprint(time.Now().UnixNano())
buf.WriteString("MIME-Version: 1.0\r\n") buf.WriteString("MIME-Version: 1.0\r\n")
buf.WriteString(fmt.Sprintf("Content-Type: multipart/alternative; boundary=\"%s\"\r\n", boundary)) buf.WriteString(fmt.Sprintf("Content-Type: multipart/alternative; boundary=\"%s\"\r\n\r\n", boundary))
buf.WriteString("\r\n") 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("--" + boundary + "\r\n") buf.WriteString(msg.HTMLBody + "\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("--" + boundary + "--\r\n") buf.WriteString("--" + boundary + "--\r\n")
} else { } else {
// 纯文本邮件 buf.WriteString("Content-Type: text/plain; charset=UTF-8\r\n\r\n")
buf.WriteString("Content-Type: text/plain; charset=UTF-8\r\n") buf.WriteString(msg.Body + "\r\n")
buf.WriteString("Content-Transfer-Encoding: quoted-printable\r\n")
buf.WriteString("\r\n")
buf.WriteString(msg.Body)
buf.WriteString("\r\n")
} }
return buf.Bytes(), nil return buf.Bytes(), nil
} }
// joinEmails 连接邮箱地址
func joinEmails(emails []string) string { func joinEmails(emails []string) string {
if len(emails) == 0 { if len(emails) == 0 {
return "" return ""
@@ -278,4 +278,3 @@ func joinEmails(emails []string) string {
} }
return result return result
} }

110
examples/email_example.go
View File

@@ -8,117 +8,35 @@ import (
"log" "log"
"git.toowon.com/jimmy/go-common/config" "git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/email" "git.toowon.com/jimmy/go-common/factory"
) )
func main() { func main() {
// 加载配置
cfg, err := config.LoadFromFile("./config/example.json") cfg, err := config.LoadFromFile("./config/example.json")
if err != nil { if err != nil {
log.Fatal("Failed to load config:", err) log.Fatal(err)
} }
// 创建邮件发送器 app := factory.New(cfg)
emailConfig := cfg.GetEmail() mail, err := app.Email()
if emailConfig == nil {
log.Fatal("Email config is nil")
}
mailer, err := email.NewEmail(emailConfig)
if err != nil { 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 ===") err = mail.SendEmail(
// 外部构建完整的邮件内容（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(
[]string{"recipient@example.com"}, []string{"recipient@example.com"},
"测试邮件", "测试邮件",
"这是一封测试邮件，使用Go标准库发送。", "这是一封测试邮件。",
) )
if err != nil { if err != nil {
log.Printf("Failed to send email: %v", err) log.Printf("sync send failed: %v", err)
} else { } else {
fmt.Println("Email sent successfully") fmt.Println("sync email sent")
} }
// 示例3：发送HTML邮件 // 异步发送（HTTP 通知类）
fmt.Println("\n=== Example 3: Send HTML Email ===") mail.SendEmailAsync(nil, []string{"recipient@example.com"}, "异步通知", "后台发送，不阻塞请求")
htmlBody := ` fmt.Println("async email enqueued")
<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.")
}

199
examples/excel_example.go
View File

@@ -6,7 +6,7 @@ package main
import ( import (
"fmt" "fmt"
"log" "log"
"net/http" "os"
"time" "time"
"git.toowon.com/jimmy/go-common/excel" "git.toowon.com/jimmy/go-common/excel"
@@ -14,7 +14,6 @@ import (
"git.toowon.com/jimmy/go-common/tools" "git.toowon.com/jimmy/go-common/tools"
) )
// User 用户结构体示例
type User struct { type User struct {
ID int `json:"id"` ID int `json:"id"`
Name string `json:"name"` Name string `json:"name"`
@@ -24,213 +23,47 @@ type User struct {
} }
func main() { func main() {
// 创建工厂（可选，Excel导出不需要配置） app := factory.New(nil)
fac, err := factory.NewFactoryFromFile("./config/example.json") ex := app.Excel()
if err != nil {
// Excel导出不需要配置，可以传nil
fac = factory.NewFactory(nil)
}
// 示例1：导出结构体切片到文件
fmt.Println("=== Example 1: Export Struct Slice to File ===")
example1(fac)
// 示例2：导出到HTTP响应
fmt.Println("\n=== Example 2: Export to HTTP Response ===")
example2(fac)
// 示例3：使用格式化函数
fmt.Println("\n=== Example 3: Export with Format Functions ===")
example3(fac)
// 示例4：使用ExportData接口
fmt.Println("\n=== Example 4: Export with ExportData Interface ===")
example4(fac)
}
// 示例1：导出结构体切片到文件
func example1(fac *factory.Factory) {
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().Add(-24 * time.Hour), Status: 1},
{ID: 3, Name: "Charlie", Email: "charlie@example.com", CreatedAt: time.Now().Add(-48 * time.Hour), Status: 0},
}
columns := []factory.ExportColumn{
{Header: "ID", Field: "ID", Width: 10},
{Header: "姓名", Field: "Name", Width: 20},
{Header: "邮箱", Field: "Email", Width: 30},
{Header: "创建时间", Field: "CreatedAt", Width: 20},
{Header: "状态", Field: "Status", Width: 10},
}
err := fac.ExportToExcelFile("users.xlsx", "用户列表", columns, users)
if err != nil {
log.Printf("Failed to export to file: %v", err)
} else {
fmt.Println("Excel file exported successfully: users.xlsx")
}
}
// 示例2：导出到HTTP响应
func example2(fac *factory.Factory) {
// 模拟HTTP响应
w := &mockResponseWriter{}
users := []User{ users := []User{
{ID: 1, Name: "Alice", Email: "alice@example.com", CreatedAt: time.Now(), Status: 1}, {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: 1}, {ID: 2, Name: "Bob", Email: "bob@example.com", CreatedAt: time.Now(), Status: 0},
} }
columns := []factory.ExportColumn{ columns := []excel.ExportColumn{
{Header: "ID", Field: "ID"},
{Header: "姓名", Field: "Name"},
{Header: "邮箱", Field: "Email"},
}
// 设置HTTP响应头
w.Header().Set("Content-Type", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
w.Header().Set("Content-Disposition", "attachment; filename=users.xlsx")
err := fac.ExportToExcel(w, "用户列表", columns, users)
if err != nil {
log.Printf("Failed to export to HTTP response: %v", err)
} else {
fmt.Printf("Excel exported to HTTP response successfully, size: %d bytes\n", len(w.data))
}
}
// 示例3：使用格式化函数
func example3(fac *factory.Factory) {
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().Add(-24 * time.Hour), Status: 0},
}
columns := []factory.ExportColumn{
{Header: "ID", Field: "ID", Width: 10}, {Header: "ID", Field: "ID", Width: 10},
{Header: "姓名", Field: "Name", Width: 20}, {Header: "姓名", Field: "Name", Width: 20},
{Header: "邮箱", Field: "Email", Width: 30}, {Header: "邮箱", Field: "Email", Width: 30},
{ {
Header: "创建时间", Header: "创建时间",
Field: "CreatedAt", Field: "CreatedAt",
Width: 20,
Format: excel.AdaptTimeFormatter(tools.FormatDateTime), // 使用适配器直接调用tools函数
},
{
Header: "状态",
Field: "Status",
Width: 10,
Format: func(value interface{}) string {
// 自定义格式化函数
if status, ok := value.(int); ok {
if status == 1 {
return "启用"
}
return "禁用"
}
return ""
},
},
}
err := fac.ExportToExcelFile("users_formatted.xlsx", "用户列表", columns, users)
if err != nil {
log.Printf("Failed to export with format: %v", err)
} else {
fmt.Println("Excel file exported with format successfully: users_formatted.xlsx")
}
}
// 示例4：使用ExportData接口
func example4(fac *factory.Factory) {
// 创建实现了ExportData接口的数据对象
exportData := &UserExportData{
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: 1},
},
}
// 使用接口方法获取列定义和数据
columns := exportData.GetExportColumns()
err := fac.ExportToExcelFile("users_interface.xlsx", "用户列表", columns, exportData)
if err != nil {
log.Printf("Failed to export with interface: %v", err)
} else {
fmt.Println("Excel file exported with interface successfully: users_interface.xlsx")
}
}
// UserExportData 实现了ExportData接口的用户导出数据
type UserExportData struct {
users []User
}
// GetExportColumns 获取导出列定义
func (d *UserExportData) GetExportColumns() []excel.ExportColumn {
return []excel.ExportColumn{
{Header: "ID", Field: "ID", Width: 10},
{Header: "姓名", Field: "Name", Width: 20},
{Header: "邮箱", Field: "Email", Width: 30},
{
Header: "创建时间",
Field: "CreatedAt",
Width: 20,
Format: excel.AdaptTimeFormatter(tools.FormatDateTime), Format: excel.AdaptTimeFormatter(tools.FormatDateTime),
}, },
{ {
Header: "状态", Header: "状态",
Field: "Status", Field: "Status",
Width: 10,
Format: func(value interface{}) string { Format: func(value interface{}) string {
if status, ok := value.(int); ok { if status, ok := value.(int); ok && status == 1 {
if status == 1 {
return "启用" return "启用"
} }
return "禁用" return "禁用"
}
return ""
}, },
}, },
} }
}
// GetExportRows 获取导出数据行 if err := ex.ExportToFile("users.xlsx", "用户列表", columns, users); err != nil {
func (d *UserExportData) GetExportRows() [][]interface{} { log.Fatal(err)
rows := make([][]interface{}, 0, len(d.users))
for _, user := range d.users {
row := []interface{}{
user.ID,
user.Name,
user.Email,
user.CreatedAt,
user.Status,
}
rows = append(rows, row)
}
return rows
} }
fmt.Println("exported users.xlsx")
// mockResponseWriter 模拟HTTP响应写入器（用于示例） f, err := os.Create("users_http.xlsx")
type mockResponseWriter struct { if err != nil {
header http.Header log.Fatal(err)
data []byte
} }
defer f.Close()
func (w *mockResponseWriter) Header() http.Header { if err := ex.ExportToWriter(f, "用户列表", columns, users); err != nil {
if w.header == nil { log.Fatal(err)
w.header = make(http.Header)
} }
return w.header fmt.Println("exported users_http.xlsx")
}
func (w *mockResponseWriter) Write(data []byte) (int, error) {
w.data = append(w.data, data...)
return len(data), nil
}
func (w *mockResponseWriter) WriteHeader(statusCode int) {
// 模拟实现
} }

166
examples/factory_blackbox_example.go
View File

@@ -1,166 +0,0 @@
package main
import (
"context"
"log"
"net/http"
"time"
"git.toowon.com/jimmy/go-common/factory"
)
// 示例：Factory黑盒模式 - 最简化的使用方式
//
// 核心理念：
//
// 外部项目只需要传递一个配置文件路径，
// 直接使用 factory 的黑盒方法，无需获取内部对象
func main() {
// ====== 第1步：创建工厂（只需要配置文件路径）======
fac, err := factory.NewFactoryFromFile("config.json")
if err != nil {
log.Fatal(err)
}
// ====== 第2步：使用黑盒方法（推荐）======
// 1. 获取中间件链（自动配置所有基础中间件）
chain := fac.GetMiddlewareChain()
// 2. 添加项目特定的自定义中间件
chain.Append(authMiddleware, metricsMiddleware)
// 3. 注册路由
http.Handle("/api/users", chain.ThenFunc(handleUsers))
http.Handle("/api/upload", chain.ThenFunc(handleUpload))
// 4. 启动服务
log.Println("Server started on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}
// ====== API处理器 ======
// 用户列表
func handleUsers(w http.ResponseWriter, r *http.Request) {
// 创建工厂（在处理器中也可以复用）
fac, _ := factory.NewFactoryFromFile("config.json")
ctx := context.Background()
// 1. 使用数据库（需要获取对象，因为GORM很复杂）
db, _ := fac.GetDatabase()
var users []map[string]interface{}
db.Table("users").Find(&users)
// 2. 使用Redis（黑盒方法，推荐）
cacheKey := "users:list"
cached, _ := fac.RedisGet(ctx, cacheKey)
if cached != "" {
fac.Success(w, cached)
return
}
// 3. 记录日志（黑盒方法，推荐）
fac.LogInfof(map[string]interface{}{
"action": "list_users",
"count": len(users),
}, "查询用户列表")
// 4. 缓存结果
fac.RedisSet(ctx, cacheKey, users, 5*time.Minute)
fac.Success(w, users)
}
// 文件上传
func handleUpload(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
ctx := context.Background()
// 解析上传的文件
file, header, err := r.FormFile("file")
if err != nil {
fac.LogError("文件上传失败: %v", err)
fac.Error(w, 400, "文件上传失败")
return
}
defer file.Close()
// 上传文件（黑盒方法，自动选择OSS或MinIO）
objectKey := "uploads/" + header.Filename
url, err := fac.UploadFile(ctx, objectKey, file, header.Header.Get("Content-Type"))
if err != nil {
fac.LogError("文件上传到存储失败: %v", err)
fac.Error(w, 500, "文件上传失败")
return
}
// 记录上传日志
fac.LogInfof(map[string]interface{}{
"filename": header.Filename,
"size": header.Size,
"url": url,
}, "文件上传成功")
fac.Success(w, map[string]interface{}{
"url": url,
})
}
// ====== 自定义中间件 ======
// 认证中间件
func authMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
ctx := context.Background()
// 获取token
token := r.Header.Get("Authorization")
if token == "" {
fac.Error(w, 401, "未授权")
return
}
// 从Redis验证token（黑盒方法）
userID, err := fac.RedisGet(ctx, "token:"+token)
if err != nil || userID == "" {
fac.Error(w, 401, "token无效")
return
}
// 记录日志（黑盒方法）
fac.LogInfof(map[string]interface{}{
"user_id": userID,
"path": r.URL.Path,
}, "用户请求")
// 将用户ID存入context（或header）
r.Header.Set("X-User-ID", userID)
next.ServeHTTP(w, r)
})
}
// 指标中间件
func metricsMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
ctx := context.Background()
start := time.Now()
// 继续处理请求
next.ServeHTTP(w, r)
// 记录请求耗时到Redis（黑盒方法）
latency := time.Since(start).Milliseconds()
key := "metrics:" + r.URL.Path
fac.RedisSet(ctx, key, latency, time.Minute)
// 记录指标日志（黑盒方法）
fac.LogDebugf(map[string]interface{}{
"path": r.URL.Path,
"latency": latency,
}, "请求指标")
})
}

116
examples/http_handler_example.go
View File

@@ -1,3 +1,6 @@
//go:build example
// +build example
package main package main
import ( import (
@@ -6,107 +9,44 @@ import (
"git.toowon.com/jimmy/go-common/factory" "git.toowon.com/jimmy/go-common/factory"
commonhttp "git.toowon.com/jimmy/go-common/http" commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/tools"
) )
// 用户结构
type User struct { type User struct {
ID int64 `json:"id"` ID int64 `json:"id"`
Name string `json:"name"` Name string `json:"name"`
Email string `json:"email"` Email string `json:"email"`
} }
// 获取用户列表（使用公共方法和factory） func main() {
func GetUserList(w http.ResponseWriter, r *http.Request) { if err := factory.Init("config.json"); err != nil {
fac, _ := factory.NewFactoryFromFile("config.json") log.Fatal(err)
}
app := factory.Default()
chain := app.MiddlewareChain()
// 获取分页参数（使用公共方法） http.Handle("/users", chain.ThenFunc(listUsers))
pagination := commonhttp.ParsePaginationRequest(r) log.Fatal(http.ListenAndServe(":8080", nil))
page := pagination.GetPage() }
pageSize := pagination.GetPageSize()
// 获取查询参数（使用公共方法） func listUsers(w http.ResponseWriter, r *http.Request) {
_ = r.URL.Query().Get("keyword") // 示例：获取查询参数 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{ users := []User{
{ID: 1, Name: "User1", Email: "user1@example.com"}, {ID: 1, Name: "User1", Email: "user1@example.com"},
{ID: 2, Name: "User2", Email: "user2@example.com"}, {ID: 2, Name: "User2", Email: "user2@example.com"},
} }
total := int64(100) h.SuccessPage(users, 100)
_ = p
// 返回分页响应（使用factory方法）
fac.SuccessPage(w, users, total, page, pageSize)
}
// 创建用户（使用公共方法和factory）
func CreateUser(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 解析请求体（使用公共方法）
var req struct {
Name string `json:"name"`
Email string `json:"email"`
}
if err := commonhttp.ParseJSON(r, &req); err != nil {
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
// 参数验证
if req.Name == "" {
fac.Error(w, 1001, "用户名不能为空")
return
}
// 模拟创建用户
user := User{
ID: 1,
Name: req.Name,
Email: req.Email,
}
// 返回成功响应（使用factory方法，统一Success方法）
fac.Success(w, user, "创建成功")
}
// 获取用户详情（使用公共方法和factory）
func GetUser(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 获取查询参数（使用公共方法）
id := tools.ConvertInt64(r.URL.Query().Get("id"), 0)
if id == 0 {
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "用户ID不能为空", nil)
return
}
// 模拟查询用户
if id == 1 {
user := User{ID: 1, Name: "User1", Email: "user1@example.com"}
fac.Success(w, user)
} else {
fac.Error(w, 1002, "用户不存在")
}
}
func main() {
// 使用标准http.HandleFunc
http.HandleFunc("/users", func(w http.ResponseWriter, r *http.Request) {
switch r.Method {
case http.MethodGet:
GetUserList(w, r)
case http.MethodPost:
CreateUser(w, r)
default:
commonhttp.WriteJSON(w, http.StatusMethodNotAllowed, 405, "方法不支持", nil)
}
})
http.HandleFunc("/user", GetUser)
log.Println("Server started on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
} }

54
examples/http_pagination_example.go
View File

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

97
examples/i18n_example.go
View File

@@ -1,3 +1,6 @@
//go:build example
// +build example
package main package main
import ( import (
@@ -8,94 +11,22 @@ import (
) )
func main() { func main() {
// 创建工厂实例 if err := factory.Init("config.json"); err != nil {
fac, err := factory.NewFactoryFromFile("config.json") log.Fatal(err)
}
app := factory.Default()
i18n, err := app.I18n()
if err != nil { if err != nil {
log.Fatal(err) log.Fatal(err)
} }
// ====== 方式1：从目录加载多个语言文件（推荐） ====== if err := i18n.LoadFromDir("locales"); err != nil {
// 目录结构：
// locales/
// zh-CN.json
// en-US.json
// ja-JP.json
fac.InitI18n("zh-CN") // 设置默认语言为中文
if err := fac.LoadI18nFromDir("locales"); err != nil {
log.Fatal(err) log.Fatal(err)
} }
// 使用示例 fmt.Println("zh-CN:", i18n.GetMessage("zh-CN", "user.not_found"))
fmt.Println("=== 示例1：简单消息 ===") fmt.Println("en-US:", i18n.GetMessage("en-US", "user.not_found"))
msg1 := fac.GetMessage("zh-CN", "user.not_found") fmt.Println("welcome:", i18n.GetMessage("zh-CN", "user.welcome", "Alice"))
fmt.Printf("中文: %s\n", msg1) fmt.Println("langs:", i18n.GetSupportedLangs())
msg2 := fac.GetMessage("en-US", "user.not_found")
fmt.Printf("英文: %s\n", msg2)
// ====== 方式2：从单个文件加载 ======
fmt.Println("\n=== 示例2：从单个文件加载 ===")
fac2, _ := factory.NewFactoryFromFile("config.json")
fac2.InitI18n("zh-CN")
fac2.LoadI18nFromFile("locales/zh-CN.json", "zh-CN")
fac2.LoadI18nFromFile("locales/en-US.json", "en-US")
msg3 := fac2.GetMessage("zh-CN", "user.login_success")
fmt.Printf("中文: %s\n", msg3)
// ====== 示例3：带参数的消息 ======
fmt.Println("\n=== 示例3：带参数的消息 ===")
// 如果消息内容是 "欢迎，%s"，可以使用参数
msg4 := fac.GetMessage("zh-CN", "user.welcome", "Alice")
fmt.Printf("中文: %s\n", msg4)
msg5 := fac.GetMessage("en-US", "user.welcome", "Alice")
fmt.Printf("英文: %s\n", msg5)
// ====== 示例4：语言回退机制 ======
fmt.Println("\n=== 示例4：语言回退机制 ===")
// 如果请求的语言不存在，会使用默认语言
msg6 := fac.GetMessage("fr-FR", "user.not_found") // fr-FR 不存在，使用默认语言 zh-CN
fmt.Printf("法语（不存在，回退到默认语言）: %s\n", msg6)
// ====== 示例5：高级功能 ======
fmt.Println("\n=== 示例5：高级功能 ===")
i18n, _ := fac.GetI18n()
langs := i18n.GetSupportedLangs()
fmt.Printf("支持的语言: %v\n", langs)
hasLang := i18n.HasLang("en-US")
fmt.Printf("是否支持英文: %v\n", hasLang)
// ====== 示例6：在HTTP处理中使用 ======
fmt.Println("\n=== 示例6：在HTTP处理中使用 ===")
// 在实际HTTP处理中，可以从请求头获取语言
// lang := r.Header.Get("Accept-Language") // 例如: "zh-CN,en-US;q=0.9"
// 简化示例，假设从请求中获取到语言代码
userLang := "zh-CN"
errorMsg := fac.GetMessage(userLang, "user.not_found")
fmt.Printf("错误消息: %s\n", errorMsg)
successMsg := fac.GetMessage(userLang, "user.login_success")
fmt.Printf("成功消息: %s\n", successMsg)
// ====== 示例7：通过错误码直接返回国际化消息（推荐） ======
fmt.Println("\n=== 示例7：通过错误码直接返回国际化消息 ===")
// 在实际HTTP处理中，Error 方法会自动识别消息代码并返回国际化消息
// 需要确保使用了 middleware.Language 中间件（factory.GetMiddlewareChain() 已包含）
//
// 示例代码（在HTTP handler中）：
// func handleGetUser(w http.ResponseWriter, r *http.Request) {
// fac, _ := factory.NewFactoryFromFile("config.json")
//
// // 如果用户不存在，直接传入消息代码，会自动获取国际化消息
// fac.Error(w, r, 404, "user.not_found")
// // 自动从context获取语言（由middleware.Language设置），返回对应语言的错误消息
// // 返回: {"code": 404, "message": "用户不存在", "message_code": "user.not_found"}
// }
//
// 如果请求头是 Accept-Language: zh-CN，返回: {"code": 404, "message": "用户不存在", "message_code": "user.not_found"}
// 如果请求头是 Accept-Language: en-US，返回: {"code": 404, "message": "User not found", "message_code": "user.not_found"}
fmt.Println("Error 方法会自动识别消息代码并返回国际化消息和消息代码")
} }

58
examples/logger_example.go
View File

@@ -1,3 +1,6 @@
//go:build example
// +build example
package main package main
import ( import (
@@ -8,57 +11,24 @@ import (
) )
func main() { func main() {
// 加载配置
cfg, err := config.LoadFromFile("./config/example.json") cfg, err := config.LoadFromFile("./config/example.json")
if err != nil { if err != nil {
log.Fatal("Failed to load config:", err) log.Fatal(err)
} }
// 方式1：使用工厂创建日志记录器（推荐方式） app := factory.New(cfg)
fac := factory.NewFactory(cfg) logInst, err := app.Logger()
logger, err := fac.GetLogger()
if err != nil { if err != nil {
log.Fatal("Failed to create logger:", err) log.Fatal(err)
} }
defer logInst.Close()
// 如果使用异步模式，程序退出前需要关闭logger logInst.Info("Application started", nil)
defer logger.Close() logInst.Info("User logged in", map[string]any{
// 方式2：直接使用工厂的日志方法（黑盒模式，更简单）
// fac.LogInfo("Application started")
// fac.LogError("An error occurred")
// 示例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{}{
"user_id": 123, "user_id": 123,
"action": "login", "action": "login",
"ip": "192.168.1.1", })
}, "User logged in successfully") logInst.Error("Failed to connect to database", map[string]any{
"error": "connection timeout",
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")
// 示例4：异步模式使用
// 如果配置中设置了 "async": true，日志会异步写入
// 程序退出前需要调用 Close() 确保所有日志写入完成
// logger.Close()
// 注意：Fatal和Panic会终止程序，示例中不执行
// logger.Fatal("This would exit the program")
// logger.Panic("This would panic")
} }

36
examples/middleware_simple_example.go
View File

@@ -1,40 +1,30 @@
//go:build example
// +build example
package main package main
import ( import (
"log" "log"
"net/http" "net/http"
"git.toowon.com/jimmy/go-common/factory"
commonhttp "git.toowon.com/jimmy/go-common/http" commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/middleware"
) )
// 示例：简单的中间件配置
// 包括：Recovery、Logging、CORS、Timezone
func main() { func main() {
// 创建简单的中间件链（使用默认配置） if err := factory.Init("config.json"); err != nil {
chain := middleware.NewChain( log.Fatal(err)
middleware.Recovery(nil), // Panic恢复（使用默认logger） }
middleware.Logging(nil), // 请求日志（使用默认logger） app := factory.Default()
middleware.CORS(nil), // CORS（允许所有源） chain := app.MiddlewareChain()
middleware.Timezone, // 时区处理（默认AsiaShanghai）
)
// 定义API处理器
http.Handle("/api/hello", chain.ThenFunc(func(w http.ResponseWriter, r *http.Request) { http.Handle("/api/hello", chain.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
// 获取时区（使用公共方法） h := commonhttp.NewHandler(w, r)
timezone := commonhttp.GetTimezone(r) h.Success(map[string]any{
// 返回响应（使用公共方法）
commonhttp.Success(w, map[string]interface{}{
"message": "Hello, World!", "message": "Hello, World!",
"timezone": timezone, "timezone": h.GetTimezone(),
}) })
})) }))
// 启动服务器 log.Fatal(http.ListenAndServe(":8080", nil))
addr := ":8080"
log.Printf("Server starting on %s", addr)
log.Printf("Try: http://localhost%s/api/hello", addr)
log.Fatal(http.ListenAndServe(addr, nil))
} }

139
examples/migrations/README.md
View File

@@ -1,139 +0,0 @@
# 数据库迁移示例
这个目录包含了数据库迁移的示例SQL文件。
## 文件说明
```
examples/migrations/
├── migrations/ # 迁移文件目录
│ ├── 20240101000001_create_users_table.sql # 迁移SQL
│ └── 20240101000001_create_users_table.down.sql # 回滚SQL
└── README.md # 本文件
```
## 快速开始
### 在你的项目中使用
#### 1. 创建迁移工具
在项目根目录创建 `migrate.go`：
```go
package main
import (
"log"
"os"
"git.toowon.com/jimmy/go-common/migration"
)
func main() {
command := "up"
if len(os.Args) > 1 {
command = os.Args[1]
}
err := migration.RunMigrationsFromConfigWithCommand("config.json", "migrations", command)
if err != nil {
log.Fatal(err)
}
}
```
#### 2. 创建迁移文件
```bash
# 创建目录
mkdir -p migrations
# 创建迁移文件（使用时间戳作为版本号）
vim migrations/20240101000001_create_users.sql
```
#### 3. 编写SQL
```sql
-- migrations/20240101000001_create_users.sql
CREATE TABLE users (
id BIGINT PRIMARY KEY AUTO_INCREMENT,
username VARCHAR(255) NOT NULL,
email VARCHAR(255) NOT NULL
);
```
#### 4. 执行迁移
```bash
# 执行迁移
go run migrate.go up
# 查看状态
go run migrate.go status
# 回滚
go run migrate.go down
```
### 更简单：在应用启动时自动执行
在你的 `main.go` 中：
```go
import "git.toowon.com/jimmy/go-common/migration"
func main() {
// 一行代码，启动时自动迁移
migration.RunMigrationsFromConfig("config.json", "migrations")
// 继续启动应用
startServer()
}
```
## 配置方式
### 方式1：配置文件
`config.json`:
```json
{
"database": {
"type": "mysql",
"host": "localhost",
"port": 3306,
"user": "root",
"password": "password",
"database": "mydb"
}
}
```
### 方式2：使用配置文件（推荐）
```bash
# 使用默认配置文件 config.json
go run migrate.go up
# 或指定配置文件路径
go run migrate.go up -config /path/to/config.json
```
**Docker 中**：
```yaml
# docker-compose.yml
services:
app:
volumes:
# 挂载配置文件
- ./config.json:/app/config.json:ro
command: sh -c "go run migrate.go up && ./app"
```
**注意**：配置文件中的数据库主机应使用服务名（`db`），不是 `localhost`
## 更多信息
- [数据库迁移完整指南](../../MIGRATION.md) ⭐
- [详细功能文档](../../docs/migration.md)

95
examples/sms_example.go
View File

@@ -1,3 +1,6 @@
//go:build example
// +build example
package main package main
import ( import (
@@ -5,98 +8,30 @@ import (
"log" "log"
"git.toowon.com/jimmy/go-common/config" "git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/sms" "git.toowon.com/jimmy/go-common/factory"
) )
func main() { func main() {
// 加载配置
cfg, err := config.LoadFromFile("./config/example.json") cfg, err := config.LoadFromFile("./config/example.json")
if err != nil { if err != nil {
log.Fatal("Failed to load config:", err) log.Fatal(err)
} }
// 创建短信发送器 app := factory.New(cfg)
smsConfig := cfg.GetSMS() smsClient, err := app.SMS()
if smsConfig == nil {
log.Fatal("SMS config is nil")
}
smsClient, err := sms.NewSMS(smsConfig)
if err != nil { if err != nil {
log.Fatal("Failed to create SMS client:", err) log.Fatal(err)
} }
defer smsClient.Close()
// 示例1：发送原始请求（推荐，最灵活） params := map[string]string{"code": "123456"}
fmt.Println("=== Example 1: Send Raw SMS Request ===") resp, err := smsClient.SendSMS([]string{"13800138000"}, params)
// 外部构建完整的请求参数
params := map[string]string{
"PhoneNumbers": "13800138000",
"SignName": smsConfig.SignName,
"TemplateCode": smsConfig.TemplateCode,
"TemplateParam": `{"code":"123456","expire":"5"}`,
}
resp, err := smsClient.SendRaw(params)
if err != nil { if err != nil {
log.Printf("Failed to send raw SMS: %v", err) log.Printf("sync send failed: %v", err)
} else { } else {
fmt.Printf("Raw SMS sent successfully, RequestID: %s\n", resp.RequestID) fmt.Printf("sync sms sent, RequestID: %s\n", resp.RequestID)
} }
// 示例2：发送简单短信（使用配置中的模板代码） smsClient.SendSMSAsync(nil, []string{"13800138000"}, params)
fmt.Println("\n=== Example 2: Send Simple SMS ===") fmt.Println("async sms enqueued")
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")
}

11
excel/excel.go
View File

@@ -3,6 +3,7 @@ package excel
import ( import (
"fmt" "fmt"
"io" "io"
"os"
"reflect" "reflect"
"time" "time"
@@ -210,6 +211,16 @@ func (e *Excel) ExportToWriter(w io.Writer, sheetName string, columns []ExportCo
return e.file.Write(w) 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文件对象（高级功能时使用） // GetFile 获取Excel文件对象（高级功能时使用）
// 返回excelize.File对象，可用于高级操作 // 返回excelize.File对象，可用于高级操作
// //

1707
factory/factory.go
View File

File diff suppressed because it is too large Load Diff

2
go.mod
View File

@@ -5,6 +5,7 @@ go 1.24.0
toolchain go1.24.10 toolchain go1.24.10
require ( require (
github.com/google/uuid v1.6.0
github.com/minio/minio-go/v7 v7.0.97 github.com/minio/minio-go/v7 v7.0.97
github.com/redis/go-redis/v9 v9.17.1 github.com/redis/go-redis/v9 v9.17.1
github.com/xuri/excelize/v2 v2.10.0 github.com/xuri/excelize/v2 v2.10.0
@@ -21,7 +22,6 @@ require (
github.com/dustin/go-humanize v1.0.1 // indirect github.com/dustin/go-humanize v1.0.1 // indirect
github.com/go-ini/ini v1.67.0 // indirect github.com/go-ini/ini v1.67.0 // indirect
github.com/go-sql-driver/mysql v1.7.1 // 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/pgpassfile v1.0.0 // indirect
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
github.com/jackc/pgx/v5 v5.6.0 // indirect github.com/jackc/pgx/v5 v5.6.0 // indirect

95
http/handler.go Normal file
View File

@@ -0,0 +1,95 @@
package http
import (
"net/http"
"git.toowon.com/jimmy/go-common/i18n"
)
// Handler HTTP 出参处理器（唯一对外出参方式）
type Handler struct {
w http.ResponseWriter
r *http.Request
i18n *i18n.I18n
pagination *PaginationRequest
}
// HandlerOption Handler 配置项
type HandlerOption func(*Handler)
// WithI18n 注入 i18n
func WithI18n(i *i18n.I18n) HandlerOption {
return func(h *Handler) {
h.i18n = i
}
}
// 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
}
// ParseJSON 解析 JSON 请求体
func (h *Handler) ParseJSON(v interface{}) error {
return ParseJSON(h.r, v)
}
// 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 成功响应
func (h *Handler) Success(data interface{}) {
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 分页成功响应
func (h *Handler) SuccessPage(list interface{}, total int64) {
p := h.Pagination()
pageData := &PageData{
List: list,
Total: total,
Page: p.GetPage(),
PageSize: p.GetPageSize(),
}
h.Success(pageData)
}
// 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)
}

16
http/request.go
View File

@@ -5,7 +5,7 @@ import (
"io" "io"
"net/http" "net/http"
"git.toowon.com/jimmy/go-common/middleware" "git.toowon.com/jimmy/go-common/requestctx"
"git.toowon.com/jimmy/go-common/tools" "git.toowon.com/jimmy/go-common/tools"
) )
@@ -97,18 +97,12 @@ func ParseJSON(r *http.Request, v interface{}) error {
return json.Unmarshal(body, v) return json.Unmarshal(body, v)
} }
// GetTimezone 从请求的context中获取时区（公共方法） // GetTimezone 从请求的 context 中获取时区
// r: HTTP请求
// 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
// 如果未设置，返回默认时区 AsiaShanghai
func GetTimezone(r *http.Request) string { func GetTimezone(r *http.Request) string {
return middleware.GetTimezoneFromContext(r.Context()) return requestctx.Timezone(r.Context())
} }
// GetLanguage 从请求的context中获取语言（公共方法） // GetLanguage 从请求的 context 中获取语言
// r: HTTP请求
// 如果使用了middleware.Language中间件，可以从context中获取语言信息
// 如果未设置，返回默认语言 zh-CN
func GetLanguage(r *http.Request) string { func GetLanguage(r *http.Request) string {
return middleware.GetLanguageFromContext(r.Context()) return requestctx.Language(r.Context())
} }

85
http/response.go
View File

@@ -8,36 +8,24 @@ import (
// Response 标准响应结构 // Response 标准响应结构
type Response struct { 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"` Code int `json:"code"`
Message string `json:"message"` Message string `json:"message"`
Timestamp int64 `json:"timestamp"` Timestamp int64 `json:"timestamp"`
Data *PageData `json:"data"` Data interface{} `json:"data"`
} }
// PageData 分页数据 // PageData 分页数据
type PageData struct { type PageData struct {
List interface{} `json:"list"` // 数据列表 List interface{} `json:"list"`
Total int64 `json:"total"` // 总记录数 Total int64 `json:"total"`
Page int `json:"page"` // 当前页码 Page int `json:"page"`
PageSize int `json:"pageSize"` // 每页大小 PageSize int `json:"pageSize"`
} }
// writeJSON 写入JSON响应（公共方法） // writeResponse 统一 JSON 出参（HTTP 恒 200）
// httpCode: HTTP状态码（200表示正常，500表示系统错误等） func writeResponse(w http.ResponseWriter, code int, message string, data interface{}) {
// code: 业务状态码（0表示成功，非0表示业务错误）
// message: 响应消息
// data: 响应数据
func writeJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{}) {
w.Header().Set("Content-Type", "application/json; charset=utf-8") w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(httpCode) w.WriteHeader(http.StatusOK)
response := Response{ response := Response{
Code: code, Code: code,
@@ -46,60 +34,5 @@ func writeJSON(w http.ResponseWriter, httpCode, code int, message string, data i
Data: data, Data: data,
} }
json.NewEncoder(w).Encode(response) _ = json.NewEncoder(w).Encode(response)
}
// Success 成功响应（公共方法）
// w: ResponseWriter
// data: 响应数据，可以为nil
// message: 响应消息（可选），如果为空则使用默认消息 "success"
//
// 使用方式：
//
// Success(w, data) // 只有数据，使用默认消息 "success"
// Success(w, data, "查询成功") // 数据+消息
func Success(w http.ResponseWriter, data interface{}, message ...string) {
msg := "success"
if len(message) > 0 && message[0] != "" {
msg = message[0]
}
writeJSON(w, http.StatusOK, 0, msg, data)
}
// SuccessPage 分页成功响应（公共方法）
// w: ResponseWriter
// list: 数据列表
// total: 总记录数
// page: 当前页码
// pageSize: 每页大小
// message: 响应消息（可选），如果为空则使用默认消息 "success"
func SuccessPage(w http.ResponseWriter, list interface{}, total int64, page, pageSize int, message ...string) {
msg := "success"
if len(message) > 0 && message[0] != "" {
msg = message[0]
}
pageData := &PageData{
List: list,
Total: total,
Page: page,
PageSize: pageSize,
}
writeJSON(w, http.StatusOK, 0, msg, pageData)
}
// Error 错误响应（公共方法）
// w: ResponseWriter
// code: 业务错误码，非0表示业务错误
// message: 错误消息
func Error(w http.ResponseWriter, code int, message string) {
writeJSON(w, http.StatusOK, code, message, nil)
}
// SystemError 系统错误响应（返回HTTP 500）（公共方法）
// w: ResponseWriter
// message: 错误消息
func SystemError(w http.ResponseWriter, message string) {
writeJSON(w, http.StatusInternalServerError, 500, message, nil)
} }

526
logger/logger.go
View File

@@ -1,72 +1,100 @@
package logger package logger
import ( import (
"context"
"encoding/json"
"fmt" "fmt"
"io" "io"
"log"
"os" "os"
"path/filepath" "path/filepath"
"sync" "sync"
"sync/atomic"
"time"
"git.toowon.com/jimmy/go-common/config" "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 ( var (
// defaultLogger 全局默认日志记录器
// 用于中间件和其他需要快速日志记录的场景
defaultLogger *Logger defaultLogger *Logger
defaultMux sync.RWMutex defaultMux sync.RWMutex
) )
func init() { func init() {
// 初始化默认logger（同步模式，输出到stdout） l, err := NewLogger(nil)
var err error
defaultLogger, err = NewLogger(nil)
if err != nil { if err != nil {
// 如果初始化失败，使用nil，后续会降级到标准输出
defaultLogger = nil defaultLogger = nil
return
} }
defaultLogger = l
} }
// logMessage 异步日志消息结构 // SetDefaultLogger 设置全局默认 logger
type logMessage struct { func SetDefaultLogger(l *Logger) {
level string // debug, info, warn, error defaultMux.Lock()
format string defer defaultMux.Unlock()
args []interface{} if defaultLogger != nil && defaultLogger != l {
fields map[string]interface{} // 用于带字段的日志 _ = 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 日志记录器 // Logger 日志记录器
type Logger struct { type Logger struct {
infoLog *log.Logger level string
errorLog *log.Logger writers []io.Writer
warnLog *log.Logger prefix string
debugLog *log.Logger async bool
config *config.LoggerConfig logChan chan logEntry
done chan struct{}
// 异步相关字段 wg sync.WaitGroup
async bool // 是否异步模式 closed bool
logChan chan *logMessage // 异步日志channel mu sync.RWMutex
done chan struct{} // 用于优雅关闭 dropped atomic.Uint64
wg sync.WaitGroup // 等待所有日志写入完成
closed bool // 是否已关闭
closeMux sync.RWMutex // 保护closed字段
} }
// NewLogger 创建日志记录器 // NewLogger 创建日志记录器
func NewLogger(cfg *config.LoggerConfig) (*Logger, error) { func NewLogger(cfg *config.LoggerConfig) (*Logger, error) {
if cfg == nil { if cfg == nil {
// 使用默认配置
cfg = &config.LoggerConfig{ cfg = &config.LoggerConfig{
Level: "info", Level: "info",
Output: "stdout", Output: "stdout",
FilePath: "", Async: config.BoolPtr(true),
Async: false, // 默认同步 BufferSize: 1000,
BufferSize: 1000, // 默认缓冲区大小
} }
} }
// 设置默认值
if cfg.Level == "" { if cfg.Level == "" {
cfg.Level = "info" cfg.Level = "info"
} }
@@ -74,10 +102,37 @@ func NewLogger(cfg *config.LoggerConfig) (*Logger, error) {
cfg.Output = "stdout" cfg.Output = "stdout"
} }
if cfg.BufferSize <= 0 { if cfg.BufferSize <= 0 {
cfg.BufferSize = 1000 // 默认缓冲区大小 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 var writers []io.Writer
switch cfg.Output { switch cfg.Output {
case "stdout": case "stdout":
@@ -88,96 +143,56 @@ func NewLogger(cfg *config.LoggerConfig) (*Logger, error) {
if cfg.FilePath == "" { if cfg.FilePath == "" {
return nil, fmt.Errorf("file path is required when output is file") return nil, fmt.Errorf("file path is required when output is file")
} }
// 确保目录存在 w, err := openLogFile(cfg.FilePath)
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)
if err != nil { 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": case "both":
writers = append(writers, os.Stdout) writers = append(writers, os.Stdout)
if cfg.FilePath == "" { if cfg.FilePath == "" {
return nil, fmt.Errorf("file path is required when output is both") return nil, fmt.Errorf("file path is required when output is both")
} }
dir := filepath.Dir(cfg.FilePath) w, err := openLogFile(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)
if err != nil { 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: default:
return nil, fmt.Errorf("invalid output type: %s", cfg.Output) 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) {
logger := &Logger{ dir := filepath.Dir(path)
config: cfg, if err := os.MkdirAll(dir, 0o755); err != nil {
async: cfg.Async, return nil, fmt.Errorf("failed to create log directory: %w", err)
}
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
}
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)
}
}
// 如果启用异步模式，启动goroutine处理日志
if cfg.Async {
logger.logChan = make(chan *logMessage, cfg.BufferSize)
logger.done = make(chan struct{})
logger.wg.Add(1)
go logger.processLogs()
}
return logger, nil
}
// processLogs 异步处理日志（goroutine）
func (l *Logger) processLogs() { func (l *Logger) processLogs() {
defer l.wg.Done() defer l.wg.Done()
for { for {
select { select {
case msg := <-l.logChan: case msg, ok := <-l.logChan:
if msg == nil { if !ok {
// channel已关闭，退出
return return
} }
l.writeLog(msg) l.writeEntry(msg)
case <-l.done: case <-l.done:
// 收到关闭信号，处理完剩余日志后退出
for { for {
select { select {
case msg := <-l.logChan: case msg, ok := <-l.logChan:
if msg == nil { if !ok {
return return
} }
l.writeLog(msg) l.writeEntry(msg)
default: default:
return return
} }
@@ -186,278 +201,161 @@ func (l *Logger) processLogs() {
} }
} }
// writeLog 实际写入日志（内部方法）
func (l *Logger) writeLog(msg *logMessage) {
var logger *log.Logger
switch msg.level {
case "debug":
logger = l.debugLog
case "info":
logger = l.infoLog
case "warn":
logger = l.warnLog
case "error":
logger = l.errorLog
default:
return
}
if logger == nil {
return
}
// 如果有字段，先格式化字段
format := msg.format
if len(msg.fields) > 0 {
fieldStr := formatFields(msg.fields)
format = fieldStr + format
}
// 写入日志
logger.Printf(format, msg.args...)
}
// isClosed 检查logger是否已关闭
func (l *Logger) isClosed() bool { func (l *Logger) isClosed() bool {
l.closeMux.RLock() l.mu.RLock()
defer l.closeMux.RUnlock() defer l.mu.RUnlock()
return l.closed return l.closed
} }
// setClosed 设置logger为已关闭状态 func (l *Logger) shouldLog(level string) bool {
func (l *Logger) setClosed() { switch l.level {
l.closeMux.Lock() case "debug":
defer l.closeMux.Unlock() return true
l.closed = true case "info":
return level != "debug"
case "error":
return level == "error"
default:
return level != "debug"
}
} }
// log 内部日志方法，根据模式选择同步或异步 func (l *Logger) emit(level, message string, fields map[string]any) {
func (l *Logger) log(level string, format string, args []interface{}, fields map[string]interface{}) { if l.isClosed() || !l.shouldLog(level) {
// 如果已关闭，直接返回
if l.isClosed() {
return return
} }
// 如果是异步模式，发送到channel entry := logEntry{level: level, message: message, fields: fields}
if l.async { if l.async {
// 检查channel是否已关闭
select { select {
case l.logChan <- &logMessage{ case l.logChan <- entry:
level: level,
format: format,
args: args,
fields: fields,
}:
// 成功发送
default: default:
// channel已满或已关闭，同步写入（降级处理） l.dropped.Add(1)
l.writeLog(&logMessage{
level: level,
format: format,
args: args,
fields: fields,
})
} }
} else { return
// 同步模式，直接写入
l.writeLog(&logMessage{
level: level,
format: format,
args: args,
fields: fields,
})
} }
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 记录调试日志 // Debug 记录调试日志
func (l *Logger) Debug(format string, v ...interface{}) { func (l *Logger) Debug(message string, fields map[string]any) {
l.log("debug", format, v, nil) l.emit("debug", message, fields)
} }
// Info 记录信息日志 // Info 记录信息日志
func (l *Logger) Info(format string, v ...interface{}) { func (l *Logger) Info(message string, fields map[string]any) {
l.log("info", format, v, nil) l.emit("info", message, fields)
}
// Warn 记录警告日志
func (l *Logger) Warn(format string, v ...interface{}) {
l.log("warn", format, v, nil)
} }
// Error 记录错误日志 // Error 记录错误日志
func (l *Logger) Error(format string, v ...interface{}) { func (l *Logger) Error(message string, fields map[string]any) {
l.log("error", format, v, nil) l.emit("error", message, fields)
} }
// Fatal 记录致命错误日志并退出程序（始终同步） // Close 刷盘并关闭异步队列
func (l *Logger) Fatal(format string, v ...interface{}) {
// Fatal必须同步执行，确保日志写入后再退出
if l.errorLog != nil {
l.errorLog.Fatalf(format, v...)
} else {
log.Fatalf(format, v...)
}
}
// Panic 记录恐慌日志并触发panic（始终同步）
func (l *Logger) Panic(format string, v ...interface{}) {
// Panic必须同步执行，确保日志写入后再panic
if l.errorLog != nil {
l.errorLog.Panicf(format, v...)
} else {
log.Panicf(format, v...)
}
}
// WithFields 创建带字段的日志记录器（简化版，返回格式化字符串）
func (l *Logger) WithFields(fields map[string]interface{}) *Logger {
// 返回自身，实际使用时可以在format中包含fields
return l
}
// formatFields 格式化字段
func formatFields(fields map[string]interface{}) string {
if len(fields) == 0 {
return ""
}
result := ""
for k, v := range fields {
result += fmt.Sprintf("%s=%v ", k, v)
}
return result
}
// Debugf 记录调试日志（带字段）
func (l *Logger) Debugf(fields map[string]interface{}, format string, v ...interface{}) {
l.log("debug", format, v, fields)
}
// Infof 记录信息日志（带字段）
func (l *Logger) Infof(fields map[string]interface{}, format string, v ...interface{}) {
l.log("info", format, v, fields)
}
// Warnf 记录警告日志（带字段）
func (l *Logger) Warnf(fields map[string]interface{}, format string, v ...interface{}) {
l.log("warn", format, v, fields)
}
// Errorf 记录错误日志（带字段）
func (l *Logger) Errorf(fields map[string]interface{}, format string, v ...interface{}) {
l.log("error", format, v, fields)
}
// Close 优雅关闭logger（仅异步模式需要）
// 等待所有日志写入完成后再返回
func (l *Logger) Close() error { func (l *Logger) Close() error {
if !l.async { if !l.async {
// 同步模式不需要关闭
return nil return nil
} }
l.mu.Lock()
// 检查是否已关闭 if l.closed {
if l.isClosed() { l.mu.Unlock()
return nil return nil
} }
l.closed = true
l.mu.Unlock()
// 设置关闭状态
l.setClosed()
// 发送关闭信号
close(l.done) close(l.done)
// 关闭channel（会触发processLogs退出）
close(l.logChan) close(l.logChan)
// 等待所有日志写入完成
l.wg.Wait() l.wg.Wait()
return nil return nil
} }
// ========== 全局默认Logger相关方法 ========== // DroppedCount 返回因队列满而丢弃的日志条数
func (l *Logger) DroppedCount() uint64 {
// SetDefaultLogger 设置全局默认logger return l.dropped.Load()
// 用于在应用启动时统一配置logger
func SetDefaultLogger(log *Logger) {
defaultMux.Lock()
defer defaultMux.Unlock()
// 如果之前有logger，先关闭它
if defaultLogger != nil {
defaultLogger.Close()
} }
defaultLogger = log // ContextLogger 带 context 的 logger（自动附加 request_id）
type ContextLogger struct {
base *Logger
ctx context.Context
} }
// GetDefaultLogger 获取全局默认logger // FromContext 从 context 获取 logger，自动附加 request_id
func GetDefaultLogger() *Logger { func FromContext(ctx context.Context) *ContextLogger {
defaultMux.RLock() base := getDefaultLogger()
defer defaultMux.RUnlock() if base == nil {
return defaultLogger if l, err := NewLogger(nil); err == nil {
base = l
}
}
return &ContextLogger{base: base, ctx: ctx}
} }
// Default 全局日志方法 - Debug // FromContextWithLogger 使用指定 logger 并从 context 附加 request_id
func Default() *Logger { func FromContextWithLogger(ctx context.Context, base *Logger) *ContextLogger {
return GetDefaultLogger() if base == nil {
base = getDefaultLogger()
}
return &ContextLogger{base: base, ctx: ctx}
} }
// ========== 全局便捷日志方法 ========== func (c *ContextLogger) mergeFields(fields map[string]any) map[string]any {
// 以下方法使用全局默认logger，方便快速记录日志 out := make(map[string]any, len(fields)+1)
for k, v := range fields {
// Debug 使用全局logger记录调试日志 out[k] = v
func Debug(format string, v ...interface{}) {
if log := GetDefaultLogger(); log != nil {
log.Debug(format, v...)
} }
if id := RequestIDFromContext(c.ctx); id != "" {
out["request_id"] = id
}
return out
} }
// Info 使用全局logger记录信息日志 // Debug 记录调试日志
func Info(format string, v ...interface{}) { func (c *ContextLogger) Debug(message string, fields map[string]any) {
if log := GetDefaultLogger(); log != nil { if c.base == nil {
log.Info(format, v...) return
} }
c.base.Debug(message, c.mergeFields(fields))
} }
// Warn 使用全局logger记录警告日志 // Info 记录信息日志
func Warn(format string, v ...interface{}) { func (c *ContextLogger) Info(message string, fields map[string]any) {
if log := GetDefaultLogger(); log != nil { if c.base == nil {
log.Warn(format, v...) return
} }
c.base.Info(message, c.mergeFields(fields))
} }
// Error 使用全局logger记录错误日志 // Error 记录错误日志
func Error(format string, v ...interface{}) { func (c *ContextLogger) Error(message string, fields map[string]any) {
if log := GetDefaultLogger(); log != nil { if c.base == nil {
log.Error(format, v...) return
}
}
// Debugf 使用全局logger记录调试日志（带字段）
func Debugf(fields map[string]interface{}, format string, v ...interface{}) {
if log := GetDefaultLogger(); log != nil {
log.Debugf(fields, format, v...)
}
}
// Infof 使用全局logger记录信息日志（带字段）
func Infof(fields map[string]interface{}, format string, v ...interface{}) {
if log := GetDefaultLogger(); log != nil {
log.Infof(fields, format, v...)
}
}
// Warnf 使用全局logger记录警告日志（带字段）
func Warnf(fields map[string]interface{}, format string, v ...interface{}) {
if log := GetDefaultLogger(); log != nil {
log.Warnf(fields, format, v...)
}
}
// Errorf 使用全局logger记录错误日志（带字段）
func Errorf(fields map[string]interface{}, format string, v ...interface{}) {
if log := GetDefaultLogger(); log != nil {
log.Errorf(fields, format, v...)
} }
c.base.Error(message, c.mergeFields(fields))
} }

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
}

21
middleware/language.go
View File

@@ -4,10 +4,9 @@ import (
"context" "context"
"net/http" "net/http"
"strings" "strings"
)
// LanguageKey context中存储语言的key "git.toowon.com/jimmy/go-common/requestctx"
type languageKey struct{} )
// LanguageHeaderName 语言请求头名称 // LanguageHeaderName 语言请求头名称
const LanguageHeaderName = "X-Language" const LanguageHeaderName = "X-Language"
@@ -15,15 +14,9 @@ const LanguageHeaderName = "X-Language"
// AcceptLanguageHeaderName Accept-Language 请求头名称 // AcceptLanguageHeaderName Accept-Language 请求头名称
const AcceptLanguageHeaderName = "Accept-Language" const AcceptLanguageHeaderName = "Accept-Language"
// DefaultLanguage 默认语言
const DefaultLanguage = "zh-CN"
// GetLanguageFromContext 从 context 中获取语言 // GetLanguageFromContext 从 context 中获取语言
func GetLanguageFromContext(ctx context.Context) string { func GetLanguageFromContext(ctx context.Context) string {
if lang, ok := ctx.Value(languageKey{}).(string); ok && lang != "" { return requestctx.Language(ctx)
return lang
}
return DefaultLanguage
} }
// Language 语言处理中间件 // Language 语言处理中间件
@@ -44,11 +37,10 @@ func Language(next http.Handler) http.Handler {
// 3. 如果都未设置，使用默认语言 // 3. 如果都未设置，使用默认语言
if lang == "" { if lang == "" {
lang = DefaultLanguage lang = requestctx.DefaultLanguage
} }
// 将语言存储到context中 ctx := requestctx.WithLanguage(r.Context(), lang)
ctx := context.WithValue(r.Context(), languageKey{}, lang)
next.ServeHTTP(w, r.WithContext(ctx)) next.ServeHTTP(w, r.WithContext(ctx))
}) })
} }
@@ -74,8 +66,7 @@ func LanguageWithDefault(defaultLanguage string) func(http.Handler) http.Handler
lang = defaultLanguage lang = defaultLanguage
} }
// 将语言存储到context中 ctx := requestctx.WithLanguage(r.Context(), lang)
ctx := context.WithValue(r.Context(), languageKey{}, lang)
next.ServeHTTP(w, r.WithContext(ctx)) next.ServeHTTP(w, r.WithContext(ctx))
}) })
} }

187
middleware/logging.go
View File

@@ -2,17 +2,15 @@ package middleware
import ( import (
"net/http" "net/http"
"strconv"
"time" "time"
"git.toowon.com/jimmy/go-common/logger" "git.toowon.com/jimmy/go-common/logger"
) )
// responseWriter 包装 http.ResponseWriter 以捕获状态码和响应大小 // responseWriter 包装 ResponseWriter 以捕获状态码
type responseWriter struct { type responseWriter struct {
http.ResponseWriter http.ResponseWriter
statusCode int statusCode int
size int
} }
func (rw *responseWriter) WriteHeader(statusCode int) { func (rw *responseWriter) WriteHeader(statusCode int) {
@@ -20,202 +18,49 @@ func (rw *responseWriter) WriteHeader(statusCode int) {
rw.ResponseWriter.WriteHeader(statusCode) rw.ResponseWriter.WriteHeader(statusCode)
} }
func (rw *responseWriter) Write(b []byte) (int, error) {
size, err := rw.ResponseWriter.Write(b)
rw.size += size
return size, err
}
// LoggingConfig 日志中间件配置 // LoggingConfig 日志中间件配置
type LoggingConfig struct { type LoggingConfig struct {
// Logger 日志记录器（可选，如果为nil则使用默认logger）
Logger *logger.Logger Logger *logger.Logger
// SkipPaths 跳过记录的路径列表（如健康检查接口）
SkipPaths []string SkipPaths []string
// LogRequestBody 是否记录请求体（谨慎使用，可能影响性能）
LogRequestBody bool
// LogResponseBody 是否记录响应体（谨慎使用，可能影响性能和内存）
LogResponseBody bool
} }
// Logging HTTP请求日志中间件 // Logging HTTP 访问日志（固定 Info 级别）
// 记录每个HTTP请求的详细信息，包括：
// - 请求方法、路径、IP、User-Agent
// - 响应状态码、响应大小
// - 请求处理时间
//
// 使用方式1：使用默认logger
//
// chain := middleware.NewChain(
// middleware.Logging(nil),
// )
//
// 使用方式2：使用自定义logger
//
// myLogger, _ := logger.NewLogger(loggerConfig)
// chain := middleware.NewChain(
// middleware.Logging(&middleware.LoggingConfig{
// Logger: myLogger,
// SkipPaths: []string{"/health", "/metrics"},
// }),
// )
func Logging(config *LoggingConfig) func(http.Handler) http.Handler { func Logging(config *LoggingConfig) func(http.Handler) http.Handler {
// 如果没有配置，使用默认配置
if config == nil { if config == nil {
config = &LoggingConfig{} config = &LoggingConfig{}
} }
// 如果没有提供logger，创建一个默认的
if config.Logger == nil {
// 使用默认配置创建logger（输出到stdout，info级别）
defaultLogger, err := logger.NewLogger(nil)
if err != nil {
// 如果创建失败，使用nil，后面会降级处理
config.Logger = nil
} else {
config.Logger = defaultLogger
}
}
return func(next http.Handler) http.Handler { return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 检查是否跳过此路径
if shouldSkipPath(r.URL.Path, config.SkipPaths) { if shouldSkipPath(r.URL.Path, config.SkipPaths) {
next.ServeHTTP(w, r) next.ServeHTTP(w, r)
return return
} }
// 记录开始时间 start := time.Now()
startTime := time.Now() rw := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK}
// 包装 ResponseWriter 以捕获状态码和响应大小
rw := &responseWriter{
ResponseWriter: w,
statusCode: http.StatusOK, // 默认200
size: 0,
}
// 处理请求
next.ServeHTTP(rw, r) next.ServeHTTP(rw, r)
// 计算处理时间 fields := map[string]any{
duration := time.Since(startTime) "method": r.Method,
"path": r.URL.Path,
"duration": time.Since(start).Milliseconds(),
}
// 记录日志 log := logger.FromContext(r.Context())
logHTTPRequest(config.Logger, r, rw, duration) if config.Logger != nil {
log = logger.FromContextWithLogger(r.Context(), config.Logger)
}
log.Info("HTTP Request", fields)
}) })
} }
} }
// shouldSkipPath 检查是否应该跳过该路径
func shouldSkipPath(path string, skipPaths []string) bool { func shouldSkipPath(path string, skipPaths []string) bool {
for _, skipPath := range skipPaths { for _, skip := range skipPaths {
if path == skipPath { if path == skip {
return true return true
} }
} }
return false return false
} }
// logHTTPRequest 记录HTTP请求日志
func logHTTPRequest(log *logger.Logger, r *http.Request, rw *responseWriter, duration time.Duration) {
// 获取客户端IP
clientIP := GetClientIP(r)
// 构建日志字段
fields := map[string]interface{}{
"method": r.Method,
"path": r.URL.Path,
"query": r.URL.RawQuery,
"status": rw.statusCode,
"size": rw.size,
"duration": duration.Milliseconds(), // 毫秒
"ip": clientIP,
"user_agent": r.UserAgent(),
"referer": r.Referer(),
}
// 构建日志消息
message := "HTTP Request"
// 根据状态码选择日志级别
if log != nil {
// 使用提供的logger
if rw.statusCode >= 500 {
log.Errorf(fields, message)
} else if rw.statusCode >= 400 {
log.Warnf(fields, message)
} else {
log.Infof(fields, message)
}
} else {
// 降级处理：使用标准输出
// 注意：这是同步的，不会有性能问题
if rw.statusCode >= 500 {
logToStdout("ERROR", fields, message)
} else if rw.statusCode >= 400 {
logToStdout("WARN", fields, message)
} else {
logToStdout("INFO", fields, message)
}
}
}
// logToStdout 降级处理：输出到标准输出（当logger不可用时）
func logToStdout(level string, fields map[string]interface{}, message string) {
// 简单的标准输出日志
var fieldStr string
for k, v := range fields {
fieldStr += " " + k + "=" + formatValue(v)
}
println("[" + level + "] " + message + fieldStr)
}
// formatValue 格式化值（用于日志输出）
func formatValue(v interface{}) string {
switch val := v.(type) {
case string:
return val
case int:
return strconv.Itoa(val)
case int64:
return strconv.FormatInt(val, 10)
default:
return ""
}
}
// GetClientIP 获取客户端真实IP
// 优先级：X-Forwarded-For > X-Real-IP > RemoteAddr
func GetClientIP(r *http.Request) string {
// 尝试从 X-Forwarded-For 获取
xff := r.Header.Get("X-Forwarded-For")
if xff != "" {
// X-Forwarded-For 可能包含多个IP，取第一个
for idx := 0; idx < len(xff); idx++ {
if xff[idx] == ',' {
return xff[:idx]
}
}
return xff
}
// 尝试从 X-Real-IP 获取
xri := r.Header.Get("X-Real-IP")
if xri != "" {
return xri
}
// 使用 RemoteAddr
remoteAddr := r.RemoteAddr
// 移除端口号
for i := len(remoteAddr) - 1; i >= 0; i-- {
if remoteAddr[i] == ':' {
return remoteAddr[:i]
}
}
return remoteAddr
}

140
middleware/recovery.go
View File

@@ -5,145 +5,43 @@ import (
"net/http" "net/http"
"runtime/debug" "runtime/debug"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/i18n"
"git.toowon.com/jimmy/go-common/logger" "git.toowon.com/jimmy/go-common/logger"
) )
// RecoveryConfig Recovery 中间件配置 // RecoveryConfig Recovery 中间件配置
type RecoveryConfig struct { type RecoveryConfig struct {
// Logger 日志记录器（可选，如果为nil则使用默认logger）
Logger *logger.Logger Logger *logger.Logger
I18n *i18n.I18n
// EnableStackTrace 是否在日志中包含堆栈跟踪
EnableStackTrace bool
// CustomHandler 自定义错误处理函数（可选）
// 如果设置了，会在记录日志后调用此函数
// 可以用于自定义错误响应格式
CustomHandler func(w http.ResponseWriter, r *http.Request, err interface{})
} }
// Recovery Panic恢复中间件 // Recovery Panic 恢复中间件，响应统一 JSON 200 + system.internal_error
// 捕获HTTP处理过程中的panic，记录错误日志并返回500错误
// 防止panic导致整个服务崩溃
//
// 使用方式1：使用默认配置
//
// chain := middleware.NewChain(
// middleware.Recovery(nil),
// )
//
// 使用方式2：使用自定义配置
//
// myLogger, _ := logger.NewLogger(loggerConfig)
// chain := middleware.NewChain(
// middleware.Recovery(&middleware.RecoveryConfig{
// Logger: myLogger,
// EnableStackTrace: true,
// }),
// )
//
// 使用方式3：自定义错误响应
//
// chain := middleware.NewChain(
// middleware.Recovery(&middleware.RecoveryConfig{
// Logger: myLogger,
// CustomHandler: func(w http.ResponseWriter, r *http.Request, err interface{}) {
// // 自定义JSON响应
// w.Header().Set("Content-Type", "application/json")
// w.WriteHeader(http.StatusInternalServerError)
// w.Write([]byte(`{"code":500,"message":"Internal Server Error"}`))
// },
// }),
// )
func Recovery(config *RecoveryConfig) func(http.Handler) http.Handler { func Recovery(config *RecoveryConfig) func(http.Handler) http.Handler {
// 如果没有配置，使用默认配置
if config == nil {
config = &RecoveryConfig{
EnableStackTrace: true, // 默认启用堆栈跟踪
}
}
// 如果没有提供logger，创建一个默认的
if config.Logger == nil {
defaultLogger, err := logger.NewLogger(nil)
if err != nil {
config.Logger = nil
} else {
config.Logger = defaultLogger
}
}
return func(next http.Handler) http.Handler { return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() { defer func() {
if err := recover(); err != nil { if err := recover(); err != nil {
// 记录panic信息 fields := map[string]any{
logPanic(config.Logger, r, err, config.EnableStackTrace) "method": r.Method,
"path": r.URL.Path,
// 如果提供了自定义处理函数，调用它 "error": fmt.Sprintf("%v", err),
if config.CustomHandler != nil { "stack": string(debug.Stack()),
config.CustomHandler(w, r, err)
return
} }
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)
http.Error(w, "Internal Server Error", http.StatusInternalServerError) if config != nil && config.I18n != nil {
h = commonhttp.NewHandler(w, r, commonhttp.WithI18n(config.I18n))
}
h.Error("system.internal_error")
} }
}() }()
next.ServeHTTP(w, r) next.ServeHTTP(w, r)
}) })
} }
} }
// logPanic 记录panic日志
func logPanic(log *logger.Logger, r *http.Request, err interface{}, enableStackTrace bool) {
// 获取堆栈跟踪
var stack string
if enableStackTrace {
stack = string(debug.Stack())
}
// 构建日志字段
fields := map[string]interface{}{
"method": r.Method,
"path": r.URL.Path,
"query": r.URL.RawQuery,
"ip": GetClientIP(r),
"error": fmt.Sprintf("%v", err),
}
// 构建日志消息
message := "Panic recovered"
if enableStackTrace && stack != "" {
message += "\n" + stack
}
// 记录错误日志
if log != nil {
log.Errorf(fields, message)
} else {
// 降级处理：输出到标准错误
fmt.Printf("[ERROR] %s\n", message)
for k, v := range fields {
fmt.Printf(" %s: %v\n", k, v)
}
}
}
// RecoveryWithLogger 使用指定logger的Recovery中间件（便捷函数）
func RecoveryWithLogger(log *logger.Logger) func(http.Handler) http.Handler {
return Recovery(&RecoveryConfig{
Logger: log,
EnableStackTrace: true,
})
}
// RecoveryWithCustomHandler 使用自定义错误处理的Recovery中间件（便捷函数）
func RecoveryWithCustomHandler(customHandler func(w http.ResponseWriter, r *http.Request, err interface{})) func(http.Handler) http.Handler {
return Recovery(&RecoveryConfig{
EnableStackTrace: true,
CustomHandler: customHandler,
})
}

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))
})
}
}

43
middleware/timezone.go
View File

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

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
}

202
sms/sms.go
View File

@@ -1,6 +1,7 @@
package sms package sms
import ( import (
"context"
"crypto/hmac" "crypto/hmac"
"crypto/sha1" "crypto/sha1"
"encoding/base64" "encoding/base64"
@@ -11,29 +12,40 @@ import (
"net/url" "net/url"
"sort" "sort"
"strings" "strings"
"sync"
"sync/atomic"
"time" "time"
"git.toowon.com/jimmy/go-common/config" "git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/logger"
) )
// SendResponse 发送短信响应 // SendResponse 发送短信响应
type SendResponse struct { type SendResponse struct {
// RequestID 请求ID
RequestID string `json:"RequestId"` RequestID string `json:"RequestId"`
// Code 响应码
Code string `json:"Code"` Code string `json:"Code"`
// Message 响应消息
Message string `json:"Message"` Message string `json:"Message"`
// BizID 业务ID
BizID string `json:"BizId"` BizID string `json:"BizId"`
} }
// SMS 短信发送器 // SMS 短信发送器
type SMS struct { type SMS struct {
config *config.SMSConfig 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 创建短信发送器 // NewSMS 创建短信发送器
@@ -41,81 +53,87 @@ func NewSMS(cfg *config.Config) *SMS {
if cfg == nil || cfg.SMS == nil { if cfg == nil || cfg.SMS == nil {
return &SMS{config: nil} return &SMS{config: nil}
} }
return &SMS{config: cfg.SMS} 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,
})
}
}
} }
// getSMSConfig 获取短信配置（内部方法）
func (s *SMS) getSMSConfig() (*config.SMSConfig, error) { func (s *SMS) getSMSConfig() (*config.SMSConfig, error) {
if s.config == nil { if s.config == nil {
return nil, fmt.Errorf("SMS config is nil") return nil, fmt.Errorf("SMS config is nil")
} }
if s.config.AccessKeyID == "" { if s.config.AccessKeyID == "" {
return nil, fmt.Errorf("AccessKeyID is required") return nil, fmt.Errorf("AccessKeyID is required")
} }
if s.config.AccessKeySecret == "" { if s.config.AccessKeySecret == "" {
return nil, fmt.Errorf("AccessKeySecret is required") return nil, fmt.Errorf("AccessKeySecret is required")
} }
if s.config.SignName == "" { if s.config.SignName == "" {
return nil, fmt.Errorf("SignName is required") return nil, fmt.Errorf("SignName is required")
} }
// 设置默认值
if s.config.Region == "" { if s.config.Region == "" {
s.config.Region = "cn-hangzhou" s.config.Region = "cn-hangzhou"
} }
if s.config.Timeout == 0 { if s.config.Timeout == 0 {
s.config.Timeout = 10 s.config.Timeout = 5
} }
return s.config, nil return s.config, nil
} }
// SendSMS 发送短信 // SendSMS 同步发送短信
// phoneNumbers: 手机号列表
// templateParam: 模板参数（map或JSON字符串）
// templateCode: 模板代码（可选，如果为空使用配置中的模板代码）
func (s *SMS) SendSMS(phoneNumbers []string, templateParam interface{}, templateCode ...string) (*SendResponse, error) { func (s *SMS) SendSMS(phoneNumbers []string, templateParam interface{}, templateCode ...string) (*SendResponse, error) {
cfg, err := s.getSMSConfig() cfg, err := s.getSMSConfig()
if err != nil { if err != nil {
return nil, err return nil, err
} }
if len(phoneNumbers) == 0 { if len(phoneNumbers) == 0 {
return nil, fmt.Errorf("phone numbers are required") return nil, fmt.Errorf("phone numbers are required")
} }
// 使用配置中的模板代码（如果请求中未指定） templateCodeValue := cfg.TemplateCode
templateCodeValue := ""
if len(templateCode) > 0 && templateCode[0] != "" { if len(templateCode) > 0 && templateCode[0] != "" {
templateCodeValue = templateCode[0] templateCodeValue = templateCode[0]
} else {
templateCodeValue = cfg.TemplateCode
} }
if templateCodeValue == "" { if templateCodeValue == "" {
return nil, fmt.Errorf("template code is required") return nil, fmt.Errorf("template code is required")
} }
signName := cfg.SignName
// 处理模板参数
var templateParamJSON string var templateParamJSON string
if templateParam != nil { if templateParam != nil {
switch v := templateParam.(type) { switch v := templateParam.(type) {
case string: case string:
// 直接使用字符串（必须是有效的JSON）
templateParamJSON = v 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: default:
// 尝试JSON序列化
paramBytes, err := json.Marshal(v) paramBytes, err := json.Marshal(v)
if err != nil { if err != nil {
return nil, fmt.Errorf("failed to marshal template param: %w", err) return nil, fmt.Errorf("failed to marshal template param: %w", err)
@@ -126,104 +144,120 @@ func (s *SMS) SendSMS(phoneNumbers []string, templateParam interface{}, template
templateParamJSON = "{}" templateParamJSON = "{}"
} }
// 构建请求参数 params := map[string]string{
params := make(map[string]string) "Action": "SendSms",
params["Action"] = "SendSms" "Version": "2017-05-25",
params["Version"] = "2017-05-25" "RegionId": cfg.Region,
params["RegionId"] = cfg.Region "AccessKeyId": cfg.AccessKeyID,
params["AccessKeyId"] = cfg.AccessKeyID "Format": "JSON",
params["Format"] = "JSON" "SignatureMethod": "HMAC-SHA1",
params["SignatureMethod"] = "HMAC-SHA1" "SignatureVersion": "1.0",
params["SignatureVersion"] = "1.0" "SignatureNonce": fmt.Sprint(time.Now().UnixNano()),
params["SignatureNonce"] = fmt.Sprint(time.Now().UnixNano()) "Timestamp": time.Now().UTC().Format("2006-01-02T15:04:05Z"),
params["Timestamp"] = time.Now().UTC().Format("2006-01-02T15:04:05Z") "PhoneNumbers": strings.Join(phoneNumbers, ","),
params["PhoneNumbers"] = strings.Join(phoneNumbers, ",") "SignName": cfg.SignName,
params["SignName"] = signName "TemplateCode": templateCodeValue,
params["TemplateCode"] = templateCodeValue "TemplateParam": templateParamJSON,
params["TemplateParam"] = templateParamJSON }
params["Signature"] = s.calculateSignature(params, "POST", cfg.AccessKeySecret)
// 计算签名
signature := s.calculateSignature(params, "POST", cfg.AccessKeySecret)
params["Signature"] = signature
// 构建请求URL
endpoint := cfg.Endpoint endpoint := cfg.Endpoint
if endpoint == "" { if endpoint == "" {
endpoint = "https://dysmsapi.aliyuncs.com" endpoint = "https://dysmsapi.aliyuncs.com"
} }
// 发送HTTP请求
formData := url.Values{} formData := url.Values{}
for k, v := range params { for k, v := range params {
formData.Set(k, v) formData.Set(k, v)
} }
httpReq, err := http.NewRequest("POST", endpoint, strings.NewReader(formData.Encode())) httpReq, err := http.NewRequest(http.MethodPost, endpoint, strings.NewReader(formData.Encode()))
if err != nil { if err != nil {
return nil, fmt.Errorf("failed to create request: %w", err) return nil, fmt.Errorf("failed to create request: %w", err)
} }
httpReq.Header.Set("Content-Type", "application/x-www-form-urlencoded") httpReq.Header.Set("Content-Type", "application/x-www-form-urlencoded")
httpReq.Header.Set("Accept", "application/json") httpReq.Header.Set("Accept", "application/json")
client := &http.Client{ client := &http.Client{Timeout: time.Duration(cfg.Timeout) * time.Second}
Timeout: time.Duration(cfg.Timeout) * time.Second,
}
resp, err := client.Do(httpReq) resp, err := client.Do(httpReq)
if err != nil { if err != nil {
return nil, fmt.Errorf("failed to send request: %w", err) return nil, fmt.Errorf("failed to send request: %w", err)
} }
defer resp.Body.Close() defer resp.Body.Close()
// 读取响应
body, err := io.ReadAll(resp.Body) body, err := io.ReadAll(resp.Body)
if err != nil { if err != nil {
return nil, fmt.Errorf("failed to read response: %w", err) return nil, fmt.Errorf("failed to read response: %w", err)
} }
// 解析响应
var sendResp SendResponse var sendResp SendResponse
if err := json.Unmarshal(body, &sendResp); err != nil { if err := json.Unmarshal(body, &sendResp); err != nil {
return nil, fmt.Errorf("failed to parse response: %w", err) return nil, fmt.Errorf("failed to parse response: %w", err)
} }
// 检查响应码
if sendResp.Code != "OK" { if sendResp.Code != "OK" {
return &sendResp, fmt.Errorf("SMS send failed: Code=%s, Message=%s", sendResp.Code, sendResp.Message) return &sendResp, fmt.Errorf("SMS send failed: Code=%s, Message=%s", sendResp.Code, sendResp.Message)
} }
return &sendResp, nil return &sendResp, nil
} }
// calculateSignature 计算签名 // 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 { func (s *SMS) calculateSignature(params map[string]string, method, accessKeySecret string) string {
// 对参数进行排序
keys := make([]string, 0, len(params)) keys := make([]string, 0, len(params))
for k := range params { for k := range params {
keys = append(keys, k) keys = append(keys, k)
} }
sort.Strings(keys) sort.Strings(keys)
// 构建查询字符串
var queryParts []string var queryParts []string
for _, k := range keys { for _, k := range keys {
v := params[k] queryParts = append(queryParts, url.QueryEscape(k)+"="+url.QueryEscape(params[k]))
// URL编码
encodedKey := url.QueryEscape(k)
encodedValue := url.QueryEscape(v)
queryParts = append(queryParts, encodedKey+"="+encodedValue)
} }
queryString := strings.Join(queryParts, "&") queryString := strings.Join(queryParts, "&")
// 构建待签名字符串
stringToSign := method + "&" + url.QueryEscape("/") + "&" + url.QueryEscape(queryString) stringToSign := method + "&" + url.QueryEscape("/") + "&" + url.QueryEscape(queryString)
// 计算HMAC-SHA1签名
mac := hmac.New(sha1.New, []byte(accessKeySecret+"&")) mac := hmac.New(sha1.New, []byte(accessKeySecret+"&"))
mac.Write([]byte(stringToSign)) mac.Write([]byte(stringToSign))
signature := base64.StdEncoding.EncodeToString(mac.Sum(nil)) return base64.StdEncoding.EncodeToString(mac.Sum(nil))
return signature
} }

35
storage/handler.go
View File

@@ -39,37 +39,32 @@ func NewUploadHandler(cfg UploadHandlerConfig) *UploadHandler {
} }
// ServeHTTP 处理文件上传请求 // ServeHTTP 处理文件上传请求
// 请求方式: POST
// 表单字段: file (文件)
// 可选字段: prefix (对象键前缀，会覆盖配置中的前缀)
func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
handler := commonhttp.NewHandler(w, r)
if r.Method != http.MethodPost { if r.Method != http.MethodPost {
commonhttp.Error(w, 4001, "Method not allowed") handler.Error("common.method_not_allowed")
return return
} }
// 解析multipart表单
err := r.ParseMultipartForm(h.maxFileSize) err := r.ParseMultipartForm(h.maxFileSize)
if err != nil { if err != nil {
commonhttp.Error(w, 4002, fmt.Sprintf("Failed to parse form: %v", err)) handler.Error("common.invalid_request")
return return
} }
// 获取文件
file, header, err := r.FormFile("file") file, header, err := r.FormFile("file")
if err != nil { if err != nil {
commonhttp.Error(w, 4003, fmt.Sprintf("Failed to get file: %v", err)) handler.Error("common.invalid_request")
return return
} }
defer file.Close() defer file.Close()
// 检查文件大小
if h.maxFileSize > 0 && header.Size > h.maxFileSize { if h.maxFileSize > 0 && header.Size > h.maxFileSize {
commonhttp.Error(w, 1001, fmt.Sprintf("File size exceeds limit: %d bytes", h.maxFileSize)) handler.Error("storage.file_too_large")
return return
} }
// 检查文件扩展名
if len(h.allowedExts) > 0 { if len(h.allowedExts) > 0 {
ext := strings.ToLower(filepath.Ext(header.Filename)) ext := strings.ToLower(filepath.Ext(header.Filename))
allowed := false allowed := false
@@ -80,22 +75,19 @@ func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
} }
} }
if !allowed { if !allowed {
commonhttp.Error(w, 1002, fmt.Sprintf("File extension not allowed. Allowed: %v", h.allowedExts)) handler.Error("storage.invalid_extension")
return return
} }
} }
// 生成对象键
prefix := h.objectPrefix prefix := h.objectPrefix
if r.FormValue("prefix") != "" { if r.FormValue("prefix") != "" {
prefix = r.FormValue("prefix") prefix = r.FormValue("prefix")
} }
// 生成唯一文件名
filename := generateUniqueFilename(header.Filename) filename := generateUniqueFilename(header.Filename)
objectKey := GenerateObjectKey(prefix, filename) objectKey := GenerateObjectKey(prefix, filename)
// 获取文件类型
contentType := header.Header.Get("Content-Type") contentType := header.Header.Get("Content-Type")
if contentType == "" { if contentType == "" {
contentType = mime.TypeByExtension(filepath.Ext(header.Filename)) contentType = mime.TypeByExtension(filepath.Ext(header.Filename))
@@ -104,22 +96,18 @@ func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
} }
} }
// 上传文件
ctx := r.Context() ctx := r.Context()
err = h.storage.Upload(ctx, objectKey, file, contentType) if err = h.storage.Upload(ctx, objectKey, file, contentType); err != nil {
if err != nil { handler.Error("system.internal_error")
commonhttp.SystemError(w, fmt.Sprintf("Failed to upload file: %v", err))
return return
} }
// 获取文件URL
fileURL, err := h.storage.GetURL(objectKey, 0) fileURL, err := h.storage.GetURL(objectKey, 0)
if err != nil { if err != nil {
commonhttp.SystemError(w, fmt.Sprintf("Failed to get file URL: %v", err)) handler.Error("system.internal_error")
return return
} }
// 返回结果
result := UploadResult{ result := UploadResult{
ObjectKey: objectKey, ObjectKey: objectKey,
URL: fileURL, URL: fileURL,
@@ -127,8 +115,7 @@ func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
ContentType: contentType, ContentType: contentType,
UploadTime: time.Now(), UploadTime: time.Now(),
} }
handler.Success(result)
commonhttp.Success(w, result, "Upload successful")
} }
// generateUniqueFilename 生成唯一文件名 // generateUniqueFilename 生成唯一文件名

2
templates/README.md
View File

@@ -37,4 +37,4 @@ cp templates/Makefile.example Makefile
## 完整文档 ## 完整文档
详细使用说明请查看：[MIGRATION.md](../MIGRATION.md) 详细使用说明请查看：[INTEGRATION.md](../INTEGRATION.md) 第 7 节「数据库迁移」