From fd37c5c301609510d95cf554cc9391c7a7ed9cf5 Mon Sep 17 00:00:00 2001
From: Jimmy Xue <jeanbi@gmail.com>
Date: Sun, 30 Nov 2025 16:03:50 +0800
Subject: [PATCH] =?UTF-8?q?=E6=81=A2=E5=A4=8D=E6=95=B0=E6=8D=AE=E5=BA=93?=
 =?UTF-8?q?=E5=AF=B9=E8=B1=A1=E4=B8=8Eredis=E5=AF=B9=E8=B1=A1=E7=9A=84?=
 =?UTF-8?q?=E8=BF=94=E5=9B=9E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                   |  6 +++-
 docs/factory.md             | 58 +++++++++++++++++++++++++++++++++----
 examples/factory_example.go | 26 +++++++++++++++--
 factory/factory.go          |  8 +++++
 4 files changed, 90 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index d2e52c0..84d6cf8 100644
--- a/README.md
+++ b/README.md
@@ -239,9 +239,13 @@ fac.RedisSet(ctx, "key", "value", time.Hour)
 value, _ := fac.RedisGet(ctx, "key")
 fac.RedisDelete(ctx, "key")
 
-// 数据库（GORM已经很灵活，直接返回对象）
+// 数据库（黑盒模式，获取已初始化对象）
 db, _ := fac.GetDatabase()
 db.Find(&users)
+
+// Redis客户端（黑盒模式，获取已初始化对象）
+redisClient, _ := fac.GetRedisClient()
+redisClient.HGet(ctx, "key", "field").Result()
 ```
 
 更多示例请查看 [examples](./examples/) 目录。
diff --git a/docs/factory.md b/docs/factory.md
index fd3ceb3..a407371 100644
--- a/docs/factory.md
+++ b/docs/factory.md
@@ -136,23 +136,52 @@ err := fac.RedisDelete(ctx, "user:123", "user:456")
 exists, err := fac.RedisExists(ctx, "user:123")
 ```
 
-### 7. 数据库操作
-
-数据库保持返回 GORM 对象，因为 GORM 已经提供了很好的抽象：
+### 7. 数据库操作（黑盒模式）
 
 ```go
-// 获取数据库对象（延迟初始化）
+// 获取数据库对象（已初始化，黑盒模式）
 db, err := fac.GetDatabase()
 if err != nil {
     log.Fatal(err)
 }
 
-// 直接使用GORM
+// 直接使用GORM，无需自己实现创建逻辑
 var users []User
 db.Find(&users)
 db.Create(&user)
 ```
 
+### 8. Redis操作（获取客户端对象）
+
+```go
+import (
+    "context"
+    "github.com/redis/go-redis/v9"
+)
+
+ctx := context.Background()
+
+// 获取Redis客户端对象（已初始化，黑盒模式）
+redisClient, err := fac.GetRedisClient()
+if err != nil {
+    log.Fatal(err)
+}
+
+// 直接使用Redis客户端，无需自己实现创建逻辑
+val, err := redisClient.Get(ctx, "key").Result()
+if err != nil && err != redis.Nil {
+    log.Printf("Redis error: %v", err)
+} else if err == redis.Nil {
+    fmt.Println("Key not found")
+} else {
+    fmt.Printf("Value: %s\n", val)
+}
+
+// 使用高级功能（如Hash操作）
+redisClient.HSet(ctx, "user:123", "name", "John")
+name, _ := redisClient.HGet(ctx, "user:123", "name").Result()
+```
+
 
 ## 完整示例
 
@@ -400,7 +429,26 @@ func main() {
 - 自动配置连接池参数
 - 数据库时间统一使用UTC时区
 - 延迟初始化，首次调用时创建连接
+- 黑盒模式：只需传递config对象，无需自己实现创建逻辑
 
+### Redis方法
+
+#### GetRedisClient() (*redis.Client, error)
+
+获取Redis客户端对象（已初始化）。
+
+**返回：** 已初始化的Redis客户端对象和错误信息
+
+**说明：** 
+- 自动处理所有配置检查和连接测试
+- 自动设置默认值（连接池大小、超时时间等）
+- 连接失败时会自动关闭客户端并返回错误
+- 返回的客户端已通过Ping测试，可直接使用
+- 黑盒模式：只需传递config对象，无需自己实现创建逻辑
+- 推荐使用 `RedisGet`、`RedisSet`、`RedisDelete` 等方法直接操作Redis
+- 如果需要使用Redis的高级功能（如Hash、List、Set等），可以使用此方法获取客户端对象
+
+### 配置方法
 
 #### GetConfig() *config.Config
 
diff --git a/examples/factory_example.go b/examples/factory_example.go
index f5acdb1..edbafce 100644
--- a/examples/factory_example.go
+++ b/examples/factory_example.go
@@ -8,6 +8,7 @@ import (
 	"time"
 
 	"git.toowon.com/jimmy/go-common/factory"
+	"github.com/redis/go-redis/v9"
 )
 
 func main() {
@@ -145,12 +146,12 @@ func main() {
 		fac.LogInfo("键是否存在: %v", exists)
 	}
 
-	// ========== 数据库操作 ==========
+	// ========== 数据库操作（黑盒模式，获取对象） ==========
 	db, err := fac.GetDatabase()
 	if err != nil {
 		fac.LogError("数据库连接失败: %v", err)
 	} else {
-		// 直接使用GORM
+		// 直接使用GORM，无需自己实现创建逻辑
 		var count int64
 		if err := db.Table("users").Count(&count).Error; err != nil {
 			fac.LogError("查询用户数量失败: %v", err)
@@ -159,6 +160,27 @@ func main() {
 		}
 	}
 
+	// ========== Redis操作（获取客户端对象，黑盒模式） ==========
+	redisClient, err := fac.GetRedisClient()
+	if err != nil {
+		fac.LogError("Redis客户端不可用: %v", err)
+	} else {
+		// 直接使用Redis客户端，无需自己实现创建逻辑
+		val, err := redisClient.Get(ctx, "test_key").Result()
+		if err != nil && err != redis.Nil {
+			fac.LogError("Redis错误: %v", err)
+		} else if err == redis.Nil {
+			fac.LogInfo("Redis键不存在")
+		} else {
+			fac.LogInfo("Redis值: %s", val)
+		}
+
+		// 使用高级功能（如Hash操作）
+		redisClient.HSet(ctx, "user:123", "name", "John")
+		name, _ := redisClient.HGet(ctx, "user:123", "name").Result()
+		fac.LogInfo("Redis Hash值: %s", name)
+	}
+
 
 	fac.LogInfo("示例执行完成")
 }
diff --git a/factory/factory.go b/factory/factory.go
index 4087557..8340107 100644
--- a/factory/factory.go
+++ b/factory/factory.go
@@ -430,6 +430,14 @@ func (f *Factory) getRedisClient() (*redis.Client, error) {
 	return client, nil
 }
 
+// GetRedisClient 获取Redis客户端对象（已初始化）
+// 返回已初始化的Redis客户端对象，可直接使用
+// 注意：推荐使用 RedisGet、RedisSet、RedisDelete 等方法直接操作Redis
+// 如果需要使用Redis的高级功能（如Hash、List、Set等），可以使用此方法获取客户端对象
+func (f *Factory) GetRedisClient() (*redis.Client, error) {
+	return f.getRedisClient()
+}
+
 // RedisGet 获取Redis值（黑盒模式）
 // key: Redis键
 func (f *Factory) RedisGet(ctx context.Context, key string) (string, error) {