# 客户端连接池

## 概述

客户端连接池（Client Pool）是一个用于管理和复用客户端连接的工具，可以显著提高客户端应用的性能和资源利用率。

## 作用

1. **连接复用**：复用已建立的连接，避免频繁创建和销毁连接，减少系统开销
2. **连接管理**：自动管理连接的生命周期，包括连接创建、验证、清理等
3. **并发控制**：限制最大连接数，防止连接数过多导致服务器压力
4. **资源优化**：预创建最小连接数，提高响应速度；自动清理空闲连接，节省资源
5. **故障恢复**：自动检测和移除无效连接，创建新连接替代

## 使用方法

### 1. 创建连接池

```go
import "github.com/noahlann/nnet/pkg/nnet"

// 创建连接池配置
poolConfig := &nnet.ClientPoolConfig{
    MaxSize:        10,  // 最大连接数
    MinSize:        2,   // 最小连接数（预创建）
    ClientConfig: &nnet.ClientConfig{
        Addr:          "tcp://127.0.0.1:8888",
        ConnectTimeout: 5 * time.Second,
        ReadTimeout:   5 * time.Second,
        WriteTimeout:  5 * time.Second,
    },
    AcquireTimeout: 5 * time.Second, // 获取连接超时时间
    IdleTimeout:    5 * time.Minute, // 空闲连接超时时间
}

// 创建连接池
pool, err := nnet.NewClientPool(poolConfig)
if err != nil {
    log.Fatalf("Failed to create connection pool: %v", err)
}
defer pool.Close()
```

### 2. 获取和释放连接

```go
// 获取连接
client, err := pool.Acquire()
if err != nil {
    log.Fatalf("Failed to acquire connection: %v", err)
}

// 使用连接
request := []byte("echo hello\n")
resp, err := client.Request(request, 5*time.Second)
if err != nil {
    log.Printf("Request failed: %v", err)
} else {
    fmt.Printf("Response: %s", string(resp))
}

// 释放连接（归还到连接池）
pool.Release(client)
```

### 3. 并发使用

```go
var wg sync.WaitGroup
for i := 0; i < numRequests; i++ {
    wg.Add(1)
    go func(id int) {
        defer wg.Done()
        
        // 从连接池获取连接
        client, err := pool.Acquire()
        if err != nil {
            log.Printf("Failed to acquire connection: %v", err)
            return
        }
        
        // 使用完毕后释放连接
        defer pool.Release(client)
        
        // 使用连接发送请求
        request := []byte(fmt.Sprintf("echo request-%d\n", id))
        resp, err := client.Request(request, 5*time.Second)
        if err != nil {
            log.Printf("Request failed: %v", err)
            return
        }
        
        fmt.Printf("Response: %s", string(resp))
    }(i)
}
wg.Wait()
```

### 4. 检查连接池状态

```go
// 获取当前连接数
size := pool.Size()

// 获取可用连接数
available := pool.Available()

// 检查连接池是否已关闭
isClosed := pool.IsClosed()

fmt.Printf("Pool status: Size=%d, Available=%d, IsClosed=%v\n", 
    size, available, isClosed)
```

## 配置说明

### ClientPoolConfig

- **MaxSize** (int): 最大连接数，默认值为 10
- **MinSize** (int): 最小连接数（预创建），默认值为 2
- **ClientConfig** (*ClientConfig): 客户端配置（地址、超时时间等）
- **AcquireTimeout** (time.Duration): 获取连接超时时间，默认值为 10 秒
- **IdleTimeout** (time.Duration): 空闲连接超时时间，默认值为 5 分钟

### 默认配置

使用 `nnet.DefaultClientPoolConfig()` 获取默认配置：

```go
config := nnet.DefaultClientPoolConfig()
config.ClientConfig.Addr = "tcp://127.0.0.1:8888"
pool, err := nnet.NewClientPool(config)
```

## 实现细节

### 1. 连接管理

- 连接池在创建时会预创建 `MinSize` 个连接
- 当连接数小于 `MaxSize` 时，可以动态创建新连接
- 连接在使用完毕后会被归还到连接池，供后续复用

### 2. 连接验证

- 从连接池获取连接时，会自动检查连接是否有效
- 如果连接无效，会自动创建新连接替代
- 释放连接时，也会检查连接有效性，无效连接会被移除

### 3. 空闲连接清理

- 如果配置了 `IdleTimeout`，连接池会定期检查并清理无效连接
- 清理间隔为 `IdleTimeout / 2`，确保及时清理无效连接

### 4. 并发安全

- 连接池使用原子操作和互斥锁保证并发安全
- `Acquire` 和 `Release` 操作是线程安全的
- 多个 goroutine 可以安全地并发使用连接池

### 5. 连接池关闭

- 调用 `Close()` 方法会关闭所有连接并停止所有 goroutine
- 关闭后的连接池不能再次使用
- 已获取的连接在释放时会被关闭（如果连接池已关闭）

## 最佳实践

1. **合理设置连接数**：根据实际并发需求设置 `MaxSize`，避免连接数过多或过少
2. **及时释放连接**：使用 `defer pool.Release(client)` 确保连接被正确释放
3. **处理错误**：始终检查 `Acquire()` 和 `Request()` 的返回错误
4. **资源清理**：在程序退出前调用 `pool.Close()` 关闭连接池
5. **超时设置**：合理设置 `AcquireTimeout` 和 `IdleTimeout`，避免资源浪费

## 示例

完整示例请参考：
- `examples/client_pool/server.go` - 服务器示例
- `examples/client_pool/client.go` - 客户端连接池示例

## API 参考

### ClientPool

- `Acquire() (Client, error)` - 获取连接
- `Release(client Client) error` - 释放连接
- `Close() error` - 关闭连接池
- `Size() int` - 获取当前连接数
- `Available() int` - 获取可用连接数
- `IsClosed() bool` - 检查连接池是否已关闭

### ClientPoolConfig

- `MaxSize int` - 最大连接数
- `MinSize int` - 最小连接数
- `ClientConfig *ClientConfig` - 客户端配置
- `AcquireTimeout time.Duration` - 获取连接超时时间
- `IdleTimeout time.Duration` - 空闲连接超时时间

## 实现状态

✅ **已实现**
- 连接池基本功能（获取、释放、关闭）
- 连接验证和自动替换
- 并发安全
- 空闲连接清理
- 最大连接数限制
- 最小连接数预创建
- 公共API导出
- 单元测试
- 使用示例

## 注意事项

1. 连接池目前仅支持 TCP 客户端
2. 连接池不支持连接的健康检查（除了连接有效性检查）
3. 空闲连接清理是基于连接有效性，而不是基于最后使用时间（简化实现）
4. 连接池关闭后，已获取的连接在使用完毕后会被关闭