goproxy/docs/api.md

# GoProxy API 文档

## 概述

GoProxy是一个高性能的HTTP/HTTPS代理服务器，提供丰富的功能和插件系统。本文档描述了GoProxy的API接口。

## 认证

所有API请求都需要进行认证。认证方式为Bearer Token：

```
Authorization: Bearer <your_token>
```

## API 端点

### 1. 代理配置

#### 1.1 获取代理配置

```
GET /api/v1/config
```

响应：
```json
{
    "listen_addr": ":8080",
    "enable_load_balancing": true,
    "backends": ["http://backend1", "http://backend2"],
    "enable_rate_limit": true,
    "rate_limit": 100,
    "max_connections": 1000,
    "enable_cache": true,
    "cache_ttl": "1h"
}
```

#### 1.2 更新代理配置

```
PUT /api/v1/config
```

请求体：
```json
{
    "listen_addr": ":8080",
    "enable_load_balancing": true,
    "backends": ["http://backend1", "http://backend2"],
    "enable_rate_limit": true,
    "rate_limit": 100,
    "max_connections": 1000,
    "enable_cache": true,
    "cache_ttl": "1h"
}
```

### 2. 用户管理

#### 2.1 创建用户

```
POST /api/v1/users
```

请求体：
```json
{
    "username": "admin",
    "password": "password123",
    "roles": ["admin"]
}
```

#### 2.2 获取用户列表

```
GET /api/v1/users
```

响应：
```json
{
    "users": [
        {
            "username": "admin",
            "roles": ["admin"],
            "created_at": "2024-03-13T10:00:00Z",
            "last_login_at": "2024-03-13T11:00:00Z"
        }
    ]
}
```

### 3. 监控指标

#### 3.1 获取代理状态

```
GET /api/v1/status
```

响应：
```json
{
    "active_connections": 100,
    "total_requests": 1000,
    "error_rate": 0.01,
    "average_latency": 0.1,
    "cache_hit_rate": 0.8
}
```

#### 3.2 获取详细指标

```
GET /api/v1/metrics
```

响应：
```json
{
    "requests_total": {
        "GET": 800,
        "POST": 200
    },
    "request_latency": {
        "p50": 0.1,
        "p90": 0.2,
        "p99": 0.5
    },
    "error_total": {
        "connection_error": 10,
        "timeout": 5
    }
}
```

### 4. 插件管理

#### 4.1 获取插件列表

```
GET /api/v1/plugins
```

响应：
```json
{
    "plugins": [
        {
            "name": "compression",
            "version": "1.0.0",
            "enabled": true
        }
    ]
}
```

#### 4.2 启用/禁用插件

```
PUT /api/v1/plugins/{plugin_name}/status
```

请求体：
```json
{
    "enabled": true
}
```

### 5. 缓存管理

#### 5.1 获取缓存统计

```
GET /api/v1/cache/stats
```

响应：
```json
{
    "total_items": 1000,
    "total_size": "100MB",
    "hit_rate": 0.8,
    "eviction_rate": 0.1
}
```

#### 5.2 清除缓存

```
DELETE /api/v1/cache
```

### 6. 健康检查

#### 6.1 获取健康状态

```
GET /api/v1/health
```

响应：
```json
{
    "status": "healthy",
    "uptime": "24h",
    "last_check": "2024-03-13T12:00:00Z"
}
```

## 错误响应

所有API在发生错误时会返回以下格式：

```json
{
    "error": {
        "code": "ERROR_CODE",
        "message": "错误描述",
        "details": {}
    }
}
```

常见错误码：
- 400: 请求参数错误
- 401: 未认证
- 403: 权限不足
- 404: 资源不存在
- 500: 服务器内部错误

## 限流

API请求默认限制为每秒100次。超过限制时会返回429状态码。

## 版本控制

API版本通过URL路径指定，当前版本为v1。

## 更新日志

### v1.0.0
- 初始版本
- 基本代理功能
- 用户认证
- 监控指标
- 插件系统