🌐 WxBot Enhanced HTTP API 参考¶

![API Reference](../images/api-banner.png) **完整的RESTful API文档和SDK参考**

📋 API概览¶

WxBot Enhanced 提供完整的HTTP API，支持：

🤖 机器人控制 - 发送消息、获取信息
📊 监控数据 - 实时指标、系统状态
🔧 插件管理 - 启用/禁用、配置管理
👥 用户管理 - 好友、群组、权限管理
📈 统计分析 - Enhanced插件数据统计

🌐 基础信息¶

项目	值
Base URL	`http://localhost:7601/wxbot`
Content-Type	`application/json`
认证方式	Token认证（可选）
API版本	v1

🤖 机器人API¶

发送文本消息¶

POST /wxbot/message/text

请求参数：

{
  "toWxId": "wxid_example123",     // 目标微信ID（必需）
  "text": "Hello, World!",         // 消息内容（必需）
  "isGroup": false                 // 是否群消息（可选，默认false）
}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "messageId": "msg_123456789",
    "timestamp": "2025-07-29T10:30:00Z"
  }
}

发送@消息¶

POST /wxbot/message/at

请求参数：

{
  "groupWxId": "group_example123",  // 群组ID（必需）
  "atWxId": "wxid_target123",       // 被@用户ID（必需）
  "atName": "用户昵称",              // 被@用户昵称（可选）
  "text": "@你 消息内容"             // 消息内容（必需）
}

发送图片消息¶

POST /wxbot/message/image

请求参数：

{
  "toWxId": "wxid_example123",
  "imagePath": "local://images/photo.jpg",  // 本地图片路径
  // 或者
  "imageUrl": "https://example.com/image.jpg"  // 网络图片URL
}

获取机器人信息¶

GET /wxbot/robot/info

响应示例：

{
  "code": 200,
  "data": {
    "wxId": "wxid_robot123",
    "nickname": "WxBot Enhanced",
    "avatar": "https://example.com/avatar.jpg",
    "status": "online",
    "version": "2.0.0-enhanced"
  }
}

获取好友列表¶

GET /wxbot/friends

查询参数：

参数	类型	说明	默认值
`refresh`	boolean	是否刷新缓存	false
`page`	int	页码	1
`limit`	int	每页数量	100

响应示例：

{
  "code": 200,
  "data": {
    "total": 250,
    "page": 1,
    "limit": 100,
    "friends": [
      {
        "wxId": "wxid_friend1",
        "nickname": "好友1",
        "remark": "备注名",
        "avatar": "https://example.com/avatar1.jpg",
        "status": "online"
      }
    ]
  }
}

获取群组列表¶

GET /wxbot/groups

查询参数：

参数	类型	说明	默认值
`refresh`	boolean	是否刷新缓存	false

响应示例：

{
  "code": 200,
  "data": [
    {
      "wxId": "group_123@chatroom",
      "nickname": "技术交流群",
      "remark": "备注名称",
      "avatar": "https://example.com/group_avatar.jpg",
      "memberCount": 128
    },
    {
      "wxId": "group_456@chatroom", 
      "nickname": "朋友群",
      "remark": "",
      "avatar": "https://example.com/group_avatar2.jpg",
      "memberCount": 45
    }
  ]
}

获取群成员¶

GET /wxbot/groups/{groupId}/members

路径参数： - groupId: 群组ID

查询参数：

参数	类型	说明	默认值
`refresh`	boolean	是否刷新缓存	false

响应示例：

{
  "code": 200,
  "data": [
    {
      "wxId": "wxid_member1",
      "nickname": "群成员1",
      "remark": "备注名",
      "avatar": "https://example.com/avatar1.jpg",
      "isAdmin": "admin_info",
      "invitedBy": "wxid_inviter123"
    },
    {
      "wxId": "wxid_member2",
      "nickname": "群成员2", 
      "remark": "",
      "avatar": "https://example.com/avatar2.jpg",
      "isAdmin": "",
      "invitedBy": "wxid_inviter456"
    }
  ]
}

📊 监控API¶

获取系统指标¶

GET /wxbot/monitor/metrics

响应示例：

{
  "code": 200,
  "data": {
    "timestamp": "2025-07-29T10:30:00Z",
    "system": {
      "uptime": "48h30m15s",
      "cpuUsage": 15.2,
      "memoryUsage": 268435456,
      "goroutineCount": 45
    },
    "business": {
      "messageCount": 12450,
      "messagePerSecond": 2.5,
      "errorCount": 12,
      "errorRate": 0.0009,
      "processingTime": "25ms"
    },
    "plugins": {
      "caichengyu": {
        "processedMessages": 450,
        "averageTime": "150ms",
        "errorCount": 2,
        "lastExecuted": "2025-07-29T10:29:45Z"
      }
    },
    "framework": {
      "eventBufferSize": 128,
      "matcherCount": 26,
      "connectionStatus": "connected"
    }
  }
}

获取健康状态¶

GET /wxbot/monitor/health

响应示例：

{
  "code": 200,
  "data": {
    "status": "healthy",
    "timestamp": "2025-07-29T10:30:00Z",
    "components": {
      "database": "healthy",
      "framework": "connected", 
      "plugins": "operational",
      "monitoring": "active"
    },
    "uptime": "48h30m15s",
    "version": "2.0.0-enhanced",
    "checks": [
      {
        "name": "database_connection",
        "status": "pass",
        "message": "Database connection successful"
      },
      {
        "name": "framework_ping",
        "status": "pass", 
        "message": "Framework responding normally"
      }
    ]
  }
}

获取告警信息¶

GET /wxbot/monitor/alerts

查询参数：

参数	类型	说明	默认值
`status`	string	告警状态：active/resolved/all	active
`level`	string	告警级别：critical/high/medium/low	all
`limit`	int	返回数量限制	50

响应示例：

{
  "code": 200,
  "data": {
    "total": 3,
    "active": 1,
    "alerts": [
      {
        "id": "alert_001",
        "name": "high_memory_usage",
        "level": "medium",
        "status": "active",
        "message": "内存使用率超过阈值",
        "value": 1073741824,
        "threshold": 1000000000,
        "createdAt": "2025-07-29T10:25:00Z",
        "resolvedAt": null
      }
    ]
  }
}

🔧 插件管理API¶

获取插件列表¶

GET /wxbot/plugins

响应示例：

{
  "code": 200,
  "data": {
    "total": 26,
    "plugins": [
      {
        "name": "caichengyu",
        "alias": "猜成语Enhanced",
        "version": "2.0.0",
        "status": "enabled",
        "type": "enhanced",
        "description": "Enhanced模式猜成语游戏",
        "author": "WxBot Team",
        "enabledGroups": 5,
        "totalGroups": 8,
        "stats": {
          "totalGames": 1234,
          "activeUsers": 89,
          "avgGameDuration": "28s"
        }
      }
    ]
  }
}

插件启用/禁用¶

POST /wxbot/plugins/{pluginName}/toggle

路径参数： - pluginName: 插件名称

请求参数：

{
  "action": "enable",        // enable/disable
  "groupId": "group_123",    // 可选，指定群组
  "global": false            // 可选，全局操作
}

响应示例：

{
  "code": 200,
  "message": "Plugin enabled successfully",
  "data": {
    "pluginName": "caichengyu",
    "status": "enabled",
    "affectedGroups": ["group_123"]
  }
}

获取插件配置¶

GET /wxbot/plugins/{pluginName}/config

响应示例：

{
  "code": 200,
  "data": {
    "pluginName": "caichengyu",
    "config": {
      "difficulty": 2,
      "timeLimit": 30,
      "maxHints": 3,
      "enableRanking": true
    },
    "schema": {
      "difficulty": {
        "type": "integer",
        "min": 1,
        "max": 4,
        "description": "游戏难度级别"
      }
    }
  }
}

更新插件配置¶

PUT /wxbot/plugins/{pluginName}/config

请求参数：

{
  "config": {
    "difficulty": 3,
    "timeLimit": 45,
    "enableRanking": true
  }
}

📈 统计分析API¶

Enhanced插件统计¶

GET /wxbot/stats/enhanced

查询参数：

参数	类型	说明	默认值
`plugin`	string	插件名称	all
`period`	string	时间周期：day/week/month	week
`groupId`	string	群组ID	all

响应示例：

{
  "code": 200,
  "data": {
    "period": "week",
    "plugins": {
      "caichengyu": {
        "totalGames": 456,
        "totalPlayers": 89,
        "avgGameDuration": "28s",
        "completionRate": 0.73,
        "playerLevels": {
          "1": 23, "2": 18, "3": 15, 
          "4": 12, "5": 21
        }
      }
    },
    "trends": {
      "dailyGames": [45, 52, 38, 61, 49, 55, 67],
      "dailyPlayers": [23, 28, 19, 31, 25, 29, 34]
    }
  }
}

用户统计¶

GET /wxbot/stats/users/{userId}

路径参数： - userId: 用户微信ID

响应示例：

{
  "code": 200,
  "data": {
    "userId": "wxid_user123",
    "nickname": "用户昵称",
    "stats": {
      "totalGames": 89,
      "totalWins": 65,
      "winRate": 0.73,
      "avgGameTime": "25s",
      "currentLevel": 5,
      "currentStreak": 8,
      "maxStreak": 15
    },
    "pluginStats": {
      "caichengyu": {
        "games": 45,
        "wins": 33,
        "level": 5
      },
      "music": {
        "games": 28,
        "wins": 21,
        "level": 4
      }
    },
    "achievements": [
      {
        "name": "first_win",
        "title": "首次胜利",
        "unlockedAt": "2025-07-01T10:00:00Z"
      }
    ]
  }
}

群组统计¶

GET /wxbot/stats/groups/{groupId}

响应示例：

{
  "code": 200,
  "data": {
    "groupId": "group_123@chatroom",
    "groupName": "技术交流群",
    "memberCount": 128,
    "activeMembers": 45,
    "stats": {
      "totalMessages": 15420,
      "pluginUsage": {
        "caichengyu": 234,
        "weather": 189,
        "chatgpt": 456
      },
      "topPlayers": [
        {
          "userId": "wxid_top1",
          "nickname": "高手1",
          "score": 1250
        }
      ]
    }
  }
}

🔐 认证和权限¶

Token认证¶

如果启用了API认证，需要在请求头中包含Token：

Authorization: Bearer your_api_token_here

权限级别¶

级别	说明	可访问的API
public	公开API	基础信息查询
user	用户级别	个人统计、基础操作
admin	管理员级别	插件管理、系统配置
system	系统级别	监控数据、系统管理

错误响应格式¶

{
  "code": 401,
  "message": "Unauthorized",
  "error": "invalid_token",
  "details": "The provided token is invalid or expired"
}

📱 SDK和客户端¶

JavaScript SDK¶

// 安装
npm install wxbot-enhanced-sdk

// 使用
import WxBotClient from 'wxbot-enhanced-sdk';

const client = new WxBotClient({
  baseURL: 'http://localhost:7601/wxbot',
  token: 'your_token_here'
});

// 发送消息
await client.message.sendText({
  toWxId: 'wxid_target',
  text: 'Hello from SDK!'
});

// 获取统计
const stats = await client.stats.getEnhanced({
  plugin: 'caichengyu',
  period: 'week'
});

Python SDK¶

# 安装
pip install wxbot-enhanced-sdk

# 使用
from wxbot import WxBotClient

client = WxBotClient(
    base_url='http://localhost:7601/wxbot',
    token='your_token_here'
)

# 发送消息
client.message.send_text(
    to_wx_id='wxid_target',
    text='Hello from Python!'
)

# 获取监控数据
metrics = client.monitor.get_metrics()
print(f"CPU使用率: {metrics.system.cpu_usage}%")

cURL示例¶

# 发送文本消息
curl -X POST http://localhost:7601/wxbot/message/text \
  -H "Content-Type: application/json" \
  -d '{
    "toWxId": "wxid_target",
    "text": "Hello from cURL!"
  }'

# 获取健康状态
curl http://localhost:7601/wxbot/monitor/health

# 获取插件列表
curl http://localhost:7601/wxbot/plugins

🚦 状态码说明¶

状态码	说明	示例场景
200	成功	正常请求处理
201	创建成功	新建配置项
400	请求错误	参数格式错误
401	未授权	Token无效或过期
403	权限不足	访问管理员API
404	资源不存在	插件或用户不存在
429	请求过频	触发限流
500	服务器错误	内部处理异常
503	服务不可用	系统维护中

📚 相关文档¶

🔧 插件开发指南 - 基础插件开发
📊 监控集成 - 监控系统集成
🔒 安全最佳实践 - 安全开发指南
🔌 Plugin API - Plugin API参考文档

**🌐 完整的API让WxBot Enhanced无限可能！** **用HTTP API构建你的微信机器人生态系统！**