cHttpClient 组件概述

简介

cHttpClient 是一个基于 WinHTTP 的 HTTP 客户端组件，提供完整的 HTTP 请求功能，支持同步/异步请求、链式调用、JSON 处理、Cookie 管理等特性。同时提供 cSSEClient 实现 SSE (Server-Sent Events) 实时消息接收。

特性

特性	说明
HTTP 方法	支持 GET/POST/PUT/DELETE/OPTIONS
数据格式	JSON、Form-UrlEncoded、Text 自动处理
同步/异步	支持同步和异步请求模式
链式调用	流畅的 API 设计，支持链式操作
Cookie 管理	自动解析和设置 Cookies，请求时自动携带
状态码	提供 StatusCode/StatusText 属性，异步/同步均可用
异步事件	OnResponseStart/OnResponseDataAvailable/OnRedirect/OnTimeout
重定向控制	FollowRedirects 属性，禁用时触发 OnRedirect 事件
下载进度	异步数据回调带累计字节数和总字节数，可直接驱动进度条
代理支持	支持配置 HTTP/HTTPS 代理服务器，可设置绕过列表
SSL 支持	自动忽略 SSL 证书错误
编码处理	支持 UTF-8 编码自动转换
调试模式	提供详细请求/响应调试信息
SSE 支持	独立的 SSE 客户端实现实时消息

快速开始

HTTP GET 请求

Dim http As New cHttpClient
Dim result As String

' 简单 GET 请求
result = http.SendGet("https://api.example.com/users").ReturnText()

' 带查询参数的 GET 请求
result = http.SendGet("https://api.example.com/users") _
    .AddQueryParam("page", "1") _
    .AddQueryParam("limit", "10") \
    .ReturnText()

HTTP POST 请求 (JSON)

Dim http As New cHttpClient
Dim json As cJson
Set json = New cJson
json.AddItem "name", "张三"
json.AddItem "age", 25

Set http.RequestDataJson = json

Dim response As cJson
Set response = http.SendPost("https://api.example.com/users").ReturnJson()

HTTP POST 请求 (Form)

Dim http As New cHttpClient

http.RequestDataForm("username") = "admin"
http.RequestDataForm("password") = "123456"

Dim result As String
result = http.SendPost("https://api.example.com/login").ReturnText()

异步请求

Private WithEvents HttpClient As cHttpClient

Private Sub StartAsyncRequest()
    Set HttpClient = New cHttpClient
    HttpClient.Async(True).SendGet("https://api.example.com/data")
End Sub

Private Sub HttpClient_OnResponseStart(ByVal Status As Long, ByVal ContentType As String)
    Debug.Print "响应开始: Status=" & Status & " ContentType=" & ContentType
End Sub

Private Sub HttpClient_OnResponseDataAvailable(Data() As Byte, ByVal BytesReceived As Long, ByVal TotalBytes As Long)
    If TotalBytes > 0 Then
        Debug.Print "下载进度: " & BytesReceived & "/" & TotalBytes
    End If
End Sub

Private Sub HttpClient_OnResponseFinished()
    Debug.Print "响应完成: " & HttpClient.ReturnText()
    Debug.Print "状态码: " & HttpClient.StatusCode
End Sub

Private Sub HttpClient_OnError(ByVal ErrorNumber As Long, ByVal ErrorDescription As String)
    Debug.Print "错误: " & ErrorDescription
End Sub

Private Sub HttpClient_OnRedirect(ByVal Url As String)
    Debug.Print "重定向到: " & Url
End Sub

Private Sub HttpClient_OnTimeout()
    Debug.Print "请求超时"
End Sub

注意：

• 异步模式下，HTTP 4xx/5xx 响应触发 OnError，3xx 响应触发 OnRedirect（需设 FollowRedirects = False），均不触发 OnResponseFinished
• OnResponseDataAvailable 的 BytesReceived 为累计值，TotalBytes 来自 Content-Length（未知时为 -1）

重定向控制

' 默认自动跟随重定向
http.Async(True).SendGet("https://api.example.com/old-url")

' 禁用自动重定向，通过事件手动处理
Dim http As New cHttpClient
http.FollowRedirects = False
http.Async(True).SendGet "https://api.example.com/redirect"

' 在 OnRedirect 事件中获取目标 URL
Private Sub http_OnRedirect(ByVal Url As String)
    Debug.Print "重定向到: " & Url
    ' 可以选择手动发起新请求
End Sub

代理服务器

Dim http As New cHttpClient

' 使用代理服务器（所有协议共用）
http.Proxy("proxy.example.com:8080").SendGet("https://api.example.com/data")

' 分别为 HTTP/HTTPS 指定代理
http.Proxy("http=proxy1:8080;https=proxy2:8443").SendGet("https://api.example.com/data")

' 带绕过列表（localhost 和内网地址不走代理）
http.Proxy("proxy.example.com:8080", "localhost;127.0.0.1;*.internal.com").SendGet("...")

' 取消代理配置（直连）
http.Proxy("").SendGet("https://api.example.com/data")

SSE (Server-Sent Events)

Private WithEvents SSE As cSSEClient

Private Sub InitializeSSE()
    Set SSE = New cSSEClient
    SSE.AutoReconnect = True
    SSE.ReconnectInterval = 3000  ' 3秒重连间隔
    SSE.MaxReconnectAttempts = 10
    Call SSE.Connect("https://api.example.com/events")
End Sub

' POST 方式连接 SSE（适用于 AI 流式聊天等场景）
Private Sub InitializeSSEPost()
    Set SSE = New cSSEClient
    SSE.SetHeader("Authorization", "Bearer sk-xxx") _
       .SetHeader("Content-Type", "application/json") _
       .RequestTimeOut = 120
    Call SSE.ConnectPost("https://api.example.com/chat", "{""model"":""gpt-4"",""messages"":[...]}")
End Sub

Private Sub SSE_OnOpen()
    Debug.Print "SSE 连接已建立"
End Sub

Private Sub SSE_OnMessage(EventName As String, Data As String, Id As String)
    Debug.Print "收到消息: " & EventName & " = " & Data
End Sub

Private Sub SSE_OnError(Description As String, ErrorNumber As Long)
    Debug.Print "SSE 错误: " & Description
End Sub

Private Sub SSE_OnClose()
    Debug.Print "SSE 连接已关闭"
End Sub

引用组件

• Microsoft WinHTTP Services, version 5.1
• Microsoft Scripting Runtime
• cJson.cls
• cTimer.cls (SSE 需要)

文件结构

文件	说明
cHttpClient.cls	HTTP 客户端主类
cSSEClient.cls	SSE 客户端实现
mSSEDemo.bas	SSE 使用示例
SSE_Client_使用文档.md	SSE 详细使用文档

---

最后更新: 2026-07-13