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

修改包名

Browse Source
This commit is contained in:
Jimmy Xue
2025-11-30 13:43:43 +08:00
parent 23d3840050
commit a655640ab2
38 changed files with 729 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
docs/README.md
View File

@@ -11,13 +11,14 @@
- [邮件工具](./email.md) - SMTP邮件发送
- [短信工具](./sms.md) - 阿里云短信发送
- [工厂工具](./factory.md) - 从配置直接创建已初始化客户端对象
- [日志工具](./logger.md) - 统一的日志记录功能
## 快速开始
### 安装
```bash
go get git.toowon.com/jimmy/go-commom
go get git.toowon.com/jimmy/go-common
```
### 使用示例
@@ -25,7 +26,7 @@ go get git.toowon.com/jimmy/go-commom
#### 数据库迁移
```go
import "git.toowon.com/jimmy/go-commom/migration"
import "git.toowon.com/jimmy/go-common/migration"
migrator := migration.NewMigrator(db)
migrator.AddMigration(migration.Migration{
@@ -41,7 +42,7 @@ migrator.Up()
#### 日期转换
```go
import "git.toowon.com/jimmy/go-commom/datetime"
import "git.toowon.com/jimmy/go-common/datetime"
datetime.SetDefaultTimeZone(datetime.AsiaShanghai)
now := datetime.Now()
@@ -51,7 +52,7 @@ str := datetime.FormatDateTime(now)
#### HTTP响应
```go
import "git.toowon.com/jimmy/go-commom/http"
import "git.toowon.com/jimmy/go-common/http"
http.Success(w, data)
http.SuccessPage(w, list, total, page, pageSize)
@@ -62,8 +63,8 @@ http.Error(w, 1001, "业务错误")
```go
import (
"git.toowon.com/jimmy/go-commom/middleware"
"git.toowon.com/jimmy/go-commom/http"
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/http"
)
// CORS + 时区中间件
@@ -80,7 +81,7 @@ timezone := http.GetTimezone(r)
#### 配置管理
```go
import "git.toowon.com/jimmy/go-commom/config"
import "git.toowon.com/jimmy/go-common/config"
// 从文件加载配置
cfg, err := config.LoadFromFile("./config.json")

24
docs/config.md
View File

@@ -103,7 +103,7 @@
### 1. 加载配置文件
```go
import "git.toowon.com/jimmy/go-commom/config"
import "git.toowon.com/jimmy/go-common/config"
// 从文件加载配置（支持绝对路径和相对路径）
config, err := config.LoadFromFile("/path/to/config.json")
@@ -167,7 +167,7 @@ addr := config.GetRedisAddr()
corsConfig := config.GetCORS()
// 使用CORS中间件
import "git.toowon.com/jimmy/go-commom/middleware"
import "git.toowon.com/jimmy/go-common/middleware"
chain := middleware.NewChain(
middleware.CORS(corsConfig),
)
@@ -279,6 +279,16 @@ if minioConfig != nil {
| Endpoint | string | 服务端点（可选，默认使用区域端点） | - |
| Timeout | int | 请求超时时间（秒） | 10 |
### LoggerConfig 日志配置
| 字段 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| Level | string | 日志级别: debug, info, warn, error | info |
| Output | string | 输出方式: stdout, stderr, file, both | stdout |
| FilePath | string | 日志文件路径（当output为file或both时必需） | - |
| Prefix | string | 日志前缀 | - |
| DisableTimestamp | bool | 禁用时间戳 | false |
## 完整示例
### 示例1：加载配置并使用
@@ -289,8 +299,8 @@ package main
import (
"log"
"git.toowon.com/jimmy/go-commom/config"
"git.toowon.com/jimmy/go-commom/middleware"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/middleware"
"gorm.io/driver/mysql"
"gorm.io/gorm"
)
@@ -466,6 +476,12 @@ dsn, err := cfg.GetDatabaseDSN()
**返回：** 短信配置对象（可能为nil）
### (c *Config) GetLogger() *LoggerConfig
获取日志配置。
**返回：** 日志配置对象（可能为nil）
## 注意事项
1. **配置文件路径**：

6
docs/datetime.md
View File

@@ -19,7 +19,7 @@
### 1. 设置默认时区
```go
import "git.toowon.com/jimmy/go-commom/datetime"
import "git.toowon.com/jimmy/go-common/datetime"
// 设置默认时区为上海时区
err := datetime.SetDefaultTimeZone(datetime.AsiaShanghai)
@@ -401,7 +401,7 @@ import (
"log"
"time"
"git.toowon.com/jimmy/go-commom/datetime"
"git.toowon.com/jimmy/go-common/datetime"
)
func main() {
@@ -428,7 +428,7 @@ import (
"fmt"
"log"
"git.toowon.com/jimmy/go-commom/datetime"
"git.toowon.com/jimmy/go-common/datetime"
)
func main() {

10
docs/email.md
View File

@@ -18,8 +18,8 @@
```go
import (
"git.toowon.com/jimmy/go-commom/config"
"git.toowon.com/jimmy/go-commom/email"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/email"
)
// 从配置加载
@@ -107,7 +107,7 @@ if err != nil {
### 5. 使用Message结构发送（便捷方法）
```go
import "git.toowon.com/jimmy/go-commom/email"
import "git.toowon.com/jimmy/go-common/email"
msg := &email.Message{
To: []string{"to@example.com"},
@@ -295,8 +295,8 @@ package main
import (
"log"
"git.toowon.com/jimmy/go-commom/config"
"git.toowon.com/jimmy/go-commom/email"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/email"
)
func main() {

32
docs/factory.md
View File

@@ -16,8 +16,8 @@
```go
import (
"git.toowon.com/jimmy/go-commom/config"
"git.toowon.com/jimmy/go-commom/factory"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/factory"
)
// 加载配置
@@ -63,7 +63,21 @@ resp, err := smsClient.SendSimple(
)
```
### 4. 完整示例
### 4. 获取日志记录器（已初始化）
```go
// 直接获取已初始化的日志记录器
logger, err := fac.GetLogger()
if err != nil {
log.Fatal(err)
}
// 直接使用，无需再创建
logger.Info("Application started")
logger.Error("Error occurred: %v", err)
```
### 5. 完整示例
```go
package main
@@ -71,8 +85,8 @@ package main
import (
"log"
"git.toowon.com/jimmy/go-commom/config"
"git.toowon.com/jimmy/go-commom/factory"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/factory"
)
func main() {
@@ -152,6 +166,14 @@ func main() {
**说明：** 如果短信配置为nil，返回错误。
### (f *Factory) GetLogger() (*logger.Logger, error)
获取日志记录器（已初始化）。
**返回：** 已初始化的日志记录器对象和错误信息
**说明：** 如果日志配置为nil，会使用默认配置创建。
### (f *Factory) GetConfig() *config.Config
获取配置对象。

4
docs/http.md
View File

@@ -49,7 +49,7 @@ HTTP Restful工具提供了标准化的HTTP请求和响应处理功能，包含
```go
import (
"net/http"
"git.toowon.com/jimmy/go-commom/http"
"git.toowon.com/jimmy/go-common/http"
)
// 简单成功响应（data为nil）
@@ -198,7 +198,7 @@ package main
import (
"net/http"
"git.toowon.com/jimmy/go-commom/http"
"git.toowon.com/jimmy/go-common/http"
)
// 用户列表接口

266
docs/logger.md Normal file
View File

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

30
docs/middleware.md
View File

@@ -29,7 +29,7 @@ CORS中间件用于处理跨域资源共享，支持：
```go
import (
"net/http"
"git.toowon.com/jimmy/go-commom/middleware"
"git.toowon.com/jimmy/go-common/middleware"
)
func main() {
@@ -50,7 +50,7 @@ func main() {
```go
import (
"net/http"
"git.toowon.com/jimmy/go-commom/middleware"
"git.toowon.com/jimmy/go-common/middleware"
)
func main() {
@@ -131,9 +131,9 @@ corsHandler := middleware.CORS(corsConfig)(handler)
```go
import (
"net/http"
"git.toowon.com/jimmy/go-commom/middleware"
"git.toowon.com/jimmy/go-commom/http"
"git.toowon.com/jimmy/go-commom/datetime"
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/datetime"
)
func handler(w http.ResponseWriter, r *http.Request) {
@@ -162,8 +162,8 @@ func main() {
```go
import (
"net/http"
"git.toowon.com/jimmy/go-commom/middleware"
"git.toowon.com/jimmy/go-commom/datetime"
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/datetime"
)
func handler(w http.ResponseWriter, r *http.Request) {
@@ -183,8 +183,8 @@ func main() {
```go
import (
"net/http"
"git.toowon.com/jimmy/go-commom/http"
"git.toowon.com/jimmy/go-commom/datetime"
"git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/datetime"
)
func GetUserList(w http.ResponseWriter, r *http.Request) {
@@ -240,7 +240,7 @@ X-Timezone: Asia/Shanghai
```go
import (
"net/http"
"git.toowon.com/jimmy/go-commom/middleware"
"git.toowon.com/jimmy/go-common/middleware"
)
func handler(w http.ResponseWriter, r *http.Request) {
@@ -282,9 +282,9 @@ import (
"log"
"net/http"
"git.toowon.com/jimmy/go-commom/middleware"
"git.toowon.com/jimmy/go-commom/http"
"git.toowon.com/jimmy/go-commom/datetime"
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/http"
"git.toowon.com/jimmy/go-common/datetime"
)
func apiHandler(w http.ResponseWriter, r *http.Request) {
@@ -331,8 +331,8 @@ package main
import (
"net/http"
"git.toowon.com/jimmy/go-commom/middleware"
"git.toowon.com/jimmy/go-commom/http"
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/http"
)
func main() {

2
docs/migration.md
View File

@@ -21,7 +21,7 @@
import (
"gorm.io/driver/mysql"
"gorm.io/gorm"
"git.toowon.com/jimmy/go-commom/migration"
"git.toowon.com/jimmy/go-common/migration"
)
// 初始化数据库连接

10
docs/sms.md
View File

@@ -19,8 +19,8 @@
```go
import (
"git.toowon.com/jimmy/go-commom/config"
"git.toowon.com/jimmy/go-commom/sms"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/sms"
)
// 从配置加载
@@ -102,7 +102,7 @@ if err != nil {
### 5. 使用SendRequest结构发送（便捷方法）
```go
import "git.toowon.com/jimmy/go-commom/sms"
import "git.toowon.com/jimmy/go-common/sms"
req := &sms.SendRequest{
PhoneNumbers: []string{"13800138000", "13900139000"},
@@ -329,8 +329,8 @@ import (
"fmt"
"log"
"git.toowon.com/jimmy/go-commom/config"
"git.toowon.com/jimmy/go-commom/sms"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/sms"
)
func main() {

22
docs/storage.md
View File

@@ -21,8 +21,8 @@
```go
import (
"git.toowon.com/jimmy/go-commom/config"
"git.toowon.com/jimmy/go-commom/storage"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/storage"
)
// 加载配置
@@ -50,7 +50,7 @@ if err != nil {
import (
"context"
"os"
"git.toowon.com/jimmy/go-commom/storage"
"git.toowon.com/jimmy/go-common/storage"
)
// 打开文件
@@ -81,7 +81,7 @@ fmt.Printf("File URL: %s\n", url)
```go
import (
"net/http"
"git.toowon.com/jimmy/go-commom/storage"
"git.toowon.com/jimmy/go-common/storage"
)
// 创建上传处理器
@@ -125,7 +125,7 @@ curl -X POST http://localhost:8080/upload \
```go
import (
"net/http"
"git.toowon.com/jimmy/go-commom/storage"
"git.toowon.com/jimmy/go-common/storage"
)
// 创建代理查看处理器
@@ -144,7 +144,7 @@ GET /file?key=images/test.jpg
### 5. 生成对象键
```go
import "git.toowon.com/jimmy/go-commom/storage"
import "git.toowon.com/jimmy/go-common/storage"
// 生成简单对象键
objectKey := storage.GenerateObjectKey("images/", "test.jpg")
@@ -288,9 +288,9 @@ import (
"log"
"net/http"
"git.toowon.com/jimmy/go-commom/config"
"git.toowon.com/jimmy/go-commom/middleware"
"git.toowon.com/jimmy/go-commom/storage"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/middleware"
"git.toowon.com/jimmy/go-common/storage"
)
func main() {
@@ -344,8 +344,8 @@ import (
"log"
"os"
"git.toowon.com/jimmy/go-commom/config"
"git.toowon.com/jimmy/go-commom/storage"
"git.toowon.com/jimmy/go-common/config"
"git.toowon.com/jimmy/go-common/storage"
)
func main() {