Compare commits
6 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 6547e7bca8 | |||
| 6146178111 | |||
| 0650feb0d2 | |||
| de8fc13f18 | |||
| fd37c5c301 | |||
| d454d8e143 |
583
MIGRATION.md
Normal file
583
MIGRATION.md
Normal file
@@ -0,0 +1,583 @@
|
||||
# 数据库迁移工具 - 完整指南
|
||||
|
||||
## 📌 核心特点
|
||||
|
||||
- ✅ **独立工具，零耦合** - 与应用代码完全分离
|
||||
- ✅ **生产就绪** - 编译成二进制，无需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
|
||||
# 使用 DATABASE_URL（最简单）
|
||||
export DATABASE_URL="mysql://root:password@localhost:3306/mydb"
|
||||
./bin/migrate up
|
||||
|
||||
# 覆盖配置路径
|
||||
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. 环境变量 `DATABASE_URL`
|
||||
4. 默认值 `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:
|
||||
DATABASE_URL: mysql://root:password@db:3306/mydb
|
||||
command: sh -c "./migrate up && ./server"
|
||||
|
||||
# 注意：DATABASE_URL 的值应该指向你的数据库服务
|
||||
# 例如：mysql://user:pass@your-db-host:3306/dbname
|
||||
```
|
||||
|
||||
### 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: Run Migrations
|
||||
env:
|
||||
DATABASE_URL: ${{ secrets.DATABASE_URL }}
|
||||
run: ./bin/migrate up
|
||||
|
||||
- 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
|
||||
DATABASE_URL="mysql://..." ./bin/migrate up
|
||||
./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
346
QUICKSTART.md
Normal 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/) - 查看更多实际示例
|
||||
|
||||
425
README.md
425
README.md
@@ -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,38 +147,154 @@ 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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 日期转换
|
||||
### 2. 使用工厂黑盒模式（最简单，推荐）⭐
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"net/http"
|
||||
"time"
|
||||
|
||||
"git.toowon.com/jimmy/go-common/factory"
|
||||
commonhttp "git.toowon.com/jimmy/go-common/http"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// 只需传入配置文件路径
|
||||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||||
|
||||
// 获取配置好的中间件链（黑盒）
|
||||
chain := fac.GetMiddlewareChain()
|
||||
|
||||
// （可选）添加自定义中间件
|
||||
chain.Append(yourAuthMiddleware)
|
||||
|
||||
// 注册路由
|
||||
http.Handle("/api/hello", chain.ThenFunc(handleHello))
|
||||
http.ListenAndServe(":8080", nil)
|
||||
}
|
||||
|
||||
func handleHello(w http.ResponseWriter, r *http.Request) {
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||||
ctx := context.Background()
|
||||
|
||||
// 使用黑盒方法（无需获取对象）
|
||||
fac.LogInfo("处理请求: /api/hello")
|
||||
fac.RedisSet(ctx, "last_visit", time.Now().String(), time.Hour)
|
||||
|
||||
h.Success(map[string]interface{}{
|
||||
"message": "Hello!",
|
||||
"timezone": h.GetTimezone(),
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 运行项目
|
||||
|
||||
```bash
|
||||
go run main.go
|
||||
# 访问 http://localhost:8080/api/hello
|
||||
```
|
||||
|
||||
## 核心功能示例
|
||||
|
||||
详细文档请参考：[完整文档](./docs/README.md) | [快速开始](./QUICKSTART.md)
|
||||
|
||||
### 数据库迁移
|
||||
```bash
|
||||
# 编译独立工具
|
||||
go build -o bin/migrate cmd/migrate/main.go
|
||||
|
||||
# 执行迁移
|
||||
./bin/migrate up # 默认配置
|
||||
./bin/migrate up -config /path/to/config.json # 指定配置
|
||||
./bin/migrate status # 查看状态
|
||||
```
|
||||
|
||||
**详细说明**：[数据库迁移指南](./MIGRATION.md) ⭐
|
||||
|
||||
### 工厂黑盒模式（推荐）
|
||||
```go
|
||||
import "git.toowon.com/jimmy/go-common/factory"
|
||||
|
||||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||||
|
||||
// 中间件
|
||||
chain := fac.GetMiddlewareChain()
|
||||
chain.Append(yourAuthMiddleware) // 添加自定义中间件
|
||||
|
||||
// 日志
|
||||
fac.LogInfo("用户登录成功")
|
||||
|
||||
// Redis
|
||||
fac.RedisSet(ctx, "key", "value", time.Hour)
|
||||
|
||||
// 邮件/短信
|
||||
fac.SendEmail([]string{"user@example.com"}, "主题", "内容")
|
||||
fac.SendSMS([]string{"13800138000"}, map[string]string{"code": "123456"})
|
||||
|
||||
// 文件上传
|
||||
url, _ := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")
|
||||
|
||||
// 数据库（高级功能）
|
||||
db, _ := fac.GetDatabase()
|
||||
db.Find(&users)
|
||||
```
|
||||
|
||||
### HTTP处理器
|
||||
```go
|
||||
import commonhttp "git.toowon.com/jimmy/go-common/http"
|
||||
|
||||
func GetUser(h *commonhttp.Handler) {
|
||||
id := h.GetQueryInt64("id", 0)
|
||||
h.Success(data)
|
||||
}
|
||||
|
||||
http.HandleFunc("/user", commonhttp.HandleFunc(GetUser))
|
||||
```
|
||||
|
||||
### 日期时间
|
||||
```go
|
||||
import "git.toowon.com/jimmy/go-common/datetime"
|
||||
|
||||
@@ -104,120 +303,7 @@ now := datetime.Now()
|
||||
str := datetime.FormatDateTime(now)
|
||||
```
|
||||
|
||||
#### HTTP响应
|
||||
```go
|
||||
import "git.toowon.com/jimmy/go-common/http"
|
||||
|
||||
http.Success(w, data)
|
||||
http.SuccessPage(w, list, total, page, pageSize)
|
||||
http.Error(w, 1001, "业务错误")
|
||||
```
|
||||
|
||||
#### 中间件
|
||||
```go
|
||||
import (
|
||||
"git.toowon.com/jimmy/go-common/middleware"
|
||||
"git.toowon.com/jimmy/go-common/http"
|
||||
)
|
||||
|
||||
// CORS + 时区中间件
|
||||
chain := middleware.NewChain(
|
||||
middleware.CORS(),
|
||||
middleware.Timezone,
|
||||
)
|
||||
handler := chain.ThenFunc(yourHandler)
|
||||
|
||||
// 在处理器中获取时区
|
||||
timezone := http.GetTimezone(r)
|
||||
```
|
||||
|
||||
#### 配置管理
|
||||
```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 "git.toowon.com/jimmy/go-common/storage"
|
||||
|
||||
// 创建存储实例
|
||||
storage, _ := storage.NewStorage(storage.StorageTypeOSS, cfg)
|
||||
|
||||
// 创建上传处理器
|
||||
uploadHandler := storage.NewUploadHandler(storage.UploadHandlerConfig{
|
||||
Storage: storage,
|
||||
MaxFileSize: 10 * 1024 * 1024,
|
||||
AllowedExts: []string{".jpg", ".png"},
|
||||
})
|
||||
|
||||
// 创建代理查看处理器
|
||||
proxyHandler := storage.NewProxyHandler(storage)
|
||||
```
|
||||
|
||||
#### 邮件发送
|
||||
```go
|
||||
import "git.toowon.com/jimmy/go-common/email"
|
||||
|
||||
// 从配置创建邮件发送器
|
||||
mailer, _ := email.NewEmail(cfg.GetEmail())
|
||||
|
||||
// 发送邮件
|
||||
mailer.SendSimple(
|
||||
[]string{"recipient@example.com"},
|
||||
"主题",
|
||||
"正文",
|
||||
)
|
||||
```
|
||||
|
||||
#### 短信发送
|
||||
```go
|
||||
import "git.toowon.com/jimmy/go-common/sms"
|
||||
|
||||
// 从配置创建短信发送器
|
||||
smsClient, _ := sms.NewSMS(cfg.GetSMS())
|
||||
|
||||
// 发送短信
|
||||
smsClient.SendSimple(
|
||||
[]string{"13800138000"},
|
||||
map[string]string{"code": "123456"},
|
||||
)
|
||||
```
|
||||
|
||||
#### 使用工厂直接获取客户端（推荐）
|
||||
```go
|
||||
import "git.toowon.com/jimmy/go-common/factory"
|
||||
|
||||
// 方式1：直接从配置文件创建工厂（最推荐）
|
||||
fac, _ := factory.NewFactoryFromFile("./config.json")
|
||||
|
||||
// 直接获取数据库对象（已初始化，可直接使用）
|
||||
db, _ := fac.GetDatabase()
|
||||
db.Find(&users) // 直接使用，无需再创建连接
|
||||
|
||||
// 直接获取Redis客户端（已初始化，可直接使用）
|
||||
redisClient, _ := fac.GetRedisClient()
|
||||
val, _ := redisClient.Get(ctx, "key").Result()
|
||||
|
||||
// 直接获取已初始化的客户端（无需重复实现创建逻辑）
|
||||
emailClient, _ := fac.GetEmailClient()
|
||||
smsClient, _ := fac.GetSMSClient()
|
||||
logger, _ := fac.GetLogger()
|
||||
|
||||
// 直接使用
|
||||
emailClient.SendSimple(...)
|
||||
smsClient.SendSimple(...)
|
||||
logger.Info("Application started")
|
||||
```
|
||||
|
||||
更多示例请查看 [examples](./examples/) 目录。
|
||||
更多示例：[examples目录](./examples/)
|
||||
|
||||
## 版本管理
|
||||
|
||||
@@ -245,3 +331,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！
|
||||
|
||||
|
||||
@@ -5,8 +5,6 @@ import (
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
|
||||
"git.toowon.com/jimmy/go-common/middleware"
|
||||
)
|
||||
|
||||
// Config 应用配置
|
||||
@@ -19,6 +17,7 @@ type Config struct {
|
||||
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配置
|
||||
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -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,22 +24,37 @@ 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
|
||||
@@ -49,33 +65,45 @@ now := datetime.Now()
|
||||
str := datetime.FormatDateTime(now)
|
||||
```
|
||||
|
||||
#### HTTP响应
|
||||
|
||||
```go
|
||||
import "git.toowon.com/jimmy/go-common/http"
|
||||
|
||||
http.Success(w, data)
|
||||
http.SuccessPage(w, list, total, page, pageSize)
|
||||
http.Error(w, 1001, "业务错误")
|
||||
```
|
||||
|
||||
#### 中间件
|
||||
#### HTTP响应（Handler黑盒模式）
|
||||
|
||||
```go
|
||||
import (
|
||||
"net/http"
|
||||
commonhttp "git.toowon.com/jimmy/go-common/http"
|
||||
)
|
||||
|
||||
func GetUser(h *commonhttp.Handler) {
|
||||
id := h.GetQueryInt64("id", 0)
|
||||
h.Success(data)
|
||||
}
|
||||
|
||||
http.HandleFunc("/user", commonhttp.HandleFunc(GetUser))
|
||||
```
|
||||
|
||||
#### 中间件（生产级配置）
|
||||
|
||||
```go
|
||||
import (
|
||||
"time"
|
||||
"git.toowon.com/jimmy/go-common/middleware"
|
||||
"git.toowon.com/jimmy/go-common/http"
|
||||
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(yourHandler)
|
||||
|
||||
// 在处理器中获取时区
|
||||
timezone := http.GetTimezone(r)
|
||||
handler := chain.ThenFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
timezone := h.GetTimezone()
|
||||
h.Success(data)
|
||||
})
|
||||
```
|
||||
|
||||
#### 配置管理
|
||||
|
||||
@@ -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配置
|
||||
|
||||
524
docs/factory.md
524
docs/factory.md
@@ -2,67 +2,181 @@
|
||||
|
||||
## 概述
|
||||
|
||||
工厂工具提供了从配置直接创建已初始化的客户端对象的功能，避免调用方重复实现创建逻辑。
|
||||
工厂工具提供了从配置直接创建已初始化客户端对象的功能，并提供了黑盒模式的便捷方法，让调用方无需关心底层实现细节，大大降低业务复杂度。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- 从配置直接创建已初始化的客户端对象
|
||||
- 统一的工厂接口
|
||||
- 避免调用方重复实现创建逻辑
|
||||
- **黑盒模式**：提供直接调用的方法，无需获取客户端对象
|
||||
- **延迟初始化**：所有客户端在首次使用时才创建
|
||||
- **自动选择**：存储类型（OSS/MinIO）根据配置自动选择
|
||||
- **统一接口**：所有操作通过工厂方法调用
|
||||
- **向后兼容**：保留 `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)` |
|
||||
|
||||
### 🔧 高级功能：Get方法（仅在必要时使用）
|
||||
|
||||
返回客户端对象，用于复杂操作：
|
||||
|
||||
| 方法 | 返回类型 | 使用场景 |
|
||||
|------|----------|----------|
|
||||
| `GetDatabase()` | `*gorm.DB` | 数据库复杂查询、事务、关联查询等 |
|
||||
| `GetRedisClient()` | `*redis.Client` | Hash、List、Set、ZSet、Pub/Sub等高级操作 |
|
||||
| `GetLogger()` | `*logger.Logger` | Close()、设置全局logger等 |
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 1. 从配置文件直接创建工厂（推荐）
|
||||
### 1. 创建工厂（推荐）
|
||||
|
||||
```go
|
||||
import "git.toowon.com/jimmy/go-common/factory"
|
||||
|
||||
// 直接传入配置文件路径，自动加载配置并创建工厂
|
||||
// 方式1：直接从配置文件创建（最推荐）
|
||||
fac, err := factory.NewFactoryFromFile("./config.json")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// 直接获取已初始化的对象
|
||||
db, _ := fac.GetDatabase() // 直接获取数据库对象
|
||||
logger, _ := fac.GetLogger() // 直接获取日志对象
|
||||
emailClient, _ := fac.GetEmailClient() // 直接获取邮件客户端
|
||||
```
|
||||
|
||||
### 2. 从配置对象创建工厂
|
||||
|
||||
```go
|
||||
import (
|
||||
"git.toowon.com/jimmy/go-common/config"
|
||||
"git.toowon.com/jimmy/go-common/factory"
|
||||
)
|
||||
|
||||
// 加载配置
|
||||
cfg, err := config.LoadFromFile("./config.json")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// 创建工厂实例
|
||||
// 方式2：从配置对象创建
|
||||
cfg, _ := config.LoadFromFile("./config.json")
|
||||
fac := factory.NewFactory(cfg)
|
||||
```
|
||||
|
||||
### 3. 获取数据库对象（已初始化，推荐）
|
||||
### 2. 日志记录（黑盒模式，推荐）
|
||||
|
||||
```go
|
||||
// 直接获取已初始化的数据库对象（*gorm.DB）
|
||||
// 简单日志
|
||||
fac.LogDebug("调试信息: %s", "test")
|
||||
fac.LogInfo("用户登录成功")
|
||||
fac.LogWarn("警告信息")
|
||||
fac.LogError("错误信息: %v", err)
|
||||
|
||||
// 带字段的日志
|
||||
fac.LogInfof(map[string]interface{}{
|
||||
"user_id": 123,
|
||||
"ip": "192.168.1.1",
|
||||
}, "用户登录成功")
|
||||
|
||||
fac.LogErrorf(map[string]interface{}{
|
||||
"error_code": 1001,
|
||||
}, "登录失败: %v", err)
|
||||
```
|
||||
|
||||
### 3. 邮件发送（黑盒模式，推荐）
|
||||
|
||||
```go
|
||||
// 简单邮件
|
||||
err := fac.SendEmail(
|
||||
[]string{"user@example.com"},
|
||||
"验证码",
|
||||
"您的验证码是：123456",
|
||||
)
|
||||
|
||||
// HTML邮件
|
||||
err := fac.SendEmail(
|
||||
[]string{"user@example.com"},
|
||||
"验证码",
|
||||
"纯文本内容",
|
||||
"<h1>HTML内容</h1>",
|
||||
)
|
||||
```
|
||||
|
||||
### 4. 短信发送（黑盒模式，推荐）
|
||||
|
||||
```go
|
||||
// 使用配置中的模板代码
|
||||
resp, err := fac.SendSMS(
|
||||
[]string{"13800138000"},
|
||||
map[string]string{"code": "123456"},
|
||||
)
|
||||
|
||||
// 指定模板代码
|
||||
resp, err := fac.SendSMS(
|
||||
[]string{"13800138000"},
|
||||
map[string]string{"code": "123456"},
|
||||
"SMS_123456789", // 模板代码
|
||||
)
|
||||
```
|
||||
|
||||
### 5. 文件上传和查看（黑盒模式，推荐）
|
||||
|
||||
```go
|
||||
import (
|
||||
"context"
|
||||
"os"
|
||||
)
|
||||
|
||||
ctx := context.Background()
|
||||
|
||||
// 上传文件（自动选择OSS或MinIO）
|
||||
file, _ := os.Open("test.jpg")
|
||||
defer file.Close()
|
||||
|
||||
url, err := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
fmt.Println("文件URL:", url)
|
||||
|
||||
// 获取文件URL（永久有效）
|
||||
url, _ := fac.GetFileURL("images/test.jpg", 0)
|
||||
|
||||
// 获取临时访问URL（1小时后过期）
|
||||
url, _ := fac.GetFileURL("images/test.jpg", 3600)
|
||||
```
|
||||
|
||||
### 6. Redis操作（黑盒模式，推荐）
|
||||
|
||||
```go
|
||||
import "context"
|
||||
|
||||
ctx := context.Background()
|
||||
|
||||
// 设置值（不过期）
|
||||
err := fac.RedisSet(ctx, "user:123", "value")
|
||||
|
||||
// 设置值（带过期时间）
|
||||
err := fac.RedisSet(ctx, "user:123", "value", time.Hour)
|
||||
|
||||
// 获取值
|
||||
value, err := fac.RedisGet(ctx, "user:123")
|
||||
|
||||
// 删除键
|
||||
err := fac.RedisDelete(ctx, "user:123", "user:456")
|
||||
|
||||
// 检查键是否存在
|
||||
exists, err := fac.RedisExists(ctx, "user:123")
|
||||
```
|
||||
|
||||
### 7. 数据库操作（黑盒模式）
|
||||
|
||||
```go
|
||||
// 获取数据库对象（已初始化，黑盒模式）
|
||||
db, err := fac.GetDatabase()
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// 直接使用，无需再创建连接
|
||||
// 直接使用GORM，无需自己实现创建逻辑
|
||||
var users []User
|
||||
db.Find(&users)
|
||||
db.Create(&user)
|
||||
```
|
||||
|
||||
### 4. 获取Redis客户端（已初始化，推荐）
|
||||
### 8. Redis操作（获取客户端对象）
|
||||
|
||||
```go
|
||||
import (
|
||||
@@ -70,14 +184,15 @@ import (
|
||||
"github.com/redis/go-redis/v9"
|
||||
)
|
||||
|
||||
// 直接获取已初始化的Redis客户端对象
|
||||
ctx := context.Background()
|
||||
|
||||
// 获取Redis客户端对象（已初始化，黑盒模式）
|
||||
redisClient, err := fac.GetRedisClient()
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// 直接使用，无需再创建连接
|
||||
ctx := context.Background()
|
||||
// 直接使用Redis客户端，无需自己实现创建逻辑
|
||||
val, err := redisClient.Get(ctx, "key").Result()
|
||||
if err != nil && err != redis.Nil {
|
||||
log.Printf("Redis error: %v", err)
|
||||
@@ -86,120 +201,104 @@ if err != nil && err != redis.Nil {
|
||||
} else {
|
||||
fmt.Printf("Value: %s\n", val)
|
||||
}
|
||||
|
||||
// 使用高级功能（如Hash操作）
|
||||
redisClient.HSet(ctx, "user:123", "name", "John")
|
||||
name, _ := redisClient.HGet(ctx, "user:123", "name").Result()
|
||||
```
|
||||
|
||||
### 5. 获取邮件客户端（已初始化）
|
||||
|
||||
```go
|
||||
// 直接获取已初始化的邮件客户端
|
||||
emailClient, err := fac.GetEmailClient()
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// 直接使用，无需再创建
|
||||
err = emailClient.SendSimple(
|
||||
[]string{"recipient@example.com"},
|
||||
"主题",
|
||||
"正文",
|
||||
)
|
||||
```
|
||||
|
||||
### 6. 获取短信客户端（已初始化）
|
||||
|
||||
```go
|
||||
// 直接获取已初始化的短信客户端
|
||||
smsClient, err := fac.GetSMSClient()
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// 直接使用，无需再创建
|
||||
resp, err := smsClient.SendSimple(
|
||||
[]string{"13800138000"},
|
||||
map[string]string{"code": "123456"},
|
||||
)
|
||||
```
|
||||
|
||||
### 7. 获取日志记录器（已初始化）
|
||||
|
||||
```go
|
||||
// 直接获取已初始化的日志记录器
|
||||
logger, err := fac.GetLogger()
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// 直接使用，无需再创建
|
||||
logger.Info("Application started")
|
||||
logger.Error("Error occurred: %v", err)
|
||||
```
|
||||
|
||||
### 8. 完整示例
|
||||
## 完整示例
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"log"
|
||||
"os"
|
||||
"time"
|
||||
|
||||
"git.toowon.com/jimmy/go-common/config"
|
||||
"git.toowon.com/jimmy/go-common/factory"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// 加载配置
|
||||
cfg, err := config.LoadFromFile("./config.json")
|
||||
// 创建工厂
|
||||
fac, err := factory.NewFactoryFromFile("./config.json")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// 创建工厂
|
||||
fac := factory.NewFactory(cfg)
|
||||
ctx := context.Background()
|
||||
|
||||
// 获取邮件客户端（已初始化，可直接使用）
|
||||
emailClient, err := fac.GetEmailClient()
|
||||
if err != nil {
|
||||
log.Printf("Email client not available: %v", err)
|
||||
} else {
|
||||
// 直接使用
|
||||
err = emailClient.SendSimple(
|
||||
[]string{"recipient@example.com"},
|
||||
"测试邮件",
|
||||
"这是测试内容",
|
||||
// 日志记录（黑盒模式）
|
||||
fac.LogInfo("应用启动")
|
||||
fac.LogInfof(map[string]interface{}{
|
||||
"version": "1.0.0",
|
||||
}, "应用启动成功")
|
||||
|
||||
// 邮件发送（黑盒模式）
|
||||
err = fac.SendEmail(
|
||||
[]string{"user@example.com"},
|
||||
"欢迎",
|
||||
"欢迎使用我们的服务",
|
||||
)
|
||||
if err != nil {
|
||||
log.Printf("Failed to send email: %v", err)
|
||||
}
|
||||
fac.LogError("发送邮件失败: %v", err)
|
||||
}
|
||||
|
||||
// 获取短信客户端（已初始化，可直接使用）
|
||||
smsClient, err := fac.GetSMSClient()
|
||||
if err != nil {
|
||||
log.Printf("SMS client not available: %v", err)
|
||||
} else {
|
||||
// 直接使用
|
||||
resp, err := smsClient.SendSimple(
|
||||
// 短信发送（黑盒模式）
|
||||
resp, err := fac.SendSMS(
|
||||
[]string{"13800138000"},
|
||||
map[string]string{"code": "123456"},
|
||||
)
|
||||
if err != nil {
|
||||
log.Printf("Failed to send SMS: %v", err)
|
||||
fac.LogError("发送短信失败: %v", err)
|
||||
} else {
|
||||
log.Printf("SMS sent: %s", resp.RequestID)
|
||||
}
|
||||
fac.LogInfo("短信发送成功: %s", resp.RequestID)
|
||||
}
|
||||
|
||||
// 如果需要访问配置对象
|
||||
cfgObj := fac.GetConfig()
|
||||
dsn, _ := cfgObj.GetDatabaseDSN()
|
||||
log.Printf("Database DSN: %s", dsn)
|
||||
// 文件上传（黑盒模式，自动选择OSS或MinIO）
|
||||
file, _ := os.Open("test.jpg")
|
||||
defer file.Close()
|
||||
|
||||
url, err := fac.UploadFile(ctx, "images/test.jpg", file, "image/jpeg")
|
||||
if err != nil {
|
||||
fac.LogError("上传文件失败: %v", err)
|
||||
} else {
|
||||
fac.LogInfo("文件上传成功: %s", url)
|
||||
}
|
||||
|
||||
// Redis操作（黑盒模式）
|
||||
err = fac.RedisSet(ctx, "user:123", "value", time.Hour)
|
||||
if err != nil {
|
||||
fac.LogError("Redis设置失败: %v", err)
|
||||
}
|
||||
|
||||
value, err := fac.RedisGet(ctx, "user:123")
|
||||
if err != nil {
|
||||
fac.LogError("Redis获取失败: %v", err)
|
||||
} else {
|
||||
fac.LogInfo("Redis值: %s", value)
|
||||
}
|
||||
|
||||
// 数据库操作
|
||||
db, err := fac.GetDatabase()
|
||||
if err != nil {
|
||||
fac.LogError("数据库连接失败: %v", err)
|
||||
} else {
|
||||
var count int64
|
||||
db.Table("users").Count(&count)
|
||||
fac.LogInfo("用户数量: %d", count)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API 参考
|
||||
|
||||
### NewFactory(cfg *config.Config) *Factory
|
||||
### 工厂创建
|
||||
|
||||
#### NewFactory(cfg *config.Config) *Factory
|
||||
|
||||
创建工厂实例。
|
||||
|
||||
@@ -208,7 +307,7 @@ func main() {
|
||||
|
||||
**返回：** 工厂实例
|
||||
|
||||
### NewFactoryFromFile(filePath string) (*Factory, error)
|
||||
#### NewFactoryFromFile(filePath string) (*Factory, error)
|
||||
|
||||
从配置文件直接创建工厂实例（便捷方法）。
|
||||
|
||||
@@ -219,31 +318,132 @@ func main() {
|
||||
|
||||
**说明：** 这是推荐的使用方式，一步完成配置加载和工厂创建。
|
||||
|
||||
### (f *Factory) GetEmailClient() (*email.Email, error)
|
||||
### 日志方法（黑盒模式）
|
||||
|
||||
获取邮件客户端（已初始化）。
|
||||
#### LogDebug(message string, args ...interface{})
|
||||
|
||||
**返回：** 已初始化的邮件客户端对象和错误信息
|
||||
记录调试日志。
|
||||
|
||||
**说明：** 如果邮件配置为nil，返回错误。
|
||||
#### LogDebugf(fields map[string]interface{}, message string, args ...interface{})
|
||||
|
||||
### (f *Factory) GetSMSClient() (*sms.SMS, error)
|
||||
记录调试日志（带字段）。
|
||||
|
||||
获取短信客户端（已初始化）。
|
||||
#### LogInfo(message string, args ...interface{})
|
||||
|
||||
**返回：** 已初始化的短信客户端对象和错误信息
|
||||
记录信息日志。
|
||||
|
||||
**说明：** 如果短信配置为nil，返回错误。
|
||||
#### LogInfof(fields map[string]interface{}, message string, args ...interface{})
|
||||
|
||||
### (f *Factory) GetLogger() (*logger.Logger, error)
|
||||
记录信息日志（带字段）。
|
||||
|
||||
获取日志记录器（已初始化）。
|
||||
#### LogWarn(message string, args ...interface{})
|
||||
|
||||
**返回：** 已初始化的日志记录器对象和错误信息
|
||||
记录警告日志。
|
||||
|
||||
**说明：** 如果日志配置为nil，会使用默认配置创建。
|
||||
#### LogWarnf(fields map[string]interface{}, message string, args ...interface{})
|
||||
|
||||
### (f *Factory) GetDatabase() (*gorm.DB, error)
|
||||
记录警告日志（带字段）。
|
||||
|
||||
#### LogError(message string, args ...interface{})
|
||||
|
||||
记录错误日志。
|
||||
|
||||
#### LogErrorf(fields map[string]interface{}, message string, args ...interface{})
|
||||
|
||||
记录错误日志（带字段）。
|
||||
|
||||
### 邮件方法（黑盒模式）
|
||||
|
||||
#### SendEmail(to []string, subject, body string, htmlBody ...string) error
|
||||
|
||||
发送邮件。
|
||||
|
||||
**参数：**
|
||||
- `to`: 收件人列表
|
||||
- `subject`: 邮件主题
|
||||
- `body`: 邮件正文（纯文本）
|
||||
- `htmlBody`: HTML正文（可选，如果设置了会优先使用）
|
||||
|
||||
### 短信方法（黑盒模式）
|
||||
|
||||
#### SendSMS(phoneNumbers []string, templateParam interface{}, templateCode ...string) (*sms.SendResponse, error)
|
||||
|
||||
发送短信。
|
||||
|
||||
**参数：**
|
||||
- `phoneNumbers`: 手机号列表
|
||||
- `templateParam`: 模板参数（map或JSON字符串）
|
||||
- `templateCode`: 模板代码（可选，如果为空使用配置中的模板代码）
|
||||
|
||||
### 存储方法（黑盒模式）
|
||||
|
||||
#### UploadFile(ctx context.Context, objectKey string, reader io.Reader, contentType ...string) (string, error)
|
||||
|
||||
上传文件。
|
||||
|
||||
**参数：**
|
||||
- `ctx`: 上下文
|
||||
- `objectKey`: 对象键（文件路径）
|
||||
- `reader`: 文件内容
|
||||
- `contentType`: 文件类型（可选）
|
||||
|
||||
**返回：** 文件访问URL和错误信息
|
||||
|
||||
**说明：** 自动根据配置选择OSS或MinIO（优先级：MinIO > OSS）
|
||||
|
||||
#### GetFileURL(objectKey string, expires int64) (string, error)
|
||||
|
||||
获取文件访问URL。
|
||||
|
||||
**参数：**
|
||||
- `objectKey`: 对象键
|
||||
- `expires`: 过期时间（秒），0表示永久有效
|
||||
|
||||
**返回：** 文件访问URL和错误信息
|
||||
|
||||
### Redis方法（黑盒模式）
|
||||
|
||||
#### RedisGet(ctx context.Context, key string) (string, error)
|
||||
|
||||
获取Redis值。
|
||||
|
||||
**参数：**
|
||||
- `ctx`: 上下文
|
||||
- `key`: Redis键
|
||||
|
||||
**返回：** 值和错误信息（key不存在时返回空字符串）
|
||||
|
||||
#### RedisSet(ctx context.Context, key string, value interface{}, expiration ...time.Duration) error
|
||||
|
||||
设置Redis值。
|
||||
|
||||
**参数：**
|
||||
- `ctx`: 上下文
|
||||
- `key`: Redis键
|
||||
- `value`: Redis值
|
||||
- `expiration`: 过期时间（可选，0表示不过期）
|
||||
|
||||
#### RedisDelete(ctx context.Context, keys ...string) error
|
||||
|
||||
删除Redis键。
|
||||
|
||||
**参数：**
|
||||
- `ctx`: 上下文
|
||||
- `keys`: Redis键列表
|
||||
|
||||
#### RedisExists(ctx context.Context, key string) (bool, error)
|
||||
|
||||
检查Redis键是否存在。
|
||||
|
||||
**参数：**
|
||||
- `ctx`: 上下文
|
||||
- `key`: Redis键
|
||||
|
||||
**返回：** 是否存在和错误信息
|
||||
|
||||
### 数据库方法
|
||||
|
||||
#### GetDatabase() (*gorm.DB, error)
|
||||
|
||||
获取数据库连接对象（已初始化）。
|
||||
|
||||
@@ -253,8 +453,12 @@ func main() {
|
||||
- 支持MySQL、PostgreSQL、SQLite
|
||||
- 自动配置连接池参数
|
||||
- 数据库时间统一使用UTC时区
|
||||
- 延迟初始化，首次调用时创建连接
|
||||
- 黑盒模式：只需传递config对象，无需自己实现创建逻辑
|
||||
|
||||
### (f *Factory) GetRedisClient() (*redis.Client, error)
|
||||
### Redis方法
|
||||
|
||||
#### GetRedisClient() (*redis.Client, error)
|
||||
|
||||
获取Redis客户端对象（已初始化）。
|
||||
|
||||
@@ -265,66 +469,38 @@ func main() {
|
||||
- 自动设置默认值（连接池大小、超时时间等）
|
||||
- 连接失败时会自动关闭客户端并返回错误
|
||||
- 返回的客户端已通过Ping测试，可直接使用
|
||||
- 黑盒模式：只需传递config对象，无需自己实现创建逻辑
|
||||
- 推荐使用 `RedisGet`、`RedisSet`、`RedisDelete` 等方法直接操作Redis
|
||||
- 如果需要使用Redis的高级功能（如Hash、List、Set等），可以使用此方法获取客户端对象
|
||||
|
||||
### (f *Factory) GetRedisConfig() *config.RedisConfig
|
||||
### 配置方法
|
||||
|
||||
获取Redis配置（用于创建Redis客户端）。
|
||||
|
||||
**返回：** Redis配置对象（可能为nil）
|
||||
|
||||
**说明：**
|
||||
- 推荐使用 `GetRedisClient()` 方法直接获取已初始化的客户端
|
||||
- 如果需要自定义创建Redis客户端，可以使用此方法获取配置
|
||||
|
||||
### (f *Factory) GetConfig() *config.Config
|
||||
#### GetConfig() *config.Config
|
||||
|
||||
获取配置对象。
|
||||
|
||||
**返回：** 配置对象
|
||||
|
||||
## 优势
|
||||
## 设计优势
|
||||
|
||||
### 之前的方式（需要调用方实现）
|
||||
### 优势总结
|
||||
|
||||
```go
|
||||
// 调用方需要自己实现创建逻辑
|
||||
cfg, _ := config.LoadFromFile("./config.json")
|
||||
dsn, _ := cfg.GetDatabaseDSN()
|
||||
db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{})
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
// 配置连接池
|
||||
sqlDB, _ := db.DB()
|
||||
sqlDB.SetMaxOpenConns(100)
|
||||
// 才能使用
|
||||
db.Find(&users)
|
||||
```
|
||||
|
||||
### 使用工厂方式（直接获取已初始化对象）
|
||||
|
||||
```go
|
||||
// 方式1：直接从配置文件创建（最推荐）
|
||||
fac, _ := factory.NewFactoryFromFile("./config.json")
|
||||
db, _ := fac.GetDatabase() // 直接获取已初始化的数据库对象
|
||||
// 直接使用
|
||||
db.Find(&users)
|
||||
|
||||
// 方式2：从配置对象创建
|
||||
cfg, _ := config.LoadFromFile("./config.json")
|
||||
fac := factory.NewFactory(cfg)
|
||||
db, _ := fac.GetDatabase() // 直接获取已初始化的数据库对象
|
||||
// 直接使用
|
||||
db.Find(&users)
|
||||
```
|
||||
1. **降低复杂度**：调用方无需关心客户端对象的创建和管理
|
||||
2. **延迟初始化**：所有客户端在首次使用时才创建，提高性能
|
||||
3. **自动选择**：存储类型根据配置自动选择，无需手动指定
|
||||
4. **统一接口**：所有操作通过工厂方法调用，接口统一
|
||||
5. **容错处理**：日志初始化失败时自动回退到标准输出
|
||||
6. **代码简洁**：只提供黑盒模式方法，保持代码简洁清晰
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **配置检查**：工厂方法会自动检查配置是否存在，如果配置为nil会返回错误
|
||||
2. **错误处理**：所有Get方法都可能返回错误，需要正确处理
|
||||
3. **配置对象**：可以通过`GetConfig()`方法访问原始配置对象，获取其他配置信息
|
||||
2. **错误处理**：所有方法都可能返回错误，需要正确处理
|
||||
3. **延迟初始化**：所有客户端在首次使用时才创建，首次调用可能稍慢
|
||||
4. **存储选择**：存储类型根据配置自动选择（优先级：MinIO > OSS）
|
||||
5. **数据库对象**：数据库保持返回GORM对象，因为GORM已经提供了很好的抽象
|
||||
6. **黑盒模式**：所有功能都通过工厂方法直接调用，无需获取底层客户端对象
|
||||
|
||||
## 示例
|
||||
|
||||
完整示例请参考 `examples/factory_example.go`
|
||||
|
||||
|
||||
409
docs/http.md
409
docs/http.md
@@ -2,16 +2,16 @@
|
||||
|
||||
## 概述
|
||||
|
||||
HTTP Restful工具提供了标准化的HTTP请求和响应处理功能，包含统一的响应结构、分页支持和HTTP状态码与业务状态码的分离。
|
||||
HTTP Restful工具提供了标准化的HTTP请求和响应处理功能，采用Handler黑盒模式，封装了`ResponseWriter`和`Request`，提供简洁的API，无需每次都传递这两个参数。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- 标准化的响应结构：`{code, message, timestamp, data}`
|
||||
- 分离HTTP状态码和业务状态码
|
||||
- 支持分页响应
|
||||
- 提供便捷的请求参数解析方法
|
||||
- 支持JSON请求体解析
|
||||
- 提供常用的HTTP错误响应方法
|
||||
- **黑盒模式**：封装`ResponseWriter`和`Request`，提供简洁的API
|
||||
- **标准化的响应结构**：`{code, message, timestamp, data}`
|
||||
- **分离HTTP状态码和业务状态码**
|
||||
- **支持分页响应**
|
||||
- **提供便捷的请求参数解析方法**
|
||||
- **支持JSON请求体解析**
|
||||
|
||||
## 响应结构
|
||||
|
||||
@@ -44,151 +44,224 @@ HTTP Restful工具提供了标准化的HTTP请求和响应处理功能，包含
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 1. 成功响应
|
||||
### 1. 创建Handler
|
||||
|
||||
```go
|
||||
import (
|
||||
"net/http"
|
||||
"git.toowon.com/jimmy/go-common/http"
|
||||
commonhttp "git.toowon.com/jimmy/go-common/http"
|
||||
)
|
||||
|
||||
// 方式1：使用HandleFunc包装器（推荐，最简洁）
|
||||
func GetUser(h *commonhttp.Handler) {
|
||||
id := h.GetQueryInt64("id", 0)
|
||||
h.Success(data)
|
||||
}
|
||||
|
||||
http.HandleFunc("/user", commonhttp.HandleFunc(GetUser))
|
||||
|
||||
// 方式2：手动创建Handler（需要更多控制时）
|
||||
http.HandleFunc("/user", func(w http.ResponseWriter, r *http.Request) {
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
GetUser(h)
|
||||
})
|
||||
```
|
||||
|
||||
### 2. 成功响应
|
||||
|
||||
```go
|
||||
func handler(h *commonhttp.Handler) {
|
||||
// 简单成功响应（data为nil）
|
||||
http.Success(w, nil)
|
||||
h.Success(nil)
|
||||
|
||||
// 带数据的成功响应
|
||||
data := map[string]interface{}{
|
||||
"id": 1,
|
||||
"name": "test",
|
||||
}
|
||||
http.Success(w, data)
|
||||
h.Success(data)
|
||||
|
||||
// 带消息的成功响应
|
||||
http.SuccessWithMessage(w, "操作成功", data)
|
||||
h.SuccessWithMessage("操作成功", data)
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 错误响应
|
||||
### 3. 错误响应
|
||||
|
||||
```go
|
||||
func handler(h *commonhttp.Handler) {
|
||||
// 业务错误（HTTP 200，业务code非0）
|
||||
http.Error(w, 1001, "用户不存在")
|
||||
h.Error(1001, "用户不存在")
|
||||
|
||||
// 系统错误（HTTP 500）
|
||||
http.SystemError(w, "服务器内部错误")
|
||||
h.SystemError("服务器内部错误")
|
||||
|
||||
// 其他HTTP错误状态码，使用WriteJSON直接指定
|
||||
// 请求错误（HTTP 400）
|
||||
http.BadRequest(w, "请求参数错误")
|
||||
h.WriteJSON(http.StatusBadRequest, 400, "请求参数错误", nil)
|
||||
|
||||
// 未授权（HTTP 401）
|
||||
http.Unauthorized(w, "未登录")
|
||||
h.WriteJSON(http.StatusUnauthorized, 401, "未登录", nil)
|
||||
|
||||
// 禁止访问（HTTP 403）
|
||||
http.Forbidden(w, "无权限访问")
|
||||
h.WriteJSON(http.StatusForbidden, 403, "无权限访问", nil)
|
||||
|
||||
// 未找到（HTTP 404）
|
||||
http.NotFound(w, "资源不存在")
|
||||
h.WriteJSON(http.StatusNotFound, 404, "资源不存在", nil)
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 分页响应
|
||||
### 4. 分页响应
|
||||
|
||||
```go
|
||||
func handler(h *commonhttp.Handler) {
|
||||
// 获取分页参数
|
||||
page, pageSize := http.GetPaginationParams(r)
|
||||
pagination := h.ParsePaginationRequest()
|
||||
page := pagination.GetPage()
|
||||
pageSize := pagination.GetSize()
|
||||
|
||||
// 查询数据（示例）
|
||||
list, total := getDataList(page, pageSize)
|
||||
|
||||
// 返回分页响应
|
||||
http.SuccessPage(w, list, total, page, pageSize)
|
||||
// 返回分页响应（使用默认消息）
|
||||
h.SuccessPage(list, total, page, pageSize)
|
||||
|
||||
// 带消息的分页响应
|
||||
http.SuccessPageWithMessage(w, "查询成功", list, total, page, pageSize)
|
||||
// 返回分页响应（自定义消息）
|
||||
h.SuccessPage(list, total, page, pageSize, "查询成功")
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 解析请求
|
||||
### 5. 解析请求
|
||||
|
||||
#### 解析JSON请求体
|
||||
|
||||
```go
|
||||
func handler(h *commonhttp.Handler) {
|
||||
type CreateUserRequest struct {
|
||||
Name string `json:"name"`
|
||||
Email string `json:"email"`
|
||||
}
|
||||
|
||||
var req CreateUserRequest
|
||||
err := http.ParseJSON(r, &req)
|
||||
if err != nil {
|
||||
http.BadRequest(w, "请求参数解析失败")
|
||||
if err := h.ParseJSON(&req); err != nil {
|
||||
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
|
||||
return
|
||||
}
|
||||
|
||||
// 使用req...
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取查询参数
|
||||
|
||||
```go
|
||||
func handler(h *commonhttp.Handler) {
|
||||
// 获取字符串参数
|
||||
name := http.GetQuery(r, "name", "")
|
||||
email := http.GetQuery(r, "email", "default@example.com")
|
||||
name := h.GetQuery("name", "")
|
||||
email := h.GetQuery("email", "default@example.com")
|
||||
|
||||
// 获取整数参数
|
||||
id := http.GetQueryInt(r, "id", 0)
|
||||
age := http.GetQueryInt(r, "age", 18)
|
||||
id := h.GetQueryInt("id", 0)
|
||||
age := h.GetQueryInt("age", 18)
|
||||
|
||||
// 获取int64参数
|
||||
userId := http.GetQueryInt64(r, "userId", 0)
|
||||
userId := h.GetQueryInt64("userId", 0)
|
||||
|
||||
// 获取布尔参数
|
||||
isActive := http.GetQueryBool(r, "isActive", false)
|
||||
isActive := h.GetQueryBool("isActive", false)
|
||||
|
||||
// 获取浮点数参数
|
||||
price := http.GetQueryFloat64(r, "price", 0.0)
|
||||
price := h.GetQueryFloat64("price", 0.0)
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取表单参数
|
||||
|
||||
```go
|
||||
func handler(h *commonhttp.Handler) {
|
||||
// 获取表单字符串
|
||||
name := http.GetFormValue(r, "name", "")
|
||||
name := h.GetFormValue("name", "")
|
||||
|
||||
// 获取表单整数
|
||||
age := http.GetFormInt(r, "age", 0)
|
||||
age := h.GetFormInt("age", 0)
|
||||
|
||||
// 获取表单int64
|
||||
userId := http.GetFormInt64(r, "userId", 0)
|
||||
userId := h.GetFormInt64("userId", 0)
|
||||
|
||||
// 获取表单布尔值
|
||||
isActive := http.GetFormBool(r, "isActive", false)
|
||||
isActive := h.GetFormBool("isActive", false)
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取请求头
|
||||
|
||||
```go
|
||||
token := http.GetHeader(r, "Authorization", "")
|
||||
contentType := http.GetHeader(r, "Content-Type", "application/json")
|
||||
func handler(h *commonhttp.Handler) {
|
||||
token := h.GetHeader("Authorization", "")
|
||||
contentType := h.GetHeader("Content-Type", "application/json")
|
||||
}
|
||||
```
|
||||
|
||||
#### 获取分页参数
|
||||
|
||||
```go
|
||||
// 自动解析page和pageSize参数
|
||||
// 默认: page=1, pageSize=10
|
||||
// 限制: pageSize最大1000
|
||||
page, pageSize := http.GetPaginationParams(r)
|
||||
**方式1：使用 PaginationRequest 结构（推荐）**
|
||||
|
||||
// 计算数据库查询偏移量
|
||||
offset := http.GetOffset(page, pageSize)
|
||||
```go
|
||||
func handler(h *commonhttp.Handler) {
|
||||
// 定义请求结构（包含分页字段）
|
||||
type ListUserRequest struct {
|
||||
Keyword string `json:"keyword"`
|
||||
commonhttp.PaginationRequest // 嵌入分页请求结构
|
||||
}
|
||||
|
||||
// 从JSON请求体解析（分页字段会自动解析）
|
||||
var req ListUserRequest
|
||||
if err := h.ParseJSON(&req); err != nil {
|
||||
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
|
||||
return
|
||||
}
|
||||
|
||||
// 使用分页方法
|
||||
page := req.GetPage() // 获取页码（默认1）
|
||||
size := req.GetSize() // 获取每页数量（默认20，最大100，优先使用page_size）
|
||||
offset := req.GetOffset() // 计算偏移量
|
||||
}
|
||||
|
||||
// 或者从查询参数/form解析分页
|
||||
func handler(h *commonhttp.Handler) {
|
||||
pagination := h.ParsePaginationRequest()
|
||||
page := pagination.GetPage()
|
||||
size := pagination.GetSize()
|
||||
offset := pagination.GetOffset()
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 自定义响应
|
||||
#### 获取时区
|
||||
|
||||
```go
|
||||
// 使用WriteJSON自定义响应
|
||||
http.WriteJSON(w, http.StatusOK, 0, "success", data)
|
||||
func handler(h *commonhttp.Handler) {
|
||||
// 从请求的context中获取时区
|
||||
// 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
|
||||
// 如果未设置，返回默认时区 AsiaShanghai
|
||||
timezone := h.GetTimezone()
|
||||
}
|
||||
```
|
||||
|
||||
// 参数说明：
|
||||
// - httpCode: HTTP状态码（200, 400, 500等）
|
||||
// - code: 业务状态码（0表示成功，非0表示业务错误）
|
||||
// - message: 响应消息
|
||||
// - data: 响应数据
|
||||
### 6. 访问原始对象
|
||||
|
||||
如果需要访问原始的`ResponseWriter`或`Request`：
|
||||
|
||||
```go
|
||||
func handler(h *commonhttp.Handler) {
|
||||
// 获取原始ResponseWriter
|
||||
w := h.ResponseWriter()
|
||||
|
||||
// 获取原始Request
|
||||
r := h.Request()
|
||||
|
||||
// 获取Context
|
||||
ctx := h.Context()
|
||||
}
|
||||
```
|
||||
|
||||
## 完整示例
|
||||
@@ -197,118 +270,159 @@ http.WriteJSON(w, http.StatusOK, 0, "success", data)
|
||||
package main
|
||||
|
||||
import (
|
||||
"log"
|
||||
"net/http"
|
||||
"git.toowon.com/jimmy/go-common/http"
|
||||
commonhttp "git.toowon.com/jimmy/go-common/http"
|
||||
)
|
||||
|
||||
// 用户结构
|
||||
type User struct {
|
||||
ID int64 `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Email string `json:"email"`
|
||||
}
|
||||
|
||||
// 用户列表接口
|
||||
func GetUserList(w http.ResponseWriter, r *http.Request) {
|
||||
func GetUserList(h *commonhttp.Handler) {
|
||||
// 获取分页参数
|
||||
page, pageSize := http.GetPaginationParams(r)
|
||||
pagination := h.ParsePaginationRequest()
|
||||
page := pagination.GetPage()
|
||||
pageSize := pagination.GetSize()
|
||||
|
||||
// 获取查询参数
|
||||
keyword := http.GetQuery(r, "keyword", "")
|
||||
keyword := h.GetQuery("keyword", "")
|
||||
|
||||
// 查询数据
|
||||
users, total := queryUsers(keyword, page, pageSize)
|
||||
|
||||
// 返回分页响应
|
||||
http.SuccessPage(w, users, total, page, pageSize)
|
||||
h.SuccessPage(users, total, page, pageSize)
|
||||
}
|
||||
|
||||
// 创建用户接口
|
||||
func CreateUser(w http.ResponseWriter, r *http.Request) {
|
||||
func CreateUser(h *commonhttp.Handler) {
|
||||
// 解析请求体
|
||||
var req struct {
|
||||
Name string `json:"name"`
|
||||
Email string `json:"email"`
|
||||
}
|
||||
|
||||
if err := http.ParseJSON(r, &req); err != nil {
|
||||
http.BadRequest(w, "请求参数解析失败")
|
||||
if err := h.ParseJSON(&req); err != nil {
|
||||
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
|
||||
return
|
||||
}
|
||||
|
||||
// 参数验证
|
||||
if req.Name == "" {
|
||||
http.Error(w, 1001, "用户名不能为空")
|
||||
h.Error(1001, "用户名不能为空")
|
||||
return
|
||||
}
|
||||
|
||||
// 创建用户
|
||||
user, err := createUser(req.Name, req.Email)
|
||||
if err != nil {
|
||||
http.SystemError(w, "创建用户失败")
|
||||
h.SystemError("创建用户失败")
|
||||
return
|
||||
}
|
||||
|
||||
// 返回成功响应
|
||||
http.SuccessWithMessage(w, "创建成功", user)
|
||||
h.SuccessWithMessage("创建成功", user)
|
||||
}
|
||||
|
||||
// 获取用户详情接口
|
||||
func GetUser(w http.ResponseWriter, r *http.Request) {
|
||||
// 获取路径参数（需要配合路由框架使用）
|
||||
id := http.GetQueryInt64(r, "id", 0)
|
||||
func GetUser(h *commonhttp.Handler) {
|
||||
// 获取查询参数
|
||||
id := h.GetQueryInt64("id", 0)
|
||||
|
||||
if id == 0 {
|
||||
http.BadRequest(w, "用户ID不能为空")
|
||||
h.WriteJSON(http.StatusBadRequest, 400, "用户ID不能为空", nil)
|
||||
return
|
||||
}
|
||||
|
||||
// 查询用户
|
||||
user, err := getUserByID(id)
|
||||
if err != nil {
|
||||
http.SystemError(w, "查询用户失败")
|
||||
h.SystemError("查询用户失败")
|
||||
return
|
||||
}
|
||||
|
||||
if user == nil {
|
||||
http.Error(w, 1002, "用户不存在")
|
||||
h.Error(1002, "用户不存在")
|
||||
return
|
||||
}
|
||||
|
||||
http.Success(w, user)
|
||||
h.Success(user)
|
||||
}
|
||||
|
||||
func main() {
|
||||
// 使用HandleFunc包装器（推荐）
|
||||
http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
|
||||
switch h.Request().Method {
|
||||
case http.MethodGet:
|
||||
GetUserList(h)
|
||||
case http.MethodPost:
|
||||
CreateUser(h)
|
||||
default:
|
||||
h.WriteJSON(http.StatusMethodNotAllowed, 405, "方法不支持", nil)
|
||||
}
|
||||
}))
|
||||
|
||||
http.HandleFunc("/user", commonhttp.HandleFunc(GetUser))
|
||||
|
||||
log.Println("Server started on :8080")
|
||||
log.Fatal(http.ListenAndServe(":8080", nil))
|
||||
}
|
||||
```
|
||||
|
||||
## API 参考
|
||||
|
||||
### 响应方法
|
||||
### Handler结构
|
||||
|
||||
#### Success(w http.ResponseWriter, data interface{})
|
||||
Handler封装了`ResponseWriter`和`Request`，提供更简洁的API。
|
||||
|
||||
```go
|
||||
type Handler struct {
|
||||
w http.ResponseWriter
|
||||
r *http.Request
|
||||
}
|
||||
```
|
||||
|
||||
### 创建Handler
|
||||
|
||||
#### NewHandler(w http.ResponseWriter, r *http.Request) *Handler
|
||||
|
||||
创建Handler实例。
|
||||
|
||||
#### HandleFunc(fn func(*Handler)) http.HandlerFunc
|
||||
|
||||
将Handler函数转换为标准的http.HandlerFunc（便捷包装器）。
|
||||
|
||||
**示例：**
|
||||
```go
|
||||
http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
|
||||
h.Success(data)
|
||||
}))
|
||||
```
|
||||
|
||||
### Handler响应方法
|
||||
|
||||
#### (h *Handler) Success(data interface{})
|
||||
|
||||
成功响应，HTTP 200，业务code 0。
|
||||
|
||||
#### SuccessWithMessage(w http.ResponseWriter, message string, data interface{})
|
||||
#### (h *Handler) SuccessWithMessage(message string, data interface{})
|
||||
|
||||
带消息的成功响应。
|
||||
|
||||
#### Error(w http.ResponseWriter, code int, message string)
|
||||
#### (h *Handler) Error(code int, message string)
|
||||
|
||||
业务错误响应，HTTP 200，业务code非0。
|
||||
|
||||
#### SystemError(w http.ResponseWriter, message string)
|
||||
#### (h *Handler) SystemError(message string)
|
||||
|
||||
系统错误响应，HTTP 500，业务code 500。
|
||||
|
||||
#### BadRequest(w http.ResponseWriter, message string)
|
||||
|
||||
请求错误响应，HTTP 400。
|
||||
|
||||
#### Unauthorized(w http.ResponseWriter, message string)
|
||||
|
||||
未授权响应，HTTP 401。
|
||||
|
||||
#### Forbidden(w http.ResponseWriter, message string)
|
||||
|
||||
禁止访问响应，HTTP 403。
|
||||
|
||||
#### NotFound(w http.ResponseWriter, message string)
|
||||
|
||||
未找到响应，HTTP 404。
|
||||
|
||||
#### WriteJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{})
|
||||
#### (h *Handler) WriteJSON(httpCode, code int, message string, data interface{})
|
||||
|
||||
写入JSON响应（自定义）。
|
||||
|
||||
@@ -318,69 +432,113 @@ func GetUser(w http.ResponseWriter, r *http.Request) {
|
||||
- `message`: 响应消息
|
||||
- `data`: 响应数据
|
||||
|
||||
#### SuccessPage(w http.ResponseWriter, list interface{}, total int64, page, pageSize int)
|
||||
#### (h *Handler) SuccessPage(list interface{}, total int64, page, pageSize int, message ...string)
|
||||
|
||||
分页成功响应。
|
||||
|
||||
#### SuccessPageWithMessage(w http.ResponseWriter, message string, list interface{}, total int64, page, pageSize int)
|
||||
**参数：**
|
||||
- `list`: 数据列表
|
||||
- `total`: 总记录数
|
||||
- `page`: 当前页码
|
||||
- `pageSize`: 每页大小
|
||||
- `message`: 响应消息（可选，如果为空则使用默认消息 "success"）
|
||||
|
||||
带消息的分页成功响应。
|
||||
### Handler请求解析方法
|
||||
|
||||
### 请求方法
|
||||
|
||||
#### ParseJSON(r *http.Request, v interface{}) error
|
||||
#### (h *Handler) ParseJSON(v interface{}) error
|
||||
|
||||
解析JSON请求体。
|
||||
|
||||
#### GetQuery(r *http.Request, key, defaultValue string) string
|
||||
#### (h *Handler) GetQuery(key, defaultValue string) string
|
||||
|
||||
获取查询参数（字符串）。
|
||||
|
||||
#### GetQueryInt(r *http.Request, key string, defaultValue int) int
|
||||
#### (h *Handler) GetQueryInt(key string, defaultValue int) int
|
||||
|
||||
获取查询参数（整数）。
|
||||
|
||||
#### GetQueryInt64(r *http.Request, key string, defaultValue int64) int64
|
||||
#### (h *Handler) GetQueryInt64(key string, defaultValue int64) int64
|
||||
|
||||
获取查询参数（int64）。
|
||||
|
||||
#### GetQueryBool(r *http.Request, key string, defaultValue bool) bool
|
||||
#### (h *Handler) GetQueryBool(key string, defaultValue bool) bool
|
||||
|
||||
获取查询参数（布尔值）。
|
||||
|
||||
#### GetQueryFloat64(r *http.Request, key string, defaultValue float64) float64
|
||||
#### (h *Handler) GetQueryFloat64(key string, defaultValue float64) float64
|
||||
|
||||
获取查询参数（浮点数）。
|
||||
|
||||
#### GetFormValue(r *http.Request, key, defaultValue string) string
|
||||
#### (h *Handler) GetFormValue(key, defaultValue string) string
|
||||
|
||||
获取表单值（字符串）。
|
||||
|
||||
#### GetFormInt(r *http.Request, key string, defaultValue int) int
|
||||
#### (h *Handler) GetFormInt(key string, defaultValue int) int
|
||||
|
||||
获取表单值（整数）。
|
||||
|
||||
#### GetFormInt64(r *http.Request, key string, defaultValue int64) int64
|
||||
#### (h *Handler) GetFormInt64(key string, defaultValue int64) int64
|
||||
|
||||
获取表单值（int64）。
|
||||
|
||||
#### GetFormBool(r *http.Request, key string, defaultValue bool) bool
|
||||
#### (h *Handler) GetFormBool(key string, defaultValue bool) bool
|
||||
|
||||
获取表单值（布尔值）。
|
||||
|
||||
#### GetHeader(r *http.Request, key, defaultValue string) string
|
||||
#### (h *Handler) GetHeader(key, defaultValue string) string
|
||||
|
||||
获取请求头。
|
||||
|
||||
#### GetPaginationParams(r *http.Request) (page, pageSize int)
|
||||
#### (h *Handler) ParsePaginationRequest() *PaginationRequest
|
||||
|
||||
获取分页参数。
|
||||
从请求中解析分页参数。
|
||||
|
||||
**返回：** page（页码，最小1），pageSize（每页大小，最小1，最大1000）
|
||||
**说明：**
|
||||
- 支持从查询参数和form表单中解析
|
||||
- 优先级：查询参数 > form表单
|
||||
- 如果请求体是JSON格式且包含分页字段，建议先使用`ParseJSON`解析完整请求体到包含`PaginationRequest`的结构体中
|
||||
|
||||
#### GetOffset(page, pageSize int) int
|
||||
#### (h *Handler) GetTimezone() string
|
||||
|
||||
根据页码和每页大小计算偏移量。
|
||||
从请求的context中获取时区。
|
||||
|
||||
**说明：**
|
||||
- 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
|
||||
- 如果未设置，返回默认时区 AsiaShanghai
|
||||
|
||||
### Handler访问原始对象
|
||||
|
||||
#### (h *Handler) ResponseWriter() http.ResponseWriter
|
||||
|
||||
获取原始的ResponseWriter（需要时使用）。
|
||||
|
||||
#### (h *Handler) Request() *http.Request
|
||||
|
||||
获取原始的Request（需要时使用）。
|
||||
|
||||
#### (h *Handler) Context() context.Context
|
||||
|
||||
获取请求的Context。
|
||||
|
||||
### 分页请求结构
|
||||
|
||||
#### PaginationRequest
|
||||
|
||||
分页请求结构，支持从JSON和form中解析分页参数。
|
||||
|
||||
**字段：**
|
||||
- `Page`: 页码（默认1）
|
||||
- `Size`: 每页数量（兼容旧版本）
|
||||
- `PageSize`: 每页数量（推荐使用，优先于Size）
|
||||
|
||||
**方法：**
|
||||
- `GetPage() int`: 获取页码，如果未设置则返回默认值1
|
||||
- `GetSize() int`: 获取每页数量，优先使用PageSize，如果未设置则使用Size，默认20，最大100
|
||||
- `GetOffset() int`: 计算数据库查询的偏移量
|
||||
|
||||
#### ParsePaginationRequest(r *http.Request) *PaginationRequest
|
||||
|
||||
从请求中解析分页参数（内部函数，Handler内部使用）。
|
||||
|
||||
## 状态码说明
|
||||
|
||||
@@ -406,18 +564,21 @@ func GetUser(w http.ResponseWriter, r *http.Request) {
|
||||
|
||||
2. **分页参数限制**：
|
||||
- page最小值为1
|
||||
- pageSize最小值为1，最大值为1000
|
||||
- pageSize最小值为1，最大值为100
|
||||
|
||||
3. **响应格式统一**：
|
||||
- 所有响应都遵循标准结构
|
||||
- timestamp为Unix时间戳（秒）
|
||||
|
||||
4. **错误处理**：
|
||||
- 使用Error方法返回业务错误
|
||||
- 使用SystemError返回系统错误
|
||||
- 使用BadRequest等返回HTTP级别的错误
|
||||
- 使用`Error`方法返回业务错误（HTTP 200，业务code非0）
|
||||
- 使用`SystemError`返回系统错误（HTTP 500）
|
||||
- 其他HTTP错误状态码（400, 401, 403, 404等）使用`WriteJSON`方法直接指定
|
||||
|
||||
5. **黑盒模式**：
|
||||
- 所有功能都通过Handler对象调用，无需传递`w`和`r`参数
|
||||
- 代码更简洁，减少调用方工作量
|
||||
|
||||
## 示例
|
||||
|
||||
完整示例请参考 `examples/http_example.go`
|
||||
|
||||
完整示例请参考 `examples/http_handler_example.go`
|
||||
|
||||
@@ -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()
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -2,12 +2,15 @@
|
||||
|
||||
## 概述
|
||||
|
||||
中间件工具提供了常用的HTTP中间件功能，包括CORS处理和时区管理。
|
||||
中间件工具提供了常用的HTTP中间件功能，包括CORS处理、时区管理、请求日志、Panic恢复和限流等。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- **CORS中间件**：支持跨域资源共享配置
|
||||
- **时区中间件**：从请求头读取时区信息，支持默认时区设置
|
||||
- **日志中间件**：自动记录每个HTTP请求的详细信息
|
||||
- **Recovery中间件**：捕获panic并恢复，防止服务崩溃
|
||||
- **限流中间件**：基于令牌桶算法的请求限流
|
||||
- **中间件链**：提供便捷的中间件链式调用
|
||||
|
||||
## CORS中间件
|
||||
@@ -121,7 +124,7 @@ corsHandler := middleware.CORS(corsConfig)(handler)
|
||||
|
||||
- 从请求头 `X-Timezone` 读取时区
|
||||
- 如果未传递时区信息，使用默认时区 `AsiaShanghai`
|
||||
- 时区信息存储到context中，可通过 `http.GetTimezone()` 获取
|
||||
- 时区信息存储到context中，可通过Handler的`GetTimezone()`方法获取
|
||||
- 自动验证时区有效性，无效时区会回退到默认时区
|
||||
|
||||
### 使用方法
|
||||
@@ -132,19 +135,21 @@ corsHandler := middleware.CORS(corsConfig)(handler)
|
||||
import (
|
||||
"net/http"
|
||||
"git.toowon.com/jimmy/go-common/middleware"
|
||||
"git.toowon.com/jimmy/go-common/http"
|
||||
commonhttp "git.toowon.com/jimmy/go-common/http"
|
||||
"git.toowon.com/jimmy/go-common/datetime"
|
||||
)
|
||||
|
||||
func handler(w http.ResponseWriter, r *http.Request) {
|
||||
// 从context获取时区
|
||||
timezone := http.GetTimezone(r)
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
|
||||
// 从Handler获取时区
|
||||
timezone := h.GetTimezone()
|
||||
|
||||
// 使用时区
|
||||
now := datetime.Now(timezone)
|
||||
datetime.FormatDateTime(now, timezone)
|
||||
|
||||
http.Success(w, map[string]interface{}{
|
||||
h.Success(map[string]interface{}{
|
||||
"timezone": timezone,
|
||||
"time": datetime.FormatDateTime(now),
|
||||
})
|
||||
@@ -183,13 +188,15 @@ func main() {
|
||||
```go
|
||||
import (
|
||||
"net/http"
|
||||
"git.toowon.com/jimmy/go-common/http"
|
||||
commonhttp "git.toowon.com/jimmy/go-common/http"
|
||||
"git.toowon.com/jimmy/go-common/datetime"
|
||||
)
|
||||
|
||||
func GetUserList(w http.ResponseWriter, r *http.Request) {
|
||||
// 从请求context获取时区
|
||||
timezone := http.GetTimezone(r)
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
|
||||
// 从Handler获取时区
|
||||
timezone := h.GetTimezone()
|
||||
|
||||
// 使用时区进行时间处理
|
||||
now := datetime.Now(timezone)
|
||||
@@ -199,7 +206,7 @@ func GetUserList(w http.ResponseWriter, r *http.Request) {
|
||||
endTime := datetime.EndOfDay(now, timezone)
|
||||
|
||||
// 返回数据
|
||||
http.Success(w, map[string]interface{}{
|
||||
h.Success(map[string]interface{}{
|
||||
"timezone": timezone,
|
||||
"startTime": datetime.FormatDateTime(startTime),
|
||||
"endTime": datetime.FormatDateTime(endTime),
|
||||
@@ -229,6 +236,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. **算法选择**：使用令牌桶算法，支持突发流量
|
||||
|
||||
## 中间件链
|
||||
|
||||
### 功能说明
|
||||
@@ -273,7 +645,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/datetime"
|
||||
)
|
||||
|
||||
func apiHandler(w http.ResponseWriter, r *http.Request) {
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
|
||||
// 从Handler获取时区
|
||||
timezone := h.GetTimezone()
|
||||
now := datetime.Now(timezone)
|
||||
|
||||
h.Success(map[string]interface{}{
|
||||
"message": "Hello",
|
||||
"timezone": timezone,
|
||||
"time": datetime.FormatDateTime(now),
|
||||
})
|
||||
}
|
||||
|
||||
func main() {
|
||||
// 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
|
||||
@@ -283,16 +755,18 @@ import (
|
||||
"net/http"
|
||||
|
||||
"git.toowon.com/jimmy/go-common/middleware"
|
||||
"git.toowon.com/jimmy/go-common/http"
|
||||
commonhttp "git.toowon.com/jimmy/go-common/http"
|
||||
"git.toowon.com/jimmy/go-common/datetime"
|
||||
)
|
||||
|
||||
func apiHandler(w http.ResponseWriter, r *http.Request) {
|
||||
// 获取时区
|
||||
timezone := http.GetTimezone(r)
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
|
||||
// 从Handler获取时区
|
||||
timezone := h.GetTimezone()
|
||||
now := datetime.Now(timezone)
|
||||
|
||||
http.Success(w, map[string]interface{}{
|
||||
h.Success(map[string]interface{}{
|
||||
"message": "Hello",
|
||||
"timezone": timezone,
|
||||
"time": datetime.FormatDateTime(now),
|
||||
@@ -300,23 +774,13 @@ func apiHandler(w http.ResponseWriter, r *http.Request) {
|
||||
}
|
||||
|
||||
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))
|
||||
@@ -332,7 +796,7 @@ import (
|
||||
"net/http"
|
||||
|
||||
"git.toowon.com/jimmy/go-common/middleware"
|
||||
"git.toowon.com/jimmy/go-common/http"
|
||||
commonhttp "git.toowon.com/jimmy/go-common/http"
|
||||
)
|
||||
|
||||
func main() {
|
||||
@@ -352,15 +816,17 @@ func main() {
|
||||
}
|
||||
|
||||
func getUsers(w http.ResponseWriter, r *http.Request) {
|
||||
timezone := http.GetTimezone(r)
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
timezone := h.GetTimezone()
|
||||
// 处理逻辑
|
||||
http.Success(w, nil)
|
||||
h.Success(nil)
|
||||
}
|
||||
|
||||
func getPosts(w http.ResponseWriter, r *http.Request) {
|
||||
timezone := http.GetTimezone(r)
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
timezone := h.GetTimezone()
|
||||
// 处理逻辑
|
||||
http.Success(w, nil)
|
||||
h.Success(nil)
|
||||
}
|
||||
```
|
||||
|
||||
@@ -400,6 +866,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
|
||||
@@ -420,19 +945,63 @@ func getPosts(w http.ResponseWriter, r *http.Request) {
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **CORS配置**：
|
||||
### 1. CORS配置
|
||||
- 生产环境建议明确指定允许的源，避免使用 "*"
|
||||
- 如果使用凭证（cookies），必须明确指定源，不能使用 "*"
|
||||
- CORS中间件应该在Recovery和Logging之后，以便正确处理预检请求
|
||||
|
||||
2. **时区处理**：
|
||||
### 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日志，优化性能瓶颈
|
||||
|
||||
|
||||
@@ -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）或使用环境变量 DATABASE_URL
|
||||
- `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
|
||||
|
||||
|
||||
@@ -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,
|
||||
)
|
||||
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
172
examples/factory_blackbox_example.go
Normal file
172
examples/factory_blackbox_example.go
Normal file
@@ -0,0 +1,172 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"log"
|
||||
"net/http"
|
||||
"time"
|
||||
|
||||
"git.toowon.com/jimmy/go-common/factory"
|
||||
commonhttp "git.toowon.com/jimmy/go-common/http"
|
||||
)
|
||||
|
||||
// 示例：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) {
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
|
||||
// 创建工厂（在处理器中也可以复用）
|
||||
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 != "" {
|
||||
h.Success(cached)
|
||||
return
|
||||
}
|
||||
|
||||
// 3. 记录日志（黑盒方法，推荐）
|
||||
fac.LogInfof(map[string]interface{}{
|
||||
"action": "list_users",
|
||||
"count": len(users),
|
||||
}, "查询用户列表")
|
||||
|
||||
// 4. 缓存结果
|
||||
fac.RedisSet(ctx, cacheKey, users, 5*time.Minute)
|
||||
|
||||
h.Success(users)
|
||||
}
|
||||
|
||||
// 文件上传
|
||||
func handleUpload(w http.ResponseWriter, r *http.Request) {
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
fac, _ := factory.NewFactoryFromFile("config.json")
|
||||
ctx := context.Background()
|
||||
|
||||
// 解析上传的文件
|
||||
file, header, err := r.FormFile("file")
|
||||
if err != nil {
|
||||
fac.LogError("文件上传失败: %v", err)
|
||||
h.Error(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)
|
||||
h.Error(500, "文件上传失败")
|
||||
return
|
||||
}
|
||||
|
||||
// 记录上传日志
|
||||
fac.LogInfof(map[string]interface{}{
|
||||
"filename": header.Filename,
|
||||
"size": header.Size,
|
||||
"url": url,
|
||||
}, "文件上传成功")
|
||||
|
||||
h.Success(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 == "" {
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
h.Error(401, "未授权")
|
||||
return
|
||||
}
|
||||
|
||||
// 从Redis验证token（黑盒方法）
|
||||
userID, err := fac.RedisGet(ctx, "token:"+token)
|
||||
if err != nil || userID == "" {
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
h.Error(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,
|
||||
}, "请求指标")
|
||||
})
|
||||
}
|
||||
@@ -1,95 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"log"
|
||||
|
||||
"git.toowon.com/jimmy/go-common/factory"
|
||||
"github.com/redis/go-redis/v9"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// 方式1：直接从配置文件创建工厂（推荐）
|
||||
fac, err := factory.NewFactoryFromFile("./config/example.json")
|
||||
if err != nil {
|
||||
log.Fatal("Failed to create factory:", err)
|
||||
}
|
||||
|
||||
// 直接获取数据库对象（已初始化，可直接使用）
|
||||
db, err := fac.GetDatabase()
|
||||
if err != nil {
|
||||
log.Printf("Database not available: %v", err)
|
||||
} else {
|
||||
// 直接使用数据库
|
||||
var count int64
|
||||
if err := db.Table("users").Count(&count).Error; err != nil {
|
||||
log.Printf("Failed to count users: %v", err)
|
||||
} else {
|
||||
fmt.Printf("User count: %d\n", count)
|
||||
}
|
||||
}
|
||||
|
||||
// 直接获取Redis客户端（已初始化，可直接使用）
|
||||
redisClient, err := fac.GetRedisClient()
|
||||
if err != nil {
|
||||
log.Printf("Redis not available: %v", err)
|
||||
} else {
|
||||
// 直接使用Redis客户端
|
||||
ctx := context.Background()
|
||||
val, err := redisClient.Get(ctx, "test_key").Result()
|
||||
if err != nil && err != redis.Nil {
|
||||
log.Printf("Redis error: %v", err)
|
||||
} else if err == redis.Nil {
|
||||
fmt.Println("Redis key not found")
|
||||
} else {
|
||||
fmt.Printf("Redis value: %s\n", val)
|
||||
}
|
||||
}
|
||||
|
||||
// 获取邮件客户端（已初始化，可直接使用）
|
||||
emailClient, err := fac.GetEmailClient()
|
||||
if err != nil {
|
||||
log.Printf("Email client not available: %v", err)
|
||||
} else {
|
||||
// 直接使用
|
||||
err = emailClient.SendSimple(
|
||||
[]string{"recipient@example.com"},
|
||||
"测试邮件",
|
||||
"这是测试内容",
|
||||
)
|
||||
if err != nil {
|
||||
log.Printf("Failed to send email: %v", err)
|
||||
} else {
|
||||
fmt.Println("Email sent successfully")
|
||||
}
|
||||
}
|
||||
|
||||
// 获取短信客户端（已初始化，可直接使用）
|
||||
smsClient, err := fac.GetSMSClient()
|
||||
if err != nil {
|
||||
log.Printf("SMS client not available: %v", err)
|
||||
} else {
|
||||
// 直接使用
|
||||
resp, err := smsClient.SendSimple(
|
||||
[]string{"13800138000"},
|
||||
map[string]string{"code": "123456"},
|
||||
)
|
||||
if err != nil {
|
||||
log.Printf("Failed to send SMS: %v", err)
|
||||
} else {
|
||||
fmt.Printf("SMS sent: %s\n", resp.RequestID)
|
||||
}
|
||||
}
|
||||
|
||||
// 获取日志记录器（已初始化，可直接使用）
|
||||
logger, err := fac.GetLogger()
|
||||
if err != nil {
|
||||
log.Printf("Logger not available: %v", err)
|
||||
} else {
|
||||
logger.Info("Application started")
|
||||
logger.Debug("Debug message")
|
||||
logger.Warn("Warning message")
|
||||
logger.Error("Error message")
|
||||
}
|
||||
}
|
||||
@@ -1,101 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"log"
|
||||
"net/http"
|
||||
|
||||
"git.toowon.com/jimmy/go-common/http"
|
||||
)
|
||||
|
||||
// 用户结构
|
||||
type User struct {
|
||||
ID int64 `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Email string `json:"email"`
|
||||
}
|
||||
|
||||
// 获取用户列表
|
||||
func GetUserList(w http.ResponseWriter, r *http.Request) {
|
||||
// 获取分页参数
|
||||
page, pageSize := http.GetPaginationParams(r)
|
||||
|
||||
// 获取查询参数
|
||||
keyword := http.GetQuery(r, "keyword", "")
|
||||
|
||||
// 模拟查询数据
|
||||
users := []User{
|
||||
{ID: 1, Name: "User1", Email: "user1@example.com"},
|
||||
{ID: 2, Name: "User2", Email: "user2@example.com"},
|
||||
}
|
||||
total := int64(100)
|
||||
|
||||
// 返回分页响应
|
||||
http.SuccessPage(w, users, total, page, pageSize)
|
||||
}
|
||||
|
||||
// 创建用户
|
||||
func CreateUser(w http.ResponseWriter, r *http.Request) {
|
||||
// 解析请求体
|
||||
var req struct {
|
||||
Name string `json:"name"`
|
||||
Email string `json:"email"`
|
||||
}
|
||||
|
||||
if err := http.ParseJSON(r, &req); err != nil {
|
||||
http.BadRequest(w, "请求参数解析失败")
|
||||
return
|
||||
}
|
||||
|
||||
// 参数验证
|
||||
if req.Name == "" {
|
||||
http.Error(w, 1001, "用户名不能为空")
|
||||
return
|
||||
}
|
||||
|
||||
// 模拟创建用户
|
||||
user := User{
|
||||
ID: 1,
|
||||
Name: req.Name,
|
||||
Email: req.Email,
|
||||
}
|
||||
|
||||
// 返回成功响应
|
||||
http.SuccessWithMessage(w, "创建成功", user)
|
||||
}
|
||||
|
||||
// 获取用户详情
|
||||
func GetUser(w http.ResponseWriter, r *http.Request) {
|
||||
// 获取查询参数
|
||||
id := http.GetQueryInt64(r, "id", 0)
|
||||
|
||||
if id == 0 {
|
||||
http.BadRequest(w, "用户ID不能为空")
|
||||
return
|
||||
}
|
||||
|
||||
// 模拟查询用户
|
||||
if id == 1 {
|
||||
user := User{ID: 1, Name: "User1", Email: "user1@example.com"}
|
||||
http.Success(w, user)
|
||||
} else {
|
||||
http.Error(w, 1002, "用户不存在")
|
||||
}
|
||||
}
|
||||
|
||||
func main() {
|
||||
http.HandleFunc("/users", func(w http.ResponseWriter, r *http.Request) {
|
||||
switch r.Method {
|
||||
case http.MethodGet:
|
||||
GetUserList(w, r)
|
||||
case http.MethodPost:
|
||||
CreateUser(w, r)
|
||||
default:
|
||||
http.NotFound(w, "方法不支持")
|
||||
}
|
||||
})
|
||||
|
||||
http.HandleFunc("/user", GetUser)
|
||||
|
||||
log.Println("Server started on :8080")
|
||||
log.Fatal(http.ListenAndServe(":8080", nil))
|
||||
}
|
||||
109
examples/http_handler_example.go
Normal file
109
examples/http_handler_example.go
Normal file
@@ -0,0 +1,109 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"log"
|
||||
"net/http"
|
||||
|
||||
commonhttp "git.toowon.com/jimmy/go-common/http"
|
||||
)
|
||||
|
||||
// 用户结构
|
||||
type User struct {
|
||||
ID int64 `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Email string `json:"email"`
|
||||
}
|
||||
|
||||
// 获取用户列表（使用Handler黑盒模式）
|
||||
func GetUserList(h *commonhttp.Handler) {
|
||||
// 获取分页参数（简洁方式）
|
||||
pagination := h.ParsePaginationRequest()
|
||||
page := pagination.GetPage()
|
||||
pageSize := pagination.GetSize()
|
||||
|
||||
// 获取查询参数（简洁方式）
|
||||
_ = h.GetQuery("keyword", "") // 示例：获取查询参数
|
||||
|
||||
// 模拟查询数据
|
||||
users := []User{
|
||||
{ID: 1, Name: "User1", Email: "user1@example.com"},
|
||||
{ID: 2, Name: "User2", Email: "user2@example.com"},
|
||||
}
|
||||
total := int64(100)
|
||||
|
||||
// 返回分页响应（简洁方式）
|
||||
h.SuccessPage(users, total, page, pageSize)
|
||||
}
|
||||
|
||||
// 创建用户（使用Handler黑盒模式）
|
||||
func CreateUser(h *commonhttp.Handler) {
|
||||
// 解析请求体（简洁方式）
|
||||
var req struct {
|
||||
Name string `json:"name"`
|
||||
Email string `json:"email"`
|
||||
}
|
||||
|
||||
if err := h.ParseJSON(&req); err != nil {
|
||||
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
|
||||
return
|
||||
}
|
||||
|
||||
// 参数验证
|
||||
if req.Name == "" {
|
||||
h.Error(1001, "用户名不能为空")
|
||||
return
|
||||
}
|
||||
|
||||
// 模拟创建用户
|
||||
user := User{
|
||||
ID: 1,
|
||||
Name: req.Name,
|
||||
Email: req.Email,
|
||||
}
|
||||
|
||||
// 返回成功响应（简洁方式）
|
||||
h.SuccessWithMessage("创建成功", user)
|
||||
}
|
||||
|
||||
// 获取用户详情（使用Handler黑盒模式）
|
||||
func GetUser(h *commonhttp.Handler) {
|
||||
// 获取查询参数（简洁方式）
|
||||
id := h.GetQueryInt64("id", 0)
|
||||
|
||||
if id == 0 {
|
||||
h.WriteJSON(http.StatusBadRequest, 400, "用户ID不能为空", nil)
|
||||
return
|
||||
}
|
||||
|
||||
// 模拟查询用户
|
||||
if id == 1 {
|
||||
user := User{ID: 1, Name: "User1", Email: "user1@example.com"}
|
||||
h.Success(user)
|
||||
} else {
|
||||
h.Error(1002, "用户不存在")
|
||||
}
|
||||
}
|
||||
|
||||
func main() {
|
||||
// 方式1：使用HandleFunc包装器（推荐，最简洁）
|
||||
http.HandleFunc("/users", commonhttp.HandleFunc(func(h *commonhttp.Handler) {
|
||||
switch h.Request().Method {
|
||||
case http.MethodGet:
|
||||
GetUserList(h)
|
||||
case http.MethodPost:
|
||||
CreateUser(h)
|
||||
default:
|
||||
h.WriteJSON(http.StatusMethodNotAllowed, 405, "方法不支持", nil)
|
||||
}
|
||||
}))
|
||||
|
||||
// 方式2：手动创建Handler（需要更多控制时）
|
||||
http.HandleFunc("/user", func(w http.ResponseWriter, r *http.Request) {
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
GetUser(h)
|
||||
})
|
||||
|
||||
log.Println("Server started on :8080")
|
||||
log.Fatal(http.ListenAndServe(":8080", nil))
|
||||
}
|
||||
|
||||
61
examples/http_pagination_example.go
Normal file
61
examples/http_pagination_example.go
Normal file
@@ -0,0 +1,61 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"log"
|
||||
"net/http"
|
||||
|
||||
commonhttp "git.toowon.com/jimmy/go-common/http"
|
||||
)
|
||||
|
||||
// ListUserRequest 用户列表请求（包含分页字段）
|
||||
type ListUserRequest struct {
|
||||
Keyword string `json:"keyword"`
|
||||
commonhttp.PaginationRequest // 嵌入分页请求结构
|
||||
}
|
||||
|
||||
// User 用户结构
|
||||
type User struct {
|
||||
ID int64 `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Email string `json:"email"`
|
||||
}
|
||||
|
||||
// 获取用户列表（使用Handler和PaginationRequest）
|
||||
func GetUserList(h *commonhttp.Handler) {
|
||||
var req ListUserRequest
|
||||
|
||||
// 方式1：从JSON请求体解析（分页字段会自动解析）
|
||||
if h.Request().Method == http.MethodPost {
|
||||
if err := h.ParseJSON(&req); err != nil {
|
||||
h.WriteJSON(http.StatusBadRequest, 400, "请求参数解析失败", nil)
|
||||
return
|
||||
}
|
||||
} else {
|
||||
// 方式2：从查询参数解析分页
|
||||
pagination := h.ParsePaginationRequest()
|
||||
req.PaginationRequest = *pagination
|
||||
req.Keyword = h.GetQuery("keyword", "")
|
||||
}
|
||||
|
||||
// 使用分页方法
|
||||
page := req.GetPage() // 获取页码（默认1）
|
||||
size := req.GetSize() // 获取每页数量（默认20，最大100）
|
||||
_ = req.GetOffset() // 计算偏移量
|
||||
|
||||
// 模拟查询数据
|
||||
users := []User{
|
||||
{ID: 1, Name: "User1", Email: "user1@example.com"},
|
||||
{ID: 2, Name: "User2", Email: "user2@example.com"},
|
||||
}
|
||||
total := int64(100)
|
||||
|
||||
// 返回分页响应
|
||||
h.SuccessPage(users, total, page, size)
|
||||
}
|
||||
|
||||
func main() {
|
||||
http.HandleFunc("/users", commonhttp.HandleFunc(GetUserList))
|
||||
|
||||
log.Println("Server started on :8080")
|
||||
log.Fatal(http.ListenAndServe(":8080", nil))
|
||||
}
|
||||
@@ -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")
|
||||
|
||||
@@ -1,64 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"log"
|
||||
"net/http"
|
||||
|
||||
"git.toowon.com/jimmy/go-common/datetime"
|
||||
"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 := chain.ThenFunc(apiHandler)
|
||||
|
||||
// 注册路由
|
||||
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请求
|
||||
func apiHandler(w http.ResponseWriter, r *http.Request) {
|
||||
// 从context获取时区
|
||||
timezone := http.GetTimezone(r)
|
||||
|
||||
// 使用时区进行时间处理
|
||||
now := datetime.Now(timezone)
|
||||
startOfDay := datetime.StartOfDay(now, timezone)
|
||||
endOfDay := datetime.EndOfDay(now, timezone)
|
||||
|
||||
// 返回响应
|
||||
http.Success(w, map[string]interface{}{
|
||||
"message": "Hello from API",
|
||||
"timezone": timezone,
|
||||
"currentTime": datetime.FormatDateTime(now),
|
||||
"startOfDay": datetime.FormatDateTime(startOfDay),
|
||||
"endOfDay": datetime.FormatDateTime(endOfDay),
|
||||
})
|
||||
}
|
||||
|
||||
42
examples/middleware_simple_example.go
Normal file
42
examples/middleware_simple_example.go
Normal file
@@ -0,0 +1,42 @@
|
||||
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) {
|
||||
h := commonhttp.NewHandler(w, r)
|
||||
|
||||
// 获取时区
|
||||
timezone := h.GetTimezone()
|
||||
|
||||
// 返回响应
|
||||
h.Success(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))
|
||||
}
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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.")
|
||||
}
|
||||
|
||||
134
examples/migrations/README.md
Normal file
134
examples/migrations/README.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# 数据库迁移示例
|
||||
|
||||
这个目录包含了数据库迁移的示例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：环境变量（Docker友好）
|
||||
|
||||
```bash
|
||||
DATABASE_URL="mysql://root:password@localhost:3306/mydb" go run migrate.go up
|
||||
```
|
||||
|
||||
**Docker 中**：
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
app:
|
||||
environment:
|
||||
DATABASE_URL: mysql://root:password@db:3306/mydb
|
||||
command: sh -c "go run migrate.go up && ./app"
|
||||
```
|
||||
|
||||
**注意**：Docker 中使用服务名（`db`），不是 `localhost`
|
||||
|
||||
## 更多信息
|
||||
|
||||
- [数据库迁移完整指南](../../MIGRATION.md) ⭐
|
||||
- [详细功能文档](../../docs/migration.md)
|
||||
@@ -0,0 +1,4 @@
|
||||
-- Rollback: Drop users table
|
||||
|
||||
DROP TABLE IF EXISTS users;
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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,
|
||||
)
|
||||
|
||||
|
||||
@@ -3,12 +3,17 @@ package factory
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"io"
|
||||
"net/http"
|
||||
"time"
|
||||
|
||||
"git.toowon.com/jimmy/go-common/config"
|
||||
"git.toowon.com/jimmy/go-common/email"
|
||||
"git.toowon.com/jimmy/go-common/logger"
|
||||
"git.toowon.com/jimmy/go-common/middleware"
|
||||
"git.toowon.com/jimmy/go-common/migration"
|
||||
"git.toowon.com/jimmy/go-common/sms"
|
||||
"git.toowon.com/jimmy/go-common/storage"
|
||||
"github.com/redis/go-redis/v9"
|
||||
"gorm.io/driver/mysql"
|
||||
"gorm.io/driver/postgres"
|
||||
@@ -16,9 +21,50 @@ import (
|
||||
"gorm.io/gorm"
|
||||
)
|
||||
|
||||
// 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
|
||||
storage storage.Storage // 存储实例（延迟初始化）
|
||||
logger *logger.Logger // 日志实例（延迟初始化）
|
||||
email *email.Email // 邮件客户端（延迟初始化）
|
||||
sms *sms.SMS // 短信客户端（延迟初始化）
|
||||
db *gorm.DB // 数据库连接（延迟初始化）
|
||||
redis *redis.Client // Redis客户端（延迟初始化）
|
||||
}
|
||||
|
||||
// NewFactory 创建工厂实例
|
||||
@@ -38,37 +84,308 @@ func NewFactoryFromFile(filePath string) (*Factory, error) {
|
||||
return NewFactory(cfg), nil
|
||||
}
|
||||
|
||||
// GetEmailClient 获取邮件客户端（已初始化）
|
||||
// 返回已初始化的邮件客户端对象，可直接使用
|
||||
func (f *Factory) GetEmailClient() (*email.Email, error) {
|
||||
// getEmailClient 获取邮件客户端（内部方法，延迟初始化）
|
||||
func (f *Factory) getEmailClient() (*email.Email, error) {
|
||||
if f.email != nil {
|
||||
return f.email, nil
|
||||
}
|
||||
|
||||
if f.cfg.Email == nil {
|
||||
return nil, fmt.Errorf("email config is nil")
|
||||
}
|
||||
return email.NewEmail(f.cfg.Email)
|
||||
|
||||
e, err := email.NewEmail(f.cfg.Email)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("failed to create email client: %w", err)
|
||||
}
|
||||
|
||||
f.email = e
|
||||
return e, nil
|
||||
}
|
||||
|
||||
// SendEmail 发送邮件（黑盒模式，推荐使用）
|
||||
// 自动使用配置文件中的SMTP配置发送邮件
|
||||
// to: 收件人列表
|
||||
// subject: 邮件主题
|
||||
// body: 邮件正文（纯文本）
|
||||
// htmlBody: HTML正文（可选，如果设置了会优先使用）
|
||||
func (f *Factory) SendEmail(to []string, subject, body string, htmlBody ...string) error {
|
||||
e, err := f.getEmailClient()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
msg := &email.Message{
|
||||
To: to,
|
||||
Subject: subject,
|
||||
Body: body,
|
||||
}
|
||||
|
||||
if len(htmlBody) > 0 && htmlBody[0] != "" {
|
||||
msg.HTMLBody = htmlBody[0]
|
||||
}
|
||||
|
||||
return e.Send(msg)
|
||||
}
|
||||
|
||||
// getSMSClient 获取短信客户端（内部方法，延迟初始化）
|
||||
func (f *Factory) getSMSClient() (*sms.SMS, error) {
|
||||
if f.sms != nil {
|
||||
return f.sms, nil
|
||||
}
|
||||
|
||||
// GetSMSClient 获取短信客户端（已初始化）
|
||||
// 返回已初始化的短信客户端对象，可直接使用
|
||||
func (f *Factory) GetSMSClient() (*sms.SMS, error) {
|
||||
if f.cfg.SMS == nil {
|
||||
return nil, fmt.Errorf("SMS config is nil")
|
||||
}
|
||||
return sms.NewSMS(f.cfg.SMS)
|
||||
|
||||
s, err := sms.NewSMS(f.cfg.SMS)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("failed to create SMS client: %w", err)
|
||||
}
|
||||
|
||||
// GetLogger 获取日志记录器（已初始化）
|
||||
// 返回已初始化的日志记录器对象，可直接使用
|
||||
func (f *Factory) GetLogger() (*logger.Logger, error) {
|
||||
f.sms = s
|
||||
return s, nil
|
||||
}
|
||||
|
||||
// SendSMS 发送短信（黑盒模式，推荐使用）
|
||||
// 自动使用配置文件中的阿里云短信配置发送短信
|
||||
// phoneNumbers: 手机号列表
|
||||
// templateParam: 模板参数（map或JSON字符串）
|
||||
// templateCode: 模板代码（可选，如果为空使用配置中的模板代码）
|
||||
func (f *Factory) SendSMS(phoneNumbers []string, templateParam interface{}, templateCode ...string) (*sms.SendResponse, error) {
|
||||
s, err := f.getSMSClient()
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
req := &sms.SendRequest{
|
||||
PhoneNumbers: phoneNumbers,
|
||||
TemplateParam: templateParam,
|
||||
}
|
||||
|
||||
if len(templateCode) > 0 && templateCode[0] != "" {
|
||||
req.TemplateCode = templateCode[0]
|
||||
}
|
||||
|
||||
return s.Send(req)
|
||||
}
|
||||
|
||||
// getLogger 获取日志记录器（内部方法，延迟初始化）
|
||||
func (f *Factory) getLogger() (*logger.Logger, error) {
|
||||
if f.logger != nil {
|
||||
return f.logger, nil
|
||||
}
|
||||
|
||||
var l *logger.Logger
|
||||
var err error
|
||||
if f.cfg.Logger == nil {
|
||||
// 如果没有配置，使用默认配置创建
|
||||
return logger.NewLogger(nil)
|
||||
}
|
||||
return logger.NewLogger(f.cfg.Logger)
|
||||
l, err = logger.NewLogger(nil)
|
||||
} else {
|
||||
l, err = logger.NewLogger(f.cfg.Logger)
|
||||
}
|
||||
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("failed to create logger: %w", err)
|
||||
}
|
||||
|
||||
f.logger = l
|
||||
return l, nil
|
||||
}
|
||||
|
||||
// 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{}) {
|
||||
l, err := f.getLogger()
|
||||
if err != nil {
|
||||
// 如果日志初始化失败，使用标准输出
|
||||
if len(args) > 0 {
|
||||
fmt.Printf("[DEBUG] "+message+"\n", args...)
|
||||
} else {
|
||||
fmt.Printf("[DEBUG] %s\n", message)
|
||||
}
|
||||
return
|
||||
}
|
||||
if len(args) > 0 {
|
||||
l.Debug(message, args...)
|
||||
} else {
|
||||
l.Debug(message)
|
||||
}
|
||||
}
|
||||
|
||||
// LogDebugf 记录调试日志（带字段，黑盒模式，推荐使用）
|
||||
// 自动使用配置文件中的logger配置
|
||||
// fields: 日志字段
|
||||
// message: 日志消息
|
||||
// args: 格式化参数（可选）
|
||||
func (f *Factory) LogDebugf(fields map[string]interface{}, message string, args ...interface{}) {
|
||||
l, err := f.getLogger()
|
||||
if err != nil {
|
||||
// 如果日志初始化失败，使用标准输出
|
||||
if len(args) > 0 {
|
||||
fmt.Printf("[DEBUG] "+message+"\n", args...)
|
||||
} else {
|
||||
fmt.Printf("[DEBUG] %s\n", message)
|
||||
}
|
||||
return
|
||||
}
|
||||
l.Debugf(fields, message, args...)
|
||||
}
|
||||
|
||||
// LogInfo 记录信息日志（黑盒模式，推荐使用）
|
||||
// 自动使用配置文件中的logger配置
|
||||
// message: 日志消息
|
||||
// args: 格式化参数（可选）
|
||||
func (f *Factory) LogInfo(message string, args ...interface{}) {
|
||||
l, err := f.getLogger()
|
||||
if err != nil {
|
||||
// 如果日志初始化失败，使用标准输出
|
||||
if len(args) > 0 {
|
||||
fmt.Printf("[INFO] "+message+"\n", args...)
|
||||
} else {
|
||||
fmt.Printf("[INFO] %s\n", message)
|
||||
}
|
||||
return
|
||||
}
|
||||
if len(args) > 0 {
|
||||
l.Info(message, args...)
|
||||
} else {
|
||||
l.Info(message)
|
||||
}
|
||||
}
|
||||
|
||||
// LogInfof 记录信息日志（带字段，黑盒模式，推荐使用）
|
||||
// 自动使用配置文件中的logger配置
|
||||
// fields: 日志字段
|
||||
// message: 日志消息
|
||||
// args: 格式化参数（可选）
|
||||
func (f *Factory) LogInfof(fields map[string]interface{}, message string, args ...interface{}) {
|
||||
l, err := f.getLogger()
|
||||
if err != nil {
|
||||
// 如果日志初始化失败，使用标准输出
|
||||
if len(args) > 0 {
|
||||
fmt.Printf("[INFO] "+message+"\n", args...)
|
||||
} else {
|
||||
fmt.Printf("[INFO] %s\n", message)
|
||||
}
|
||||
return
|
||||
}
|
||||
l.Infof(fields, message, args...)
|
||||
}
|
||||
|
||||
// LogWarn 记录警告日志（黑盒模式，推荐使用）
|
||||
// 自动使用配置文件中的logger配置
|
||||
// message: 日志消息
|
||||
// args: 格式化参数（可选）
|
||||
func (f *Factory) LogWarn(message string, args ...interface{}) {
|
||||
l, err := f.getLogger()
|
||||
if err != nil {
|
||||
// 如果日志初始化失败，使用标准输出
|
||||
if len(args) > 0 {
|
||||
fmt.Printf("[WARN] "+message+"\n", args...)
|
||||
} else {
|
||||
fmt.Printf("[WARN] %s\n", message)
|
||||
}
|
||||
return
|
||||
}
|
||||
if len(args) > 0 {
|
||||
l.Warn(message, args...)
|
||||
} else {
|
||||
l.Warn(message)
|
||||
}
|
||||
}
|
||||
|
||||
// LogWarnf 记录警告日志（带字段，黑盒模式，推荐使用）
|
||||
// 自动使用配置文件中的logger配置
|
||||
// fields: 日志字段
|
||||
// message: 日志消息
|
||||
// args: 格式化参数（可选）
|
||||
func (f *Factory) LogWarnf(fields map[string]interface{}, message string, args ...interface{}) {
|
||||
l, err := f.getLogger()
|
||||
if err != nil {
|
||||
// 如果日志初始化失败，使用标准输出
|
||||
if len(args) > 0 {
|
||||
fmt.Printf("[WARN] "+message+"\n", args...)
|
||||
} else {
|
||||
fmt.Printf("[WARN] %s\n", message)
|
||||
}
|
||||
return
|
||||
}
|
||||
l.Warnf(fields, message, args...)
|
||||
}
|
||||
|
||||
// LogError 记录错误日志（黑盒模式，推荐使用）
|
||||
// 自动使用配置文件中的logger配置
|
||||
// message: 日志消息
|
||||
// args: 格式化参数（可选）
|
||||
func (f *Factory) LogError(message string, args ...interface{}) {
|
||||
l, err := f.getLogger()
|
||||
if err != nil {
|
||||
// 如果日志初始化失败，使用标准输出
|
||||
if len(args) > 0 {
|
||||
fmt.Printf("[ERROR] "+message+"\n", args...)
|
||||
} else {
|
||||
fmt.Printf("[ERROR] %s\n", message)
|
||||
}
|
||||
return
|
||||
}
|
||||
if len(args) > 0 {
|
||||
l.Error(message, args...)
|
||||
} else {
|
||||
l.Error(message)
|
||||
}
|
||||
}
|
||||
|
||||
// LogErrorf 记录错误日志（带字段，黑盒模式，推荐使用）
|
||||
// 自动使用配置文件中的logger配置
|
||||
// fields: 日志字段
|
||||
// message: 日志消息
|
||||
// args: 格式化参数（可选）
|
||||
func (f *Factory) LogErrorf(fields map[string]interface{}, message string, args ...interface{}) {
|
||||
l, err := f.getLogger()
|
||||
if err != nil {
|
||||
// 如果日志初始化失败，使用标准输出
|
||||
if len(args) > 0 {
|
||||
fmt.Printf("[ERROR] "+message+"\n", args...)
|
||||
} else {
|
||||
fmt.Printf("[ERROR] %s\n", message)
|
||||
}
|
||||
return
|
||||
}
|
||||
l.Errorf(fields, message, args...)
|
||||
}
|
||||
|
||||
// getDatabase 获取数据库连接对象（内部方法，延迟初始化）
|
||||
func (f *Factory) getDatabase() (*gorm.DB, error) {
|
||||
if f.db != nil {
|
||||
return f.db, nil
|
||||
}
|
||||
|
||||
// GetDatabase 获取数据库连接对象（已初始化）
|
||||
// 返回已初始化的GORM数据库对象，可直接使用
|
||||
func (f *Factory) GetDatabase() (*gorm.DB, error) {
|
||||
if f.cfg.Database == nil {
|
||||
return nil, fmt.Errorf("database config is nil")
|
||||
}
|
||||
@@ -112,12 +429,34 @@ func (f *Factory) GetDatabase() (*gorm.DB, error) {
|
||||
sqlDB.SetConnMaxLifetime(time.Duration(f.cfg.Database.ConnMaxLifetime) * time.Second)
|
||||
}
|
||||
|
||||
f.db = db
|
||||
return db, nil
|
||||
}
|
||||
|
||||
// GetRedisClient 获取Redis客户端对象（已初始化）
|
||||
// 返回已初始化的Redis客户端对象，可直接使用
|
||||
func (f *Factory) GetRedisClient() (*redis.Client, error) {
|
||||
// GetDatabase 获取数据库连接对象（推荐使用）
|
||||
// 返回已初始化的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()
|
||||
}
|
||||
|
||||
// getRedisClient 获取Redis客户端对象（内部方法，延迟初始化）
|
||||
func (f *Factory) getRedisClient() (*redis.Client, error) {
|
||||
if f.redis != nil {
|
||||
return f.redis, nil
|
||||
}
|
||||
|
||||
if f.cfg.Redis == nil {
|
||||
return nil, fmt.Errorf("redis config is nil")
|
||||
}
|
||||
@@ -169,17 +508,349 @@ func (f *Factory) GetRedisClient() (*redis.Client, error) {
|
||||
return nil, fmt.Errorf("failed to connect to redis: %w", err)
|
||||
}
|
||||
|
||||
f.redis = client
|
||||
return client, nil
|
||||
}
|
||||
|
||||
// GetRedisConfig 获取Redis配置（用于创建Redis客户端）
|
||||
// 返回Redis配置对象，调用方可以使用此配置创建Redis客户端
|
||||
// 注意：推荐使用 GetRedisClient 方法直接获取已初始化的客户端
|
||||
func (f *Factory) GetRedisConfig() *config.RedisConfig {
|
||||
return f.cfg.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()
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
|
||||
result, err := client.Get(ctx, key).Result()
|
||||
if err == redis.Nil {
|
||||
return "", nil // key不存在，返回空字符串
|
||||
}
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("failed to get redis key: %w", err)
|
||||
}
|
||||
|
||||
return result, nil
|
||||
}
|
||||
|
||||
// RedisSet 设置Redis值（黑盒模式，推荐使用）
|
||||
// 自动使用配置文件中的Redis配置
|
||||
// key: Redis键
|
||||
// value: Redis值
|
||||
// expiration: 过期时间（可选，0表示不过期）
|
||||
func (f *Factory) RedisSet(ctx context.Context, key string, value interface{}, expiration ...time.Duration) error {
|
||||
client, err := f.getRedisClient()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
var exp time.Duration
|
||||
if len(expiration) > 0 {
|
||||
exp = expiration[0]
|
||||
}
|
||||
|
||||
err = client.Set(ctx, key, value, exp).Err()
|
||||
if err != nil {
|
||||
return fmt.Errorf("failed to set redis key: %w", err)
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// RedisDelete 删除Redis键（黑盒模式，推荐使用）
|
||||
// 自动使用配置文件中的Redis配置
|
||||
// keys: Redis键列表
|
||||
func (f *Factory) RedisDelete(ctx context.Context, keys ...string) error {
|
||||
if len(keys) == 0 {
|
||||
return nil
|
||||
}
|
||||
|
||||
client, err := f.getRedisClient()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
err = client.Del(ctx, keys...).Err()
|
||||
if err != nil {
|
||||
return fmt.Errorf("failed to delete redis keys: %w", err)
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// RedisExists 检查Redis键是否存在（黑盒模式，推荐使用）
|
||||
// 自动使用配置文件中的Redis配置
|
||||
// key: Redis键
|
||||
func (f *Factory) RedisExists(ctx context.Context, key string) (bool, error) {
|
||||
client, err := f.getRedisClient()
|
||||
if err != nil {
|
||||
return false, err
|
||||
}
|
||||
|
||||
count, err := client.Exists(ctx, key).Result()
|
||||
if err != nil {
|
||||
return false, fmt.Errorf("failed to check redis key existence: %w", err)
|
||||
}
|
||||
|
||||
return count > 0, nil
|
||||
}
|
||||
|
||||
// GetConfig 获取配置对象
|
||||
func (f *Factory) GetConfig() *config.Config {
|
||||
return f.cfg
|
||||
}
|
||||
|
||||
// getStorage 获取存储实例（内部方法，延迟初始化）
|
||||
func (f *Factory) getStorage() (storage.Storage, error) {
|
||||
if f.storage != nil {
|
||||
return f.storage, nil
|
||||
}
|
||||
|
||||
// 根据配置自动选择存储类型
|
||||
// 优先级：MinIO > OSS
|
||||
var storageType storage.StorageType
|
||||
if f.cfg.MinIO != nil {
|
||||
storageType = storage.StorageTypeMinIO
|
||||
} else if f.cfg.OSS != nil {
|
||||
storageType = storage.StorageTypeOSS
|
||||
} else {
|
||||
return nil, fmt.Errorf("no storage config found (OSS or MinIO)")
|
||||
}
|
||||
|
||||
// 创建存储实例
|
||||
s, err := storage.NewStorage(storageType, f.cfg)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("failed to create storage: %w", err)
|
||||
}
|
||||
|
||||
f.storage = s
|
||||
return s, nil
|
||||
}
|
||||
|
||||
// UploadFile 上传文件（黑盒模式，推荐使用）
|
||||
// 自动根据配置选择存储类型（OSS 或 MinIO），无需关心内部实现
|
||||
// ctx: 上下文
|
||||
// objectKey: 对象键（文件路径）
|
||||
// reader: 文件内容
|
||||
// contentType: 文件类型（可选）
|
||||
// 返回文件访问URL和错误
|
||||
func (f *Factory) UploadFile(ctx context.Context, objectKey string, reader io.Reader, contentType ...string) (string, error) {
|
||||
s, err := f.getStorage()
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
|
||||
// 上传文件
|
||||
err = s.Upload(ctx, objectKey, reader, contentType...)
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("failed to upload file: %w", err)
|
||||
}
|
||||
|
||||
// 获取文件URL
|
||||
url, err := s.GetURL(objectKey, 0)
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("failed to get file URL: %w", err)
|
||||
}
|
||||
|
||||
return url, nil
|
||||
}
|
||||
|
||||
// GetFileURL 获取文件访问URL（黑盒模式，推荐使用）
|
||||
// 自动根据配置选择存储类型，返回文件的访问URL
|
||||
// objectKey: 对象键（文件路径）
|
||||
// expires: 过期时间（秒），0表示永久有效
|
||||
func (f *Factory) GetFileURL(objectKey string, expires int64) (string, error) {
|
||||
s, err := f.getStorage()
|
||||
if err != nil {
|
||||
return "", err
|
||||
}
|
||||
|
||||
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)
|
||||
}
|
||||
|
||||
// 创建迁移器
|
||||
migrator := migration.NewMigrator(db)
|
||||
|
||||
// 自动发现并加载迁移文件
|
||||
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)
|
||||
}
|
||||
|
||||
// 创建迁移器
|
||||
migrator := migration.NewMigrator(db)
|
||||
|
||||
// 加载迁移文件
|
||||
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
|
||||
}
|
||||
|
||||
29
go.mod
29
go.mod
@@ -1,8 +1,12 @@
|
||||
module git.toowon.com/jimmy/go-common
|
||||
|
||||
go 1.21
|
||||
go 1.23.0
|
||||
|
||||
toolchain go1.24.10
|
||||
|
||||
require (
|
||||
github.com/minio/minio-go/v7 v7.0.97
|
||||
github.com/redis/go-redis/v9 v9.17.1
|
||||
gorm.io/driver/mysql v1.5.2
|
||||
gorm.io/driver/postgres v1.6.0
|
||||
gorm.io/driver/sqlite v1.6.0
|
||||
@@ -12,16 +16,31 @@ require (
|
||||
require (
|
||||
github.com/cespare/xxhash/v2 v2.3.0 // indirect
|
||||
github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
|
||||
github.com/dustin/go-humanize v1.0.1 // indirect
|
||||
github.com/go-ini/ini v1.67.0 // indirect
|
||||
github.com/go-sql-driver/mysql v1.7.1 // indirect
|
||||
github.com/google/uuid v1.6.0 // indirect
|
||||
github.com/jackc/pgpassfile v1.0.0 // indirect
|
||||
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
|
||||
github.com/jackc/pgx/v5 v5.6.0 // indirect
|
||||
github.com/jackc/puddle/v2 v2.2.2 // indirect
|
||||
github.com/jinzhu/inflection v1.0.0 // indirect
|
||||
github.com/jinzhu/now v1.1.5 // indirect
|
||||
github.com/klauspost/compress v1.18.0 // indirect
|
||||
github.com/klauspost/cpuid/v2 v2.2.11 // indirect
|
||||
github.com/klauspost/crc32 v1.3.0 // indirect
|
||||
github.com/kr/text v0.2.0 // indirect
|
||||
github.com/mattn/go-sqlite3 v1.14.22 // indirect
|
||||
github.com/redis/go-redis/v9 v9.17.1 // indirect
|
||||
golang.org/x/crypto v0.31.0 // indirect
|
||||
golang.org/x/sync v0.10.0 // indirect
|
||||
golang.org/x/text v0.21.0 // indirect
|
||||
github.com/minio/crc64nvme v1.1.0 // indirect
|
||||
github.com/minio/md5-simd v1.1.2 // indirect
|
||||
github.com/philhofer/fwd v1.2.0 // indirect
|
||||
github.com/rogpeppe/go-internal v1.14.1 // indirect
|
||||
github.com/rs/xid v1.6.0 // indirect
|
||||
github.com/tinylib/msgp v1.3.0 // indirect
|
||||
golang.org/x/crypto v0.36.0 // indirect
|
||||
golang.org/x/net v0.38.0 // indirect
|
||||
golang.org/x/sync v0.15.0 // indirect
|
||||
golang.org/x/sys v0.34.0 // indirect
|
||||
golang.org/x/text v0.26.0 // indirect
|
||||
gopkg.in/yaml.v3 v3.0.1 // indirect
|
||||
)
|
||||
|
||||
58
go.sum
58
go.sum
@@ -1,13 +1,24 @@
|
||||
github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs=
|
||||
github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c=
|
||||
github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
|
||||
github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
|
||||
github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
|
||||
github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
|
||||
github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
|
||||
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
|
||||
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
|
||||
github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
|
||||
github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
|
||||
github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
|
||||
github.com/go-ini/ini v1.67.0 h1:z6ZrTEZqSWOTyH2FlglNbNgARyHG8oLW9gMELqKr06A=
|
||||
github.com/go-ini/ini v1.67.0/go.mod h1:ByCAeIL28uOIIG0E3PJtZPDL8WnHpFKFOtgjp+3Ies8=
|
||||
github.com/go-sql-driver/mysql v1.7.0/go.mod h1:OXbVy3sEdcQ2Doequ6Z5BW6fXNQTmx+9S1MCJN5yJMI=
|
||||
github.com/go-sql-driver/mysql v1.7.1 h1:lUIinVbN1DY0xBg0eMOzmmtGoHwWBbvnWubQUrtU8EI=
|
||||
github.com/go-sql-driver/mysql v1.7.1/go.mod h1:OXbVy3sEdcQ2Doequ6Z5BW6fXNQTmx+9S1MCJN5yJMI=
|
||||
github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
|
||||
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
|
||||
github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
|
||||
github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
|
||||
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
|
||||
@@ -20,24 +31,55 @@ github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD
|
||||
github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
|
||||
github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
|
||||
github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
|
||||
github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
|
||||
github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
|
||||
github.com/klauspost/cpuid/v2 v2.0.1/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
|
||||
github.com/klauspost/cpuid/v2 v2.2.11 h1:0OwqZRYI2rFrjS4kvkDnqJkKHdHaRnCm68/DY4OxRzU=
|
||||
github.com/klauspost/cpuid/v2 v2.2.11/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
|
||||
github.com/klauspost/crc32 v1.3.0 h1:sSmTt3gUt81RP655XGZPElI0PelVTZ6YwCRnPSupoFM=
|
||||
github.com/klauspost/crc32 v1.3.0/go.mod h1:D7kQaZhnkX/Y0tstFGf8VUzv2UofNGqCjnC3zdHB0Hw=
|
||||
github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
|
||||
github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
|
||||
github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
|
||||
github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
|
||||
github.com/mattn/go-sqlite3 v1.14.22 h1:2gZY6PC6kBnID23Tichd1K+Z0oS6nE/XwU+Vz/5o4kU=
|
||||
github.com/mattn/go-sqlite3 v1.14.22/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
|
||||
github.com/minio/crc64nvme v1.1.0 h1:e/tAguZ+4cw32D+IO/8GSf5UVr9y+3eJcxZI2WOO/7Q=
|
||||
github.com/minio/crc64nvme v1.1.0/go.mod h1:eVfm2fAzLlxMdUGc0EEBGSMmPwmXD5XiNRpnu9J3bvg=
|
||||
github.com/minio/md5-simd v1.1.2 h1:Gdi1DZK69+ZVMoNHRXJyNcxrMA4dSxoYHZSQbirFg34=
|
||||
github.com/minio/md5-simd v1.1.2/go.mod h1:MzdKDxYpY2BT9XQFocsiZf/NKVtR7nkE4RoEpN+20RM=
|
||||
github.com/minio/minio-go/v7 v7.0.97 h1:lqhREPyfgHTB/ciX8k2r8k0D93WaFqxbJX36UZq5occ=
|
||||
github.com/minio/minio-go/v7 v7.0.97/go.mod h1:re5VXuo0pwEtoNLsNuSr0RrLfT/MBtohwdaSmPPSRSk=
|
||||
github.com/philhofer/fwd v1.2.0 h1:e6DnBTl7vGY+Gz322/ASL4Gyp1FspeMvx1RNDoToZuM=
|
||||
github.com/philhofer/fwd v1.2.0/go.mod h1:RqIHx9QI14HlwKwm98g9Re5prTQ6LdeRQn+gXJFxsJM=
|
||||
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
|
||||
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
|
||||
github.com/redis/go-redis/v9 v9.17.1 h1:7tl732FjYPRT9H9aNfyTwKg9iTETjWjGKEJ2t/5iWTs=
|
||||
github.com/redis/go-redis/v9 v9.17.1/go.mod h1:u410H11HMLoB+TP67dz8rL9s6QW2j76l0//kSOd3370=
|
||||
github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
|
||||
github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
|
||||
github.com/rs/xid v1.6.0 h1:fV591PaemRlL6JfRxGDEPl69wICngIQ3shQtzfy2gxU=
|
||||
github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
|
||||
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
|
||||
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
|
||||
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
|
||||
github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
|
||||
github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
|
||||
golang.org/x/crypto v0.31.0 h1:ihbySMvVjLAeSH1IbfcRTkD/iNscyz8rGzjF/E5hV6U=
|
||||
golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
|
||||
golang.org/x/sync v0.10.0 h1:3NQrjDixjgGwUOCaF8w2+VYHv0Ve/vGYSbdkTa98gmQ=
|
||||
golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
|
||||
golang.org/x/text v0.21.0 h1:zyQAAkrwaneQ066sspRyJaG9VNi/YJ1NfzcGB3hZ/qo=
|
||||
golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
|
||||
github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
|
||||
github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
|
||||
github.com/tinylib/msgp v1.3.0 h1:ULuf7GPooDaIlbyvgAxBV/FI7ynli6LZ1/nVUNu+0ww=
|
||||
github.com/tinylib/msgp v1.3.0/go.mod h1:ykjzy2wzgrlvpDCRc4LA8UXy6D8bzMSuAF3WD57Gok0=
|
||||
golang.org/x/crypto v0.36.0 h1:AnAEvhDddvBdpY+uR+MyHmuZzzNqXSe/GvuDeob5L34=
|
||||
golang.org/x/crypto v0.36.0/go.mod h1:Y4J0ReaxCR1IMaabaSMugxJES1EpwhBHhv2bDHklZvc=
|
||||
golang.org/x/net v0.38.0 h1:vRMAPTMaeGqVhG5QyLJHqNDwecKTomGeqbnfZyKlBI8=
|
||||
golang.org/x/net v0.38.0/go.mod h1:ivrbrMbzFq5J41QOQh0siUuly180yBYtLp+CKbEaFx8=
|
||||
golang.org/x/sync v0.15.0 h1:KWH3jNZsfyT6xfAfKiz6MRNmd46ByHDYaZ7KSkCtdW8=
|
||||
golang.org/x/sync v0.15.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
|
||||
golang.org/x/sys v0.34.0 h1:H5Y5sJ2L2JRdyv7ROF1he/lPdvFsd0mJHFw2ThKHxLA=
|
||||
golang.org/x/sys v0.34.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
|
||||
golang.org/x/text v0.26.0 h1:P42AVeLghgTYr4+xUnTRKDMqpar+PtX7KWuNQL21L8M=
|
||||
golang.org/x/text v0.26.0/go.mod h1:QK15LZJUUQVJxhz7wXgxSy/CJaTFjd0G+YLonydOVQA=
|
||||
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|
||||
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
|
||||
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
|
||||
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
||||
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
|
||||
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
||||
|
||||
279
http/handler.go
Normal file
279
http/handler.go
Normal file
@@ -0,0 +1,279 @@
|
||||
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)
|
||||
}
|
||||
}
|
||||
225
http/request.go
225
http/request.go
@@ -1,49 +1,12 @@
|
||||
package http
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"io"
|
||||
"net/http"
|
||||
"strconv"
|
||||
|
||||
"git.toowon.com/jimmy/go-common/middleware"
|
||||
)
|
||||
|
||||
// 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 {
|
||||
// getQueryInt 获取整数查询参数（内部方法，供ParsePaginationRequest使用）
|
||||
func getQueryInt(r *http.Request, key string, defaultValue int) int {
|
||||
value := r.URL.Query().Get(key)
|
||||
if value == "" {
|
||||
return defaultValue
|
||||
@@ -57,62 +20,8 @@ func GetQueryInt(r *http.Request, key string, defaultValue int) int {
|
||||
return intValue
|
||||
}
|
||||
|
||||
// GetQueryInt64 获取int64查询参数
|
||||
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 获取布尔查询参数
|
||||
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查询参数
|
||||
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 获取表单值
|
||||
func GetFormValue(r *http.Request, key, defaultValue string) string {
|
||||
value := r.FormValue(key)
|
||||
if value == "" {
|
||||
return defaultValue
|
||||
}
|
||||
return value
|
||||
}
|
||||
|
||||
// GetFormInt 获取表单整数
|
||||
func GetFormInt(r *http.Request, key string, defaultValue int) int {
|
||||
// getFormInt 获取表单整数（内部方法，供ParsePaginationRequest使用）
|
||||
func getFormInt(r *http.Request, key string, defaultValue int) int {
|
||||
value := r.FormValue(key)
|
||||
if value == "" {
|
||||
return defaultValue
|
||||
@@ -126,82 +35,82 @@ func GetFormInt(r *http.Request, key string, defaultValue int) int {
|
||||
return intValue
|
||||
}
|
||||
|
||||
// GetFormInt64 获取表单int64
|
||||
func GetFormInt64(r *http.Request, key string, defaultValue int64) int64 {
|
||||
value := r.FormValue(key)
|
||||
if value == "" {
|
||||
return defaultValue
|
||||
// PaginationRequest 分页请求结构
|
||||
// 支持从JSON和form中解析分页参数
|
||||
type PaginationRequest struct {
|
||||
Page int `json:"page" form:"page"` // 页码，默认1
|
||||
Size int `json:"size" form:"size"` // 每页数量（兼容旧版本）
|
||||
PageSize int `json:"page_size" form:"page_size"` // 每页数量（推荐使用）
|
||||
}
|
||||
|
||||
intValue, err := strconv.ParseInt(value, 10, 64)
|
||||
if err != nil {
|
||||
return defaultValue
|
||||
// GetPage 获取页码，如果未设置则返回默认值1
|
||||
func (p *PaginationRequest) GetPage() int {
|
||||
if p.Page <= 0 {
|
||||
return 1
|
||||
}
|
||||
return p.Page
|
||||
}
|
||||
|
||||
return intValue
|
||||
// GetSize 获取每页数量，如果未设置则返回默认值20，最大限制100
|
||||
// 优先使用 PageSize 字段，如果未设置则使用 Size 字段（兼容旧版本）
|
||||
func (p *PaginationRequest) GetSize() int {
|
||||
size := p.PageSize
|
||||
if size <= 0 {
|
||||
size = p.Size // 兼容旧版本的 Size 字段
|
||||
}
|
||||
if size <= 0 {
|
||||
return 20 // 默认20条
|
||||
}
|
||||
if size > 100 {
|
||||
return 100 // 最大100条
|
||||
}
|
||||
return size
|
||||
}
|
||||
|
||||
// GetFormBool 获取表单布尔值
|
||||
func GetFormBool(r *http.Request, key string, defaultValue bool) bool {
|
||||
value := r.FormValue(key)
|
||||
if value == "" {
|
||||
return defaultValue
|
||||
// GetOffset 计算数据库查询的偏移量
|
||||
func (p *PaginationRequest) GetOffset() int {
|
||||
return (p.GetPage() - 1) * p.GetSize()
|
||||
}
|
||||
|
||||
boolValue, err := strconv.ParseBool(value)
|
||||
if err != nil {
|
||||
return defaultValue
|
||||
// getPaginationFromQuery 从查询参数获取分页参数（内部辅助方法）
|
||||
func getPaginationFromQuery(r *http.Request) (page, size, pageSize int) {
|
||||
page = getQueryInt(r, "page", 0)
|
||||
size = getQueryInt(r, "size", 0)
|
||||
pageSize = getQueryInt(r, "page_size", 0)
|
||||
return
|
||||
}
|
||||
|
||||
return boolValue
|
||||
// getPaginationFromForm 从form表单获取分页参数（内部辅助方法）
|
||||
func getPaginationFromForm(r *http.Request) (page, size, pageSize int) {
|
||||
page = getFormInt(r, "page", 0)
|
||||
size = getFormInt(r, "size", 0)
|
||||
pageSize = getFormInt(r, "page_size", 0)
|
||||
return
|
||||
}
|
||||
|
||||
// GetHeader 获取请求头
|
||||
func GetHeader(r *http.Request, key, defaultValue string) string {
|
||||
value := r.Header.Get(key)
|
||||
if value == "" {
|
||||
return defaultValue
|
||||
// ParsePaginationRequest 从请求中解析分页参数
|
||||
// 支持从查询参数和form表单中解析
|
||||
// 优先级：查询参数 > form表单
|
||||
// 注意：如果请求体是JSON格式且包含分页字段，建议先使用ParseJSON解析完整请求体到包含PaginationRequest的结构体中
|
||||
func ParsePaginationRequest(r *http.Request) *PaginationRequest {
|
||||
req := &PaginationRequest{}
|
||||
|
||||
// 1. 从查询参数解析（优先级最高）
|
||||
req.Page, req.Size, req.PageSize = getPaginationFromQuery(r)
|
||||
|
||||
// 2. 如果查询参数中没有，尝试从form表单解析
|
||||
if req.Page == 0 || (req.Size == 0 && req.PageSize == 0) {
|
||||
page, size, pageSize := getPaginationFromForm(r)
|
||||
if req.Page == 0 && page != 0 {
|
||||
req.Page = page
|
||||
}
|
||||
if req.Size == 0 && size != 0 {
|
||||
req.Size = size
|
||||
}
|
||||
if req.PageSize == 0 && pageSize != 0 {
|
||||
req.PageSize = pageSize
|
||||
}
|
||||
return value
|
||||
}
|
||||
|
||||
// GetPaginationParams 获取分页参数
|
||||
// 返回 page, pageSize
|
||||
// 默认 page=1, pageSize=10
|
||||
func GetPaginationParams(r *http.Request) (page, pageSize int) {
|
||||
page = GetQueryInt(r, "page", 1)
|
||||
pageSize = GetQueryInt(r, "pageSize", 10)
|
||||
|
||||
// 参数校验
|
||||
if page < 1 {
|
||||
page = 1
|
||||
}
|
||||
if pageSize < 1 {
|
||||
pageSize = 10
|
||||
}
|
||||
if pageSize > 1000 {
|
||||
pageSize = 1000 // 限制最大页面大小
|
||||
}
|
||||
|
||||
return page, pageSize
|
||||
}
|
||||
|
||||
// GetOffset 根据页码和每页大小计算偏移量
|
||||
func GetOffset(page, pageSize int) int {
|
||||
if page < 1 {
|
||||
page = 1
|
||||
}
|
||||
return (page - 1) * pageSize
|
||||
}
|
||||
|
||||
// GetTimezone 从请求的context中获取时区
|
||||
// 如果使用了middleware.Timezone中间件，可以从context中获取时区信息
|
||||
// 如果未设置，返回默认时区 AsiaShanghai
|
||||
func GetTimezone(r *http.Request) string {
|
||||
return middleware.GetTimezoneFromContext(r.Context())
|
||||
}
|
||||
|
||||
// GetTimezoneFromContext 从context中获取时区
|
||||
func GetTimezoneFromContext(ctx context.Context) string {
|
||||
return middleware.GetTimezoneFromContext(ctx)
|
||||
return req
|
||||
}
|
||||
|
||||
@@ -30,56 +30,12 @@ type PageData struct {
|
||||
PageSize int `json:"pageSize"` // 每页大小
|
||||
}
|
||||
|
||||
// Success 成功响应
|
||||
// data: 响应数据，可以为nil
|
||||
func Success(w http.ResponseWriter, data interface{}) {
|
||||
WriteJSON(w, http.StatusOK, 0, "success", data)
|
||||
}
|
||||
|
||||
// SuccessWithMessage 带消息的成功响应
|
||||
func SuccessWithMessage(w http.ResponseWriter, message string, data interface{}) {
|
||||
WriteJSON(w, http.StatusOK, 0, message, data)
|
||||
}
|
||||
|
||||
// Error 错误响应
|
||||
// code: 业务错误码，非0表示业务错误
|
||||
// message: 错误消息
|
||||
func Error(w http.ResponseWriter, code int, message string) {
|
||||
WriteJSON(w, http.StatusOK, code, message, nil)
|
||||
}
|
||||
|
||||
// SystemError 系统错误响应（返回HTTP 500）
|
||||
// message: 错误消息
|
||||
func SystemError(w http.ResponseWriter, message string) {
|
||||
WriteJSON(w, http.StatusInternalServerError, 500, message, nil)
|
||||
}
|
||||
|
||||
// BadRequest 请求错误响应（HTTP 400）
|
||||
func BadRequest(w http.ResponseWriter, message string) {
|
||||
WriteJSON(w, http.StatusBadRequest, 400, message, nil)
|
||||
}
|
||||
|
||||
// Unauthorized 未授权响应（HTTP 401）
|
||||
func Unauthorized(w http.ResponseWriter, message string) {
|
||||
WriteJSON(w, http.StatusUnauthorized, 401, message, nil)
|
||||
}
|
||||
|
||||
// Forbidden 禁止访问响应（HTTP 403）
|
||||
func Forbidden(w http.ResponseWriter, message string) {
|
||||
WriteJSON(w, http.StatusForbidden, 403, message, nil)
|
||||
}
|
||||
|
||||
// NotFound 未找到响应（HTTP 404）
|
||||
func NotFound(w http.ResponseWriter, message string) {
|
||||
WriteJSON(w, http.StatusNotFound, 404, message, nil)
|
||||
}
|
||||
|
||||
// WriteJSON 写入JSON响应
|
||||
// writeJSON 写入JSON响应（内部方法）
|
||||
// httpCode: HTTP状态码（200表示正常，500表示系统错误等）
|
||||
// code: 业务状态码（0表示成功，非0表示业务错误）
|
||||
// message: 响应消息
|
||||
// data: 响应数据
|
||||
func WriteJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{}) {
|
||||
func writeJSON(w http.ResponseWriter, httpCode, code int, message string, data interface{}) {
|
||||
w.Header().Set("Content-Type", "application/json; charset=utf-8")
|
||||
w.WriteHeader(httpCode)
|
||||
|
||||
@@ -92,47 +48,3 @@ func WriteJSON(w http.ResponseWriter, httpCode, code int, message string, data i
|
||||
|
||||
json.NewEncoder(w).Encode(response)
|
||||
}
|
||||
|
||||
// SuccessPage 分页成功响应
|
||||
// list: 数据列表
|
||||
// total: 总记录数
|
||||
// page: 当前页码
|
||||
// pageSize: 每页大小
|
||||
func SuccessPage(w http.ResponseWriter, list interface{}, total int64, page, pageSize int) {
|
||||
w.Header().Set("Content-Type", "application/json; charset=utf-8")
|
||||
w.WriteHeader(http.StatusOK)
|
||||
|
||||
response := PageResponse{
|
||||
Code: 0,
|
||||
Message: "success",
|
||||
Timestamp: time.Now().Unix(),
|
||||
Data: &PageData{
|
||||
List: list,
|
||||
Total: total,
|
||||
Page: page,
|
||||
PageSize: pageSize,
|
||||
},
|
||||
}
|
||||
|
||||
json.NewEncoder(w).Encode(response)
|
||||
}
|
||||
|
||||
// SuccessPageWithMessage 带消息的分页成功响应
|
||||
func SuccessPageWithMessage(w http.ResponseWriter, message string, list interface{}, total int64, page, pageSize int) {
|
||||
w.Header().Set("Content-Type", "application/json; charset=utf-8")
|
||||
w.WriteHeader(http.StatusOK)
|
||||
|
||||
response := PageResponse{
|
||||
Code: 0,
|
||||
Message: message,
|
||||
Timestamp: time.Now().Unix(),
|
||||
Data: &PageData{
|
||||
List: list,
|
||||
Total: total,
|
||||
Page: page,
|
||||
PageSize: pageSize,
|
||||
},
|
||||
}
|
||||
|
||||
json.NewEncoder(w).Encode(response)
|
||||
}
|
||||
|
||||
314
logger/logger.go
314
logger/logger.go
@@ -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 创建日志记录器
|
||||
@@ -27,6 +61,8 @@ func NewLogger(cfg *config.LoggerConfig) (*Logger, error) {
|
||||
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...)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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
221
middleware/logging.go
Normal 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
286
middleware/ratelimit.go
Normal 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
149
middleware/recovery.go
Normal 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,
|
||||
})
|
||||
}
|
||||
|
||||
231
migration/helper.go
Normal file
231
migration/helper.go
Normal file
@@ -0,0 +1,231 @@
|
||||
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）
|
||||
// - 环境变量 DATABASE_URL：直接使用数据库URL
|
||||
// - migrationsDir: 迁移文件目录，支持：
|
||||
// - 空字符串：使用默认目录 "migrations"
|
||||
// - 相对路径或绝对路径
|
||||
// - command: 命令，支持 "up", "down", "status"
|
||||
//
|
||||
// 使用示例：
|
||||
//
|
||||
// // 最简单：使用默认配置和默认迁移目录
|
||||
// migration.RunMigrationsFromConfigWithCommand("", "", "up")
|
||||
//
|
||||
// // 指定配置文件，使用默认迁移目录
|
||||
// migration.RunMigrationsFromConfigWithCommand("config.json", "", "up")
|
||||
//
|
||||
// // 指定配置和迁移目录
|
||||
// migration.RunMigrationsFromConfigWithCommand("config.json", "scripts/sql", "up")
|
||||
//
|
||||
// // 使用环境变量
|
||||
// // DATABASE_URL="mysql://..." migration.RunMigrationsFromConfigWithCommand("", "migrations", "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 := NewMigrator(db)
|
||||
|
||||
// 加载迁移文件
|
||||
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 dbURL := os.Getenv("DATABASE_URL"); dbURL != "" {
|
||||
return &config.Config{
|
||||
Database: &config.DatabaseConfig{
|
||||
DSN: dbURL,
|
||||
},
|
||||
}, nil
|
||||
}
|
||||
|
||||
// 尝试从配置文件加载
|
||||
if configFile != "" {
|
||||
if _, err := os.Stat(configFile); err == nil {
|
||||
return config.LoadFromFile(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("未找到配置文件，也未设置环境变量 DATABASE_URL")
|
||||
}
|
||||
|
||||
// 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()
|
||||
}
|
||||
@@ -72,17 +72,38 @@ func (m *Migrator) initTable() error {
|
||||
}
|
||||
|
||||
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
|
||||
checkSQL := fmt.Sprintf(`
|
||||
SELECT COUNT(*) > 0
|
||||
FROM information_schema.columns
|
||||
WHERE table_schema = CURRENT_SCHEMA()
|
||||
AND table_name = '%s'
|
||||
AND column_name = 'execution_time'
|
||||
`, m.tableName)
|
||||
err = m.db.Raw(checkSQL).Scan(&hasExecutionTime).Error
|
||||
if err == nil && !hasExecutionTime {
|
||||
// 尝试添加字段（如果失败不影响功能）
|
||||
_ = m.db.Exec(fmt.Sprintf(`
|
||||
ALTER TABLE %s
|
||||
ADD COLUMN execution_time INT COMMENT '执行耗时(ms)'
|
||||
`, m.tableName))
|
||||
}
|
||||
}
|
||||
|
||||
return nil
|
||||
@@ -109,17 +130,34 @@ func (m *Migrator) getAppliedMigrations() (map[string]bool, error) {
|
||||
}
|
||||
|
||||
// recordMigration 记录迁移
|
||||
func (m *Migrator) recordMigration(version, description string, isUp bool) error {
|
||||
func (m *Migrator) recordMigration(version, description string, isUp bool, executionTime ...int) error {
|
||||
if err := m.initTable(); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
if isUp {
|
||||
// 记录迁移
|
||||
err := m.db.Exec(fmt.Sprintf(`
|
||||
// 记录迁移（包含执行时间，如果提供了）
|
||||
var err error
|
||||
if len(executionTime) > 0 && executionTime[0] > 0 {
|
||||
// 尝试插入执行时间（如果字段存在）
|
||||
err = m.db.Exec(fmt.Sprintf(`
|
||||
INSERT INTO %s (version, description, applied_at, execution_time)
|
||||
VALUES (?, ?, ?, ?)
|
||||
`, m.tableName), version, description, time.Now(), executionTime[0]).Error
|
||||
if err != nil {
|
||||
// 如果失败（可能是字段不存在），尝试不包含执行时间
|
||||
err = m.db.Exec(fmt.Sprintf(`
|
||||
INSERT INTO %s (version, description, applied_at)
|
||||
VALUES (?, ?, ?)
|
||||
`, m.tableName), version, description, time.Now()).Error
|
||||
}
|
||||
} else {
|
||||
// 不包含执行时间
|
||||
err = m.db.Exec(fmt.Sprintf(`
|
||||
INSERT INTO %s (version, description, applied_at)
|
||||
VALUES (?, ?, ?)
|
||||
`, m.tableName), version, description, time.Now()).Error
|
||||
}
|
||||
if err != nil {
|
||||
return fmt.Errorf("failed to record migration: %w", err)
|
||||
}
|
||||
@@ -160,6 +198,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 +213,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 +227,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 +290,29 @@ func (m *Migrator) Down() error {
|
||||
}
|
||||
|
||||
// recordMigrationWithDB 使用指定的数据库连接记录迁移
|
||||
func (m *Migrator) recordMigrationWithDB(db *gorm.DB, version, description string, isUp bool) error {
|
||||
func (m *Migrator) recordMigrationWithDB(db *gorm.DB, version, description string, isUp bool, executionTime ...int) error {
|
||||
if isUp {
|
||||
err := db.Exec(fmt.Sprintf(`
|
||||
var err error
|
||||
if len(executionTime) > 0 && executionTime[0] > 0 {
|
||||
// 尝试插入执行时间（如果字段存在）
|
||||
err = db.Exec(fmt.Sprintf(`
|
||||
INSERT INTO %s (version, description, applied_at, execution_time)
|
||||
VALUES (?, ?, ?, ?)
|
||||
`, m.tableName), version, description, time.Now(), executionTime[0]).Error
|
||||
if err != nil {
|
||||
// 如果失败（可能是字段不存在），尝试不包含执行时间
|
||||
err = db.Exec(fmt.Sprintf(`
|
||||
INSERT INTO %s (version, description, applied_at)
|
||||
VALUES (?, ?, ?)
|
||||
`, m.tableName), version, description, time.Now()).Error
|
||||
}
|
||||
} else {
|
||||
// 不包含执行时间
|
||||
err = db.Exec(fmt.Sprintf(`
|
||||
INSERT INTO %s (version, description, applied_at)
|
||||
VALUES (?, ?, ?)
|
||||
`, m.tableName), version, description, time.Now()).Error
|
||||
}
|
||||
if err != nil {
|
||||
return fmt.Errorf("failed to record migration: %w", err)
|
||||
}
|
||||
@@ -300,10 +361,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 +460,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 +488,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
|
||||
|
||||
@@ -43,29 +43,31 @@ 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 {
|
||||
commonhttp.NotFound(w, "Method not allowed")
|
||||
handler.Error(4001, "Method not allowed")
|
||||
return
|
||||
}
|
||||
|
||||
// 解析multipart表单
|
||||
err := r.ParseMultipartForm(h.maxFileSize)
|
||||
if err != nil {
|
||||
commonhttp.BadRequest(w, fmt.Sprintf("Failed to parse form: %v", err))
|
||||
handler.Error(4002, fmt.Sprintf("Failed to parse form: %v", err))
|
||||
return
|
||||
}
|
||||
|
||||
// 获取文件
|
||||
file, header, err := r.FormFile("file")
|
||||
if err != nil {
|
||||
commonhttp.BadRequest(w, fmt.Sprintf("Failed to get file: %v", err))
|
||||
handler.Error(4003, fmt.Sprintf("Failed to get file: %v", err))
|
||||
return
|
||||
}
|
||||
defer file.Close()
|
||||
|
||||
// 检查文件大小
|
||||
if h.maxFileSize > 0 && header.Size > h.maxFileSize {
|
||||
commonhttp.Error(w, 1001, fmt.Sprintf("File size exceeds limit: %d bytes", h.maxFileSize))
|
||||
handler.Error(1001, fmt.Sprintf("File size exceeds limit: %d bytes", h.maxFileSize))
|
||||
return
|
||||
}
|
||||
|
||||
@@ -80,7 +82,7 @@ func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
|
||||
}
|
||||
}
|
||||
if !allowed {
|
||||
commonhttp.Error(w, 1002, fmt.Sprintf("File extension not allowed. Allowed: %v", h.allowedExts))
|
||||
handler.Error(1002, fmt.Sprintf("File extension not allowed. Allowed: %v", h.allowedExts))
|
||||
return
|
||||
}
|
||||
}
|
||||
@@ -108,14 +110,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 {
|
||||
commonhttp.SystemError(w, fmt.Sprintf("Failed to upload file: %v", err))
|
||||
handler.SystemError(fmt.Sprintf("Failed to upload file: %v", err))
|
||||
return
|
||||
}
|
||||
|
||||
// 获取文件URL
|
||||
fileURL, err := h.storage.GetURL(objectKey, 0)
|
||||
if err != nil {
|
||||
commonhttp.SystemError(w, fmt.Sprintf("Failed to get file URL: %v", err))
|
||||
handler.SystemError(fmt.Sprintf("Failed to get file URL: %v", err))
|
||||
return
|
||||
}
|
||||
|
||||
@@ -128,7 +130,7 @@ func (h *UploadHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
|
||||
UploadTime: time.Now(),
|
||||
}
|
||||
|
||||
commonhttp.SuccessWithMessage(w, "Upload successful", result)
|
||||
handler.SuccessWithMessage("Upload successful", result)
|
||||
}
|
||||
|
||||
// generateUniqueFilename 生成唯一文件名
|
||||
@@ -153,16 +155,17 @@ func NewProxyHandler(storage Storage) *ProxyHandler {
|
||||
|
||||
// ServeHTTP 处理文件查看请求
|
||||
// URL参数: key (对象键)
|
||||
// 注意：此方法直接返回文件内容（二进制），错误时返回标准HTTP错误状态码
|
||||
func (h *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
|
||||
if r.Method != http.MethodGet {
|
||||
commonhttp.NotFound(w, "Method not allowed")
|
||||
http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
|
||||
return
|
||||
}
|
||||
|
||||
// 获取对象键
|
||||
objectKey := r.URL.Query().Get("key")
|
||||
if objectKey == "" {
|
||||
commonhttp.BadRequest(w, "Missing parameter: key")
|
||||
http.Error(w, "Missing parameter: key", http.StatusBadRequest)
|
||||
return
|
||||
}
|
||||
|
||||
@@ -170,19 +173,19 @@ func (h *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
|
||||
ctx := r.Context()
|
||||
exists, err := h.storage.Exists(ctx, objectKey)
|
||||
if err != nil {
|
||||
commonhttp.SystemError(w, 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 {
|
||||
commonhttp.NotFound(w, "File not found")
|
||||
http.Error(w, "File not found", http.StatusNotFound)
|
||||
return
|
||||
}
|
||||
|
||||
// 获取文件内容
|
||||
reader, err := h.storage.GetObject(ctx, objectKey)
|
||||
if err != nil {
|
||||
commonhttp.SystemError(w, 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()
|
||||
@@ -206,7 +209,8 @@ func (h *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
|
||||
// 复制文件内容到响应
|
||||
_, err = io.Copy(w, reader)
|
||||
if err != nil {
|
||||
commonhttp.SystemError(w, fmt.Sprintf("Failed to write response: %v", err))
|
||||
// 如果已经开始写入响应，无法再设置错误状态码
|
||||
// 这里只能记录错误，无法返回错误响应
|
||||
return
|
||||
}
|
||||
}
|
||||
|
||||
198
storage/minio.go
198
storage/minio.go
@@ -5,16 +5,20 @@ import (
|
||||
"fmt"
|
||||
"io"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"git.toowon.com/jimmy/go-common/config"
|
||||
"github.com/minio/minio-go/v7"
|
||||
"github.com/minio/minio-go/v7/pkg/credentials"
|
||||
)
|
||||
|
||||
// MinIOStorage MinIO存储实现
|
||||
type MinIOStorage struct {
|
||||
config *config.MinIOConfig
|
||||
// client 存储MinIO客户端（实际使用时需要根据具体的MinIO SDK实现）
|
||||
// 这里使用interface{}，实际使用时需要替换为具体的客户端类型
|
||||
client interface{}
|
||||
client *minio.Client
|
||||
bucket string
|
||||
domain string
|
||||
protocol string
|
||||
}
|
||||
|
||||
// NewMinIOStorage 创建MinIO存储实例
|
||||
@@ -23,122 +27,138 @@ func NewMinIOStorage(cfg *config.MinIOConfig) (*MinIOStorage, error) {
|
||||
return nil, fmt.Errorf("MinIO config is nil")
|
||||
}
|
||||
|
||||
storage := &MinIOStorage{
|
||||
config: cfg,
|
||||
// 创建MinIO客户端
|
||||
client, err := minio.New(cfg.Endpoint, &minio.Options{
|
||||
Creds: credentials.NewStaticV4(cfg.AccessKeyID, cfg.SecretAccessKey, ""),
|
||||
Secure: cfg.UseSSL,
|
||||
})
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("failed to create MinIO client: %w", err)
|
||||
}
|
||||
|
||||
// 初始化MinIO客户端
|
||||
// 注意：这里需要根据实际的MinIO SDK实现
|
||||
// 例如使用MinIO Go SDK:
|
||||
// client, err := minio.New(cfg.Endpoint, &minio.Options{
|
||||
// Creds: credentials.NewStaticV4(cfg.AccessKeyID, cfg.SecretAccessKey, ""),
|
||||
// Secure: cfg.UseSSL,
|
||||
// })
|
||||
// if err != nil {
|
||||
// return nil, fmt.Errorf("failed to create MinIO client: %w", err)
|
||||
// }
|
||||
// storage.client = client
|
||||
// 检查bucket是否存在，不存在则创建
|
||||
ctx := context.Background()
|
||||
exists, err := client.BucketExists(ctx, cfg.Bucket)
|
||||
if err != nil {
|
||||
// 如果检查失败，可能是网络问题，但不阻止客户端创建
|
||||
// 继续创建客户端，后续上传时会再次检查
|
||||
} else if !exists {
|
||||
err = client.MakeBucket(ctx, cfg.Bucket, minio.MakeBucketOptions{})
|
||||
if err != nil {
|
||||
// 不阻止客户端创建，后续上传时会再次尝试
|
||||
}
|
||||
}
|
||||
|
||||
return storage, nil
|
||||
protocol := "http"
|
||||
if cfg.UseSSL {
|
||||
protocol = "https"
|
||||
}
|
||||
|
||||
return &MinIOStorage{
|
||||
config: cfg,
|
||||
client: client,
|
||||
bucket: cfg.Bucket,
|
||||
domain: cfg.Domain,
|
||||
protocol: protocol,
|
||||
}, nil
|
||||
}
|
||||
|
||||
// Upload 上传文件到MinIO
|
||||
func (s *MinIOStorage) Upload(ctx context.Context, objectKey string, reader io.Reader, contentType ...string) error {
|
||||
// 实现MinIO上传逻辑
|
||||
// 注意：这里需要根据实际的MinIO SDK实现
|
||||
// 示例（使用MinIO Go SDK）:
|
||||
// ct := "application/octet-stream"
|
||||
// if len(contentType) > 0 && contentType[0] != "" {
|
||||
// ct = contentType[0]
|
||||
// }
|
||||
//
|
||||
// _, err := s.client.PutObject(ctx, s.config.Bucket, objectKey, reader, -1, minio.PutObjectOptions{
|
||||
// ContentType: ct,
|
||||
// })
|
||||
// if err != nil {
|
||||
// return fmt.Errorf("failed to upload object: %w", err)
|
||||
// }
|
||||
if s.client == nil {
|
||||
return fmt.Errorf("MinIO client is not initialized")
|
||||
}
|
||||
|
||||
// 当前实现返回错误，提示需要实现具体的MinIO SDK
|
||||
return fmt.Errorf("MinIO upload not implemented, please implement with actual MinIO SDK")
|
||||
ct := "application/octet-stream"
|
||||
if len(contentType) > 0 && contentType[0] != "" {
|
||||
ct = contentType[0]
|
||||
}
|
||||
|
||||
opts := minio.PutObjectOptions{
|
||||
ContentType: ct,
|
||||
}
|
||||
|
||||
_, err := s.client.PutObject(ctx, s.bucket, objectKey, reader, -1, opts)
|
||||
if err != nil {
|
||||
return fmt.Errorf("failed to upload object: %w", err)
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// GetURL 获取MinIO文件访问URL
|
||||
func (s *MinIOStorage) GetURL(objectKey string, expires int64) (string, error) {
|
||||
if s.config.Domain != "" {
|
||||
// 使用自定义域名
|
||||
if strings.HasSuffix(s.config.Domain, "/") {
|
||||
return s.config.Domain + objectKey, nil
|
||||
if s.client == nil {
|
||||
return "", fmt.Errorf("MinIO client is not initialized")
|
||||
}
|
||||
return s.config.Domain + "/" + objectKey, nil
|
||||
|
||||
// 如果设置了过期时间，生成预签名URL
|
||||
if expires > 0 {
|
||||
ctx := context.Background()
|
||||
expiry := time.Duration(expires) * time.Second
|
||||
presignedURL, err := s.client.PresignedGetObject(ctx, s.bucket, objectKey, expiry, nil)
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("failed to generate presigned URL: %w", err)
|
||||
}
|
||||
return presignedURL.String(), nil
|
||||
}
|
||||
|
||||
// 使用自定义域名或默认域名
|
||||
if s.domain != "" {
|
||||
// 使用自定义域名
|
||||
if strings.HasSuffix(s.domain, "/") {
|
||||
return fmt.Sprintf("%s://%s%s/%s", s.protocol, s.domain, s.bucket, objectKey), nil
|
||||
}
|
||||
return fmt.Sprintf("%s://%s/%s/%s", s.protocol, s.domain, s.bucket, objectKey), nil
|
||||
}
|
||||
|
||||
// 使用MinIO默认域名
|
||||
protocol := "http"
|
||||
if s.config.UseSSL {
|
||||
protocol = "https"
|
||||
}
|
||||
|
||||
// 构建MinIO URL
|
||||
// 格式: http://endpoint/bucket/objectKey
|
||||
url := fmt.Sprintf("%s://%s/%s/%s", protocol, s.config.Endpoint, s.config.Bucket, objectKey)
|
||||
|
||||
// 如果设置了过期时间，需要生成预签名URL
|
||||
// 注意：这里需要根据实际的MinIO SDK实现
|
||||
// 示例（使用MinIO Go SDK）:
|
||||
// if expires > 0 {
|
||||
// expiry := time.Duration(expires) * time.Second
|
||||
// presignedURL, err := s.client.PresignedGetObject(ctx, s.config.Bucket, objectKey, expiry, nil)
|
||||
// if err != nil {
|
||||
// return "", err
|
||||
// }
|
||||
// return presignedURL.String(), nil
|
||||
// }
|
||||
|
||||
return url, nil
|
||||
return fmt.Sprintf("%s://%s/%s/%s", s.protocol, s.config.Endpoint, s.bucket, objectKey), nil
|
||||
}
|
||||
|
||||
// Delete 删除MinIO文件
|
||||
func (s *MinIOStorage) Delete(ctx context.Context, objectKey string) error {
|
||||
// 实现MinIO删除逻辑
|
||||
// 注意：这里需要根据实际的MinIO SDK实现
|
||||
// 示例（使用MinIO Go SDK）:
|
||||
// err := s.client.RemoveObject(ctx, s.config.Bucket, objectKey, minio.RemoveObjectOptions{})
|
||||
// if err != nil {
|
||||
// return fmt.Errorf("failed to delete object: %w", err)
|
||||
// }
|
||||
if s.client == nil {
|
||||
return fmt.Errorf("MinIO client is not initialized")
|
||||
}
|
||||
|
||||
return fmt.Errorf("MinIO delete not implemented, please implement with actual MinIO SDK")
|
||||
err := s.client.RemoveObject(ctx, s.bucket, objectKey, minio.RemoveObjectOptions{})
|
||||
if err != nil {
|
||||
return fmt.Errorf("failed to delete object: %w", err)
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
|
||||
// Exists 检查MinIO文件是否存在
|
||||
func (s *MinIOStorage) Exists(ctx context.Context, objectKey string) (bool, error) {
|
||||
// 实现MinIO存在性检查逻辑
|
||||
// 注意：这里需要根据实际的MinIO SDK实现
|
||||
// 示例（使用MinIO Go SDK）:
|
||||
// _, err := s.client.StatObject(ctx, s.config.Bucket, objectKey, minio.StatObjectOptions{})
|
||||
// if err != nil {
|
||||
// if minio.ToErrorResponse(err).Code == "NoSuchKey" {
|
||||
// return false, nil
|
||||
// }
|
||||
// return false, fmt.Errorf("failed to check object existence: %w", err)
|
||||
// }
|
||||
// return true, nil
|
||||
if s.client == nil {
|
||||
return false, fmt.Errorf("MinIO client is not initialized")
|
||||
}
|
||||
|
||||
return false, fmt.Errorf("MinIO exists check not implemented, please implement with actual MinIO SDK")
|
||||
_, err := s.client.StatObject(ctx, s.bucket, objectKey, minio.StatObjectOptions{})
|
||||
if err != nil {
|
||||
errResp := minio.ToErrorResponse(err)
|
||||
if errResp.Code == "NoSuchKey" {
|
||||
return false, nil
|
||||
}
|
||||
return false, fmt.Errorf("failed to check object existence: %w", err)
|
||||
}
|
||||
|
||||
return true, nil
|
||||
}
|
||||
|
||||
// GetObject 获取MinIO文件内容
|
||||
func (s *MinIOStorage) GetObject(ctx context.Context, objectKey string) (io.ReadCloser, error) {
|
||||
// 实现MinIO获取对象逻辑
|
||||
// 注意：这里需要根据实际的MinIO SDK实现
|
||||
// 示例（使用MinIO Go SDK）:
|
||||
// obj, err := s.client.GetObject(ctx, s.config.Bucket, objectKey, minio.GetObjectOptions{})
|
||||
// if err != nil {
|
||||
// return nil, fmt.Errorf("failed to get object: %w", err)
|
||||
// }
|
||||
// return obj, nil
|
||||
|
||||
return nil, fmt.Errorf("MinIO get object not implemented, please implement with actual MinIO SDK")
|
||||
if s.client == nil {
|
||||
return nil, fmt.Errorf("MinIO client is not initialized")
|
||||
}
|
||||
|
||||
obj, err := s.client.GetObject(ctx, s.bucket, objectKey, minio.GetObjectOptions{})
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("failed to get object: %w", err)
|
||||
}
|
||||
|
||||
return obj, nil
|
||||
}
|
||||
|
||||
39
templates/Dockerfile.example
Normal file
39
templates/Dockerfile.example
Normal 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
78
templates/Makefile.example
Normal 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
40
templates/README.md
Normal 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
22
templates/docker-compose.example.yml
Normal 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. 无需重启容器！
|
||||
|
||||
151
templates/migrate/main.go
Normal file
151
templates/migrate/main.go
Normal file
@@ -0,0 +1,151 @@
|
||||
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 DATABASE_URL="mysql://..." 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. 环境变量 DATABASE_URL（直接连接，无需配置文件）
|
||||
// 4. 默认值（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(" DATABASE_URL='mysql://...' 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. 环境变量 DATABASE_URL")
|
||||
fmt.Println(" 4. 默认值（config.json 和 migrations）")
|
||||
}
|
||||
Reference in New Issue
Block a user