feat(instance): migrate instance containers to type-safe generics (#4617)

### 变更说明

本次重构将项目中用于**实例管理的容器**从 `StrAnyMap`/`IntAnyMap` 迁移到类型安全的泛型实现
`KVMapWithChecker`,同时将相关的 `glist.List` 和 `gqueue.Queue`
替换为对应的泛型版本,以提高实例管理的类型安全性。并且减少原先代码中的大量类型断言,提高性能。

### 前因

目前`goframe`中大量使用了包含`any`的容器,然后通过断言去转换类型,麻烦且影响性能,尤其是对`gdb/gredis/glog`等需要高频获取`instance`实例的组件影响较大。最近几个版本中gf完成了数据结构容器的泛型化改造,以及我最近解决了其中几个泛型容器对于`typed
nil`过滤的问题,所以可以逐步迁移这些实例容器到泛型容器,减少断言优化性能

### 主要改进

#### 1. 实例容器泛型化

以下模块的实例管理容器已迁移到泛型实现:

**核心实例管理**:
- `database/gdb`: 数据库实例容器 → `KVMap[string, DB]`
- `database/gredis`: Redis 实例容器 → `KVMap[string, *Redis]`
- `database/gredis`: Redis 配置容器 → `KVMap[string, *Config]`
- `os/gcfg`: 配置实例容器 → `KVMap[string, *Config]`
- `os/glog`: 日志实例容器 → `KVMap[string, *Logger]`
- `os/gview`: 视图实例容器 → `KVMap[string, *View]`
- `i18n/gi18n`: 国际化实例容器 → `KVMap[string, *Manager]`

**网络服务实例**:
- `net/ghttp`: HTTP 服务器容器 → `KVMap[string, *Server]`
- `net/gtcp`: TCP 服务器容器 → `KVMap[any, *Server]`
- `net/gudp`: UDP 服务器容器 → `KVMap[string, *Server]`

**其他实例容器**:
- `os/gres`: 资源实例容器 → `KVMap[string, *Resource]`
- `os/gfpool`: 文件池容器 → `KVMap[string, *Pool]`
- `os/gspath`: 路径搜索容器 → `KVMap[string, *SPath]`
- `net/gtcp`: 连接池容器 → `KVMap[string, *gpool.Pool]`

#### 2. 相关数据结构泛型化

- `os/gfsnotify`: 回调列表 → `TList[*Callback]`,事件队列 → `TQueue[*Event]`
- `os/grpool`: 任务队列 → `TList[*localPoolItem]`
- `os/gcache`: 事件队列 → `TList[*adapterMemoryEvent]`
- `net/ghttp`: 解析项列表 → `TList[*HandlerItemParsed]`
- `os/gproc`: 消息队列 → `TQueue[*MsgRequest]`
- `os/gmlock`: 锁映射 → `KVMap[string, *sync.RWMutex]`

### 技术实现

1. **引入检查器函数**: 为每个实例容器添加 `checker` 函数用于空值检测
2. **消除类型断言**: 实例获取时无需 `v.(*Type)` 转换
3. **明确函数签名**: `GetOrSetFuncLock` 的回调从 `func() any` 改为 `func() T`

### 使用示例

#### 实例容器的变更

**变更前**:
```go
// 旧的实例管理方式
var instances = gmap.NewStrAnyMap(true)

func Instance(name string) *Logger {
    v := instances.GetOrSetFuncLock(name, func() any {
        return New()
    })
    return v.(*Logger)  // 需要类型断言
}
```


**变更后**:
```go
// 新的泛型实例容器
var (
    checker   = func(v *Logger) bool { return v == nil }
    instances = gmap.NewKVMapWithChecker[string, *Logger](checker, true)
)

func Instance(name string) *Logger {
    return instances.GetOrSetFuncLock(name, New)  // 直接返回,无需断言
}
```


#### 队列容器的变更

**变更前**:
```go
// 旧的队列方式
events := gqueue.New()
events.Push(&Event{Path: "/tmp/file"})

if v := events.Pop(); v != nil {
    event := v.(*Event)  // 需要类型断言
    handleEvent(event)
}
```


**变更后**:
```go
// 新的泛型队列
events := gqueue.NewTQueue[*Event]()
events.Push(&Event{Path: "/tmp/file"})

if event := events.Pop(); event != nil {
    handleEvent(event)  // event 已是 *Event 类型
}
```


### 收益

-  **编译时类型安全**: 实例容器的类型错误在编译期捕获
-  **消除运行时断言**: 避免类型断言带来的 panic 风险
-  **提升代码可读性**: 实例管理逻辑更清晰
-  **改善开发体验**: IDE 类型提示和代码补全更准确

### 性能权衡

**编译时**:
- 泛型实例化会增加编译时间和二进制体积
- 预估编译时间增加 5-15%,二进制体积增加约 1-2MB

**运行时**:
- 减少类型断言的反射开销
- 提升实例获取等热点路径的性能
This commit is contained in:
Lance Add
2026-01-16 15:23:13 +08:00
committed by GitHub
parent 5d1712b4ab
commit d8a173d9f0
33 changed files with 208 additions and 225 deletions

View File

@ -863,8 +863,10 @@ const (
)
var (
// checker is the checker function for instances map.
checker = func(v DB) bool { return v == nil }
// instances is the management map for instances.
instances = gmap.NewStrAnyMap(true)
instances = gmap.NewKVMapWithChecker[string, DB](checker, true)
// driverMap manages all custom registered driver.
driverMap = map[string]Driver{}
@ -985,14 +987,14 @@ func Instance(name ...string) (db DB, err error) {
if len(name) > 0 && name[0] != "" {
group = name[0]
}
v := instances.GetOrSetFuncLock(group, func() any {
v := instances.GetOrSetFuncLock(group, func() DB {
db, err = NewByGroup(group)
return db
})
if v != nil {
return v.(DB), nil
return v, nil
}
return
return nil, err
}
// getConfigNodeByGroup calculates and returns a configuration node of given group. It

View File

@ -50,8 +50,10 @@ const (
)
var (
// configChecker checks whether the *Config is nil.
configChecker = func(v *Config) bool { return v == nil }
// Configuration groups.
localConfigMap = gmap.NewStrAnyMap(true)
localConfigMap = gmap.NewKVMapWithChecker[string, *Config](configChecker, true)
)
// SetConfig sets the global configuration for specified group.
@ -119,7 +121,7 @@ func GetConfig(name ...string) (config *Config, ok bool) {
group = name[0]
}
if v := localConfigMap.Get(group); v != nil {
return v.(*Config), true
return v, true
}
return &Config{}, false
}

View File

@ -14,8 +14,9 @@ import (
)
var (
// localInstances for instance management of redis client.
localInstances = gmap.NewStrAnyMap(true)
// checker is the checker function for instances map.
checker = func(v *Redis) bool { return v == nil }
localInstances = gmap.NewKVMapWithChecker[string, *Redis](checker, true)
)
// Instance returns an instance of redis client with specified group.
@ -26,7 +27,7 @@ func Instance(name ...string) *Redis {
if len(name) > 0 && name[0] != "" {
group = name[0]
}
v := localInstances.GetOrSetFuncLock(group, func() any {
return localInstances.GetOrSetFuncLock(group, func() *Redis {
if config, ok := GetConfig(group); ok {
r, err := New(config)
if err != nil {
@ -37,8 +38,4 @@ func Instance(name ...string) *Redis {
}
return nil
})
if v != nil {
return v.(*Redis)
}
return nil
}