# 负载均衡功能

`ModifiableRequest` 类现在支持 round-robin 负载均衡功能，可以自动在多个后端服务器之间分发请求。

## 功能特性

- 🔄 **Round-Robin 轮询**: 按顺序在多个主机之间分发请求
- 🛡️ **线程安全**: 使用锁机制确保并发安全
- 🔧 **灵活配置**: 支持带协议和不带协议的主机配置
- 🎯 **智能路由**: 自动判断是否需要负载均衡

## 使用方法

### 1. 基本负载均衡

```python
from pkg.dial import client
from pkg.dial.req import ModifiableRequest

def request_handler(request: ModifiableRequest):
    # 只指定路径，让负载均衡器自动选择主机
    request.rewrite_uri("/api/users")
    return request.build()

# 创建代理，支持多个后端服务器
proxy_handler = client.proxy(
    hosts=["server1.com", "server2.com", "server3.com"],
    req_fn=request_handler
)
```

### 2. 带协议的主机配置

```python
# 支持混合协议配置
hosts = [
    "http://server1.com",
    "https://server2.com", 
    "server3.com"  # 自动添加 http:// 前缀
]

proxy_handler = client.proxy(hosts, request_handler)
```

### 3. 绕过负载均衡

```python
def request_handler_fixed(request: ModifiableRequest):
    # 指定完整 URL，绕过负载均衡
    request.rewrite_uri("https://specific-server.com/api/users")
    return request.build()

# 即使配置了多个主机，也会使用指定的 URL
proxy_handler = client.proxy(
    hosts=["server1.com", "server2.com"],
    req_fn=request_handler_fixed
)
```

## 工作原理

### URL 解析逻辑

1. **检查 URL 是否包含主机**:
   - 如果 URL 包含主机（如 `https://example.com/api/users`），直接使用该 URL
   - 如果 URL 只有路径（如 `/api/users`），从主机列表中选择一个

2. **Round-Robin 选择**:
   - 使用线程安全的计数器
   - 按顺序循环选择主机
   - 自动处理主机数量变化

3. **URL 构建**:
   - 自动添加协议前缀（如果缺失）
   - 确保路径格式正确
   - 合并查询参数

### 示例请求分发

假设配置了 3 个主机：`["server1.com", "server2.com", "server3.com"]`

```
请求 1: http://server1.com/api/users
请求 2: http://server2.com/api/users  
请求 3: http://server3.com/api/users
请求 4: http://server1.com/api/users  # 重新开始轮询
请求 5: http://server2.com/api/users
...
```

## 配置示例

### Starlette 应用中的使用

```python
from starlette.applications import Starlette
from starlette.routing import Route
from pkg.dial import client

def api_handler(request: ModifiableRequest):
    request.rewrite_uri("/api/v1/data")
    return request.build()

app = Starlette(routes=[
    Route(
        "/api/data",
        client.proxy(
            hosts=[
                "http://backend1:8080",
                "http://backend2:8080", 
                "http://backend3:8080"
            ],
            req_fn=api_handler
        )
    )
])
```

### 健康检查集成

```python
def health_check_handler(request: ModifiableRequest):
    request.rewrite_uri("/health")
    return request.build()

# 健康检查路由
health_proxy = client.proxy(
    hosts=["server1.com", "server2.com"],
    req_fn=health_check_handler
)
```

## 注意事项

1. **主机格式**: 建议使用完整的主机名或 IP 地址
2. **协议处理**: 如果不指定协议，默认使用 `http://`
3. **并发安全**: 使用线程锁确保多线程环境下的安全性
4. **错误处理**: 如果主机列表为空，会抛出 `ValueError` 异常
5. **性能考虑**: 负载均衡器本身开销很小，适合高并发场景

## 故障排除

### 常见问题

1. **主机无法访问**: 确保所有配置的主机都是可访问的
2. **协议错误**: 检查主机配置中的协议是否正确
3. **路径问题**: 确保路径格式正确（以 `/` 开头）

### 调试技巧

```python
def debug_handler(request: ModifiableRequest):
    # 添加调试信息
    request.add_header("X-Debug", "true")
    request.rewrite_uri("/api/debug")
    return request.build()
```