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

Compare commits

base: jimmy:v0.1.0
Branches Tags
jimmy:main
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:v0.5.3
Branches Tags
jimmy:main
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

7 Commits
v0.1.0 ... v0.5.3

Author SHA1 Message Date
Jimmy Xue
339920a940 调整项目结构,factory只负责暴露方法，不实现业务细节 2025-12-07 00:04:01 +08:00
Jimmy Xue
b66f345281 修复迁移时,数据库未指定的情况下数据库脚本混乱的问题 2025-12-06 22:03:57 +08:00
Jimmy Xue
6547e7bca8 调整迁移的逻辑 2025-12-06 21:38:53 +08:00
Jimmy Xue
6146178111 调整工厂模式的方法 2025-12-05 00:07:15 +08:00
Jimmy Xue
0650feb0d2 调整工具类的方法，优化方法调用及增加迁移工具及其用法 2025-12-04 22:30:48 +08:00
Jimmy Xue
de8fc13f18 日志方法增加异步与同步的方法 2025-11-30 21:01:47 +08:00
Jimmy Xue
fd37c5c301 恢复数据库对象与redis对象的返回 2025-11-30 16:03:50 +08:00
53 changed files with 6964 additions and 1952 deletions
Expand all files Collapse all files

580
MIGRATION.md Normal file
View File

@@ -0,0 +1,580 @@
# 数据库迁移工具 - 完整指南
## 📌 核心特点
- ✅ **独立工具，零耦合** - 与应用代码完全分离
- ✅ **生产就绪** - 编译成二进制，无需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 Normal file
View File

@@ -0,0 +1,346 @@
# 快速开始指南
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

@@ -2,11 +2,44 @@
这是一个Go语言开发的通用工具类库，为其他Go项目提供常用的工具方法集合。
**📖 快速链接**：
- [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)
提供日期时间转换功能，支持时区设定和多种格式转换。
@@ -14,7 +47,13 @@
提供HTTP请求/响应处理工具，包含标准化的响应结构、分页支持和HTTP状态码与业务状态码的分离。
### 4. 中间件工具 (middleware)
提供常用的HTTP中间件，包括CORS处理和时区管理。
提供生产级HTTP中间件，包括：
- **CORS** - 跨域资源共享
- **Timezone** - 时区处理
- **Logging** - 请求日志记录（支持异步）
- **Recovery** - Panic恢复，防止服务崩溃
- **RateLimit** - 请求限流（令牌桶算法）
- **Chain** - 中间件链式组合
### 5. 配置工具 (config)
提供从外部文件加载配置的功能，支持数据库、OSS、Redis、CORS、MinIO等配置。
@@ -34,6 +73,50 @@
### 10. 日志工具 (logger)
提供统一的日志记录功能，支持多种日志级别和输出方式，使用Go标准库实现。
---
## 🎯 Factory 黑盒模式（核心设计）
**理念**：外部项目只需传递一个配置文件路径，直接使用黑盒方法，无需获取内部对象。
### 方法分类
| 类型 | 方法 | 使用方式 | 推荐度 |
|------|------|----------|--------|
| **黑盒方法（推荐）** | | | |
| 中间件 | `GetMiddlewareChain()` | 直接使用，可Append自定义中间件 | ⭐⭐⭐ |
| 日志 | `LogInfo()`, `LogError()` 等 | 直接调用，无需获取logger对象 | ⭐⭐⭐ |
| Redis | `RedisSet()`, `RedisGet()` 等 | 直接调用，覆盖常用操作 | ⭐⭐⭐ |
| 邮件 | `SendEmail()` | 直接调用 | ⭐⭐⭐ |
| 短信 | `SendSMS()` | 直接调用 | ⭐⭐⭐ |
| 存储 | `UploadFile()`, `GetFileURL()` | 直接调用 | ⭐⭐⭐ |
| **Get方法（高级功能）** | | | |
| 数据库 | `GetDatabase()` | 返回GORM对象，用于复杂查询 | ⭐⭐ |
| Redis高级 | `GetRedisClient()` | 返回Redis客户端，用于Hash/List/Set等 | ⭐ |
| Logger高级 | `GetLogger()` | 返回Logger对象，用于Close等 | ⭐ |
### 使用示例
```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")
```
---
## 安装
### 1. 配置私有仓库（重要）
@@ -64,187 +147,175 @@ go get git.toowon.com/jimmy/go-common@v1.0.0
**版本管理说明请参考 [VERSION.md](./VERSION.md)**
## 使用示例
---
详细的使用说明请参考各模块的文档：
- [数据库迁移工具文档](./docs/migration.md)
- [日期转换工具文档](./docs/datetime.md)
- [HTTP Restful工具文档](./docs/http.md)
- [中间件工具文档](./docs/middleware.md)
- [配置工具文档](./docs/config.md)
- [存储工具文档](./docs/storage.md)
- [邮件工具文档](./docs/email.md)
- [短信工具文档](./docs/sms.md)
- [工厂工具文档](./docs/factory.md)
- [日志工具文档](./docs/logger.md)
## 📚 文档导航
### 快速示例
- **[快速开始指南](./QUICKSTART.md)** ⭐ - 5分钟快速上手
- [完整文档](./docs/README.md) - 所有模块详细文档
- [故障排除](./TROUBLESHOOTING.md) - 常见问题解决
- [版本管理](./VERSION.md) - 版本发布说明
#### 数据库迁移
```go
import "git.toowon.com/jimmy/go-common/migration"
---
migrator := migration.NewMigrator(db)
migrator.AddMigration(migration.Migration{
Version: "20240101000001",
Description: "create_users_table",
Up: func(db *gorm.DB) error {
return db.Exec("CREATE TABLE users ...").Error
## 快速开始
### 1. 创建配置文件 `config.json`
```json
{
"database": {
"type": "mysql",
"host": "localhost",
"port": 3306,
"user": "root",
"password": "password",
"database": "mydb"
},
})
migrator.Up()
"redis": {
"host": "localhost",
"port": 6379
},
"logger": {
"level": "info",
"output": "both",
"filePath": "./logs/app.log",
"async": true
}
}
```
#### 日期转换
```go
import "git.toowon.com/jimmy/go-common/datetime"
### 2. 使用工厂黑盒模式（最简单，推荐）⭐
datetime.SetDefaultTimeZone(datetime.AsiaShanghai)
now := datetime.Now()
str := datetime.FormatDateTime(now)
```
#### HTTP响应（Handler黑盒模式）
```go
package main
import (
"context"
"net/http"
"time"
"git.toowon.com/jimmy/go-common/factory"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
// 使用Handler（黑盒模式）
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")
// 数据库（高级功能）
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) // 无需传递r
h.Success(data) // 无需传递w
id := h.GetQueryInt64("id", 0)
h.Success(data)
}
http.HandleFunc("/user", commonhttp.HandleFunc(GetUser))
```
#### 中间件
```go
import (
"git.toowon.com/jimmy/go-common/middleware"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
### 日期时间
**推荐方式：通过 factory 使用（黑盒模式）**
// CORS + 时区中间件
chain := middleware.NewChain(
middleware.CORS(),
middleware.Timezone,
)
handler := chain.ThenFunc(yourHandler)
// 在Handler中获取时区
func handler(h *commonhttp.Handler) {
timezone := h.GetTimezone()
}
```
#### 配置管理
```go
import "git.toowon.com/jimmy/go-common/config"
// 从文件加载配置
cfg, err := config.LoadFromFile("./config.json")
// 获取各种配置
dsn, _ := cfg.GetDatabaseDSN()
redisAddr := cfg.GetRedisAddr()
corsConfig := cfg.GetCORS()
```
#### 文件上传和查看（推荐使用工厂黑盒模式）
```go
import (
"context"
"git.toowon.com/jimmy/go-common/factory"
)
fac, _ := factory.NewFactoryFromFile("./config.json")
ctx := context.Background()
// 黑盒模式（推荐，自动选择OSS或MinIO）
file, _ := os.Open("test.jpg")
url, _ := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")
// 获取文件URL
url, _ := fac.GetFileURL("images/test.jpg", 0) // 永久有效
url, _ := fac.GetFileURL("images/test.jpg", 3600) // 1小时后过期
// 或使用存储处理器（需要HTTP处理器时）
storage, _ := storage.NewStorage(storage.StorageTypeOSS, cfg)
uploadHandler := storage.NewUploadHandler(...)
```
#### 邮件发送（推荐使用工厂黑盒模式）
```go
import "git.toowon.com/jimmy/go-common/factory"
fac, _ := factory.NewFactoryFromFile("./config.json")
// 黑盒模式（推荐）
fac.SendEmail([]string{"user@example.com"}, "主题", "正文")
fac.SendEmail([]string{"user@example.com"}, "主题", "纯文本", "<h1>HTML内容</h1>")
// 或获取客户端对象（需要高级功能时）
emailClient, _ := fac.GetEmailClient()
emailClient.SendSimple(...)
fac, _ := factory.NewFactoryFromFile("config.json")
now := fac.Now("Asia/Shanghai")
str := fac.FormatDateTime(now)
```
#### 短信发送（推荐使用工厂黑盒模式）
**或者直接使用 tools 包：**
```go
import "git.toowon.com/jimmy/go-common/factory"
import "git.toowon.com/jimmy/go-common/tools"
fac, _ := factory.NewFactoryFromFile("./config.json")
// 黑盒模式（推荐）
fac.SendSMS([]string{"13800138000"}, map[string]string{"code": "123456"})
// 或获取客户端对象（需要高级功能时）
smsClient, _ := fac.GetSMSClient()
smsClient.SendSimple(...)
tools.SetDefaultTimeZone(tools.AsiaShanghai)
now := tools.Now()
str := tools.FormatDateTime(now)
```
#### 使用工厂（黑盒模式，推荐）
```go
import (
"context"
"git.toowon.com/jimmy/go-common/factory"
)
// 从配置文件创建工厂（最推荐）
fac, _ := factory.NewFactoryFromFile("./config.json")
ctx := context.Background()
// 日志（黑盒模式，直接调用）
fac.LogInfo("用户登录成功")
fac.LogError("登录失败: %v", err)
// 邮件发送（黑盒模式，直接调用）
fac.SendEmail([]string{"user@example.com"}, "验证码", "您的验证码是：123456")
// 短信发送（黑盒模式，直接调用）
fac.SendSMS([]string{"13800138000"}, map[string]string{"code": "123456"})
// 文件上传（黑盒模式，自动选择OSS或MinIO）
file, _ := os.Open("test.jpg")
url, _ := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")
// 获取文件URL
url, _ := fac.GetFileURL("images/test.jpg", 0) // 永久有效
url, _ := fac.GetFileURL("images/test.jpg", 3600) // 1小时后过期
// Redis操作（黑盒模式，直接调用）
fac.RedisSet(ctx, "key", "value", time.Hour)
value, _ := fac.RedisGet(ctx, "key")
fac.RedisDelete(ctx, "key")
// 数据库（GORM已经很灵活，直接返回对象）
db, _ := fac.GetDatabase()
db.Find(&users)
```
更多示例请查看 [examples](./examples/) 目录。
更多示例：[examples目录](./examples/)
## 版本管理
@@ -272,3 +343,62 @@ 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
## 联系方式
- 作者：Jimmy
- 邮箱：jimmy@toowon.com
- 项目地址：git.toowon.com/jimmy/go-common
---
⭐ 如果这个项目对你有帮助，请给个 Star！

78
config/config.go
View File

@@ -5,20 +5,19 @@ import (
"fmt"
"os"
"path/filepath"
"git.toowon.com/jimmy/go-common/middleware"
)
// Config 应用配置
type Config struct {
Database *DatabaseConfig `json:"database"`
OSS *OSSConfig `json:"oss"`
Redis *RedisConfig `json:"redis"`
CORS *CORSConfig `json:"cors"`
MinIO *MinIOConfig `json:"minio"`
Email *EmailConfig `json:"email"`
SMS *SMSConfig `json:"sms"`
Logger *LoggerConfig `json:"logger"`
Database *DatabaseConfig `json:"database"`
OSS *OSSConfig `json:"oss"`
Redis *RedisConfig `json:"redis"`
CORS *CORSConfig `json:"cors"`
MinIO *MinIOConfig `json:"minio"`
Email *EmailConfig `json:"email"`
SMS *SMSConfig `json:"sms"`
Logger *LoggerConfig `json:"logger"`
RateLimit *RateLimitConfig `json:"rateLimit"`
}
// DatabaseConfig 数据库配置
@@ -235,6 +234,33 @@ type LoggerConfig struct {
// DisableTimestamp 禁用时间戳
DisableTimestamp bool `json:"disableTimestamp"`
// Async 是否使用异步模式（默认false，即同步模式）
// 异步模式：日志写入通过channel异步处理，不阻塞调用方
// 同步模式：日志直接写入，会阻塞调用方直到写入完成
Async bool `json:"async"`
// BufferSize 异步模式下的缓冲区大小（默认1000）
// 当缓冲区满时，新的日志会阻塞直到有空间
BufferSize int `json:"bufferSize"`
}
// RateLimitConfig 限流配置
type RateLimitConfig struct {
// Enable 是否启用限流
Enable bool `json:"enable"`
// Rate 每个时间窗口允许的请求数量
Rate int `json:"rate"`
// Period 时间窗口（秒）
Period int `json:"period"`
// ByIP 按IP限流
ByIP bool `json:"byIP"`
// ByUserID 按用户ID限流（从X-User-ID header获取）
ByUserID bool `json:"byUserID"`
}
// LoadFromFile 从文件加载配置
@@ -371,6 +397,19 @@ func (c *Config) setDefaults() {
c.Logger.Output = "stdout"
}
}
// 限流默认值
if c.RateLimit != nil {
if c.RateLimit.Rate == 0 {
c.RateLimit.Rate = 100 // 默认每个窗口100个请求
}
if c.RateLimit.Period == 0 {
c.RateLimit.Period = 60 // 默认时间窗口60秒
}
if !c.RateLimit.ByIP && !c.RateLimit.ByUserID {
c.RateLimit.ByIP = true // 默认按IP限流
}
}
}
// GetDatabase 获取数据库配置
@@ -388,20 +427,11 @@ func (c *Config) GetRedis() *RedisConfig {
return c.Redis
}
// GetCORS 获取CORS配置，并转换为middleware.CORSConfig
func (c *Config) GetCORS() *middleware.CORSConfig {
if c.CORS == nil {
return middleware.DefaultCORSConfig()
}
return &middleware.CORSConfig{
AllowedOrigins: c.CORS.AllowedOrigins,
AllowedMethods: c.CORS.AllowedMethods,
AllowedHeaders: c.CORS.AllowedHeaders,
ExposedHeaders: c.CORS.ExposedHeaders,
AllowCredentials: c.CORS.AllowCredentials,
MaxAge: c.CORS.MaxAge,
}
// GetCORS 获取CORS配置
// 返回的是 config.CORSConfig，需要转换为 middleware.CORSConfig 时
// 可以使用 middleware.CORSFromConfig() 函数
func (c *Config) GetCORS() *CORSConfig {
return c.CORS
}
// GetMinIO 获取MinIO配置

11
config/example.json
View File

@@ -75,7 +75,16 @@
"output": "stdout",
"filePath": "",
"prefix": "app",
"disableTimestamp": false
"disableTimestamp": false,
"async": false,
"bufferSize": 1000
},
"rateLimit": {
"enable": true,
"rate": 100,
"period": 60,
"byIP": true,
"byUserID": false
}
}

78
docs/README.md
View File

@@ -3,9 +3,10 @@
## 目录
- [数据库迁移工具](./migration.md) - 数据库版本管理和迁移
- [完整使用指南](../MIGRATION.md) ⭐ - 独立工具，零耦合，Docker友好
- [日期转换工具](./datetime.md) - 日期时间处理和时区转换
- [HTTP Restful工具](./http.md) - HTTP请求响应处理和分页
- [中间件工具](./middleware.md) - CORS和时区处理中间件
- [中间件工具](./middleware.md) - 生产级HTTP中间件（CORS、时区、日志、Recovery、限流）
- [配置工具](./config.md) - 外部配置文件加载和管理
- [存储工具](./storage.md) - 文件上传和查看（OSS、MinIO）
- [邮件工具](./email.md) - SMTP邮件发送
@@ -23,30 +24,57 @@ go get git.toowon.com/jimmy/go-common
### 使用示例
#### 数据库迁移
#### 数据库迁移（独立工具，零耦合）
```go
import "git.toowon.com/jimmy/go-common/migration"
```bash
# 1. 复制模板：templates/migrate/main.go -> cmd/migrate/main.go
# 2. 创建迁移文件：migrations/20240101000001_create_users.sql
migrator := migration.NewMigrator(db)
migrator.AddMigration(migration.Migration{
Version: "20240101000001",
Description: "create_users_table",
Up: func(db *gorm.DB) error {
return db.Exec("CREATE TABLE users ...").Error
},
})
migrator.Up()
# 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)
#### 日期转换
```go
import "git.toowon.com/jimmy/go-common/datetime"
**推荐方式：通过 factory 使用（黑盒模式）**
datetime.SetDefaultTimeZone(datetime.AsiaShanghai)
now := datetime.Now()
str := datetime.FormatDateTime(now)
```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响应（Handler黑盒模式）
@@ -65,24 +93,26 @@ func GetUser(h *commonhttp.Handler) {
http.HandleFunc("/user", commonhttp.HandleFunc(GetUser))
```
#### 中间件
#### 中间件（生产级配置）
```go
import (
"net/http"
"time"
"git.toowon.com/jimmy/go-common/middleware"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
// CORS + 时区中间件
// 完整的中间件链
chain := middleware.NewChain(
middleware.CORS(),
middleware.Timezone,
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)
// 在Handler中获取时区
timezone := h.GetTimezone()
h.Success(data)
})

36
docs/config.md
View File

@@ -163,13 +163,26 @@ addr := config.GetRedisAddr()
### 5. 获取CORS配置
```go
// 获取CORS配置（返回middleware.CORSConfig类型，可直接用于中间件）
corsConfig := config.GetCORS()
// 获取CORS配置（返回config.CORSConfig类型）
configCORS := config.GetCORS()
// 使用CORS中间件
// 转换为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(corsConfig),
middleware.CORS(middlewareCORS),
)
```
@@ -328,9 +341,20 @@ func main() {
fmt.Printf("Redis Address: %s\n", redisAddr)
// 使用CORS配置
corsConfig := cfg.GetCORS()
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(corsConfig),
middleware.CORS(middlewareCORS),
)
// 使用OSS配置

439
docs/datetime.md
View File

@@ -4,6 +4,8 @@
日期转换工具提供了丰富的日期时间处理功能，支持时区设定、格式转换、时间计算等常用操作。
**重要说明**：日期时间功能位于 `tools` 包中，推荐通过 `factory` 包使用（黑盒模式），也可以直接使用 `tools` 包。
## 功能特性
- 支持时区设定和转换
@@ -16,13 +18,34 @@
## 使用方法
### 1. 设置默认时区
### 方式1：通过 factory 使用（推荐，黑盒模式）
```go
import "git.toowon.com/jimmy/go-common/datetime"
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 := datetime.SetDefaultTimeZone(datetime.AsiaShanghai)
err := tools.SetDefaultTimeZone(tools.AsiaShanghai)
if err != nil {
log.Fatal(err)
}
@@ -30,166 +53,284 @@ if err != nil {
### 2. 获取当前时间
**通过 factory：**
```go
// 使用默认时区
now := datetime.Now()
now := fac.Now()
// 使用指定时区
now := datetime.Now(datetime.AsiaShanghai)
now := datetime.Now("America/New_York")
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 := datetime.Parse("2006-01-02 15:04:05", "2024-01-01 12:00:00")
if err != nil {
log.Fatal(err)
}
t, err := fac.ParseDateTime("2024-01-01 12:00:00")
// 使用指定时区解析
t, err := datetime.Parse("2006-01-02 15:04:05", "2024-01-01 12:00:00", datetime.AsiaShanghai)
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 := datetime.ParseDateTime("2024-01-01 12:00:00")
t, err := datetime.ParseDate("2024-01-01")
t, err := tools.ParseDateTime("2024-01-01 12:00:00")
t, err := tools.ParseDate("2024-01-01")
```
### 4. 格式化时间
**通过 factory：**
```go
t := time.Now()
// 使用默认时区格式化
str := datetime.Format(t, "2006-01-02 15:04:05")
str := fac.FormatDateTime(t)
str := fac.FormatDate(t)
str := fac.FormatTime(t)
// 使用指定时区格式化
str := datetime.Format(t, "2006-01-02 15:04:05", datetime.AsiaShanghai)
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 := datetime.FormatDateTime(t) // "2006-01-02 15:04:05"
str := datetime.FormatDate(t) // "2006-01-02"
str := datetime.FormatTime(t) // "15:04:05"
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")
```
// 转换到指定时区
t2, err := datetime.ToTimezone(t, datetime.AsiaShanghai)
if err != nil {
log.Fatal(err)
}
**直接使用 tools：**
```go
t := time.Now()
t2, err := tools.ToTimezone(t, tools.AsiaShanghai)
```
### 6. Unix时间戳转换
**通过 factory：**
```go
t := time.Now()
// 转换为Unix时间戳（秒）
unix := datetime.ToUnix(t)
unix := fac.ToUnix(t)
// 从Unix时间戳创建时间
t2 := datetime.FromUnix(unix)
t2 := fac.FromUnix(unix)
// 转换为Unix毫秒时间戳
unixMilli := datetime.ToUnixMilli(t)
unixMilli := fac.ToUnixMilli(t)
// 从Unix毫秒时间戳创建时间
t3 := datetime.FromUnixMilli(unixMilli)
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 := datetime.AddDays(t, 7)
t1 := fac.AddDays(t, 7)
// 添加月数
t2 := datetime.AddMonths(t, 1)
t2 := fac.AddMonths(t, 1)
// 添加年数
t3 := datetime.AddYears(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 := datetime.StartOfDay(t)
start := fac.StartOfDay(t)
// 获取一天的结束时间（23:59:59.999999999）
end := datetime.EndOfDay(t)
end := fac.EndOfDay(t)
// 获取月份的开始时间
monthStart := datetime.StartOfMonth(t)
monthStart := fac.StartOfMonth(t)
// 获取月份的结束时间
monthEnd := datetime.EndOfMonth(t)
monthEnd := fac.EndOfMonth(t)
// 获取年份的开始时间
yearStart := datetime.StartOfYear(t)
yearStart := fac.StartOfYear(t)
// 获取年份的结束时间
yearEnd := datetime.EndOfYear(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 := datetime.DiffDays(t1, t2)
days := fac.DiffDays(t1, t2)
// 计算小时差
hours := datetime.DiffHours(t1, t2)
hours := fac.DiffHours(t1, t2)
// 计算分钟差
minutes := datetime.DiffMinutes(t1, t2)
minutes := fac.DiffMinutes(t1, t2)
// 计算秒数差
seconds := datetime.DiffSeconds(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 := datetime.ToUTC(t)
utcTime := tools.ToUTC(t)
// 从指定时区转换为UTC
t, _ := datetime.ParseDateTime("2024-01-01 12:00:00", datetime.AsiaShanghai)
utcTime, err := datetime.ToUTCFromTimezone(t, datetime.AsiaShanghai)
t, _ := tools.ParseDateTime("2024-01-01 12:00:00", tools.AsiaShanghai)
utcTime, err := tools.ToUTCFromTimezone(t, tools.AsiaShanghai)
// 解析时间字符串并直接转换为UTC
utcTime, err := datetime.ParseDateTimeToUTC("2024-01-01 12:00:00", datetime.AsiaShanghai)
utcTime, err := tools.ParseDateTimeToUTC("2024-01-01 12:00:00", tools.AsiaShanghai)
// 解析日期并转换为UTC（当天的00:00:00 UTC）
utcTime, err := datetime.ParseDateToUTC("2024-01-01", datetime.AsiaShanghai)
utcTime, err := tools.ParseDateToUTC("2024-01-01", tools.AsiaShanghai)
```
## API 参考
### 时区常量
**通过 tools 包使用：**
```go
import "git.toowon.com/jimmy/go-common/tools"
const (
UTC = "UTC"
AsiaShanghai = "Asia/Shanghai"
AmericaNewYork = "America/New_York"
EuropeLondon = "Europe/London"
AsiaTokyo = "Asia/Tokyo"
tools.UTC = "UTC"
tools.AsiaShanghai = "Asia/Shanghai"
tools.AmericaNewYork = "America/New_York"
tools.EuropeLondon = "Europe/London"
tools.AsiaTokyo = "Asia/Tokyo"
)
```
@@ -208,15 +349,22 @@ 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
获取当前时间。
@@ -226,105 +374,54 @@ CommonLayouts.RFC3339Nano = time.RFC3339Nano
**返回：** 时间对象
#### Parse(layout, value string, timezone ...string) (time.Time, error)
**使用方式：**
```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）。
**参数：**
- `layout`: 时间格式，如 "2006-01-02 15:04:05"
- `value`: 时间字符串
- `timezone`: 可选，时区字符串
**返回：** 时间对象和错误信息
#### Format(t time.Time, layout string, timezone ...string) string
**使用方式：**
```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`: 时间对象
- `layout`: 时间格式
- `timezone`: 可选，时区字符串
**返回：** 格式化后的时间字符串
#### ToTimezone(t time.Time, timezone string) (time.Time, error)
**使用方式：**
```go
// 通过 factory
str := fac.FormatDateTime(t, "Asia/Shanghai")
转换时区。
// 直接使用 tools
str := tools.FormatDateTime(t, tools.AsiaShanghai)
```
**参数：**
- `t`: 时间对象
- `timezone`: 目标时区
**返回：** 转换后的时间对象和错误信息
#### ToUnix(t time.Time) int64
转换为Unix时间戳（秒）。
#### FromUnix(sec int64, timezone ...string) time.Time
从Unix时间戳创建时间。
#### ToUnixMilli(t time.Time) int64
转换为Unix毫秒时间戳。
#### FromUnixMilli(msec int64, timezone ...string) time.Time
从Unix毫秒时间戳创建时间。
#### AddDays(t time.Time, days int) time.Time
添加天数。
#### AddMonths(t time.Time, months int) time.Time
添加月数。
#### AddYears(t time.Time, years int) time.Time
添加年数。
#### StartOfDay(t time.Time, timezone ...string) time.Time
获取一天的开始时间。
#### EndOfDay(t time.Time, timezone ...string) time.Time
获取一天的结束时间。
#### StartOfMonth(t time.Time, timezone ...string) time.Time
获取月份的开始时间。
#### EndOfMonth(t time.Time, timezone ...string) time.Time
获取月份的结束时间。
#### StartOfYear(t time.Time, timezone ...string) time.Time
获取年份的开始时间。
#### EndOfYear(t time.Time, timezone ...string) time.Time
获取年份的结束时间。
#### DiffDays(t1, t2 time.Time) int
计算两个时间之间的天数差。
#### DiffHours(t1, t2 time.Time) int64
计算两个时间之间的小时差。
#### DiffMinutes(t1, t2 time.Time) int64
计算两个时间之间的分钟差。
#### DiffSeconds(t1, t2 time.Time) int64
计算两个时间之间的秒数差。
更多函数请参考 `factory` 包或 `tools` 包的 API 文档。
### UTC转换函数
@@ -391,7 +488,7 @@ CommonLayouts.RFC3339Nano = time.RFC3339Nano
## 完整示例
### 示例1：基本使用
### 示例1：通过 factory 使用（推荐）
```go
package main
@@ -399,27 +496,67 @@ package main
import (
"fmt"
"log"
"time"
"git.toowon.com/jimmy/go-common/datetime"
"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() {
// 设置默认时区
datetime.SetDefaultTimeZone(datetime.AsiaShanghai)
err := tools.SetDefaultTimeZone(tools.AsiaShanghai)
if err != nil {
log.Fatal(err)
}
// 获取当前时间
now := datetime.Now()
fmt.Printf("Current time: %s\n", datetime.FormatDateTime(now))
now := tools.Now()
fmt.Printf("Current time: %s\n", tools.FormatDateTime(now))
// 时区转换
t, _ := datetime.ParseDateTime("2024-01-01 12:00:00")
t2, _ := datetime.ToTimezone(t, datetime.AmericaNewYork)
fmt.Printf("Time in New York: %s\n", datetime.FormatDateTime(t2))
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))
}
```
### 示例2：UTC转换（数据库存储场景）
### 示例3：UTC转换（数据库存储场景）
```go
package main
@@ -428,34 +565,32 @@ import (
"fmt"
"log"
"git.toowon.com/jimmy/go-common/datetime"
"git.toowon.com/jimmy/go-common/tools"
)
func main() {
// 从请求中获取时间（假设是上海时区）
requestTimeStr := "2024-01-01 12:00:00"
requestTimezone := datetime.AsiaShanghai
requestTimezone := tools.AsiaShanghai
// 转换为UTC时间（用于数据库存储）
dbTime, err := datetime.ParseDateTimeToUTC(requestTimeStr, requestTimezone)
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", datetime.FormatDateTime(dbTime, datetime.UTC))
fmt.Printf("Database time (UTC): %s\n", tools.FormatDateTime(dbTime, tools.UTC))
// 从数据库读取UTC时间，转换为用户时区显示
userTimezone := datetime.AsiaShanghai
displayTime, err := datetime.ToTimezone(dbTime, userTimezone)
userTimezone := tools.AsiaShanghai
displayTime, err := tools.ToTimezone(dbTime, userTimezone)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Display time (Shanghai): %s\n", datetime.FormatDateTime(displayTime, userTimezone))
fmt.Printf("Display time (Shanghai): %s\n", tools.FormatDateTime(displayTime, userTimezone))
}
```
完整示例请参考：
- `examples/datetime_example.go` - 基本使用示例
- `examples/datetime_utc_example.go` - UTC转换示例
完整示例请参考 `factory` 包中的 datetime 相关方法，通过 `factory` 调用 `tools` 包中的 datetime 功能。

380
docs/factory.md
View File

@@ -12,6 +12,36 @@
- **统一接口**：所有操作通过工厂方法调用
- **向后兼容**：保留 `GetXXX()` 方法，需要时可获取对象
## 方法分类总览
### 🌟 推荐使用：黑盒方法（一行代码搞定）
外部项目直接调用，无需获取内部对象：
| 功能 | 方法 | 示例 |
|------|------|------|
| **中间件** | `GetMiddlewareChain()` | `chain := fac.GetMiddlewareChain()` |
| **日志** | `LogInfo()`, `LogError()` 等 | `fac.LogInfo("用户登录")` |
| **Redis** | `RedisSet()`, `RedisGet()` 等 | `fac.RedisSet(ctx, "key", "val", time.Hour)` |
| **邮件** | `SendEmail()` | `fac.SendEmail(to, subject, body)` |
| **短信** | `SendSMS()` | `fac.SendSMS(phones, params)` |
| **存储** | `UploadFile()`, `GetFileURL()` | `fac.UploadFile(ctx, key, file)` |
| **日期时间** | `Now()`, `ParseDateTime()`, `FormatDateTime()` 等 | `fac.Now("Asia/Shanghai")` |
| **金额计算** | `YuanToCents()`, `CentsToYuan()`, `FormatYuan()` | `fac.YuanToCents(100.5)` |
| **版本信息** | `GetVersion()` | `fac.GetVersion()` |
| **HTTP响应** | `Success()`, `Error()`, `SuccessPage()` | `fac.Success(w, data)` |
| **HTTP请求** | `ParseJSON()`, `GetQuery()`, `GetTimezone()` 等 | `fac.ParseJSON(r, &req)` |
### 🔧 高级功能：Get方法（仅在必要时使用）
返回客户端对象，用于复杂操作：
| 方法 | 返回类型 | 使用场景 |
|------|----------|----------|
| `GetDatabase()` | `*gorm.DB` | 数据库复杂查询、事务、关联查询等 |
| `GetRedisClient()` | `*redis.Client` | Hash、List、Set、ZSet、Pub/Sub等高级操作 |
| `GetLogger()` | `*logger.Logger` | Close()、设置全局logger等 |
## 使用方法
### 1. 创建工厂（推荐）
@@ -136,23 +166,128 @@ err := fac.RedisDelete(ctx, "user:123", "user:456")
exists, err := fac.RedisExists(ctx, "user:123")
```
### 7. 数据库操作
数据库保持返回 GORM 对象，因为 GORM 已经提供了很好的抽象：
### 7. 数据库操作（黑盒模式）
```go
// 获取数据库对象（延迟初始化）
// 获取数据库对象（已初始化，黑盒模式）
db, err := fac.GetDatabase()
if err != nil {
log.Fatal(err)
}
// 直接使用GORM
// 直接使用GORM，无需自己实现创建逻辑
var users []User
db.Find(&users)
db.Create(&user)
```
### 8. 日期时间操作（黑盒模式）
```go
// 获取当前时间
now := fac.Now("Asia/Shanghai")
// 解析时间
t, _ := fac.ParseDateTime("2024-01-01 12:00:00", "Asia/Shanghai")
// 格式化时间
str := fac.FormatDateTime(now)
// 时间计算
tomorrow := fac.AddDays(now, 1)
startOfDay := fac.StartOfDay(now, "Asia/Shanghai")
endOfDay := fac.EndOfDay(now, "Asia/Shanghai")
// Unix时间戳
unix := fac.ToUnix(now)
t2 := fac.FromUnix(unix, "Asia/Shanghai")
```
### 9. 金额计算（黑盒模式）
```go
// 元转分
cents := fac.YuanToCents(100.5) // 10050
// 分转元
yuan := fac.CentsToYuan(10050) // 100.5
// 格式化显示
str := fac.FormatYuan(10050) // "100.50"
```
### 10. 版本信息（黑盒模式）
```go
version := fac.GetVersion()
fmt.Println("当前版本:", version)
```
### 11. HTTP响应（黑盒模式）
```go
import "net/http"
// 成功响应
fac.Success(w, data)
fac.Success(w, data, "操作成功")
// 分页响应
fac.SuccessPage(w, users, total, page, pageSize)
// 错误响应
fac.Error(w, 1001, "用户不存在")
fac.SystemError(w, "系统错误")
```
### 12. HTTP请求解析（黑盒模式）
```go
import "net/http"
// 解析JSON
var req UserRequest
fac.ParseJSON(r, &req)
// 获取查询参数
id := fac.GetQueryInt64(r, "id", 0)
keyword := fac.GetQuery(r, "keyword", "")
// 获取时区（需要配合middleware.Timezone使用）
timezone := fac.GetTimezone(r)
```
### 13. Redis操作（获取客户端对象）
```go
import (
"context"
"github.com/redis/go-redis/v9"
)
ctx := context.Background()
// 获取Redis客户端对象（已初始化，黑盒模式）
redisClient, err := fac.GetRedisClient()
if err != nil {
log.Fatal(err)
}
// 直接使用Redis客户端，无需自己实现创建逻辑
val, err := redisClient.Get(ctx, "key").Result()
if err != nil && err != redis.Nil {
log.Printf("Redis error: %v", err)
} else if err == redis.Nil {
fmt.Println("Key not found")
} else {
fmt.Printf("Value: %s\n", val)
}
// 使用高级功能（如Hash操作）
redisClient.HSet(ctx, "user:123", "name", "John")
name, _ := redisClient.HGet(ctx, "user:123", "name").Result()
```
## 完整示例
@@ -400,7 +535,26 @@ func main() {
- 自动配置连接池参数
- 数据库时间统一使用UTC时区
- 延迟初始化，首次调用时创建连接
- 黑盒模式：只需传递config对象，无需自己实现创建逻辑
### Redis方法
#### GetRedisClient() (*redis.Client, error)
获取Redis客户端对象（已初始化）。
**返回：** 已初始化的Redis客户端对象和错误信息
**说明：**
- 自动处理所有配置检查和连接测试
- 自动设置默认值（连接池大小、超时时间等）
- 连接失败时会自动关闭客户端并返回错误
- 返回的客户端已通过Ping测试，可直接使用
- 黑盒模式：只需传递config对象，无需自己实现创建逻辑
- 推荐使用 `RedisGet`、`RedisSet`、`RedisDelete` 等方法直接操作Redis
- 如果需要使用Redis的高级功能（如Hash、List、Set等），可以使用此方法获取客户端对象
### 配置方法
#### GetConfig() *config.Config
@@ -408,6 +562,222 @@ func main() {
**返回：** 配置对象
### HTTP响应方法（黑盒模式）
#### Success(w http.ResponseWriter, data interface{}, message ...string)
发送成功响应。
**参数：**
- `w`: HTTP响应写入器
- `data`: 响应数据
- `message`: 可选，成功消息（如果不提供，使用默认消息）
**示例：**
```go
fac.Success(w, user) // 使用默认消息
fac.Success(w, user, "获取成功") // 自定义消息
```
#### Error(w http.ResponseWriter, code int, message string)
发送错误响应。
**参数：**
- `w`: HTTP响应写入器
- `code`: 业务错误码
- `message`: 错误消息
#### SystemError(w http.ResponseWriter, message string)
发送系统错误响应（HTTP 500）。
**参数：**
- `w`: HTTP响应写入器
- `message`: 错误消息
#### SuccessPage(w http.ResponseWriter, data interface{}, total int64, page, pageSize int, message ...string)
发送分页成功响应。
**参数：**
- `w`: HTTP响应写入器
- `data`: 响应数据列表
- `total`: 总记录数
- `page`: 当前页码
- `pageSize`: 每页大小
- `message`: 可选，成功消息
### HTTP请求方法（黑盒模式）
#### ParseJSON(r *http.Request, v interface{}) error
解析JSON请求体。
**参数：**
- `r`: HTTP请求
- `v`: 目标结构体指针
#### GetQuery(r *http.Request, key, defaultValue string) string
获取查询参数。
#### GetQueryInt(r *http.Request, key string, defaultValue int) int
获取查询整数参数。
#### GetQueryInt64(r *http.Request, key string, defaultValue int64) int64
获取查询64位整数参数。
#### GetFormValue(r *http.Request, key, defaultValue string) string
获取表单值。
#### GetTimezone(r *http.Request) string
从请求的context中获取时区（需要配合middleware.Timezone使用）。
### 日期时间工具方法（黑盒模式）
#### Now(timezone ...string) time.Time
获取当前时间。
**参数：**
- `timezone`: 可选，时区字符串（如 "Asia/Shanghai"），不指定则使用默认时区
#### ParseDateTime(value string, timezone ...string) (time.Time, error)
解析日期时间字符串（格式：2006-01-02 15:04:05）。
#### ParseDate(value string, timezone ...string) (time.Time, error)
解析日期字符串（格式：2006-01-02）。
#### FormatDateTime(t time.Time, timezone ...string) string
格式化日期时间（格式：2006-01-02 15:04:05）。
#### FormatDate(t time.Time, timezone ...string) string
格式化日期（格式：2006-01-02）。
#### FormatTime(t time.Time, timezone ...string) string
格式化时间（格式：15:04:05）。
#### ToUnix(t time.Time) int64
转换为Unix时间戳（秒）。
#### FromUnix(sec int64, timezone ...string) time.Time
从Unix时间戳创建时间。
#### ToUnixMilli(t time.Time) int64
转换为Unix毫秒时间戳。
#### FromUnixMilli(msec int64, timezone ...string) time.Time
从Unix毫秒时间戳创建时间。
#### AddDays(t time.Time, days int) time.Time
添加天数。
#### AddMonths(t time.Time, months int) time.Time
添加月数。
#### AddYears(t time.Time, years int) time.Time
添加年数。
#### StartOfDay(t time.Time, timezone ...string) time.Time
获取一天的开始时间（00:00:00）。
#### EndOfDay(t time.Time, timezone ...string) time.Time
获取一天的结束时间（23:59:59.999999999）。
#### StartOfMonth(t time.Time, timezone ...string) time.Time
获取月份的开始时间。
#### EndOfMonth(t time.Time, timezone ...string) time.Time
获取月份的结束时间。
#### StartOfYear(t time.Time, timezone ...string) time.Time
获取年份的开始时间。
#### EndOfYear(t time.Time, timezone ...string) time.Time
获取年份的结束时间。
#### DiffDays(t1, t2 time.Time) int
计算两个时间之间的天数差。
#### DiffHours(t1, t2 time.Time) int64
计算两个时间之间的小时差。
#### DiffMinutes(t1, t2 time.Time) int64
计算两个时间之间的分钟差。
#### DiffSeconds(t1, t2 time.Time) int64
计算两个时间之间的秒数差。
### 金额工具方法（黑盒模式）
#### GetMoneyCalculator() *tools.MoneyCalculator
获取金额计算器实例。
#### YuanToCents(yuan float64) int64
元转分。
**示例：**
```go
cents := fac.YuanToCents(100.5) // 返回 10050
```
#### CentsToYuan(cents int64) float64
分转元。
**示例：**
```go
yuan := fac.CentsToYuan(10050) // 返回 100.5
```
#### FormatYuan(cents int64) string
格式化显示金额（分转元，保留2位小数）。
**示例：**
```go
str := fac.FormatYuan(10050) // 返回 "100.50"
```
### 版本工具方法（黑盒模式）
#### GetVersion() string
获取版本号。
**说明：**
- 优先从环境变量 `DOCKER_TAG` 或 `VERSION` 中读取
- 如果没有设置环境变量，则使用默认版本号
## 设计优势
### 优势总结

660
docs/http.md
View File

@@ -2,16 +2,17 @@
## 概述
HTTP Restful工具提供了标准化的HTTP请求和响应处理功能，采用Handler黑盒模式，封装了`ResponseWriter`和`Request`，提供简洁的API，无需每次都传递这两个参数。
HTTP Restful工具提供了标准化的HTTP请求和响应处理功能，提供公共方法供外部调用，保持低耦合。
## 功能特性
- **黑盒模式**：封装`ResponseWriter`和`Request`，提供简洁的API
- **低耦合设计**：提供公共方法，不封装Handler结构
- **标准化的响应结构**：`{code, message, timestamp, data}`
- **分离HTTP状态码和业务状态码**
- **支持分页响应**
- **提供便捷的请求参数解析方法**
- **支持JSON请求体解析**
- **Factory黑盒模式**：推荐使用 `factory.Success()` 等方法
## 响应结构
@@ -26,6 +27,18 @@ HTTP Restful工具提供了标准化的HTTP请求和响应处理功能，采用H
}
```
**结构体类型（暴露在 factory 中）：**
```go
// 在 factory 包中可以直接使用
type Response struct {
Code int `json:"code"` // 业务状态码，0表示成功
Message string `json:"message"` // 响应消息
Timestamp int64 `json:"timestamp"` // 时间戳
Data interface{} `json:"data"` // 响应数据
}
```
### 分页响应结构
```json
@@ -42,9 +55,116 @@ HTTP Restful工具提供了标准化的HTTP请求和响应处理功能，采用H
}
```
**结构体类型（暴露在 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)
```
## 使用方法
### 1. 创建Handler
### 方式一：使用Factory黑盒方法（推荐）⭐
这是最简单的方式，直接使用 `factory.Success()` 等方法：
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/factory"
commonhttp "git.toowon.com/jimmy/go-common/http"
)
func GetUser(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 获取查询参数（使用公共方法）
id := commonhttp.GetQueryInt64(r, "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.GetSize()
// 获取查询参数（使用factory方法，推荐）
keyword := fac.GetQuery(r, "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 (
@@ -52,154 +172,110 @@ import (
commonhttp "git.toowon.com/jimmy/go-common/http"
)
// 方式1：使用HandleFunc包装器（推荐，最简洁）
func GetUser(h *commonhttp.Handler) {
id := h.GetQueryInt64("id", 0)
h.Success(data)
func GetUser(w http.ResponseWriter, r *http.Request) {
// 获取查询参数
id := commonhttp.GetQueryInt64(r, "id", 0)
// 返回成功响应
commonhttp.Success(w, data)
}
http.HandleFunc("/user", commonhttp.HandleFunc(GetUser))
// 方式2：手动创建Handler（需要更多控制时）
http.HandleFunc("/user", func(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
GetUser(h)
})
```
### 2. 成功响应
```go
func handler(h *commonhttp.Handler) {
// 简单成功响应（data为nil）
h.Success(nil)
// 带数据的成功响应
data := map[string]interface{}{
"id": 1,
"name": "test",
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
}
h.Success(data)
// 带消息的成功响应
h.SuccessWithMessage("操作成功", data)
// 返回成功响应
commonhttp.Success(w, data, "创建成功")
}
```
### 3. 错误响应
### 成功响应
```go
func handler(h *commonhttp.Handler) {
// 业务错误（HTTP 200，业务code非0）
h.Error(1001, "用户不存在")
// 系统错误（HTTP 500）
h.SystemError("服务器内部错误")
// 其他HTTP错误状态码，使用WriteJSON直接指定
// 请求错误（HTTP 400）
h.WriteJSON(http.StatusBadRequest, 400, "请求参数错误", nil)
// 未授权（HTTP 401）
h.WriteJSON(http.StatusUnauthorized, 401, "未登录", nil)
// 禁止访问（HTTP 403）
h.WriteJSON(http.StatusForbidden, 403, "无权限访问", nil)
// 未找到（HTTP 404）
h.WriteJSON(http.StatusNotFound, 404, "资源不存在", nil)
}
// 使用Factory（推荐）
fac.Success(w, data) // 只有数据，使用默认消息 "success"
fac.Success(w, data, "操作成功") // 数据+消息
// 或直接使用公共方法
commonhttp.Success(w, data) // 只有数据
commonhttp.Success(w, data, "操作成功") // 数据+消息
```
### 4. 分页响应
### 错误响应
```go
func handler(h *commonhttp.Handler) {
// 获取分页参数
pagination := h.ParsePaginationRequest()
page := pagination.GetPage()
pageSize := pagination.GetSize()
// 查询数据（示例）
list, total := getDataList(page, pageSize)
// 返回分页响应（使用默认消息）
h.SuccessPage(list, total, page, pageSize)
// 返回分页响应（自定义消息）
h.SuccessPage(list, total, page, pageSize, "查询成功")
}
// 使用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状态码（仅公共方法）
```
### 5. 解析请求
### 分页响应
```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
func handler(h *commonhttp.Handler) {
type CreateUserRequest struct {
Name string `json:"name"`
Email string `json:"email"`
}
var req CreateUserRequest
if err := h.ParseJSON(&req); err != nil {
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
// 使用req...
// 使用公共方法
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
func handler(h *commonhttp.Handler) {
// 获取字符串参数
name := h.GetQuery("name", "")
email := h.GetQuery("email", "default@example.com")
// 获取整数参数
id := h.GetQueryInt("id", 0)
age := h.GetQueryInt("age", 18)
// 获取int64参数
userId := h.GetQueryInt64("userId", 0)
// 获取布尔参数
isActive := h.GetQueryBool("isActive", false)
// 获取浮点数参数
price := h.GetQueryFloat64("price", 0.0)
}
// 使用公共方法
name := commonhttp.GetQuery(r, "name", "")
id := commonhttp.GetQueryInt(r, "id", 0)
userId := commonhttp.GetQueryInt64(r, "userId", 0)
isActive := commonhttp.GetQueryBool(r, "isActive", false)
price := commonhttp.GetQueryFloat64(r, "price", 0.0)
```
#### 获取表单参数
```go
func handler(h *commonhttp.Handler) {
// 获取表单字符串
name := h.GetFormValue("name", "")
// 获取表单整数
age := h.GetFormInt("age", 0)
// 获取表单int64
userId := h.GetFormInt64("userId", 0)
// 获取表单布尔值
isActive := h.GetFormBool("isActive", false)
}
// 使用公共方法
name := commonhttp.GetFormValue(r, "name", "")
age := commonhttp.GetFormInt(r, "age", 0)
userId := commonhttp.GetFormInt64(r, "userId", 0)
isActive := commonhttp.GetFormBool(r, "isActive", false)
```
#### 获取请求头
```go
func handler(h *commonhttp.Handler) {
token := h.GetHeader("Authorization", "")
contentType := h.GetHeader("Content-Type", "application/json")
}
// 使用公共方法
token := commonhttp.GetHeader(r, "Authorization", "")
contentType := commonhttp.GetHeader(r, "Content-Type", "application/json")
```
#### 获取分页参数
@@ -207,71 +283,55 @@ func handler(h *commonhttp.Handler) {
**方式1：使用 PaginationRequest 结构（推荐）**
```go
func handler(h *commonhttp.Handler) {
// 定义请求结构（包含分页字段）
type ListUserRequest struct {
Keyword string `json:"keyword"`
commonhttp.PaginationRequest // 嵌入分页请求结构
}
// 从JSON请求体解析（分页字段会自动解析）
var req ListUserRequest
if err := h.ParseJSON(&req); err != nil {
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
// 使用分页方法
page := req.GetPage() // 获取页码（默认1）
size := req.GetSize() // 获取每页数量（默认20，最大100，优先使用page_size）
offset := req.GetOffset() // 计算偏移量
// 定义请求结构（包含分页字段）
type ListUserRequest struct {
Keyword string `json:"keyword"`
commonhttp.PaginationRequest // 嵌入分页请求结构
}
// 或者从查询参数/form解析分页
func handler(h *commonhttp.Handler) {
pagination := h.ParsePaginationRequest()
page := pagination.GetPage()
size := pagination.GetSize()
offset := pagination.GetOffset()
// 从JSON请求体解析（分页字段会自动解析）
var req ListUserRequest
if err := commonhttp.ParseJSON(r, &req); err != nil {
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
// 使用分页方法
page := req.GetPage() // 获取页码（默认1）
size := req.GetSize() // 获取每页数量（默认20，最大100，优先使用page_size）
offset := req.GetOffset() // 计算偏移量
```
**方式2：从查询参数/form解析分页**
```go
// 使用公共方法
pagination := commonhttp.ParsePaginationRequest(r)
page := pagination.GetPage()
size := pagination.GetSize()
offset := pagination.GetOffset()
```
#### 获取时区
```go
func handler(h *commonhttp.Handler) {
// 从请求的context中获取时区
// 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
// 如果未设置，返回默认时区 AsiaShanghai
timezone := h.GetTimezone()
}
```
### 6. 访问原始对象
如果需要访问原始的`ResponseWriter`或`Request`：
```go
func handler(h *commonhttp.Handler) {
// 获取原始ResponseWriter
w := h.ResponseWriter()
// 获取原始Request
r := h.Request()
// 获取Context
ctx := h.Context()
}
// 使用公共方法
// 如果使用了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"
)
@@ -283,91 +343,97 @@ type User struct {
}
// 用户列表接口
func GetUserList(h *commonhttp.Handler) {
// 获取分页参数
pagination := h.ParsePaginationRequest()
func GetUserList(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 获取分页参数（使用公共方法）
pagination := commonhttp.ParsePaginationRequest(r)
page := pagination.GetPage()
pageSize := pagination.GetSize()
// 获取查询参数
keyword := h.GetQuery("keyword", "")
// 获取查询参数（使用公共方法）
keyword := commonhttp.GetQuery(r, "keyword", "")
// 查询数据
users, total := queryUsers(keyword, page, pageSize)
// 返回分页响应
h.SuccessPage(users, total, page, pageSize)
// 返回分页响应（使用factory方法）
fac.SuccessPage(w, users, total, page, pageSize)
}
// 创建用户接口
func CreateUser(h *commonhttp.Handler) {
// 解析请求体
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 := h.ParseJSON(&req); err != nil {
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
if err := commonhttp.ParseJSON(r, &req); err != nil {
fac.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
// 参数验证
if req.Name == "" {
h.Error(1001, "用户名不能为空")
fac.Error(w, 1001, "用户名不能为空")
return
}
// 创建用户
user, err := createUser(req.Name, req.Email)
if err != nil {
h.SystemError("创建用户失败")
fac.SystemError(w, "创建用户失败")
return
}
// 返回成功响应
h.SuccessWithMessage("创建成功", user)
// 返回成功响应（使用factory方法）
fac.Success(w, user, "创建成功")
}
// 获取用户详情接口
func GetUser(h *commonhttp.Handler) {
// 获取查询参数
id := h.GetQueryInt64("id", 0)
func GetUser(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 获取查询参数（使用factory方法，推荐）
id := fac.GetQueryInt64(r, "id", 0)
if id == 0 {
h.WriteJSON(http.StatusBadRequest, 400, "用户ID不能为空", nil)
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "用户ID不能为空", nil)
return
}
// 查询用户
user, err := getUserByID(id)
if err != nil {
h.SystemError("查询用户失败")
fac.SystemError(w, "查询用户失败")
return
}
if user == nil {
h.Error(1002, "用户不存在")
fac.Error(w, 1002, "用户不存在")
return
}
h.Success(user)
// 返回成功响应（使用factory方法）
fac.Success(w, user)
}
func main() {
// 使用HandleFunc包装器（推荐）
http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
switch h.Request().Method {
http.HandleFunc("/users", func(w http.ResponseWriter, r *http.Request) {
switch r.Method {
case http.MethodGet:
GetUserList(h)
GetUserList(w, r)
case http.MethodPost:
CreateUser(h)
CreateUser(w, r)
default:
h.WriteJSON(http.StatusMethodNotAllowed, 405, "方法不支持", nil)
commonhttp.WriteJSON(w, http.StatusMethodNotAllowed, 405, "方法不支持", nil)
}
}))
})
http.HandleFunc("/user", commonhttp.HandleFunc(GetUser))
http.HandleFunc("/user", GetUser)
log.Println("Server started on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
@@ -376,53 +442,93 @@ func main() {
## API 参考
### Handler结构
### Factory HTTP响应结构体（暴露给外部项目使用）
Handler封装了`ResponseWriter`和`Request`，提供更简洁的API。
#### Response
```go
type Handler struct {
w http.ResponseWriter
r *http.Request
}
```
标准响应结构体，外部项目可以直接使用 `factory.Response`。
### 创建Handler
#### NewHandler(w http.ResponseWriter, r *http.Request) *Handler
创建Handler实例。
#### HandleFunc(fn func(*Handler)) http.HandlerFunc
将Handler函数转换为标准的http.HandlerFunc（便捷包装器）。
**字段：**
- `Code`: 业务状态码，0表示成功
- `Message`: 响应消息
- `Timestamp`: 时间戳（Unix时间戳，秒）
- `Data`: 响应数据
**示例：**
```go
http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
h.Success(data)
}))
response := factory.Response{
Code: 0,
Message: "success",
Data: userData,
}
```
### Handler响应方法
#### PageData
#### (h *Handler) Success(data interface{})
分页数据结构体，外部项目可以直接使用 `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。
#### (h *Handler) SuccessWithMessage(message string, data interface{})
**参数：**
- `data`: 响应数据，可以为nil
- `message`: 响应消息（可选），如果为空则使用默认消息 "success"
带消息的成功响应。
**示例：**
```go
fac.Success(w, data) // 只有数据，使用默认消息 "success"
fac.Success(w, data, "操作成功") // 数据+消息
```
#### (h *Handler) Error(code int, message string)
#### (f *Factory) Error(w http.ResponseWriter, code int, message string)
业务错误响应，HTTP 200，业务code非0。
#### (h *Handler) SystemError(message string)
**示例：**
```go
fac.Error(w, 1001, "用户不存在")
```
#### (f *Factory) SystemError(w http.ResponseWriter, message string)
系统错误响应，HTTP 500，业务code 500。
#### (h *Handler) WriteJSON(httpCode, code int, message string, data interface{})
**示例：**
```go
fac.SystemError(w, "服务器内部错误")
```
#### (f *Factory) WriteJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{})
写入JSON响应（自定义）。
@@ -432,7 +538,17 @@ http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
- `message`: 响应消息
- `data`: 响应数据
#### (h *Handler) SuccessPage(list interface{}, total int64, page, pageSize int, message ...string)
**说明：**
- 此方法不在 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)
分页成功响应。
@@ -443,53 +559,81 @@ http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
- `pageSize`: 每页大小
- `message`: 响应消息（可选，如果为空则使用默认消息 "success"）
### Handler请求解析方法
**示例：**
```go
fac.SuccessPage(w, users, total, page, pageSize)
fac.SuccessPage(w, users, total, page, pageSize, "查询成功")
```
#### (h *Handler) ParseJSON(v interface{}) error
### 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请求体。
#### (h *Handler) GetQuery(key, defaultValue string) string
**示例：**
```go
var req CreateUserRequest
if err := commonhttp.ParseJSON(r, &req); err != nil {
// 处理错误
}
```
#### GetQuery(r *http.Request, key, defaultValue string) string
获取查询参数（字符串）。
#### (h *Handler) GetQueryInt(key string, defaultValue int) int
#### GetQueryInt(r *http.Request, key string, defaultValue int) int
获取查询参数（整数）。
#### (h *Handler) GetQueryInt64(key string, defaultValue int64) int64
#### GetQueryInt64(r *http.Request, key string, defaultValue int64) int64
获取查询参数（int64）。
#### (h *Handler) GetQueryBool(key string, defaultValue bool) bool
#### GetQueryBool(r *http.Request, key string, defaultValue bool) bool
获取查询参数（布尔值）。
#### (h *Handler) GetQueryFloat64(key string, defaultValue float64) float64
#### GetQueryFloat64(r *http.Request, key string, defaultValue float64) float64
获取查询参数（浮点数）。
#### (h *Handler) GetFormValue(key, defaultValue string) string
#### GetFormValue(r *http.Request, key, defaultValue string) string
获取表单值（字符串）。
#### (h *Handler) GetFormInt(key string, defaultValue int) int
#### GetFormInt(r *http.Request, key string, defaultValue int) int
获取表单值（整数）。
#### (h *Handler) GetFormInt64(key string, defaultValue int64) int64
#### GetFormInt64(r *http.Request, key string, defaultValue int64) int64
获取表单值（int64）。
#### (h *Handler) GetFormBool(key string, defaultValue bool) bool
#### GetFormBool(r *http.Request, key string, defaultValue bool) bool
获取表单值（布尔值）。
#### (h *Handler) GetHeader(key, defaultValue string) string
#### GetHeader(r *http.Request, key, defaultValue string) string
获取请求头。
#### (h *Handler) ParsePaginationRequest() *PaginationRequest
#### ParsePaginationRequest(r *http.Request) *PaginationRequest
从请求中解析分页参数。
@@ -498,7 +642,7 @@ http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
- 优先级：查询参数 > form表单
- 如果请求体是JSON格式且包含分页字段，建议先使用`ParseJSON`解析完整请求体到包含`PaginationRequest`的结构体中
#### (h *Handler) GetTimezone() string
#### GetTimezone(r *http.Request) string
从请求的context中获取时区。
@@ -506,19 +650,39 @@ http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
- 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
- 如果未设置，返回默认时区 AsiaShanghai
### Handler访问原始对象
#### Success(w http.ResponseWriter, data interface{}, message ...string)
#### (h *Handler) ResponseWriter() http.ResponseWriter
成功响应（公共方法）。
获取原始的ResponseWriter（需要时使用）。
**参数：**
- `data`: 响应数据，可以为nil
- `message`: 响应消息（可选），如果为空则使用默认消息 "success"
#### (h *Handler) Request() *http.Request
**示例：**
```go
commonhttp.Success(w, data) // 只有数据
commonhttp.Success(w, data, "操作成功") // 数据+消息
```
获取原始的Request（需要时使用）。
#### Error(w http.ResponseWriter, code int, message string)
#### (h *Handler) Context() context.Context
错误响应（公共方法）。
获取请求的Context。
#### 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)
分页成功响应（公共方法）。
### 分页请求结构
@@ -575,10 +739,14 @@ http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
- 使用`SystemError`返回系统错误（HTTP 500）
- 其他HTTP错误状态码（400, 401, 403, 404等）使用`WriteJSON`方法直接指定
5. **黑盒模式**：
- 所有功能都通过Handler对象调用，无需传递`w`和`r`参数
- 代码更简洁，减少调用方工作量
5. **推荐使用Factory**：
- 使用 `factory.Success()` 等方法，代码更简洁
- 直接使用 `http` 包的公共方法，保持低耦合
- 不需要Handler结构，减少不必要的封装
## 示例
完整示例请参考 `examples/http_handler_example.go`
完整示例请参考：
- `examples/http_handler_example.go` - 使用Factory和公共方法
- `examples/http_pagination_example.go` - 分页示例
- `examples/factory_blackbox_example.go` - Factory黑盒模式示例

75
docs/logger.md
View File

@@ -12,6 +12,7 @@
- 支持日志前缀
- 支持禁用时间戳
- 支持带字段的日志记录
- **支持异步/同步日志模式（默认同步）**
- 使用配置工具统一管理配置
## 使用方法
@@ -92,6 +93,40 @@ 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)
@@ -143,6 +178,15 @@ logger.Errorf(fields, "Failed to process request")
记录错误日志（带字段）。
### (l *Logger) Close() error
优雅关闭logger（仅异步模式需要）。
**说明：**
- 等待所有日志写入完成后再返回
- 同步模式下调用此方法会立即返回，无需等待
- 程序退出前应调用此方法，确保所有日志写入完成
## 配置说明
日志配置通过 `config.LoggerConfig` 提供：
@@ -154,6 +198,8 @@ logger.Errorf(fields, "Failed to process request")
| FilePath | string | 日志文件路径（当output为file或both时必需） | - |
| Prefix | string | 日志前缀 | - |
| DisableTimestamp | bool | 禁用时间戳 | false |
| Async | bool | 是否使用异步模式 | false（同步） |
| BufferSize | int | 异步模式下的缓冲区大小 | 1000 |
## 配置示例
@@ -196,6 +242,25 @@ logger.Errorf(fields, "Failed to process request")
}
```
### 异步模式配置
```json
{
"logger": {
"level": "info",
"output": "file",
"filePath": "./logs/app.log",
"prefix": "app",
"async": true,
"bufferSize": 1000
}
}
```
**说明：**
- `async`: 设置为 `true` 启用异步模式，`false` 或不设置则使用同步模式（默认）
- `bufferSize`: 异步模式下的channel缓冲区大小，默认1000。当缓冲区满时，新的日志会阻塞直到有空间，或降级为同步写入
## 日志级别说明
- **debug**: 调试信息，最详细的日志级别
@@ -222,6 +287,13 @@ logger.Errorf(fields, "Failed to process request")
4. **性能考虑**：
- 使用标准库log包，性能较好
- 文件输出使用追加模式，不会覆盖已有日志
- 异步模式适合高并发场景，减少日志写入对业务代码的阻塞
- 同步模式适合需要确保日志立即写入的场景（如调试）
5. **异步模式注意事项**：
- 异步模式下，程序退出前必须调用 `Close()` 方法，确保所有日志写入完成
- 如果channel缓冲区已满，会自动降级为同步写入，避免丢失日志
- `Fatal` 和 `Panic` 方法始终使用同步模式，确保日志写入后再退出/panic
## 完整示例
@@ -257,6 +329,9 @@ func main() {
}, "User logged in successfully")
logger.Error("An error occurred: %v", err)
// 如果使用异步模式，程序退出前需要关闭logger
// defer logger.Close()
}
```

679
docs/middleware.md
View File

@@ -2,12 +2,15 @@
## 概述
中间件工具提供了常用的HTTP中间件功能，包括CORS处理和时区管理。
中间件工具提供了常用的HTTP中间件功能，包括CORS处理、时区管理、请求日志、Panic恢复和限流等。
## 功能特性
- **CORS中间件**：支持跨域资源共享配置
- **时区中间件**：从请求头读取时区信息，支持默认时区设置
- **日志中间件**：自动记录每个HTTP请求的详细信息
- **Recovery中间件**：捕获panic并恢复，防止服务崩溃
- **限流中间件**：基于令牌桶算法的请求限流
- **中间件链**：提供便捷的中间件链式调用
## CORS中间件
@@ -133,7 +136,7 @@ import (
"net/http"
"git.toowon.com/jimmy/go-common/middleware"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/datetime"
"git.toowon.com/jimmy/go-common/tools"
)
func handler(w http.ResponseWriter, r *http.Request) {
@@ -143,12 +146,12 @@ func handler(w http.ResponseWriter, r *http.Request) {
timezone := h.GetTimezone()
// 使用时区
now := datetime.Now(timezone)
datetime.FormatDateTime(now, timezone)
now := tools.Now(timezone)
tools.FormatDateTime(now, timezone)
h.Success(map[string]interface{}{
"timezone": timezone,
"time": datetime.FormatDateTime(now),
"time": tools.FormatDateTime(now),
})
}
@@ -165,7 +168,7 @@ func main() {
import (
"net/http"
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/datetime"
"git.toowon.com/jimmy/go-common/tools"
)
func handler(w http.ResponseWriter, r *http.Request) {
@@ -174,7 +177,7 @@ func handler(w http.ResponseWriter, r *http.Request) {
func main() {
// 使用自定义默认时区
handler := middleware.TimezoneWithDefault(datetime.UTC)(http.HandlerFunc(handler))
handler := middleware.TimezoneWithDefault(tools.UTC)(http.HandlerFunc(handler))
http.Handle("/api", handler)
http.ListenAndServe(":8080", nil)
}
@@ -182,11 +185,43 @@ func main() {
#### 在业务代码中使用时区
**推荐方式：通过 factory 使用（黑盒模式）**
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/factory"
)
func GetUserList(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 从请求中获取时区
timezone := fac.GetTimezone(r)
// 使用时区进行时间处理
now := fac.Now(timezone)
// 查询数据时使用时区
startTime := fac.StartOfDay(now, timezone)
endTime := fac.EndOfDay(now, timezone)
// 返回数据
fac.Success(w, map[string]interface{}{
"timezone": timezone,
"startTime": fac.FormatDateTime(startTime),
"endTime": fac.FormatDateTime(endTime),
})
}
```
**或者直接使用 tools 包：**
```go
import (
"net/http"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/datetime"
"git.toowon.com/jimmy/go-common/tools"
)
func GetUserList(w http.ResponseWriter, r *http.Request) {
@@ -196,17 +231,17 @@ func GetUserList(w http.ResponseWriter, r *http.Request) {
timezone := h.GetTimezone()
// 使用时区进行时间处理
now := datetime.Now(timezone)
now := tools.Now(timezone)
// 查询数据时使用时区
startTime := datetime.StartOfDay(now, timezone)
endTime := datetime.EndOfDay(now, timezone)
startTime := tools.StartOfDay(now, timezone)
endTime := tools.EndOfDay(now, timezone)
// 返回数据
h.Success(map[string]interface{}{
"timezone": timezone,
"startTime": datetime.FormatDateTime(startTime),
"endTime": datetime.FormatDateTime(endTime),
"startTime": tools.FormatDateTime(startTime),
"endTime": tools.FormatDateTime(endTime),
})
}
```
@@ -233,6 +268,371 @@ X-Timezone: Asia/Shanghai
3. 时区信息存储在context中，可以在整个请求生命周期中使用
4. 建议在CORS配置中包含 `X-Timezone` 请求头
## 日志中间件
### 功能说明
日志中间件用于自动记录每个HTTP请求的详细信息，帮助监控和调试应用。
记录内容包括：
- 请求方法、路径、查询参数
- 响应状态码、响应大小
- 请求处理时间（毫秒）
- 客户端IP地址（支持X-Forwarded-For）
- User-Agent、Referer等信息
### 使用方法
#### 基本使用（使用默认logger）
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/middleware"
)
func main() {
chain := middleware.NewChain(
middleware.Logging(nil), // 使用默认配置
middleware.CORS(),
middleware.Timezone,
)
handler := chain.ThenFunc(apiHandler)
http.Handle("/api", handler)
http.ListenAndServe(":8080", nil)
}
```
#### 使用自定义logger
```go
import (
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/logger"
)
func main() {
// 创建自定义logger（异步模式，输出到文件）
loggerConfig := &logger.LoggerConfig{
Level: "info",
Output: "file",
FilePath: "./logs/app.log",
Async: true, // 异步模式，不阻塞请求
BufferSize: 1000,
}
myLogger, _ := logger.NewLogger(loggerConfig)
// 配置日志中间件
loggingConfig := &middleware.LoggingConfig{
Logger: myLogger,
SkipPaths: []string{"/health", "/metrics"}, // 跳过健康检查接口
}
chain := middleware.NewChain(
middleware.Logging(loggingConfig),
middleware.CORS(),
middleware.Timezone,
)
handler := chain.ThenFunc(apiHandler)
http.Handle("/api", handler)
http.ListenAndServe(":8080", nil)
}
```
### LoggingConfig 配置说明
| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| Logger | *logger.Logger | 日志记录器 | 创建默认logger（stdout） |
| SkipPaths | []string | 跳过记录的路径列表 | [] |
| LogRequestBody | bool | 是否记录请求体（慎用） | false |
| LogResponseBody | bool | 是否记录响应体（慎用） | false |
### 日志输出示例
```
[INFO] HTTP Request method=GET path=/api/users query= status=200 size=1024 duration=45 ip=192.168.1.100 user_agent=Mozilla/5.0 referer=
[WARN] HTTP Request method=POST path=/api/users query= status=400 size=128 duration=12 ip=192.168.1.100 user_agent=PostmanRuntime/7.29
[ERROR] HTTP Request method=GET path=/api/error query= status=500 size=256 duration=89 ip=192.168.1.100 user_agent=curl/7.64.1 referer=
```
### 注意事项
1. **异步模式推荐**：生产环境建议使用异步logger，避免日志写入阻塞请求
2. **跳过路径**：健康检查、监控接口等高频接口建议跳过日志记录
3. **日志级别**：根据状态码自动选择日志级别（5xx=ERROR, 4xx=WARN, 2xx-3xx=INFO）
4. **客户端IP**：自动从X-Forwarded-For、X-Real-IP或RemoteAddr获取真实IP
## Recovery中间件
### 功能说明
Recovery中间件用于捕获HTTP处理过程中的panic，防止panic导致整个服务崩溃。
功能包括：
- 捕获panic并恢复服务
- 记录panic信息和堆栈跟踪
- 返回500错误响应
- 支持自定义错误处理
### 使用方法
#### 基本使用（使用默认配置）
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/middleware"
)
func main() {
chain := middleware.NewChain(
middleware.Recovery(nil), // 使用默认配置
middleware.Logging(nil),
middleware.CORS(),
middleware.Timezone,
)
handler := chain.ThenFunc(apiHandler)
http.Handle("/api", handler)
http.ListenAndServe(":8080", nil)
}
```
#### 使用自定义logger
```go
import (
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/logger"
)
func main() {
myLogger, _ := logger.NewLogger(nil)
recoveryConfig := &middleware.RecoveryConfig{
Logger: myLogger,
EnableStackTrace: true, // 启用堆栈跟踪
}
chain := middleware.NewChain(
middleware.Recovery(recoveryConfig),
middleware.Logging(nil),
)
handler := chain.ThenFunc(apiHandler)
http.Handle("/api", handler)
http.ListenAndServe(":8080", nil)
}
```
#### 自定义错误响应
```go
import (
"net/http"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/middleware"
)
func main() {
recoveryConfig := &middleware.RecoveryConfig{
EnableStackTrace: true,
CustomHandler: func(w http.ResponseWriter, r *http.Request, err interface{}) {
// 使用统一的JSON响应格式
h := commonhttp.NewHandler(w, r)
h.SystemError("服务器内部错误")
},
}
chain := middleware.NewChain(
middleware.Recovery(recoveryConfig),
)
handler := chain.ThenFunc(apiHandler)
http.Handle("/api", handler)
http.ListenAndServe(":8080", nil)
}
```
### RecoveryConfig 配置说明
| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| Logger | *logger.Logger | 日志记录器 | 创建默认logger |
| EnableStackTrace | bool | 是否记录堆栈跟踪 | true |
| CustomHandler | func(...) | 自定义错误处理函数 | nil（返回500文本） |
### 注意事项
1. **放在最外层**：Recovery中间件应该放在中间件链的最前面，以捕获所有panic
2. **日志记录**：建议配置logger，确保panic信息被记录下来
3. **堆栈跟踪**：生产环境建议启用，方便排查问题
4. **自定义响应**：可以自定义错误响应格式，统一错误处理
## 限流中间件
### 功能说明
限流中间件用于限制请求频率，防止API被滥用或遭受攻击。
特性：
- 基于令牌桶算法
- 支持按IP、用户ID等维度限流
- 自动设置限流响应头
- 内存存储，自动清理过期数据
### 使用方法
#### 基本使用（默认配置：100请求/分钟）
```go
import (
"net/http"
"git.toowon.com/jimmy/go-common/middleware"
)
func main() {
chain := middleware.NewChain(
middleware.Recovery(nil),
middleware.Logging(nil),
middleware.RateLimit(nil), // 默认100请求/分钟，按IP限流
middleware.CORS(),
)
handler := chain.ThenFunc(apiHandler)
http.Handle("/api", handler)
http.ListenAndServe(":8080", nil)
}
```
#### 自定义限流规则
```go
import (
"time"
"git.toowon.com/jimmy/go-common/middleware"
)
func main() {
// 创建限流器：10请求/分钟
limiter := middleware.NewTokenBucketLimiter(10, time.Minute)
rateLimitConfig := &middleware.RateLimitConfig{
Limiter: limiter,
}
chain := middleware.NewChain(
middleware.RateLimit(rateLimitConfig),
)
handler := chain.ThenFunc(apiHandler)
http.Handle("/api", handler)
http.ListenAndServe(":8080", nil)
}
```
#### 按用户ID限流
```go
import (
"net/http"
"time"
"git.toowon.com/jimmy/go-common/middleware"
)
func main() {
limiter := middleware.NewTokenBucketLimiter(100, time.Minute)
rateLimitConfig := &middleware.RateLimitConfig{
Limiter: limiter,
KeyFunc: func(r *http.Request) string {
// 从请求头或JWT token中获取用户ID
userID := r.Header.Get("X-User-ID")
if userID != "" {
return "user:" + userID
}
// 如果没有用户ID，使用IP
return "ip:" + r.RemoteAddr
},
OnRateLimitExceeded: func(w http.ResponseWriter, r *http.Request, key string) {
// 记录限流事件
println("Rate limit exceeded for:", key)
},
}
chain := middleware.NewChain(
middleware.RateLimit(rateLimitConfig),
)
handler := chain.ThenFunc(apiHandler)
http.Handle("/api", handler)
http.ListenAndServe(":8080", nil)
}
```
#### 便捷函数
```go
// 按IP限流：10请求/分钟
chain := middleware.NewChain(
middleware.RateLimitByIP(10, time.Minute),
)
// 或使用自定义速率
chain := middleware.NewChain(
middleware.RateLimitWithRate(50, time.Minute),
)
```
### RateLimitConfig 配置说明
| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| Limiter | RateLimiter | 限流器实例 | 100请求/分钟 |
| KeyFunc | func(*http.Request) string | 生成限流键的函数 | 使用客户端IP |
| OnRateLimitExceeded | func(...) | 限流触发回调 | nil |
### 响应头说明
限流中间件会自动设置以下响应头：
| 响应头 | 说明 |
|--------|------|
| X-RateLimit-Limit | 窗口期内允许的请求数 |
| X-RateLimit-Remaining | 当前窗口剩余配额 |
| X-RateLimit-Reset | 配额重置时间（Unix时间戳） |
| Retry-After | 限流时，建议重试的等待时间（秒） |
### 响应示例
正常请求：
```
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000
```
触发限流：
```
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640000000
Retry-After: 45
Too Many Requests
```
### 注意事项
1. **内存存储**：当前实现使用内存存储，适用于单机部署。如需分布式限流，建议使用Redis
2. **键设计**：合理设计限流键，可以按IP、用户、API等维度限流
3. **清理机制**：自动清理过期的限流数据，避免内存泄漏
4. **算法选择**：使用令牌桶算法，支持突发流量
## 中间件链
### 功能说明
@@ -277,7 +677,107 @@ handler := chain.ThenFunc(handler)
## 完整示例
### 示例1：CORS + 时区中间件
### 示例1：完整的生产级中间件配置
```go
package main
import (
"log"
"net/http"
"time"
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/logger"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/tools"
)
func apiHandler(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
// 从Handler获取时区
timezone := h.GetTimezone()
now := tools.Now(timezone)
h.Success(map[string]interface{}{
"message": "Hello",
"timezone": timezone,
"time": tools.FormatDateTime(now),
})
}
func main() {
// 1. 配置logger（异步模式，输出到文件）
loggerConfig := &logger.LoggerConfig{
Level: "info",
Output: "both", // 同时输出到stdout和文件
FilePath: "./logs/app.log",
Async: true,
BufferSize: 1000,
}
myLogger, err := logger.NewLogger(loggerConfig)
if err != nil {
log.Fatal(err)
}
defer myLogger.Close() // 确保程序退出时关闭logger
// 2. 配置CORS
corsConfig := &middleware.CORSConfig{
AllowedOrigins: []string{"*"},
AllowedMethods: []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
AllowedHeaders: []string{"Content-Type", "Authorization", "X-Timezone"},
}
// 3. 配置日志中间件
loggingConfig := &middleware.LoggingConfig{
Logger: myLogger,
SkipPaths: []string{"/health", "/metrics"},
}
// 4. 配置Recovery中间件
recoveryConfig := &middleware.RecoveryConfig{
Logger: myLogger,
EnableStackTrace: true,
CustomHandler: func(w http.ResponseWriter, r *http.Request, err interface{}) {
h := commonhttp.NewHandler(w, r)
h.SystemError("服务器内部错误")
},
}
// 5. 配置限流中间件（100请求/分钟）
rateLimiter := middleware.NewTokenBucketLimiter(100, time.Minute)
rateLimitConfig := &middleware.RateLimitConfig{
Limiter: rateLimiter,
OnRateLimitExceeded: func(w http.ResponseWriter, r *http.Request, key string) {
myLogger.Warnf(map[string]interface{}{
"key": key,
"path": r.URL.Path,
}, "Rate limit exceeded")
},
}
// 6. 创建中间件链（顺序很重要！）
chain := middleware.NewChain(
middleware.Recovery(recoveryConfig), // 最外层：捕获panic
middleware.Logging(loggingConfig), // 日志记录
middleware.RateLimit(rateLimitConfig), // 限流
middleware.CORS(corsConfig), // CORS处理
middleware.Timezone, // 时区处理
)
// 7. 应用中间件
http.Handle("/api", chain.ThenFunc(apiHandler))
http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("OK"))
})
log.Println("Server started on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}
```
### 示例2：基础的CORS + 时区中间件
```go
package main
@@ -288,7 +788,7 @@ import (
"git.toowon.com/jimmy/go-common/middleware"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/datetime"
"git.toowon.com/jimmy/go-common/tools"
)
func apiHandler(w http.ResponseWriter, r *http.Request) {
@@ -296,33 +796,23 @@ func apiHandler(w http.ResponseWriter, r *http.Request) {
// 从Handler获取时区
timezone := h.GetTimezone()
now := datetime.Now(timezone)
now := tools.Now(timezone)
h.Success(map[string]interface{}{
"message": "Hello",
"timezone": timezone,
"time": datetime.FormatDateTime(now),
"time": tools.FormatDateTime(now),
})
}
func main() {
// 配置CORS
corsConfig := &middleware.CORSConfig{
AllowedOrigins: []string{"*"},
AllowedMethods: []string{"GET", "POST", "OPTIONS"},
AllowedHeaders: []string{"Content-Type", "Authorization", "X-Timezone"},
}
// 创建中间件链
// 创建简单的中间件链
chain := middleware.NewChain(
middleware.CORS(corsConfig),
middleware.Timezone,
middleware.CORS(nil), // 使用默认CORS配置
middleware.Timezone, // 使用默认时区
)
// 应用中间件
handler := chain.ThenFunc(apiHandler)
http.Handle("/api", handler)
http.Handle("/api", chain.ThenFunc(apiHandler))
log.Println("Server started on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
@@ -408,6 +898,65 @@ func getPosts(w http.ResponseWriter, r *http.Request) {
从context中获取时区。
### 日志中间件
#### Logging(config *LoggingConfig) func(http.Handler) http.Handler
创建日志中间件。
**参数：**
- `config`: 日志配置，nil则使用默认配置
**返回：** 中间件函数
### Recovery中间件
#### Recovery(config *RecoveryConfig) func(http.Handler) http.Handler
创建Recovery中间件。
**参数：**
- `config`: Recovery配置，nil则使用默认配置
**返回：** 中间件函数
#### RecoveryWithLogger(log *logger.Logger) func(http.Handler) http.Handler
使用指定logger的Recovery中间件（便捷函数）。
#### RecoveryWithCustomHandler(customHandler func(...)) func(http.Handler) http.Handler
使用自定义错误处理的Recovery中间件（便捷函数）。
### 限流中间件
#### RateLimit(config *RateLimitConfig) func(http.Handler) http.Handler
创建限流中间件。
**参数：**
- `config`: 限流配置，nil则使用默认配置（100请求/分钟）
**返回：** 中间件函数
#### NewTokenBucketLimiter(rate int, windowSize time.Duration) RateLimiter
创建令牌桶限流器。
**参数：**
- `rate`: 每个窗口期允许的请求数
- `windowSize`: 窗口大小
**返回：** 限流器实例
#### RateLimitWithRate(rate int, windowSize time.Duration) func(http.Handler) http.Handler
使用指定速率创建限流中间件（便捷函数）。
#### RateLimitByIP(rate int, windowSize time.Duration) func(http.Handler) http.Handler
按IP限流（便捷函数）。
### 中间件链
#### NewChain(middlewares ...func(http.Handler) http.Handler) *Chain
@@ -428,19 +977,63 @@ func getPosts(w http.ResponseWriter, r *http.Request) {
## 注意事项
1. **CORS配置**：
- 生产环境建议明确指定允许的源，避免使用 "*"
- 如果使用凭证（cookies），必须明确指定源，不能使用 "*"
### 1. CORS配置
- 生产环境建议明确指定允许的源，避免使用 "*"
- 如果使用凭证（cookies），必须明确指定源，不能使用 "*"
- CORS中间件应该在Recovery和Logging之后，以便正确处理预检请求
2. **时区处理**：
- 时区信息存储在context中，确保中间件在处理器之前执行
- 时区验证失败时会自动回退到默认时区，不会返回错误
### 2. 时区处理
- 时区信息存储在context中，确保中间件在处理器之前执行
- 时区验证失败时会自动回退到默认时区，不会返回错误
- 建议在CORS配置中包含 `X-Timezone` 请求头
3. **中间件顺序**：
- CORS中间件应该放在最外层，以便处理预检请求
- 时区中间件可以放在CORS之后
### 3. 日志记录
- **生产环境推荐异步模式**：避免日志写入阻塞请求，提升性能
- **跳过高频接口**：健康检查、监控接口等高频接口建议跳过日志
- **日志轮转**：使用文件输出时，建议配合日志轮转工具（如logrotate）
- **敏感信息**：不要记录请求体和响应体，避免泄露敏感信息
4. **性能考虑**：
- CORS预检请求会被缓存，减少重复请求
- 时区验证只在请求头存在时进行，性能影响很小
### 4. Panic恢复
- **放在最外层**：Recovery中间件应该放在中间件链的最前面
- **记录日志**：务必配置logger，确保panic信息被记录
- **监控告警**：建议将panic事件接入监控系统，及时发现问题
- **堆栈跟踪**：生产环境建议启用，方便排查问题
### 5. 限流配置
- **合理设置阈值**：根据实际业务需求设置限流阈值
- **分布式部署**：当前实现使用内存存储，适用于单机。分布式部署建议使用Redis
- **键设计**：合理设计限流键，可以按IP、用户、API等维度限流
- **响应头**：客户端可以根据X-RateLimit-*响应头实现智能重试
### 6. 中间件顺序（推荐）
建议的中间件顺序（从外到内）：
1. **Recovery** - 最外层，捕获所有panic
2. **Logging** - 记录所有请求（包括限流的请求）
3. **RateLimit** - 限流保护
4. **CORS** - 处理跨域
5. **Timezone** - 时区处理
6. **业务中间件** - 认证、授权等
```go
chain := middleware.NewChain(
middleware.Recovery(recoveryConfig), // 1. Panic恢复
middleware.Logging(loggingConfig), // 2. 日志记录
middleware.RateLimit(rateLimitConfig), // 3. 限流
middleware.CORS(corsConfig), // 4. CORS
middleware.Timezone, // 5. 时区
)
```
### 7. 性能考虑
- **异步日志**：使用异步logger，避免IO阻塞
- **限流算法**：令牌桶算法支持突发流量
- **自动清理**：限流数据会自动清理，避免内存泄漏
- **跳过路径**：合理使用SkipPaths，减少不必要的处理
### 8. 生产环境建议
- 使用异步logger，配置日志文件和轮转
- 启用Recovery中间件，配置告警
- 根据业务设置合理的限流阈值
- 配置监控指标（请求量、错误率、限流触发次数等）
- 定期review日志，优化性能瓶颈

140
docs/migration.md
View File

@@ -13,7 +13,101 @@
- 自动创建迁移记录表
- 事务支持，确保迁移的原子性
## 使用方法
## 🚀 最简单的使用方式（黑盒模式，推荐）
这是最简单的迁移方式，内部自动处理配置加载、数据库连接、迁移执行等所有细节。
### 方式一：使用独立迁移工具（推荐）
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. 创建迁移器
@@ -86,14 +180,16 @@ migrations := []migration.Migration{
migrator.AddMigrations(migrations...)
```
#### 方式三：从文件加载迁移
#### 方式三：从文件加载迁移（推荐）
```go
// 文件命名格式: {version}_{description}.sql 或 {version}_{description}.up.sql
// 例如: 20240101000001_create_users_table.up.sql
// 对应的回滚文件: 20240101000001_create_users_table.down.sql
// 支持的文件命名格式：
// 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", "*.up.sql")
migrations, err := migration.LoadMigrationsFromFiles("./migrations", "*.sql")
if err != nil {
log.Fatal(err)
}
@@ -101,6 +197,12 @@ if err != nil {
migrator.AddMigrations(migrations...)
```
**新特性：**
- ✅ 支持数字前缀命名（如 `01_init_schema.sql`）
- ✅ 自动分割多行 SQL 语句
- ✅ 自动处理注释（单行 `--` 和多行 `/* */`）
- ✅ 记录执行时间（毫秒）
### 3. 执行迁移
```go
@@ -289,15 +391,31 @@ type MigrationStatus struct {
**参数：**
- `dir`: 迁移文件目录
- `pattern`: 文件匹配模式，如 "*.up.sql"
- `pattern`: 文件匹配模式，如 "*.sql" 或 "*.up.sql"
**返回：** 迁移列表和错误信息
**文件命名格式：** `{version}_{description}.up.sql`
**支持的文件命名格式：**
**示例：**
- `20240101000001_create_users_table.up.sql` - 升级文件
- `20240101000001_create_users_table.down.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

23
docs/storage.md
View File

@@ -265,7 +265,14 @@ type Storage interface {
#### 响应
直接返回文件内容，设置适当的Content-Type。
- **成功**：直接返回文件内容（二进制），设置适当的Content-Type
- **错误**：返回标准HTTP错误状态码和错误消息（文本格式）
- `400 Bad Request`: 缺少必需参数
- `404 Not Found`: 文件不存在
- `405 Method Not Allowed`: 请求方法不正确
- `500 Internal Server Error`: 系统错误
**注意**：`ProxyHandler` 返回的是文件内容（二进制），而不是JSON响应。错误时使用标准HTTP状态码，保持与文件响应的一致性。
### 辅助函数
@@ -318,8 +325,20 @@ func main() {
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(cfg.GetCORS()),
middleware.CORS(corsConfig),
middleware.Timezone,
)

179
email/email.go
View File

@@ -17,37 +17,43 @@ type Email struct {
}
// NewEmail 创建邮件发送器
func NewEmail(cfg *config.EmailConfig) (*Email, error) {
if cfg == nil {
func NewEmail(cfg *config.Config) *Email {
if cfg == nil || cfg.Email == nil {
return &Email{config: nil}
}
return &Email{config: cfg.Email}
}
// getEmailConfig 获取邮件配置（内部方法）
func (e *Email) getEmailConfig() (*config.EmailConfig, error) {
if e.config == nil {
return nil, fmt.Errorf("email config is nil")
}
if cfg.Host == "" {
if e.config.Host == "" {
return nil, fmt.Errorf("email host is required")
}
if cfg.Username == "" {
if e.config.Username == "" {
return nil, fmt.Errorf("email username is required")
}
if cfg.Password == "" {
if e.config.Password == "" {
return nil, fmt.Errorf("email password is required")
}
// 设置默认值
if cfg.Port == 0 {
cfg.Port = 587
if e.config.Port == 0 {
e.config.Port = 587
}
if cfg.From == "" {
cfg.From = cfg.Username
if e.config.From == "" {
e.config.From = e.config.Username
}
if cfg.Timeout == 0 {
cfg.Timeout = 30
if e.config.Timeout == 0 {
e.config.Timeout = 30
}
return &Email{
config: cfg,
}, nil
return e.config, nil
}
// Message 邮件消息
@@ -69,66 +75,91 @@ type Message struct {
// HTMLBody HTML正文（可选，如果设置了会优先使用）
HTMLBody string
// Attachments 附件列表（可选）
Attachments []Attachment
}
// Attachment 附件
type Attachment struct {
// Filename 文件名
Filename string
// SendEmail 发送邮件
// to: 收件人列表
// subject: 邮件主题
// body: 邮件正文（纯文本）
// htmlBody: HTML正文（可选，如果设置了会优先使用）
func (e *Email) SendEmail(to []string, subject, body string, htmlBody ...string) error {
cfg, err := e.getEmailConfig()
if err != nil {
return err
}
// Content 文件内容
Content []byte
msg := &Message{
To: to,
Subject: subject,
Body: body,
}
// ContentType 文件类型（如：application/pdf）
ContentType string
if len(htmlBody) > 0 && htmlBody[0] != "" {
msg.HTMLBody = htmlBody[0]
}
return e.send(msg, cfg)
}
// SendRaw 发送原始邮件内容
// recipients: 收件人列表（To、Cc、Bcc的合并列表）
// body: 完整的邮件内容（MIME格式），由外部构建
func (e *Email) SendRaw(recipients []string, body []byte) error {
if len(recipients) == 0 {
// send 发送邮件（内部方法）
func (e *Email) send(msg *Message, cfg *config.EmailConfig) error {
if msg == nil {
return fmt.Errorf("message is nil")
}
if len(msg.To) == 0 {
return fmt.Errorf("recipients are required")
}
if len(body) == 0 {
return fmt.Errorf("email body is required")
if msg.Subject == "" {
return fmt.Errorf("subject is required")
}
if msg.Body == "" && msg.HTMLBody == "" {
return fmt.Errorf("body or HTMLBody is required")
}
// 构建邮件内容
emailBody, err := e.buildEmailBody(msg, cfg)
if err != nil {
return fmt.Errorf("failed to build email body: %w", err)
}
// 合并收件人列表
recipients := append(msg.To, msg.Cc...)
recipients = append(recipients, msg.Bcc...)
// 连接SMTP服务器
addr := fmt.Sprintf("%s:%d", e.config.Host, e.config.Port)
auth := smtp.PlainAuth("", e.config.Username, e.config.Password, e.config.Host)
addr := net.JoinHostPort(cfg.Host, fmt.Sprintf("%d", cfg.Port))
auth := smtp.PlainAuth("", cfg.Username, cfg.Password, cfg.Host)
// 创建连接
conn, err := net.DialTimeout("tcp", addr, time.Duration(e.config.Timeout)*time.Second)
conn, err := net.DialTimeout("tcp", addr, time.Duration(cfg.Timeout)*time.Second)
if err != nil {
return fmt.Errorf("failed to connect to SMTP server: %w", err)
}
defer conn.Close()
// 创建SMTP客户端
client, err := smtp.NewClient(conn, e.config.Host)
client, err := smtp.NewClient(conn, cfg.Host)
if err != nil {
return fmt.Errorf("failed to create SMTP client: %w", err)
}
defer client.Close()
// TLS/SSL处理
if e.config.UseSSL {
if cfg.UseSSL {
// SSL模式（端口通常是465）
tlsConfig := &tls.Config{
ServerName: e.config.Host,
ServerName: cfg.Host,
}
if err := client.StartTLS(tlsConfig); err != nil {
return fmt.Errorf("failed to start TLS: %w", err)
}
} else if e.config.UseTLS {
} else if cfg.UseTLS {
// TLS模式（STARTTLS，端口通常是587）
tlsConfig := &tls.Config{
ServerName: e.config.Host,
ServerName: cfg.Host,
}
if err := client.StartTLS(tlsConfig); err != nil {
return fmt.Errorf("failed to start TLS: %w", err)
@@ -141,7 +172,7 @@ func (e *Email) SendRaw(recipients []string, body []byte) error {
}
// 设置发件人
if err := client.Mail(e.config.From); err != nil {
if err := client.Mail(cfg.From); err != nil {
return fmt.Errorf("failed to set sender: %w", err)
}
@@ -158,7 +189,7 @@ func (e *Email) SendRaw(recipients []string, body []byte) error {
return fmt.Errorf("failed to get data writer: %w", err)
}
_, err = writer.Write(body)
_, err = writer.Write(emailBody)
if err != nil {
writer.Close()
return fmt.Errorf("failed to write email body: %w", err)
@@ -177,47 +208,14 @@ func (e *Email) SendRaw(recipients []string, body []byte) error {
return nil
}
// Send 发送邮件（使用Message结构，内部会构建邮件内容）
// 注意：如果需要完全控制邮件内容，请使用SendRaw方法
func (e *Email) Send(msg *Message) error {
if msg == nil {
return fmt.Errorf("message is nil")
}
if len(msg.To) == 0 {
return fmt.Errorf("recipients are required")
}
if msg.Subject == "" {
return fmt.Errorf("subject is required")
}
if msg.Body == "" && msg.HTMLBody == "" {
return fmt.Errorf("body or HTMLBody is required")
}
// 构建邮件内容
emailBody, err := e.buildEmailBody(msg)
if err != nil {
return fmt.Errorf("failed to build email body: %w", err)
}
// 合并收件人列表
recipients := append(msg.To, msg.Cc...)
recipients = append(recipients, msg.Bcc...)
// 使用SendRaw发送
return e.SendRaw(recipients, emailBody)
}
// buildEmailBody 构建邮件内容
func (e *Email) buildEmailBody(msg *Message) ([]byte, error) {
func (e *Email) buildEmailBody(msg *Message, cfg *config.EmailConfig) ([]byte, error) {
var buf bytes.Buffer
// 邮件头
from := e.config.From
if e.config.FromName != "" {
from = fmt.Sprintf("%s <%s>", e.config.FromName, e.config.From)
from := cfg.From
if cfg.FromName != "" {
from = fmt.Sprintf("%s <%s>", cfg.FromName, cfg.From)
}
buf.WriteString(fmt.Sprintf("From: %s\r\n", from))
@@ -281,26 +279,3 @@ func joinEmails(emails []string) string {
return result
}
// SendSimple 发送简单邮件（便捷方法）
// to: 收件人
// subject: 主题
// body: 正文
func (e *Email) SendSimple(to []string, subject, body string) error {
return e.Send(&Message{
To: to,
Subject: subject,
Body: body,
})
}
// SendHTML 发送HTML邮件（便捷方法）
// to: 收件人
// subject: 主题
// htmlBody: HTML正文
func (e *Email) SendHTML(to []string, subject, htmlBody string) error {
return e.Send(&Message{
To: to,
Subject: subject,
HTMLBody: htmlBody,
})
}

23
examples/config_example.go
View File

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

56
examples/datetime_example.go
View File

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

74
examples/datetime_utc_example.go
View File

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

166
examples/factory_blackbox_example.go Normal file
View File

@@ -0,0 +1,166 @@
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,
}, "请求指标")
})
}

164
examples/factory_example.go
View File

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

74
examples/http_handler_example.go
View File

@@ -5,6 +5,7 @@ import (
"net/http"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/factory"
)
// 用户结构
@@ -14,15 +15,17 @@ type User struct {
Email string `json:"email"`
}
// 获取用户列表（使用Handler黑盒模式）
func GetUserList(h *commonhttp.Handler) {
// 获取分页参数（简洁方式）
pagination := h.ParsePaginationRequest()
// 获取用户列表（使用公共方法和factory）
func GetUserList(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 获取分页参数（使用公共方法）
pagination := commonhttp.ParsePaginationRequest(r)
page := pagination.GetPage()
pageSize := pagination.GetSize()
// 获取查询参数（简洁方式）
_ = h.GetQuery("keyword", "") // 示例：获取查询参数
// 获取查询参数（使用公共方法）
_ = commonhttp.GetQuery(r, "keyword", "") // 示例：获取查询参数
// 模拟查询数据
users := []User{
@@ -31,26 +34,28 @@ func GetUserList(h *commonhttp.Handler) {
}
total := int64(100)
// 返回分页响应（简洁方式）
h.SuccessPage(users, total, page, pageSize)
// 返回分页响应（使用factory方法）
fac.SuccessPage(w, users, total, page, pageSize)
}
// 创建用户（使用Handler黑盒模式）
func CreateUser(h *commonhttp.Handler) {
// 解析请求体（简洁方式）
// 创建用户（使用公共方法和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 := h.ParseJSON(&req); err != nil {
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
if err := commonhttp.ParseJSON(r, &req); err != nil {
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
// 参数验证
if req.Name == "" {
h.Error(1001, "用户名不能为空")
fac.Error(w, 1001, "用户名不能为空")
return
}
@@ -61,49 +66,46 @@ func CreateUser(h *commonhttp.Handler) {
Email: req.Email,
}
// 返回成功响应（简洁方式）
h.SuccessWithMessage("创建成功", user)
// 返回成功响应（使用factory方法，统一Success方法）
fac.Success(w, user, "创建成功")
}
// 获取用户详情（使用Handler黑盒模式）
func GetUser(h *commonhttp.Handler) {
// 获取查询参数（简洁方式）
id := h.GetQueryInt64("id", 0)
// 获取用户详情（使用公共方法和factory）
func GetUser(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
// 获取查询参数（使用公共方法）
id := commonhttp.GetQueryInt64(r, "id", 0)
if id == 0 {
h.WriteJSON(http.StatusBadRequest, 400, "用户ID不能为空", nil)
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "用户ID不能为空", nil)
return
}
// 模拟查询用户
if id == 1 {
user := User{ID: 1, Name: "User1", Email: "user1@example.com"}
h.Success(user)
fac.Success(w, user)
} else {
h.Error(1002, "用户不存在")
fac.Error(w, 1002, "用户不存在")
}
}
func main() {
// 方式1：使用HandleFunc包装器（推荐，最简洁）
http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
switch h.Request().Method {
// 使用标准http.HandleFunc
http.HandleFunc("/users", func(w http.ResponseWriter, r *http.Request) {
switch r.Method {
case http.MethodGet:
GetUserList(h)
GetUserList(w, r)
case http.MethodPost:
CreateUser(h)
CreateUser(w, r)
default:
h.WriteJSON(http.StatusMethodNotAllowed, 405, "方法不支持", nil)
commonhttp.WriteJSON(w, http.StatusMethodNotAllowed, 405, "方法不支持", nil)
}
}))
// 方式2：手动创建Handler（需要更多控制时）
http.HandleFunc("/user", func(w http.ResponseWriter, r *http.Request) {
h := commonhttp.NewHandler(w, r)
GetUser(h)
})
http.HandleFunc("/user", GetUser)
log.Println("Server started on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}

22
examples/http_pagination_example.go
View File

@@ -5,6 +5,7 @@ import (
"net/http"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/factory"
)
// ListUserRequest 用户列表请求（包含分页字段）
@@ -20,21 +21,22 @@ type User struct {
Email string `json:"email"`
}
// 获取用户列表（使用Handler和PaginationRequest）
func GetUserList(h *commonhttp.Handler) {
// 获取用户列表（使用公共方法和factory）
func GetUserList(w http.ResponseWriter, r *http.Request) {
fac, _ := factory.NewFactoryFromFile("config.json")
var req ListUserRequest
// 方式1：从JSON请求体解析（分页字段会自动解析）
if h.Request().Method == http.MethodPost {
if err := h.ParseJSON(&req); err != nil {
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
if r.Method == http.MethodPost {
if err := commonhttp.ParseJSON(r, &req); err != nil {
commonhttp.WriteJSON(w, http.StatusBadRequest, 400, "请求参数解析失败", nil)
return
}
} else {
// 方式2：从查询参数解析分页
pagination := h.ParsePaginationRequest()
pagination := commonhttp.ParsePaginationRequest(r)
req.PaginationRequest = *pagination
req.Keyword = h.GetQuery("keyword", "")
req.Keyword = commonhttp.GetQuery(r, "keyword", "")
}
// 使用分页方法
@@ -49,12 +51,12 @@ func GetUserList(h *commonhttp.Handler) {
}
total := int64(100)
// 返回分页响应
h.SuccessPage(users, total, page, size)
// 返回分页响应（使用factory方法）
fac.SuccessPage(w, users, total, page, size)
}
func main() {
http.HandleFunc("/users", commonhttp.HandleFunc(GetUserList))
http.HandleFunc("/users", GetUserList)
log.Println("Server started on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))

14
examples/logger_example.go
View File

@@ -14,13 +14,20 @@ func main() {
log.Fatal("Failed to load config:", err)
}
// 使用工厂创建日志记录器（推荐方式）
// 方式1：使用工厂创建日志记录器（推荐方式）
fac := factory.NewFactory(cfg)
logger, err := fac.GetLogger()
if err != nil {
log.Fatal("Failed to create logger:", err)
}
// 如果使用异步模式，程序退出前需要关闭logger
defer logger.Close()
// 方式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")
@@ -45,6 +52,11 @@ func main() {
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")

66
examples/middleware_example.go
View File

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

40
examples/middleware_simple_example.go Normal file
View File

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

58
examples/migration_example.go
View File

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

105
examples/migration_reset_example.go
View File

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

139
examples/migrations/README.md Normal file
View File

@@ -0,0 +1,139 @@
# 数据库迁移示例
这个目录包含了数据库迁移的示例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)

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

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

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

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

14
examples/storage_example.go
View File

@@ -36,8 +36,20 @@ func main() {
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(cfg.GetCORS()),
middleware.CORS(corsConfig),
middleware.Timezone,
)

745
factory/factory.go
View File

@@ -4,13 +4,18 @@ import (
"context"
"fmt"
"io"
"net/http"
"time"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/email"
commonhttp "git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/logger"
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/migration"
"git.toowon.com/jimmy/go-common/sms"
"git.toowon.com/jimmy/go-common/storage"
"git.toowon.com/jimmy/go-common/tools"
"github.com/redis/go-redis/v9"
"gorm.io/driver/mysql"
"gorm.io/driver/postgres"
@@ -18,6 +23,86 @@ import (
"gorm.io/gorm"
)
// ========== HTTP响应结构体（暴露给外部项目使用） ==========
// Response 标准响应结构（暴露给外部项目使用）
// 外部项目可以直接使用 factory.Response 创建响应对象
//
// 示例：
//
// response := factory.Response{
// Code: 0,
// Message: "success",
// Data: data,
// }
type Response = commonhttp.Response
// PageResponse 分页响应结构（暴露给外部项目使用）
// 外部项目可以直接使用 factory.PageResponse 创建分页响应对象
type PageResponse = commonhttp.PageResponse
// PageData 分页数据（暴露给外部项目使用）
// 外部项目可以直接使用 factory.PageData 创建分页数据对象
//
// 示例：
//
// pageData := &factory.PageData{
// List: users,
// Total: 100,
// Page: 1,
// PageSize: 20,
// }
// fac.Success(w, pageData)
type PageData = commonhttp.PageData
// ========== HTTP请求结构体（暴露给外部项目使用） ==========
// PaginationRequest 分页请求结构（暴露给外部项目使用）
// 外部项目可以直接使用 factory.PaginationRequest 创建分页请求对象
//
// 示例：
//
// type ListUserRequest struct {
// Keyword string `json:"keyword"`
// factory.PaginationRequest // 嵌入分页请求结构
// }
type PaginationRequest = commonhttp.PaginationRequest
// Factory 工厂类 - 黑盒模式设计
//
// 核心理念：
//
// 外部项目只需传递一个配置文件路径，即可直接使用所有功能，
// 无需关心内部实现细节。
//
// 推荐使用的黑盒方法：
// - GetMiddlewareChain()：获取配置好的中间件链
// - LogInfo(), LogError()：记录日志
// - RedisSet(), RedisGet()：操作Redis
// - SendEmail(), SendSMS()：发送邮件和短信
// - UploadFile(), GetFileURL()：文件上传和访问
//
// 需要获取客户端对象的场景（高级功能）：
// - GetDatabase()：数据库操作（GORM已经是很好的抽象）
// - GetRedisClient()：Redis高级操作（Hash, List, Set, ZSet等）
// - GetLogger()：Logger高级功能（Close等）
//
// 使用示例：
//
// // 1. 创建工厂（传入配置文件路径）
// fac, _ := factory.NewFactoryFromFile("config.json")
//
// // 2. 直接使用黑盒方法（推荐）
// fac.LogInfo("用户登录成功")
// fac.RedisSet(ctx, "session:123", "data", time.Hour)
// fac.SendEmail([]string{"user@example.com"}, "主题", "内容")
// chain := fac.GetMiddlewareChain()
// chain.Append(yourAuthMiddleware) // 添加自定义中间件
//
// // 3. 获取客户端对象（仅在需要高级功能时）
// db, _ := fac.GetDatabase()
// db.Find(&users)
//
// Factory 工厂类，用于从配置创建各种客户端对象
type Factory struct {
cfg *config.Config
@@ -52,20 +137,12 @@ func (f *Factory) getEmailClient() (*email.Email, error) {
return f.email, nil
}
if f.cfg.Email == nil {
return nil, fmt.Errorf("email config is nil")
}
e, err := email.NewEmail(f.cfg.Email)
if err != nil {
return nil, fmt.Errorf("failed to create email client: %w", err)
}
f.email = e
return e, nil
f.email = email.NewEmail(f.cfg)
return f.email, nil
}
// SendEmail 发送邮件（黑盒模式）
// SendEmail 发送邮件（黑盒模式，推荐使用）
// 自动使用配置文件中的SMTP配置发送邮件
// to: 收件人列表
// subject: 邮件主题
// body: 邮件正文（纯文本）
@@ -75,18 +152,7 @@ func (f *Factory) SendEmail(to []string, subject, body string, htmlBody ...strin
if err != nil {
return err
}
msg := &email.Message{
To: to,
Subject: subject,
Body: body,
}
if len(htmlBody) > 0 && htmlBody[0] != "" {
msg.HTMLBody = htmlBody[0]
}
return e.Send(msg)
return e.SendEmail(to, subject, body, htmlBody...)
}
// getSMSClient 获取短信客户端（内部方法，延迟初始化）
@@ -95,20 +161,12 @@ func (f *Factory) getSMSClient() (*sms.SMS, error) {
return f.sms, nil
}
if f.cfg.SMS == nil {
return nil, fmt.Errorf("SMS config is nil")
}
s, err := sms.NewSMS(f.cfg.SMS)
if err != nil {
return nil, fmt.Errorf("failed to create SMS client: %w", err)
}
f.sms = s
return s, nil
f.sms = sms.NewSMS(f.cfg)
return f.sms, nil
}
// SendSMS 发送短信（黑盒模式）
// SendSMS 发送短信（黑盒模式，推荐使用）
// 自动使用配置文件中的阿里云短信配置发送短信
// phoneNumbers: 手机号列表
// templateParam: 模板参数（map或JSON字符串）
// templateCode: 模板代码（可选，如果为空使用配置中的模板代码）
@@ -117,17 +175,7 @@ func (f *Factory) SendSMS(phoneNumbers []string, templateParam interface{}, temp
if err != nil {
return nil, err
}
req := &sms.SendRequest{
PhoneNumbers: phoneNumbers,
TemplateParam: templateParam,
}
if len(templateCode) > 0 && templateCode[0] != "" {
req.TemplateCode = templateCode[0]
}
return s.Send(req)
return s.SendSMS(phoneNumbers, templateParam, templateCode...)
}
// getLogger 获取日志记录器（内部方法，延迟初始化）
@@ -153,7 +201,31 @@ func (f *Factory) getLogger() (*logger.Logger, error) {
return l, nil
}
// LogDebug 记录调试日志
// GetLogger 获取日志记录器对象（不推荐直接使用）
//
// ⚠️ 不推荐直接使用此方法，推荐使用黑盒方法：
// - LogDebug, LogInfo, LogWarn, LogError（记录简单日志）
// - LogDebugf, LogInfof, LogWarnf, LogErrorf（记录带字段的日志）
//
// 仅在以下高级场景时使用：
// - 需要调用 Close() 方法关闭logger
// - 需要使用logger的其他高级功能
//
// 示例（不推荐）：
//
// logger, _ := factory.GetLogger()
// defer logger.Close()
//
// 示例（推荐）：
//
// factory.LogInfo("用户登录成功")
// factory.LogErrorf(map[string]interface{}{"user_id": 123}, "登录失败")
func (f *Factory) GetLogger() (*logger.Logger, error) {
return f.getLogger()
}
// LogDebug 记录调试日志（黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogDebug(message string, args ...interface{}) {
@@ -174,7 +246,8 @@ func (f *Factory) LogDebug(message string, args ...interface{}) {
}
}
// LogDebugf 记录调试日志（带字段）
// LogDebugf 记录调试日志（带字段，黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// fields: 日志字段
// message: 日志消息
// args: 格式化参数（可选）
@@ -192,7 +265,8 @@ func (f *Factory) LogDebugf(fields map[string]interface{}, message string, args
l.Debugf(fields, message, args...)
}
// LogInfo 记录信息日志
// LogInfo 记录信息日志（黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogInfo(message string, args ...interface{}) {
@@ -213,7 +287,8 @@ func (f *Factory) LogInfo(message string, args ...interface{}) {
}
}
// LogInfof 记录信息日志（带字段）
// LogInfof 记录信息日志（带字段，黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// fields: 日志字段
// message: 日志消息
// args: 格式化参数（可选）
@@ -231,7 +306,8 @@ func (f *Factory) LogInfof(fields map[string]interface{}, message string, args .
l.Infof(fields, message, args...)
}
// LogWarn 记录警告日志
// LogWarn 记录警告日志（黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogWarn(message string, args ...interface{}) {
@@ -252,7 +328,8 @@ func (f *Factory) LogWarn(message string, args ...interface{}) {
}
}
// LogWarnf 记录警告日志（带字段）
// LogWarnf 记录警告日志（带字段，黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// fields: 日志字段
// message: 日志消息
// args: 格式化参数（可选）
@@ -270,7 +347,8 @@ func (f *Factory) LogWarnf(fields map[string]interface{}, message string, args .
l.Warnf(fields, message, args...)
}
// LogError 记录错误日志
// LogError 记录错误日志（黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// message: 日志消息
// args: 格式化参数（可选）
func (f *Factory) LogError(message string, args ...interface{}) {
@@ -291,7 +369,8 @@ func (f *Factory) LogError(message string, args ...interface{}) {
}
}
// LogErrorf 记录错误日志（带字段）
// LogErrorf 记录错误日志（带字段，黑盒模式，推荐使用）
// 自动使用配置文件中的logger配置
// fields: 日志字段
// message: 日志消息
// args: 格式化参数（可选）
@@ -362,9 +441,20 @@ func (f *Factory) getDatabase() (*gorm.DB, error) {
return db, nil
}
// GetDatabase 获取数据库连接对象（已初始化）
// GetDatabase 获取数据库连接对象（推荐使用）
// 返回已初始化的GORM数据库对象，可直接使用
// 注意：数据库保持返回GORM对象，因为GORM已经提供了很好的抽象
//
// ℹ️ 数据库操作保持使用 GORM 对象，因为：
// - 数据库操作非常复杂多样（查询、插入、更新、删除、事务等）
// - GORM 已经提供了很好的抽象和 API
// - 无需在 factory 中重复封装所有数据库方法
//
// 示例：
//
// db, _ := factory.GetDatabase()
// db.Find(&users)
// db.Create(&user)
// db.Transaction(func(tx *gorm.DB) error { ... })
func (f *Factory) GetDatabase() (*gorm.DB, error) {
return f.getDatabase()
}
@@ -430,7 +520,35 @@ func (f *Factory) getRedisClient() (*redis.Client, error) {
return client, nil
}
// RedisGet 获取Redis值（黑盒模式）
// GetRedisClient 获取Redis客户端对象（高级功能时使用）
// 返回已初始化的Redis客户端对象
//
// ℹ️ 推荐使用黑盒方法：
// - RedisGet, RedisSet, RedisDelete, RedisExists（常用操作）
//
// 仅在需要使用高级功能时获取客户端：
// - Hash 操作（HSet, HGet, HGetAll 等）
// - List 操作（LPush, RPush, LRange 等）
// - Set 操作（SAdd, SMembers 等）
// - ZSet 操作（ZAdd, ZRange 等）
// - 其他高级功能
//
// 示例（常用操作，推荐）：
//
// factory.RedisSet(ctx, "key", "value", time.Hour)
// value, _ := factory.RedisGet(ctx, "key")
//
// 示例（高级功能）：
//
// client, _ := factory.GetRedisClient()
// client.HSet(ctx, "user:1", "name", "Alice")
// client.LPush(ctx, "queue", "task1")
func (f *Factory) GetRedisClient() (*redis.Client, error) {
return f.getRedisClient()
}
// RedisGet 获取Redis值（黑盒模式，推荐使用）
// 自动使用配置文件中的Redis配置
// key: Redis键
func (f *Factory) RedisGet(ctx context.Context, key string) (string, error) {
client, err := f.getRedisClient()
@@ -449,7 +567,8 @@ func (f *Factory) RedisGet(ctx context.Context, key string) (string, error) {
return result, nil
}
// RedisSet 设置Redis值（黑盒模式）
// RedisSet 设置Redis值（黑盒模式，推荐使用）
// 自动使用配置文件中的Redis配置
// key: Redis键
// value: Redis值
// expiration: 过期时间（可选，0表示不过期）
@@ -472,7 +591,8 @@ func (f *Factory) RedisSet(ctx context.Context, key string, value interface{}, e
return nil
}
// RedisDelete 删除Redis键（黑盒模式）
// RedisDelete 删除Redis键（黑盒模式，推荐使用）
// 自动使用配置文件中的Redis配置
// keys: Redis键列表
func (f *Factory) RedisDelete(ctx context.Context, keys ...string) error {
if len(keys) == 0 {
@@ -492,7 +612,8 @@ func (f *Factory) RedisDelete(ctx context.Context, keys ...string) error {
return nil
}
// RedisExists 检查Redis键是否存在（黑盒模式）
// RedisExists 检查Redis键是否存在（黑盒模式，推荐使用）
// 自动使用配置文件中的Redis配置
// key: Redis键
func (f *Factory) RedisExists(ctx context.Context, key string) (bool, error) {
client, err := f.getRedisClient()
@@ -540,7 +661,8 @@ func (f *Factory) getStorage() (storage.Storage, error) {
return s, nil
}
// UploadFile 上传文件
// UploadFile 上传文件（黑盒模式，推荐使用）
// 自动根据配置选择存储类型（OSS 或 MinIO），无需关心内部实现
// ctx: 上下文
// objectKey: 对象键（文件路径）
// reader: 文件内容
@@ -567,8 +689,9 @@ func (f *Factory) UploadFile(ctx context.Context, objectKey string, reader io.Re
return url, nil
}
// GetFileURL 获取文件访问URL（Show方法）
// objectKey: 对象键
// GetFileURL 获取文件访问URL（黑盒模式，推荐使用）
// 自动根据配置选择存储类型，返回文件的访问URL
// objectKey: 对象键（文件路径）
// expires: 过期时间（秒），0表示永久有效
func (f *Factory) GetFileURL(objectKey string, expires int64) (string, error) {
s, err := f.getStorage()
@@ -578,3 +701,497 @@ func (f *Factory) GetFileURL(objectKey string, expires int64) (string, error) {
return s.GetURL(objectKey, expires)
}
// GetMiddlewareChain 获取配置好的中间件链（黑盒模式）
// 自动包含：Recovery、Logging、RateLimit（如果配置了）、CORS（如果配置了）、Timezone
// 返回已配置好的中间件链，可以通过 Append() 方法添加自定义中间件
//
// 示例1：直接使用
//
// chain := factory.GetMiddlewareChain()
// http.Handle("/api/users", chain.ThenFunc(handleUsers))
//
// 示例2：添加自定义中间件
//
// chain := factory.GetMiddlewareChain()
// chain.Append(yourCustomMiddleware1, yourCustomMiddleware2)
// http.Handle("/api/users", chain.ThenFunc(handleUsers))
func (f *Factory) GetMiddlewareChain() *middleware.Chain {
var middlewares []func(http.Handler) http.Handler
// 1. Recovery 中间件（必需，防止panic导致服务崩溃）
l, _ := f.getLogger() // 获取logger，如果失败会使用默认logger
middlewares = append(middlewares, middleware.Recovery(&middleware.RecoveryConfig{
Logger: l,
}))
// 2. Logging 中间件（必需，记录所有请求）
middlewares = append(middlewares, middleware.Logging(&middleware.LoggingConfig{
Logger: l,
}))
// 3. RateLimit 中间件（如果配置了限流）
if f.cfg != nil && f.cfg.RateLimit != nil {
if f.cfg.RateLimit.Enable {
// 从配置创建限流中间件
limiter := middleware.NewTokenBucketLimiter(
f.cfg.RateLimit.Rate,
time.Duration(f.cfg.RateLimit.Period)*time.Second,
)
var keyFunc func(r *http.Request) string
if f.cfg.RateLimit.ByIP {
keyFunc = func(r *http.Request) string {
return middleware.GetClientIP(r)
}
} else if f.cfg.RateLimit.ByUserID {
keyFunc = func(r *http.Request) string {
return r.Header.Get("X-User-ID")
}
}
middlewares = append(middlewares, middleware.RateLimit(&middleware.RateLimitConfig{
Limiter: limiter,
KeyFunc: keyFunc,
}))
}
}
// 4. CORS 中间件（如果配置了）
if f.cfg != nil && f.cfg.CORS != nil {
corsConfig := &middleware.CORSConfig{
AllowedOrigins: f.cfg.CORS.AllowedOrigins,
AllowedMethods: f.cfg.CORS.AllowedMethods,
AllowedHeaders: f.cfg.CORS.AllowedHeaders,
ExposedHeaders: f.cfg.CORS.ExposedHeaders,
AllowCredentials: f.cfg.CORS.AllowCredentials,
MaxAge: f.cfg.CORS.MaxAge,
}
middlewares = append(middlewares, middleware.CORS(corsConfig))
}
// 5. Timezone 中间件（必需，处理时区）
middlewares = append(middlewares, middleware.Timezone)
return middleware.NewChain(middlewares...)
}
// RunMigrations 执行数据库迁移（黑盒模式，推荐使用）
// 自动发现并执行指定目录下的所有迁移文件
// migrationsDir: 迁移文件目录（如 "migrations" 或 "scripts/sql"）
//
// 支持的文件命名格式：
// - 数字前缀: 01_init_schema.sql
// - 时间戳: 20240101000001_create_users.sql
// - 带.up后缀: 20240101000001_create_users.up.sql
//
// 示例：
//
// fac, _ := factory.NewFactoryFromFile("config.json")
// err := fac.RunMigrations("migrations")
// if err != nil {
// log.Fatal(err)
// }
func (f *Factory) RunMigrations(migrationsDir string) error {
// 获取数据库连接
db, err := f.getDatabase()
if err != nil {
return fmt.Errorf("failed to get database: %w", err)
}
// 创建迁移器（传入数据库类型，性能更好）
dbType := "mysql" // 默认值
if f.cfg.Database != nil && f.cfg.Database.Type != "" {
dbType = f.cfg.Database.Type
}
migrator := migration.NewMigratorWithType(db, dbType)
// 自动发现并加载迁移文件
migrations, err := migration.LoadMigrationsFromFiles(migrationsDir, "*.sql")
if err != nil {
return fmt.Errorf("failed to load migrations: %w", err)
}
if len(migrations) == 0 {
f.LogInfo("在目录 '%s' 中没有找到迁移文件", migrationsDir)
return nil
}
migrator.AddMigrations(migrations...)
// 执行迁移
if err := migrator.Up(); err != nil {
return fmt.Errorf("failed to run migrations: %w", err)
}
f.LogInfo("迁移执行成功: %d 个迁移文件", len(migrations))
return nil
}
// GetMigrationStatus 获取迁移状态（黑盒模式，推荐使用）
// migrationsDir: 迁移文件目录
// 返回迁移状态列表，包含版本、描述、是否已应用等信息
//
// 示例：
//
// fac, _ := factory.NewFactoryFromFile("config.json")
// status, err := fac.GetMigrationStatus("migrations")
// if err != nil {
// log.Fatal(err)
// }
// for _, s := range status {
// fmt.Printf("Version: %s, Applied: %v\n", s.Version, s.Applied)
// }
func (f *Factory) GetMigrationStatus(migrationsDir string) ([]migration.MigrationStatus, error) {
// 获取数据库连接
db, err := f.getDatabase()
if err != nil {
return nil, fmt.Errorf("failed to get database: %w", err)
}
// 创建迁移器（传入数据库类型，性能更好）
dbType := "mysql" // 默认值
if f.cfg.Database != nil && f.cfg.Database.Type != "" {
dbType = f.cfg.Database.Type
}
migrator := migration.NewMigratorWithType(db, dbType)
// 加载迁移文件
migrations, err := migration.LoadMigrationsFromFiles(migrationsDir, "*.sql")
if err != nil {
return nil, fmt.Errorf("failed to load migrations: %w", err)
}
migrator.AddMigrations(migrations...)
// 获取状态
status, err := migrator.Status()
if err != nil {
return nil, fmt.Errorf("failed to get migration status: %w", err)
}
return status, nil
}
// ========== HTTP响应方法（黑盒模式，推荐使用） ==========
//
// 这些方法直接调用 http 包的公共方法，保持低耦合。
// 推荐直接使用 factory.Success() 等方法，而不是通过 handler。
// Success 成功响应（黑盒模式，推荐使用）
// w: ResponseWriter
// data: 响应数据，可以为nil
// message: 响应消息（可选），如果为空则使用默认消息 "success"
//
// 示例：
//
// fac, _ := factory.NewFactoryFromFile("config.json")
// http.HandleFunc("/user", func(w http.ResponseWriter, r *http.Request) {
// fac.Success(w, user) // 只有数据
// fac.Success(w, user, "查询成功") // 数据+消息
// })
func (f *Factory) Success(w http.ResponseWriter, data interface{}, message ...string) {
commonhttp.Success(w, data, message...)
}
// SuccessPage 分页成功响应（黑盒模式，推荐使用）
// w: ResponseWriter
// list: 数据列表
// total: 总记录数
// page: 当前页码
// pageSize: 每页大小
// message: 响应消息（可选），如果为空则使用默认消息 "success"
func (f *Factory) SuccessPage(w http.ResponseWriter, list interface{}, total int64, page, pageSize int, message ...string) {
commonhttp.SuccessPage(w, list, total, page, pageSize, message...)
}
// Error 错误响应（黑盒模式，推荐使用）
// w: ResponseWriter
// code: 业务错误码，非0表示业务错误
// message: 错误消息
func (f *Factory) Error(w http.ResponseWriter, code int, message string) {
commonhttp.Error(w, code, message)
}
// SystemError 系统错误响应（返回HTTP 500）（黑盒模式，推荐使用）
// w: ResponseWriter
// message: 错误消息
func (f *Factory) SystemError(w http.ResponseWriter, message string) {
commonhttp.SystemError(w, message)
}
// ========== HTTP请求解析方法（黑盒模式，推荐使用） ==========
//
// 这些方法直接调用 http 包的公共方法，保持低耦合。
// 推荐直接使用 factory.ParseJSON()、factory.GetQuery() 等方法。
// ParseJSON 解析JSON请求体（黑盒模式，推荐使用）
// r: HTTP请求
// v: 目标结构体指针
//
// 示例：
//
// var req struct {
// Name string `json:"name"`
// }
// if err := fac.ParseJSON(r, &req); err != nil {
// fac.Error(w, 400, "请求参数解析失败")
// return
// }
func (f *Factory) ParseJSON(r *http.Request, v interface{}) error {
return commonhttp.ParseJSON(r, v)
}
// ParsePaginationRequest 从请求中解析分页参数（黑盒模式，推荐使用）
// r: HTTP请求
// 支持从查询参数和form表单中解析
// 优先级：查询参数 > form表单
//
// 示例：
//
// pagination := fac.ParsePaginationRequest(r)
// page := pagination.GetPage()
// pageSize := pagination.GetSize()
func (f *Factory) ParsePaginationRequest(r *http.Request) *PaginationRequest {
return commonhttp.ParsePaginationRequest(r)
}
// GetQuery 获取查询参数（字符串）（黑盒模式，推荐使用）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func (f *Factory) GetQuery(r *http.Request, key, defaultValue string) string {
return commonhttp.GetQuery(r, key, defaultValue)
}
// GetQueryInt 获取整数查询参数（黑盒模式，推荐使用）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func (f *Factory) GetQueryInt(r *http.Request, key string, defaultValue int) int {
return commonhttp.GetQueryInt(r, key, defaultValue)
}
// GetQueryInt64 获取int64查询参数（黑盒模式，推荐使用）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func (f *Factory) GetQueryInt64(r *http.Request, key string, defaultValue int64) int64 {
return commonhttp.GetQueryInt64(r, key, defaultValue)
}
// GetQueryBool 获取布尔查询参数（黑盒模式，推荐使用）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func (f *Factory) GetQueryBool(r *http.Request, key string, defaultValue bool) bool {
return commonhttp.GetQueryBool(r, key, defaultValue)
}
// GetQueryFloat64 获取float64查询参数（黑盒模式，推荐使用）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func (f *Factory) GetQueryFloat64(r *http.Request, key string, defaultValue float64) float64 {
return commonhttp.GetQueryFloat64(r, key, defaultValue)
}
// GetFormValue 获取表单值（字符串）（黑盒模式，推荐使用）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func (f *Factory) GetFormValue(r *http.Request, key, defaultValue string) string {
return commonhttp.GetFormValue(r, key, defaultValue)
}
// GetFormInt 获取表单整数（黑盒模式，推荐使用）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func (f *Factory) GetFormInt(r *http.Request, key string, defaultValue int) int {
return commonhttp.GetFormInt(r, key, defaultValue)
}
// GetFormInt64 获取表单int64（黑盒模式，推荐使用）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func (f *Factory) GetFormInt64(r *http.Request, key string, defaultValue int64) int64 {
return commonhttp.GetFormInt64(r, key, defaultValue)
}
// GetFormBool 获取表单布尔值（黑盒模式，推荐使用）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func (f *Factory) GetFormBool(r *http.Request, key string, defaultValue bool) bool {
return commonhttp.GetFormBool(r, key, defaultValue)
}
// GetHeader 获取请求头（黑盒模式，推荐使用）
// r: HTTP请求
// key: 请求头名称
// defaultValue: 默认值
func (f *Factory) GetHeader(r *http.Request, key, defaultValue string) string {
return commonhttp.GetHeader(r, key, defaultValue)
}
// GetTimezone 从请求的context中获取时区（黑盒模式，推荐使用）
// r: HTTP请求
// 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
// 如果未设置，返回默认时区 AsiaShanghai
func (f *Factory) GetTimezone(r *http.Request) string {
return commonhttp.GetTimezone(r)
}
// ========== Tools工具方法（黑盒模式，推荐使用） ==========
//
// 这些方法直接调用 tools 包的公共方法，保持低耦合。
// factory 只负责方法暴露，具体业务在 tools 包中实现。
// ========== Version 版本工具 ==========
// GetVersion 获取版本号（黑盒模式，推荐使用）
// 优先从环境变量 DOCKER_TAG 或 VERSION 中读取
// 如果没有设置环境变量，则使用默认版本号
func (f *Factory) GetVersion() string {
return tools.GetVersion()
}
// ========== Money 金额工具 ==========
// GetMoneyCalculator 获取金额计算器（黑盒模式，推荐使用）
// 返回金额计算器实例，可用于金额计算操作
func (f *Factory) GetMoneyCalculator() *tools.MoneyCalculator {
return tools.NewMoneyCalculator()
}
// YuanToCents 元转分（黑盒模式，推荐使用）
func (f *Factory) YuanToCents(yuan float64) int64 {
return tools.YuanToCents(yuan)
}
// CentsToYuan 分转元（黑盒模式，推荐使用）
func (f *Factory) CentsToYuan(cents int64) float64 {
return tools.CentsToYuan(cents)
}
// FormatYuan 格式化显示金额（分转元，保留2位小数）（黑盒模式，推荐使用）
func (f *Factory) FormatYuan(cents int64) string {
return tools.FormatYuan(cents)
}
// ========== DateTime 日期时间工具 ==========
// Now 获取当前时间（使用指定时区）（黑盒模式，推荐使用）
func (f *Factory) Now(timezone ...string) time.Time {
return tools.Now(timezone...)
}
// ParseDateTime 解析日期时间字符串（2006-01-02 15:04:05）（黑盒模式，推荐使用）
func (f *Factory) ParseDateTime(value string, timezone ...string) (time.Time, error) {
return tools.ParseDateTime(value, timezone...)
}
// ParseDate 解析日期字符串（2006-01-02）（黑盒模式，推荐使用）
func (f *Factory) ParseDate(value string, timezone ...string) (time.Time, error) {
return tools.ParseDate(value, timezone...)
}
// FormatDateTime 格式化日期时间（2006-01-02 15:04:05）（黑盒模式，推荐使用）
func (f *Factory) FormatDateTime(t time.Time, timezone ...string) string {
return tools.FormatDateTime(t, timezone...)
}
// FormatDate 格式化日期（2006-01-02）（黑盒模式，推荐使用）
func (f *Factory) FormatDate(t time.Time, timezone ...string) string {
return tools.FormatDate(t, timezone...)
}
// FormatTime 格式化时间（15:04:05）（黑盒模式，推荐使用）
func (f *Factory) FormatTime(t time.Time, timezone ...string) string {
return tools.FormatTime(t, timezone...)
}
// ToUnix 转换为Unix时间戳（黑盒模式，推荐使用）
func (f *Factory) ToUnix(t time.Time) int64 {
return tools.ToUnix(t)
}
// FromUnix 从Unix时间戳创建时间（黑盒模式，推荐使用）
func (f *Factory) FromUnix(sec int64, timezone ...string) time.Time {
return tools.FromUnix(sec, timezone...)
}
// ToUnixMilli 转换为Unix毫秒时间戳（黑盒模式，推荐使用）
func (f *Factory) ToUnixMilli(t time.Time) int64 {
return tools.ToUnixMilli(t)
}
// FromUnixMilli 从Unix毫秒时间戳创建时间（黑盒模式，推荐使用）
func (f *Factory) FromUnixMilli(msec int64, timezone ...string) time.Time {
return tools.FromUnixMilli(msec, timezone...)
}
// AddDays 添加天数（黑盒模式，推荐使用）
func (f *Factory) AddDays(t time.Time, days int) time.Time {
return tools.AddDays(t, days)
}
// AddMonths 添加月数（黑盒模式，推荐使用）
func (f *Factory) AddMonths(t time.Time, months int) time.Time {
return tools.AddMonths(t, months)
}
// AddYears 添加年数（黑盒模式，推荐使用）
func (f *Factory) AddYears(t time.Time, years int) time.Time {
return tools.AddYears(t, years)
}
// StartOfDay 获取一天的开始时间（00:00:00）（黑盒模式，推荐使用）
func (f *Factory) StartOfDay(t time.Time, timezone ...string) time.Time {
return tools.StartOfDay(t, timezone...)
}
// EndOfDay 获取一天的结束时间（23:59:59.999999999）（黑盒模式，推荐使用）
func (f *Factory) EndOfDay(t time.Time, timezone ...string) time.Time {
return tools.EndOfDay(t, timezone...)
}
// StartOfMonth 获取月份的开始时间（黑盒模式，推荐使用）
func (f *Factory) StartOfMonth(t time.Time, timezone ...string) time.Time {
return tools.StartOfMonth(t, timezone...)
}
// EndOfMonth 获取月份的结束时间（黑盒模式，推荐使用）
func (f *Factory) EndOfMonth(t time.Time, timezone ...string) time.Time {
return tools.EndOfMonth(t, timezone...)
}
// StartOfYear 获取年份的开始时间（黑盒模式，推荐使用）
func (f *Factory) StartOfYear(t time.Time, timezone ...string) time.Time {
return tools.StartOfYear(t, timezone...)
}
// EndOfYear 获取年份的结束时间（黑盒模式，推荐使用）
func (f *Factory) EndOfYear(t time.Time, timezone ...string) time.Time {
return tools.EndOfYear(t, timezone...)
}
// DiffDays 计算两个时间之间的天数差（黑盒模式，推荐使用）
func (f *Factory) DiffDays(t1, t2 time.Time) int {
return tools.DiffDays(t1, t2)
}
// DiffHours 计算两个时间之间的小时差（黑盒模式，推荐使用）
func (f *Factory) DiffHours(t1, t2 time.Time) int64 {
return tools.DiffHours(t1, t2)
}
// DiffMinutes 计算两个时间之间的分钟差（黑盒模式，推荐使用）
func (f *Factory) DiffMinutes(t1, t2 time.Time) int64 {
return tools.DiffMinutes(t1, t2)
}
// DiffSeconds 计算两个时间之间的秒数差（黑盒模式，推荐使用）
func (f *Factory) DiffSeconds(t1, t2 time.Time) int64 {
return tools.DiffSeconds(t1, t2)
}

279
http/handler.go
View File

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

193
http/request.go
View File

@@ -1,8 +1,12 @@
package http
import (
"encoding/json"
"io"
"net/http"
"strconv"
"git.toowon.com/jimmy/go-common/middleware"
)
// getQueryInt 获取整数查询参数（内部方法，供ParsePaginationRequest使用）
@@ -114,3 +118,192 @@ func ParsePaginationRequest(r *http.Request) *PaginationRequest {
return req
}
// ========== 请求解析公共方法 ==========
// ParseJSON 解析JSON请求体（公共方法）
// r: HTTP请求
// v: 目标结构体指针
func ParseJSON(r *http.Request, v interface{}) error {
body, err := io.ReadAll(r.Body)
if err != nil {
return err
}
defer r.Body.Close()
if len(body) == 0 {
return nil
}
return json.Unmarshal(body, v)
}
// GetQuery 获取查询参数（公共方法）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func GetQuery(r *http.Request, key, defaultValue string) string {
value := r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
return value
}
// GetQueryInt 获取整数查询参数（公共方法）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func GetQueryInt(r *http.Request, key string, defaultValue int) int {
value := r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.Atoi(value)
if err != nil {
return defaultValue
}
return intValue
}
// GetQueryInt64 获取int64查询参数（公共方法）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func GetQueryInt64(r *http.Request, key string, defaultValue int64) int64 {
value := r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.ParseInt(value, 10, 64)
if err != nil {
return defaultValue
}
return intValue
}
// GetQueryBool 获取布尔查询参数（公共方法）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func GetQueryBool(r *http.Request, key string, defaultValue bool) bool {
value := r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
boolValue, err := strconv.ParseBool(value)
if err != nil {
return defaultValue
}
return boolValue
}
// GetQueryFloat64 获取float64查询参数（公共方法）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func GetQueryFloat64(r *http.Request, key string, defaultValue float64) float64 {
value := r.URL.Query().Get(key)
if value == "" {
return defaultValue
}
floatValue, err := strconv.ParseFloat(value, 64)
if err != nil {
return defaultValue
}
return floatValue
}
// GetFormValue 获取表单值（公共方法）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func GetFormValue(r *http.Request, key, defaultValue string) string {
value := r.FormValue(key)
if value == "" {
return defaultValue
}
return value
}
// GetFormInt 获取表单整数（公共方法）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func GetFormInt(r *http.Request, key string, defaultValue int) int {
value := r.FormValue(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.Atoi(value)
if err != nil {
return defaultValue
}
return intValue
}
// GetFormInt64 获取表单int64（公共方法）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func GetFormInt64(r *http.Request, key string, defaultValue int64) int64 {
value := r.FormValue(key)
if value == "" {
return defaultValue
}
intValue, err := strconv.ParseInt(value, 10, 64)
if err != nil {
return defaultValue
}
return intValue
}
// GetFormBool 获取表单布尔值（公共方法）
// r: HTTP请求
// key: 参数名
// defaultValue: 默认值
func GetFormBool(r *http.Request, key string, defaultValue bool) bool {
value := r.FormValue(key)
if value == "" {
return defaultValue
}
boolValue, err := strconv.ParseBool(value)
if err != nil {
return defaultValue
}
return boolValue
}
// GetHeader 获取请求头（公共方法）
// r: HTTP请求
// key: 请求头名称
// defaultValue: 默认值
func GetHeader(r *http.Request, key, defaultValue string) string {
value := r.Header.Get(key)
if value == "" {
return defaultValue
}
return value
}
// GetTimezone 从请求的context中获取时区（公共方法）
// r: HTTP请求
// 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
// 如果未设置，返回默认时区 AsiaShanghai
func GetTimezone(r *http.Request) string {
return middleware.GetTimezoneFromContext(r.Context())
}

57
http/response.go
View File

@@ -30,7 +30,7 @@ type PageData struct {
PageSize int `json:"pageSize"` // 每页大小
}
// writeJSON 写入JSON响应（内部方法）
// writeJSON 写入JSON响应（公共方法）
// httpCode: HTTP状态码（200表示正常，500表示系统错误等）
// code: 业务状态码（0表示成功，非0表示业务错误）
// message: 响应消息
@@ -48,3 +48,58 @@ func writeJSON(w http.ResponseWriter, httpCode, code int, message string, data i
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)
}

320
logger/logger.go
View File

@@ -6,10 +6,36 @@ import (
"log"
"os"
"path/filepath"
"sync"
"git.toowon.com/jimmy/go-common/config"
)
var (
// defaultLogger 全局默认日志记录器
// 用于中间件和其他需要快速日志记录的场景
defaultLogger *Logger
defaultMux sync.RWMutex
)
func init() {
// 初始化默认logger（同步模式，输出到stdout）
var err error
defaultLogger, err = NewLogger(nil)
if err != nil {
// 如果初始化失败，使用nil，后续会降级到标准输出
defaultLogger = nil
}
}
// logMessage 异步日志消息结构
type logMessage struct {
level string // debug, info, warn, error
format string
args []interface{}
fields map[string]interface{} // 用于带字段的日志
}
// Logger 日志记录器
type Logger struct {
infoLog *log.Logger
@@ -17,6 +43,14 @@ type Logger struct {
warnLog *log.Logger
debugLog *log.Logger
config *config.LoggerConfig
// 异步相关字段
async bool // 是否异步模式
logChan chan *logMessage // 异步日志channel
done chan struct{} // 用于优雅关闭
wg sync.WaitGroup // 等待所有日志写入完成
closed bool // 是否已关闭
closeMux sync.RWMutex // 保护closed字段
}
// NewLogger 创建日志记录器
@@ -24,9 +58,11 @@ func NewLogger(cfg *config.LoggerConfig) (*Logger, error) {
if cfg == nil {
// 使用默认配置
cfg = &config.LoggerConfig{
Level: "info",
Output: "stdout",
FilePath: "",
Level: "info",
Output: "stdout",
FilePath: "",
Async: false, // 默认同步
BufferSize: 1000, // 默认缓冲区大小
}
}
@@ -37,6 +73,9 @@ func NewLogger(cfg *config.LoggerConfig) (*Logger, error) {
if cfg.Output == "" {
cfg.Output = "stdout"
}
if cfg.BufferSize <= 0 {
cfg.BufferSize = 1000 // 默认缓冲区大小
}
// 创建输出目标
var writers []io.Writer
@@ -89,6 +128,7 @@ func NewLogger(cfg *config.LoggerConfig) (*Logger, error) {
// 创建日志记录器
logger := &Logger{
config: cfg,
async: cfg.Async,
}
// 根据日志级别创建不同的logger
@@ -106,39 +146,152 @@ func NewLogger(cfg *config.LoggerConfig) (*Logger, error) {
}
}
// 如果启用异步模式，启动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() {
defer l.wg.Done()
for {
select {
case msg := <-l.logChan:
if msg == nil {
// channel已关闭，退出
return
}
l.writeLog(msg)
case <-l.done:
// 收到关闭信号，处理完剩余日志后退出
for {
select {
case msg := <-l.logChan:
if msg == nil {
return
}
l.writeLog(msg)
default:
return
}
}
}
}
}
// 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 {
l.closeMux.RLock()
defer l.closeMux.RUnlock()
return l.closed
}
// setClosed 设置logger为已关闭状态
func (l *Logger) setClosed() {
l.closeMux.Lock()
defer l.closeMux.Unlock()
l.closed = true
}
// log 内部日志方法，根据模式选择同步或异步
func (l *Logger) log(level string, format string, args []interface{}, fields map[string]interface{}) {
// 如果已关闭，直接返回
if l.isClosed() {
return
}
// 如果是异步模式，发送到channel
if l.async {
// 检查channel是否已关闭
select {
case l.logChan <- &logMessage{
level: level,
format: format,
args: args,
fields: fields,
}:
// 成功发送
default:
// channel已满或已关闭，同步写入（降级处理）
l.writeLog(&logMessage{
level: level,
format: format,
args: args,
fields: fields,
})
}
} else {
// 同步模式，直接写入
l.writeLog(&logMessage{
level: level,
format: format,
args: args,
fields: fields,
})
}
}
// Debug 记录调试日志
func (l *Logger) Debug(format string, v ...interface{}) {
if l.debugLog != nil {
l.debugLog.Printf(format, v...)
}
l.log("debug", format, v, nil)
}
// Info 记录信息日志
func (l *Logger) Info(format string, v ...interface{}) {
if l.infoLog != nil {
l.infoLog.Printf(format, v...)
}
l.log("info", format, v, nil)
}
// Warn 记录警告日志
func (l *Logger) Warn(format string, v ...interface{}) {
if l.warnLog != nil {
l.warnLog.Printf(format, v...)
}
l.log("warn", format, v, nil)
}
// Error 记录错误日志
func (l *Logger) Error(format string, v ...interface{}) {
if l.errorLog != nil {
l.errorLog.Printf(format, v...)
}
l.log("error", format, v, nil)
}
// Fatal 记录致命错误日志并退出程序
// Fatal 记录致命错误日志并退出程序（始终同步）
func (l *Logger) Fatal(format string, v ...interface{}) {
// Fatal必须同步执行，确保日志写入后再退出
if l.errorLog != nil {
l.errorLog.Fatalf(format, v...)
} else {
@@ -146,8 +299,9 @@ func (l *Logger) Fatal(format string, v ...interface{}) {
}
}
// Panic 记录恐慌日志并触发panic
// Panic 记录恐慌日志并触发panic（始终同步）
func (l *Logger) Panic(format string, v ...interface{}) {
// Panic必须同步执行，确保日志写入后再panic
if l.errorLog != nil {
l.errorLog.Panicf(format, v...)
} else {
@@ -175,33 +329,135 @@ func formatFields(fields map[string]interface{}) string {
// Debugf 记录调试日志（带字段）
func (l *Logger) Debugf(fields map[string]interface{}, format string, v ...interface{}) {
if l.debugLog != nil {
fieldStr := formatFields(fields)
l.debugLog.Printf(fieldStr+format, v...)
}
l.log("debug", format, v, fields)
}
// Infof 记录信息日志（带字段）
func (l *Logger) Infof(fields map[string]interface{}, format string, v ...interface{}) {
if l.infoLog != nil {
fieldStr := formatFields(fields)
l.infoLog.Printf(fieldStr+format, v...)
}
l.log("info", format, v, fields)
}
// Warnf 记录警告日志（带字段）
func (l *Logger) Warnf(fields map[string]interface{}, format string, v ...interface{}) {
if l.warnLog != nil {
fieldStr := formatFields(fields)
l.warnLog.Printf(fieldStr+format, v...)
}
l.log("warn", format, v, fields)
}
// Errorf 记录错误日志（带字段）
func (l *Logger) Errorf(fields map[string]interface{}, format string, v ...interface{}) {
if l.errorLog != nil {
fieldStr := formatFields(fields)
l.errorLog.Printf(fieldStr+format, v...)
l.log("error", format, v, fields)
}
// Close 优雅关闭logger（仅异步模式需要）
// 等待所有日志写入完成后再返回
func (l *Logger) Close() error {
if !l.async {
// 同步模式不需要关闭
return nil
}
// 检查是否已关闭
if l.isClosed() {
return nil
}
// 设置关闭状态
l.setClosed()
// 发送关闭信号
close(l.done)
// 关闭channel（会触发processLogs退出）
close(l.logChan)
// 等待所有日志写入完成
l.wg.Wait()
return nil
}
// ========== 全局默认Logger相关方法 ==========
// SetDefaultLogger 设置全局默认logger
// 用于在应用启动时统一配置logger
func SetDefaultLogger(log *Logger) {
defaultMux.Lock()
defer defaultMux.Unlock()
// 如果之前有logger，先关闭它
if defaultLogger != nil {
defaultLogger.Close()
}
defaultLogger = log
}
// GetDefaultLogger 获取全局默认logger
func GetDefaultLogger() *Logger {
defaultMux.RLock()
defer defaultMux.RUnlock()
return defaultLogger
}
// Default 全局日志方法 - Debug
func Default() *Logger {
return GetDefaultLogger()
}
// ========== 全局便捷日志方法 ==========
// 以下方法使用全局默认logger，方便快速记录日志
// Debug 使用全局logger记录调试日志
func Debug(format string, v ...interface{}) {
if log := GetDefaultLogger(); log != nil {
log.Debug(format, v...)
}
}
// Info 使用全局logger记录信息日志
func Info(format string, v ...interface{}) {
if log := GetDefaultLogger(); log != nil {
log.Info(format, v...)
}
}
// Warn 使用全局logger记录警告日志
func Warn(format string, v ...interface{}) {
if log := GetDefaultLogger(); log != nil {
log.Warn(format, v...)
}
}
// Error 使用全局logger记录错误日志
func Error(format string, v ...interface{}) {
if log := GetDefaultLogger(); log != nil {
log.Error(format, v...)
}
}
// 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...)
}
}

30
middleware/cors.go
View File

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

221
middleware/logging.go Normal file
View File

@@ -0,0 +1,221 @@
package middleware
import (
"net/http"
"strconv"
"time"
"git.toowon.com/jimmy/go-common/logger"
)
// responseWriter 包装 http.ResponseWriter 以捕获状态码和响应大小
type responseWriter struct {
http.ResponseWriter
statusCode int
size int
}
func (rw *responseWriter) WriteHeader(statusCode int) {
rw.statusCode = 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 日志中间件配置
type LoggingConfig struct {
// Logger 日志记录器（可选，如果为nil则使用默认logger）
Logger *logger.Logger
// SkipPaths 跳过记录的路径列表（如健康检查接口）
SkipPaths []string
// LogRequestBody 是否记录请求体（谨慎使用，可能影响性能）
LogRequestBody bool
// LogResponseBody 是否记录响应体（谨慎使用，可能影响性能和内存）
LogResponseBody bool
}
// Logging HTTP请求日志中间件
// 记录每个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 {
// 如果没有配置，使用默认配置
if config == nil {
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 http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 检查是否跳过此路径
if shouldSkipPath(r.URL.Path, config.SkipPaths) {
next.ServeHTTP(w, r)
return
}
// 记录开始时间
startTime := time.Now()
// 包装 ResponseWriter 以捕获状态码和响应大小
rw := &responseWriter{
ResponseWriter: w,
statusCode: http.StatusOK, // 默认200
size: 0,
}
// 处理请求
next.ServeHTTP(rw, r)
// 计算处理时间
duration := time.Since(startTime)
// 记录日志
logHTTPRequest(config.Logger, r, rw, duration)
})
}
}
// shouldSkipPath 检查是否应该跳过该路径
func shouldSkipPath(path string, skipPaths []string) bool {
for _, skipPath := range skipPaths {
if path == skipPath {
return true
}
}
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
}

286
middleware/ratelimit.go Normal file
View File

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

149
middleware/recovery.go Normal file
View File

@@ -0,0 +1,149 @@
package middleware
import (
"fmt"
"net/http"
"runtime/debug"
"git.toowon.com/jimmy/go-common/logger"
)
// RecoveryConfig Recovery中间件配置
type RecoveryConfig struct {
// Logger 日志记录器（可选，如果为nil则使用默认logger）
Logger *logger.Logger
// EnableStackTrace 是否在日志中包含堆栈跟踪
EnableStackTrace bool
// CustomHandler 自定义错误处理函数（可选）
// 如果设置了，会在记录日志后调用此函数
// 可以用于自定义错误响应格式
CustomHandler func(w http.ResponseWriter, r *http.Request, err interface{})
}
// Recovery Panic恢复中间件
// 捕获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 {
// 如果没有配置，使用默认配置
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 http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
defer func() {
if err := recover(); err != nil {
// 记录panic信息
logPanic(config.Logger, r, err, config.EnableStackTrace)
// 如果提供了自定义处理函数，调用它
if config.CustomHandler != nil {
config.CustomHandler(w, r, err)
return
}
// 默认错误响应
http.Error(w, "Internal Server Error", http.StatusInternalServerError)
}
}()
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,
})
}

11
middleware/timezone.go
View File

@@ -4,7 +4,7 @@ import (
"context"
"net/http"
"git.toowon.com/jimmy/go-common/datetime"
"git.toowon.com/jimmy/go-common/tools"
)
// TimezoneKey context中存储时区的key
@@ -14,7 +14,7 @@ type timezoneKey struct{}
const TimezoneHeaderName = "X-Timezone"
// DefaultTimezone 默认时区
const DefaultTimezone = datetime.AsiaShanghai
const DefaultTimezone = tools.AsiaShanghai
// GetTimezoneFromContext 从context中获取时区
func GetTimezoneFromContext(ctx context.Context) string {
@@ -38,7 +38,7 @@ func Timezone(next http.Handler) http.Handler {
}
// 验证时区是否有效
if _, err := datetime.GetLocation(timezone); err != nil {
if _, err := tools.GetLocation(timezone); err != nil {
// 如果时区无效，使用默认时区
timezone = DefaultTimezone
}
@@ -53,7 +53,7 @@ func Timezone(next http.Handler) http.Handler {
// defaultTimezone: 默认时区，如果未指定则使用 AsiaShanghai
func TimezoneWithDefault(defaultTimezone string) func(http.Handler) http.Handler {
// 验证默认时区是否有效
if _, err := datetime.GetLocation(defaultTimezone); err != nil {
if _, err := tools.GetLocation(defaultTimezone); err != nil {
defaultTimezone = DefaultTimezone
}
@@ -68,7 +68,7 @@ func TimezoneWithDefault(defaultTimezone string) func(http.Handler) http.Handler
}
// 验证时区是否有效
if _, err := datetime.GetLocation(timezone); err != nil {
if _, err := tools.GetLocation(timezone); err != nil {
// 如果时区无效，使用默认时区
timezone = defaultTimezone
}
@@ -79,4 +79,3 @@ func TimezoneWithDefault(defaultTimezone string) func(http.Handler) http.Handler
})
}
}

222
migration/helper.go Normal file
View File

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

398
migration/migration.go
View File

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

269
sms/sms.go
View File

@@ -16,59 +16,6 @@ import (
"git.toowon.com/jimmy/go-common/config"
)
// SMS 短信发送器
type SMS struct {
config *config.SMSConfig
}
// NewSMS 创建短信发送器
func NewSMS(cfg *config.SMSConfig) (*SMS, error) {
if cfg == nil {
return nil, fmt.Errorf("SMS config is nil")
}
if cfg.AccessKeyID == "" {
return nil, fmt.Errorf("AccessKeyID is required")
}
if cfg.AccessKeySecret == "" {
return nil, fmt.Errorf("AccessKeySecret is required")
}
if cfg.SignName == "" {
return nil, fmt.Errorf("SignName is required")
}
// 设置默认值
if cfg.Region == "" {
cfg.Region = "cn-hangzhou"
}
if cfg.Timeout == 0 {
cfg.Timeout = 10
}
return &SMS{
config: cfg,
}, nil
}
// SendRequest 发送短信请求
type SendRequest struct {
// PhoneNumbers 手机号列表
PhoneNumbers []string
// TemplateCode 模板代码（如果为空，使用配置中的模板代码）
TemplateCode string
// TemplateParam 模板参数（可以是map或JSON字符串）
// 如果是map，会自动转换为JSON字符串
// 如果是string，直接使用（必须是有效的JSON字符串）
TemplateParam interface{}
// SignName 签名（如果为空，使用配置中的签名）
SignName string
}
// SendResponse 发送短信响应
type SendResponse struct {
// RequestID 请求ID
@@ -84,48 +31,123 @@ type SendResponse struct {
BizID string `json:"BizId"`
}
// SendRaw 发送原始请求（允许外部完全控制请求参数）
// params: 请求参数map，工具只负责添加必要的系统参数（如签名、时间戳等）并发送
func (s *SMS) SendRaw(params map[string]string) (*SendResponse, error) {
if params == nil {
params = make(map[string]string)
// SMS 短信发送器
type SMS struct {
config *config.SMSConfig
}
// NewSMS 创建短信发送器
func NewSMS(cfg *config.Config) *SMS {
if cfg == nil || cfg.SMS == nil {
return &SMS{config: nil}
}
return &SMS{config: cfg.SMS}
}
// getSMSConfig 获取短信配置（内部方法）
func (s *SMS) getSMSConfig() (*config.SMSConfig, error) {
if s.config == nil {
return nil, fmt.Errorf("SMS config is nil")
}
// 确保必要的系统参数存在
if params["Action"] == "" {
params["Action"] = "SendSms"
if s.config.AccessKeyID == "" {
return nil, fmt.Errorf("AccessKeyID is required")
}
if params["Version"] == "" {
params["Version"] = "2017-05-25"
if s.config.AccessKeySecret == "" {
return nil, fmt.Errorf("AccessKeySecret is required")
}
if params["RegionId"] == "" {
params["RegionId"] = s.config.Region
if s.config.SignName == "" {
return nil, fmt.Errorf("SignName is required")
}
if params["AccessKeyId"] == "" {
params["AccessKeyId"] = s.config.AccessKeyID
// 设置默认值
if s.config.Region == "" {
s.config.Region = "cn-hangzhou"
}
if params["Format"] == "" {
params["Format"] = "JSON"
if s.config.Timeout == 0 {
s.config.Timeout = 10
}
if params["SignatureMethod"] == "" {
params["SignatureMethod"] = "HMAC-SHA1"
return s.config, nil
}
// SendSMS 发送短信
// phoneNumbers: 手机号列表
// templateParam: 模板参数（map或JSON字符串）
// templateCode: 模板代码（可选，如果为空使用配置中的模板代码）
func (s *SMS) SendSMS(phoneNumbers []string, templateParam interface{}, templateCode ...string) (*SendResponse, error) {
cfg, err := s.getSMSConfig()
if err != nil {
return nil, err
}
if params["SignatureVersion"] == "" {
params["SignatureVersion"] = "1.0"
if len(phoneNumbers) == 0 {
return nil, fmt.Errorf("phone numbers are required")
}
if params["SignatureNonce"] == "" {
params["SignatureNonce"] = fmt.Sprint(time.Now().UnixNano())
// 使用配置中的模板代码（如果请求中未指定）
templateCodeValue := ""
if len(templateCode) > 0 && templateCode[0] != "" {
templateCodeValue = templateCode[0]
} else {
templateCodeValue = cfg.TemplateCode
}
if params["Timestamp"] == "" {
params["Timestamp"] = time.Now().UTC().Format("2006-01-02T15:04:05Z")
if templateCodeValue == "" {
return nil, fmt.Errorf("template code is required")
}
signName := cfg.SignName
// 处理模板参数
var templateParamJSON string
if templateParam != nil {
switch v := templateParam.(type) {
case string:
// 直接使用字符串（必须是有效的JSON）
templateParamJSON = v
case map[string]string:
// 转换为JSON字符串
paramBytes, err := json.Marshal(v)
if err != nil {
return nil, fmt.Errorf("failed to marshal template param: %w", err)
}
templateParamJSON = string(paramBytes)
default:
// 尝试JSON序列化
paramBytes, err := json.Marshal(v)
if err != nil {
return nil, fmt.Errorf("failed to marshal template param: %w", err)
}
templateParamJSON = string(paramBytes)
}
} else {
templateParamJSON = "{}"
}
// 构建请求参数
params := make(map[string]string)
params["Action"] = "SendSms"
params["Version"] = "2017-05-25"
params["RegionId"] = cfg.Region
params["AccessKeyId"] = cfg.AccessKeyID
params["Format"] = "JSON"
params["SignatureMethod"] = "HMAC-SHA1"
params["SignatureVersion"] = "1.0"
params["SignatureNonce"] = fmt.Sprint(time.Now().UnixNano())
params["Timestamp"] = time.Now().UTC().Format("2006-01-02T15:04:05Z")
params["PhoneNumbers"] = strings.Join(phoneNumbers, ",")
params["SignName"] = signName
params["TemplateCode"] = templateCodeValue
params["TemplateParam"] = templateParamJSON
// 计算签名
signature := s.calculateSignature(params, "POST")
signature := s.calculateSignature(params, "POST", cfg.AccessKeySecret)
params["Signature"] = signature
// 构建请求URL
endpoint := s.config.Endpoint
endpoint := cfg.Endpoint
if endpoint == "" {
endpoint = "https://dysmsapi.aliyuncs.com"
}
@@ -145,7 +167,7 @@ func (s *SMS) SendRaw(params map[string]string) (*SendResponse, error) {
httpReq.Header.Set("Accept", "application/json")
client := &http.Client{
Timeout: time.Duration(s.config.Timeout) * time.Second,
Timeout: time.Duration(cfg.Timeout) * time.Second,
}
resp, err := client.Do(httpReq)
@@ -174,70 +196,8 @@ func (s *SMS) SendRaw(params map[string]string) (*SendResponse, error) {
return &sendResp, nil
}
// Send 发送短信（使用SendRequest结构）
// 注意：如果需要完全控制请求参数，请使用SendRaw方法
func (s *SMS) Send(req *SendRequest) (*SendResponse, error) {
if req == nil {
return nil, fmt.Errorf("request is nil")
}
if len(req.PhoneNumbers) == 0 {
return nil, fmt.Errorf("phone numbers are required")
}
// 使用配置中的模板代码和签名（如果请求中未指定）
templateCode := req.TemplateCode
if templateCode == "" {
templateCode = s.config.TemplateCode
}
if templateCode == "" {
return nil, fmt.Errorf("template code is required")
}
signName := req.SignName
if signName == "" {
signName = s.config.SignName
}
// 处理模板参数
var templateParamJSON string
if req.TemplateParam != nil {
switch v := req.TemplateParam.(type) {
case string:
// 直接使用字符串（必须是有效的JSON）
templateParamJSON = v
case map[string]string:
// 转换为JSON字符串
paramBytes, err := json.Marshal(v)
if err != nil {
return nil, fmt.Errorf("failed to marshal template param: %w", err)
}
templateParamJSON = string(paramBytes)
default:
// 尝试JSON序列化
paramBytes, err := json.Marshal(v)
if err != nil {
return nil, fmt.Errorf("failed to marshal template param: %w", err)
}
templateParamJSON = string(paramBytes)
}
} else {
templateParamJSON = "{}"
}
// 构建请求参数
params := make(map[string]string)
params["PhoneNumbers"] = strings.Join(req.PhoneNumbers, ",")
params["SignName"] = signName
params["TemplateCode"] = templateCode
params["TemplateParam"] = templateParamJSON
// 使用SendRaw发送
return s.SendRaw(params)
}
// calculateSignature 计算签名
func (s *SMS) calculateSignature(params map[string]string, method string) string {
func (s *SMS) calculateSignature(params map[string]string, method, accessKeySecret string) string {
// 对参数进行排序
keys := make([]string, 0, len(params))
for k := range params {
@@ -260,31 +220,10 @@ func (s *SMS) calculateSignature(params map[string]string, method string) string
stringToSign := method + "&" + url.QueryEscape("/") + "&" + url.QueryEscape(queryString)
// 计算HMAC-SHA1签名
mac := hmac.New(sha1.New, []byte(s.config.AccessKeySecret+"&"))
mac := hmac.New(sha1.New, []byte(accessKeySecret+"&"))
mac.Write([]byte(stringToSign))
signature := base64.StdEncoding.EncodeToString(mac.Sum(nil))
return signature
}
// SendSimple 发送简单短信（便捷方法）
// phoneNumbers: 手机号列表
// templateParam: 模板参数
func (s *SMS) SendSimple(phoneNumbers []string, templateParam map[string]string) (*SendResponse, error) {
return s.Send(&SendRequest{
PhoneNumbers: phoneNumbers,
TemplateParam: templateParam,
})
}
// SendWithTemplate 使用指定模板发送短信（便捷方法）
// phoneNumbers: 手机号列表
// templateCode: 模板代码
// templateParam: 模板参数
func (s *SMS) SendWithTemplate(phoneNumbers []string, templateCode string, templateParam map[string]string) (*SendResponse, error) {
return s.Send(&SendRequest{
PhoneNumbers: phoneNumbers,
TemplateCode: templateCode,
TemplateParam: templateParam,
})
}

36
storage/handler.go
View File

@@ -43,31 +43,29 @@ func NewUploadHandler(cfg UploadHandlerConfig) *UploadHandler {
// 表单字段: file (文件)
// 可选字段: prefix (对象键前缀，会覆盖配置中的前缀)
func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
handler := commonhttp.NewHandler(w, r)
if r.Method != http.MethodPost {
handler.Error(4001, "Method not allowed")
commonhttp.Error(w, 4001, "Method not allowed")
return
}
// 解析multipart表单
err := r.ParseMultipartForm(h.maxFileSize)
if err != nil {
handler.Error(4002, fmt.Sprintf("Failed to parse form: %v", err))
commonhttp.Error(w, 4002, fmt.Sprintf("Failed to parse form: %v", err))
return
}
// 获取文件
file, header, err := r.FormFile("file")
if err != nil {
handler.Error(4003, fmt.Sprintf("Failed to get file: %v", err))
commonhttp.Error(w, 4003, fmt.Sprintf("Failed to get file: %v", err))
return
}
defer file.Close()
// 检查文件大小
if h.maxFileSize > 0 && header.Size > h.maxFileSize {
handler.Error(1001, fmt.Sprintf("File size exceeds limit: %d bytes", h.maxFileSize))
commonhttp.Error(w, 1001, fmt.Sprintf("File size exceeds limit: %d bytes", h.maxFileSize))
return
}
@@ -82,7 +80,7 @@ func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
}
}
if !allowed {
handler.Error(1002, fmt.Sprintf("File extension not allowed. Allowed: %v", h.allowedExts))
commonhttp.Error(w, 1002, fmt.Sprintf("File extension not allowed. Allowed: %v", h.allowedExts))
return
}
}
@@ -110,14 +108,14 @@ func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
err = h.storage.Upload(ctx, objectKey, file, contentType)
if err != nil {
handler.SystemError(fmt.Sprintf("Failed to upload file: %v", err))
commonhttp.SystemError(w, fmt.Sprintf("Failed to upload file: %v", err))
return
}
// 获取文件URL
fileURL, err := h.storage.GetURL(objectKey, 0)
if err != nil {
handler.SystemError(fmt.Sprintf("Failed to get file URL: %v", err))
commonhttp.SystemError(w, fmt.Sprintf("Failed to get file URL: %v", err))
return
}
@@ -130,7 +128,7 @@ func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
UploadTime: time.Now(),
}
handler.SuccessWithMessage("Upload successful", result)
commonhttp.Success(w, result, "Upload successful")
}
// generateUniqueFilename 生成唯一文件名
@@ -155,18 +153,17 @@ func NewProxyHandler(storage Storage) *ProxyHandler {
// ServeHTTP 处理文件查看请求
// URL参数: key (对象键)
// 注意：此方法直接返回文件内容（二进制），错误时返回标准HTTP错误状态码
func (h *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
handler := commonhttp.NewHandler(w, r)
if r.Method != http.MethodGet {
handler.Error(4001, "Method not allowed")
http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
return
}
// 获取对象键
objectKey := handler.GetQuery("key", "")
objectKey := r.URL.Query().Get("key")
if objectKey == "" {
handler.Error(4004, "Missing parameter: key")
http.Error(w, "Missing parameter: key", http.StatusBadRequest)
return
}
@@ -174,19 +171,19 @@ func (h *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
exists, err := h.storage.Exists(ctx, objectKey)
if err != nil {
handler.SystemError(fmt.Sprintf("Failed to check file existence: %v", err))
http.Error(w, fmt.Sprintf("Failed to check file existence: %v", err), http.StatusInternalServerError)
return
}
if !exists {
handler.Error(4005, "File not found")
http.Error(w, "File not found", http.StatusNotFound)
return
}
// 获取文件内容
reader, err := h.storage.GetObject(ctx, objectKey)
if err != nil {
handler.SystemError(fmt.Sprintf("Failed to get file: %v", err))
http.Error(w, fmt.Sprintf("Failed to get file: %v", err), http.StatusInternalServerError)
return
}
defer reader.Close()
@@ -210,7 +207,8 @@ func (h *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
// 复制文件内容到响应
_, err = io.Copy(w, reader)
if err != nil {
handler.SystemError(fmt.Sprintf("Failed to write response: %v", err))
// 如果已经开始写入响应，无法再设置错误状态码
// 这里只能记录错误，无法返回错误响应
return
}
}

39
templates/Dockerfile.example Normal file
View File

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

78
templates/Makefile.example Normal file
View File

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

40
templates/README.md Normal file
View File

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

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

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

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

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

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

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

173
tools/money.go Normal file
View File

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

26
tools/version.go Normal file
View File

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