# BaseFramework

**Repository Path**: mstes/base-framework

## Basic Information

- **Project Name**: BaseFramework
- **Description**: 基于go开发的后端组脚手架，使用说明详见README.md
- **Primary Language**: Go
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-01-25
- **Last Updated**: 2026-02-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# base-framework
## 语言切换 / Language Switch
- 🇨🇳 中文文档：[README-zh.md](https://gitee.com/mstes/base-framework/blob/master/README.md)
- English Documentation：[README-en.md](https://gitee.com/mstes/base-framework/blob/master/README.en.md)
## 项目概览
该框架封装了 8 大核心组件，覆盖数据存储、消息队列、文件存储、日志、连接池等后端开发核心场景，各组件均提供统一的初始化方式与核心功能封装，开箱即用。

| 组件名称       | 对应目录        | 核心功能                                                                 |
|----------------|-----------------|--------------------------------------------------------------------------|
| DB（MySQL）    | `db`            | 基于 GORM 封装，支持连接池配置、事务执行、数据 CURD，简化 MySQL 操作流程  |
| Elasticsearch  | `es`            | 支持索引创建/查询、文档增删改查（匹配查询等），简化 ES 交互逻辑            |
| Logger         | `logger`        | 支持同步（标准输出）、异步（文件存储）日志，支持日志分级、文件切割/压缩    |
| MinIO          | `minio`         | 支持对象存储的文件上传、下载、删除，自动初始化 Bucket，支持大文件处理      |
| MongoDB        | `mongodriver`   | 支持文档增删改查、分页查询、索引创建（唯一索引/复合索引）、事务处理       |
| Object Pool    | `pool`          | 通用对象池封装，支持自定义对象创建，减少对象频繁创建/销毁的性能开销        |
| RabbitMQ       | `rabbitmq`      | 支持连接自动重试、消息发布/消费、死信队列配置、消息回调通知              |
| Redis          | `redis`         | 基于 go-redis 封装，支持连接池配置、事务执行，简化 Redis 键值对操作        |

## 前置要求
1. Go 版本：`1.19+`（兼容后续高版本）
2. 中间件环境：使用对应组件前，需部署并启动该中间件（如 MySQL、RabbitMQ 等），确保网络互通
3. 依赖拉取：框架依赖以下第三方包，可通过 `go mod tidy` 自动拉取
    - GORM：`gorm.io/gorm`
    - go-redis：`github.com/redis/go-redis/v9`
    - MinIO SDK：`github.com/minio/minio-go/v7`
    - MongoDB SDK：`go.mongodb.org/mongo-driver/v2/mongo`
    - RabbitMQ SDK：`github.com/streadway/amqp`

## 包导入说明
### 1. 初始化 Go Module（若项目未初始化）
如果你的项目还未配置 `go.mod`，先执行以下命令初始化模块（替换 `your/project/module` 为你的项目模块路径，如 `github.com/你的用户名/你的项目名`）：
```bash
go mod init your/project/module
```

### 2. 拉取框架包
执行以下 `go get` 命令拉取该框架到你的项目中（确保网络能访问 Gitee 仓库）：
```bash
go get "gitee.com/mstes/base-framework@v1.0.4"
```

### 3. 代码中导入具体组件
框架的各组件支持独立导入，无需整体引入，减少项目依赖体积，示例如下：
```go
// 导入 DB 组件
import "gitee.com/mstes/base-framework/db"

// 导入 Redis 组件
import redisdriver "gitee.com/mstes/base-framework/redis"

// 导入 Logger 组件
import "gitee.com/mstes/base-framework/logger"

// 导入 MongoDB 组件
import "gitee.com/mstes/base-framework/mongodriver"

// 导入其他组件
import esdriver "gitee.com/mstes/base-framework/es"
import miniodriver "gitee.com/mstes/base-framework/minio"
import objpool "gitee.com/mstes/base-framework/pool"
import mqdriver "gitee.com/mstes/base-framework/rabbitmq"
```

### 4. 更新框架版本
若后续框架有更新，可执行以下命令升级到最新版本：
```bash
go get -u gitee.com/mstes/base-framework
```

## 快速开始
以下是各组件的核心使用示例，完整可运行代码见各组件目录下的 `test.go` 文件。

### 1. DB（MySQL）
#### 功能说明
初始化 MySQL 连接、配置连接池、通过事务插入数据，附带日志错误捕获。

#### 使用示例
```go
package main

import (
	"context"

	"gitee.com/mstes/base-framework/db"
	logger "gitee.com/mstes/fast-logger-go/logger"
	"gorm.io/gorm"
)

var ServiceLog logger.OutPut

// 初始化日志
func MakeLogger() {
	ServiceLog = logger.NewSyncLogger()
	ServiceLog.SetLogLevel(logger.Debug)
}

// 定义数据模型
type Test struct {
	gorm.Model
	Name string `gorm:"column:name"`
}

func main() {
	MakeLogger()

	// 初始化 DB 客户端
	dbClient, err := db.New(db.WithProductLogModel[Test](), db.WithDriverWithDefaultMode[Test](&db.MysqlConfig{
		Host:     "127.0.0.1",
		Port:     "50001",
		Username: "root",
		Password: "123456",
		Database: "my_system",
		SSL:      false,
		ConnectionPool: &db.ConnectionPoolConfig{
			MaxOpenConns:    5,
			MaxIdleConns:    5,
			ConnMaxLifetime: 4,
			ConnMaxIdleTime: 1,
		},
	}))
	if err != nil {
		ServiceLog.Error(map[string]any{"err": err.Error()}, "create db driver error")
		return
	}

	// 执行事务插入数据
	if err := dbClient.Execute(context.Background(), func(db *gorm.DB) error {
		return db.Create(&Test{Name: "test-name-001"}).Error
	}); err != nil {
		ServiceLog.Error(map[string]any{"err": err.Error()}, "create test error")
		return
	}

	ServiceLog.Info(map[string]any{"name": "test-name-001"}, "create test success")
}
```

### 2. Elasticsearch
#### 功能说明
初始化 ES 客户端，支持文档匹配查询，可扩展索引创建、文档新增/删除等功能。

#### 使用示例
```go
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"time"

	esdriver "gitee.com/mstes/base-framework/es"
)

func main() {
	// 初始化 ES 客户端
	driver, err := esdriver.New(esdriver.WithSetConfig(&esdriver.Config{
		Addresses: []string{"http://127.0.0.1:9200"},
		Password:  "123456",
	}))
	if err != nil {
		fmt.Println("es driver init failed,err = ", err)
		return
	}

	// 上下文超时控制
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	// 匹配查询文档
	searchReq := &esdriver.SearchRequest{
		IndexName: "dish",
		Key:       "name",
		Val:       "辣椒炒肉",
	}
	results, err := driver.MatchSearch(ctx, searchReq)
	if err != nil {
		fmt.Println("search document failed,err = ", err)
		return
	}

	// 打印查询结果
	for _, result := range results {
		jsonResult, err := json.Marshal(result)
		if err != nil {
			fmt.Println("marshal result failed,err = ", err)
			return
		}
		fmt.Println("查询结果 = ", string(jsonResult))
	}
}
```

### 3. Logger
#### 功能说明
支持两种日志模式：同步日志（标准输出）、异步日志（文件存储，自动切割/压缩），支持日志分级输出。

#### 使用示例
```go
package main

import (
	"time"

	"gitee.com/mstes/base-framework/logger"
)

// 同步日志（标准输出）
func TestSync() {
	logger.InitLogger(logger.StdoutModel, nil)
	logger.Log.Debug(logger.M{"err_msg": "错误消息1"}, "test debug")
	logger.Log.Info(logger.M{"err_msg": "错误消息2"}, "test info")
}

// 异步日志（文件存储）
func TestAsync() {
	logger.InitLogger(logger.FileModel, &logger.AsyncLogConfig{
		LoggerName: "test",
		Filename:   "test.log",
		MaxSize:    10,
		MaxBackups: 3,
		MaxDay:     7,
		Compress:   true,
	})
	logger.Log.Debug(logger.M{"err_msg": "错误消息1"}, "test debug")
	logger.Log.Info(logger.M{"err_msg": "错误消息2"}, "test info")
	time.Sleep(time.Second * 5) // 等待异步日志写入完成
}

func main() {
	TestAsync() // 切换 TestSync() 可运行同步日志
}
```

### 4. MinIO
#### 功能说明
初始化 MinIO 客户端，自动创建 Bucket，支持文件上传、下载、删除等对象存储核心操作。

#### 使用示例
```go
package main

import (
	"bufio"
	"context"
	"encoding/json"
	"fmt"
	"os"
	"time"

	miniodriver "gitee.com/mstes/base-framework/minio"
	"github.com/google/uuid"
)

const MockDataFileName = "./test.json"

// 生成模拟 JSON 数据文件
func MakeMockJsonData() error {
	file, err := os.OpenFile(MockDataFileName, os.O_CREATE|os.O_WRONLY, 0644)
	if err != nil {
		return err
	}
	defer file.Close()

	data := map[string]any{"k1": "v1", "k2": "v2"}
	writer := bufio.NewWriter(file)
	defer writer.Flush()

	for i := 0; i < 1000; i++ {
		jdata, err := json.MarshalIndent(data, "", "  ")
		if err != nil {
			return err
		}
		if _, err := writer.Write(jdata); err != nil {
			return err
		}
	}
	return nil
}

func main() {
	bucketName := "test-bucket"

	// 初始化 MinIO 客户端
	client, err := miniodriver.New(miniodriver.WithSetConfig(&miniodriver.DriverConfig{
		Addr:            "127.0.0.1:9000",
		AccessKeyID:     "admin",
		SecretAccessKey: "12345678",
		UseSSL:          false,
		InitBucketName:  bucketName,
		ObjectLocking:   true,
	}))
	if err != nil {
		fmt.Println("minio driver init failed,err = ", err)
		return
	}

	// 生成模拟数据文件
	if err := MakeMockJsonData(); err != nil {
		fmt.Println(err)
		return
	}

	// 打开模拟数据文件
	file, err := os.Open(MockDataFileName)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer file.Close()

	fileInfo, err := os.Stat(MockDataFileName)
	if err != nil {
		fmt.Println(err)
		return
	}

	// 上下文超时控制
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	// 构建文件上传信息
	fileID := "test" + uuid.NewString()
	uploadEvent := &miniodriver.UploadEvent{
		FileID:   fileID,
		MimeType: "application/json",
		In:       bufio.NewReader(file),
		Size:     fileInfo.Size(),
	}

	// 上传文件
	if err := client.UpLoad(ctx, bucketName, uploadEvent); err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println("文件上传成功,file_id = ", fileID)

	// 下载文件
	downloadEvent := &miniodriver.DownloadEvent{
		FileID: fileID,
		Buff:   make([]byte, 0, fileInfo.Size()),
	}
	response, err := client.Get(ctx, bucketName, downloadEvent)
	if err != nil {
		fmt.Println("文件下载失败,err = ", err)
		return
	}
	for _, rsp := range response {
		fmt.Println("file_id = ", rsp.FileID)
	}
	fmt.Println("文件下载完毕")

	// 删除文件
	if err := client.RemoveFile(ctx, bucketName, fileID); err != nil {
		fmt.Println("文件删除失败,err = ", err)
		return
	}
	fmt.Println("文件删除成功,file_id = ", fileID)
}
```

### 5. MongoDB
#### 功能说明
封装了文档增删改查、分页查询、索引创建等核心功能，支持事务处理与对象池管理，基于泛型实现通用化调用。

#### 使用示例（初始化与新增文档）
```go
package main

import (
	"context"
	"fmt"

	"gitee.com/mstes/base-framework/mongodriver"
)

// 定义文档模型
type User struct {
	Name string `bson:"name"`
	Age  int    `bson:"age"`
}

func main() {
	ctx := context.Background()
	// MongoDB 连接 URI
	uri := "mongodb+srv://<用户名>:<密码>@cluster0.mongodb.net/?retryWrites=true&w=majority"
	dbName := "my_db"

	// 初始化 MongoDB 客户端
	client, err := mongodriver.NewClient[User](ctx, uri, dbName)
	if err != nil {
		fmt.Println("mongo client init failed,err = ", err)
		return
	}

	// 新增文档
	docs := []*User{{Name: "zhangsan", Age: 20}}
	if err := client.AddDocs(ctx, "user", docs); err != nil {
		fmt.Println("add docs failed,err = ", err)
		return
	}
	fmt.Println("add docs success")
}
```

### 6. Object Pool
#### 功能说明
通用对象池封装，基于泛型实现，减少对象频繁创建/销毁的性能损耗，支持自定义对象生成逻辑。

#### 使用示例
```go
package main

import (
	"fmt"
	"time"

	objpool "gitee.com/liuhaodon/base-framework/pool"
	"github.com/google/uuid"
)

// 定义自定义对象
type Test struct {
	ID string
}

func main() {
	// 初始化对象池
	p := objpool.New(objpool.WithSetConfig(&objpool.PoolConfig[*Test]{
		NewFunc: func() *Test { // 自定义对象生成逻辑
			return &Test{
				ID: uuid.NewString(),
			}
		},
	}))

	// 循环从对象池获取/归还对象
	for {
		t, err := p.Get()
		if err != nil {
			fmt.Println("get obj failed,err = ", err)
			return
		}
		fmt.Println("获取对象ID = ", t.ID)

		if err := p.Put(t); err != nil {
			fmt.Println("put obj failed,err = ", err)
			return
		}
		time.Sleep(time.Second)
	}
}
```

### 7. RabbitMQ
#### 功能说明
支持连接自动重试、消息发布/消费、死信队列配置，提供错误回调与消息退回回调，简化消息队列的使用流程。

#### 使用示例
```go
package main

import (
	"fmt"
	"time"

	mqdriver "gitee.com/liuhaodon/base-framework/rabbitmq"
	"github.com/google/uuid"
)

const connectURL = "amqp://admin:123456@127.0.0.1:5672"

func main() {
	// 初始化 RabbitMQ 驱动
	driver, err := mqdriver.New(mqdriver.WithSetConfig(&mqdriver.RabbitmqConfig{
		URL:         connectURL,
		Username:    "admin",
		Password:    "123456",
		VirtualHost: "Test",
		BindAndDeclareConfig: &mqdriver.BindAndDeclareConfig{
			Exchange:           "test-exchange",
			Queue:              "test-queue",
			DeadLetterExchange: "test-dead-letter-exchange",
			DeadLetterQueue:    "test-dead-letter-queue",
		},
	}))
	if err != nil {
		fmt.Println("创建驱动失败,err = ", err)
		return
	}
	fmt.Println("创建驱动成功")

	// 设置错误回调
	driver.SetOnErrCallBack(func(err error) {
		fmt.Println("触发错误回调,err = ", err)
	})

	// 设置消息退回回调
	driver.SetOnReturnCallBack(func(msg *mqdriver.Message, err error) {
		fmt.Println("消息发布失败,被mq退回,err = ", err)
		fmt.Println("消息内容 = ", string(msg.Content))
		fmt.Println("消息ID = ", msg.ID)
	})

	// 发布消息
	if err := driver.Publish(&mqdriver.Message{
		ID:          uuid.NewString(),
		RoutingKey:  "test-queue",
		ContentType: "application/json",
		Content:     []byte("test_data"),
	}); err != nil {
		fmt.Println("发布消息失败,err = ", err)
		return
	}

	// 消息去重消费
	msgSet := map[string]bool{}
	if err := driver.Consumer("test-consumer", func(msg *mqdriver.Message) error {
		if _, ok := msgSet[msg.ID]; ok {
			return nil
		}
		fmt.Println("消费消息,内容 = ", string(msg.Content))
		msgSet[msg.ID] = true
		return nil
	}); err != nil {
		fmt.Println("消费消息失败,err = ", err)
		return
	}

	time.Sleep(time.Minute * 10)
}
```

### 8. Redis
#### 功能说明
基于 go-redis 封装，支持连接池配置、事务执行，简化 Redis 批量操作与事务处理流程，支持重试配置。

#### 使用示例
```go
package main

import (
	"context"
	"fmt"
	"time"

	redisdriver "gitee.com/liuhaodon/base-framework/redis"
	"github.com/redis/go-redis/v9"
)

func main() {
	// 初始化 Redis 客户端
	client, err := redisdriver.New(redisdriver.WithInitConfig(&redisdriver.DriverConfig{
		Addr:       "127.0.0.1:6379",
		Password:   "123456",
		DB:         0,
		MaxRetries: 3,
		ConnPoolConfig: &redisdriver.ConnectionPoolConfig{
			PoolSize:     10,
			MinIdleConns: 10,
		},
	}))
	if err != nil {
		fmt.Println("redis client init failed,err = ", err)
		return
	}

	// 上下文超时控制
	ctx, cancel := context.WithTimeout(context.Background(), time.Second*10)
	defer cancel()

	// 执行 Redis 事务
	if err := client.WithTransaction(ctx, func(tx *redis.Tx) error {
		pipe := tx.Pipeline()
		pipe.Set(ctx, "k1", "v1", 0)
		pipe.Set(ctx, "k2", "v2", 0)
		_, err := pipe.Exec(ctx)
		return err
	}, "k1", "k2"); err != nil {
		fmt.Println("执行事务失败,err = ", err)
		return
	}

	fmt.Println("redis 事务执行成功")
}
```

## 核心特性
1. **统一封装**：所有组件提供一致的 `New()` 初始化方法，配置项通过结构体传入，基于 Option 模式实现灵活配置，降低学习成本。
2. **高可用**：内置连接池、自动重连、事务处理、超时控制，关键操作附带错误回调，提升服务稳定性。
3. **泛型支持**：基于 Go 泛型实现通用化封装，无需重复编写类型转换代码，提升开发效率。
4. **易用性强**：屏蔽中间件底层复杂逻辑，暴露简洁的核心 API，开箱即用，无需额外的复杂配置。
5. **独立解耦**：各组件解耦设计，支持独立导入和使用，不会引入无用依赖，减少项目体积。
6. **完善的错误处理**：所有核心操作均返回错误信息，配合日志组件，方便问题排查与线上运维。

## 注意事项
1. 使用各组件前，需确保对应的中间件已正常启动，且配置项（地址、端口、密码等）与实际环境一致。
2. 日志组件使用文件模式时，需确保程序对日志目录有读写权限，避免日志写入失败。
3. RabbitMQ 使用前，需提前创建对应的虚拟主机，框架会自动创建交换器、队列与死信队列绑定关系。
4. MongoDB 连接 URI 需根据部署模式（单机/集群/云服务）调整，确保账号拥有对应的数据库操作权限。
5. 生产环境中，建议根据业务流量调整连接池大小、日志保留策略、超时时间等配置，避免资源耗尽。
6. MinIO 上传大文件时，建议调整上下文超时时间，避免因超时导致上传失败。
7. 所有组件的 `test.go` 文件均为可运行的示例，可直接修改配置后运行测试。

## 总结
本框架是 Go 语言后端开发的基础组件集合，覆盖了后端开发中最常用的 8 大核心场景，通过统一的封装风格和简洁的 API，大幅减少开发者的重复开发工作。

框架的核心使用流程为：**初始化 Go Mod → 拉取框架包 → 导入指定组件 → 配置中间件参数 → 调用核心 API**，所有组件均支持开箱即用，同时保留了灵活的配置扩展能力，可适配不同的业务场景和生产环境需求。