Dial - HTTP 客户端和代理工具

Dial 是一个基于 httpx 的异步 HTTP 客户端类，提供了连接池管理、直接请求和代理功能。

功能特性

🔄 连接池管理: 自动管理 HTTP 连接池，提高性能
🌐 直接请求: 支持各种 HTTP 方法的直接请求
🔀 代理功能: 可以创建代理处理器，支持请求和响应重写
⚡ 异步支持: 完全异步实现，与 Starlette 框架完美集成
🛡️ 类型安全: 完整的类型注解支持

安装依赖

确保已安装 httpx 依赖：

pip install httpx

或在 pyproject.toml 中添加：

dependencies = [
    "httpx>=0.27.0",
]

基本使用

1. 直接请求

from pkg.dial import client

# 简单 GET 请求
response = await client.dial("https://api.example.com/users")
print(response.status_code)
print(response.json())

# POST 请求带 JSON 数据
response = await client.dial(
    url="https://api.example.com/users",
    method="POST",
    headers={"Content-Type": "application/json"},
    body={"name": "John", "email": "john@example.com"}
)

2. 自定义客户端

from pkg.dial import Dial
import httpx

# 创建自定义客户端
dial = Dial(
    timeout=30.0,
    limits=httpx.Limits(max_keepalive_connections=10, max_connections=50)
)

# 使用上下文管理器
async with dial as client:
    response = await client.dial("https://api.example.com/data")
    print(response.text)

3. 代理功能

from pkg.dial import client
from starlette.requests import Request
from starlette.responses import JSONResponse

# 请求处理函数
def request_handler(request: Request):
    return {
        'url': f'https://api.example.com{request.url.path}',
        'method': request.method,
        'headers': dict(request.headers),
        'params': dict(request.query_params)
    }

# 响应处理函数
def response_handler(response):
    return JSONResponse({
        'status': response.status_code,
        'data': response.json()
    })

# 创建代理处理器
proxy_handler = client.proxy(
    req_fn=request_handler,
    res_fn=response_handler
)

# 在 Starlette 应用中使用
from starlette.applications import Starlette
from starlette.routing import Route

app = Starlette(routes=[
    Route('/api/{path:path}', proxy_handler)
])

API 参考

Dial 类

构造函数

Dial(timeout: float = 30.0, limits: Optional[httpx.Limits] = None)

timeout: 请求超时时间（秒）
limits: HTTP 连接限制配置

方法

`dial()`

async def dial(
    self, 
    url: str, 
    method: str = "GET", 
    headers: Optional[Dict[str, str]] = None, 
    body: Optional[Any] = None,
    params: Optional[Dict[str, Any]] = None
) -> httpx.Response

直接发送 HTTP 请求。

`proxy()`

def proxy(
    self, 
    req_fn: Optional[Callable[[Request], Dict[str, Any]]] = None, 
    res_fn: Optional[Callable[[httpx.Response], Response]] = None
) -> Callable[[Request], Response]

创建代理处理器。

req_fn: 请求处理函数，接收 Request 对象，返回请求配置字典
res_fn: 响应处理函数，接收 httpx.Response 对象，返回 Response 对象

`close()`

async def close()

关闭客户端连接。

示例

查看 examples/dial_example.py 文件获取完整的使用示例。

注意事项

连接池管理: 客户端会自动管理连接池，无需手动管理
异步使用: 所有方法都是异步的，需要在异步环境中使用
资源清理: 使用上下文管理器或手动调用 close() 方法清理资源
类型安全: 建议使用类型注解以获得更好的开发体验