cHttpServerResponse 响应对象

简介

cHttpServerResponse 用于构建和发送 HTTP 响应，支持文本、HTML、JSON、文件等多种响应类型。

响应方法

Text

发送纯文本响应。

Public Sub Text(Data As String)

参数:

• Data - 响应文本内容

示例:

ctx.Response.Text "Hello, World!"

---

Html

发送 HTML 响应。

Public Sub Html(Data As String)

参数:

• Data - HTML 内容

示例:

ctx.Response.Html "<h1>Hello</h1><p>Welcome to my site</p>"

---

Json

发送 JSON 响应。

Public Sub Json(Data As Variant, Optional Code As Long = -1, Optional msg As String, Optional Count As Long, Optional Whitespace As Variant)

参数:

• Data - 要序列化为 JSON 的数据（Dictionary、Array 等）
• Code - 状态码（默认 -1 表示不包装）
• msg - 消息文本
• Count - 数据总数（用于分页）
• Whitespace - JSON 格式化选项

示例:

' 简单 JSON
Dim data As New Dictionary
data("name") = "张三"
data("age") = 25
ctx.Response.Json data

' 包装格式（API 标准响应）
' 输出: {"code": 0, "msg": "Success", "data": {...}, "count": 1}
ctx.Response.Json data, 0, "Success", 1

' 格式化输出
ctx.Response.Json data, , , , True

---

File

发送文件响应（内置 ETag + 304 协商缓存 + 懒内容缓存）。

Public Sub File(Path As String)

参数:

• Path - 文件路径（相对于 WebRoot）

说明:

• 自动计算 ETag（基于文件修改时间 + 大小）并设置 ETag、Last-Modified 响应头
• 浏览器发送 If-None-Match 且匹配时返回 304 Not Modified（零传输）
• 文件大小 ≤ MaxCacheFileSize 时自动加入内存缓存（懒缓存），后续访问直接内存输出跳过磁盘 I/O
• 超出缓存上限的文件仍从磁盘读取，但享受 ETag/304 协商缓存
• 文件在磁盘更新后 ETag 自动变化，旧缓存自动失效
• 路径对应目录时，自动查找默认文档（index.html 等）；无默认文档返回 403

示例:

' 发送静态文件（自动带缓存头）
ctx.Response.File "/css/style.css"

' 访问目录（自动查找 index.html）
ctx.Response.File "/"

' 大文件（超出缓存上限，始终从磁盘读取，但有 ETag/304）
ctx.Response.File "/videos/demo.mp4"

缓存机制详解:

请求 → 计算 ETag（FSO元数据，不读文件内容）
  ├─> If-None-Match 匹配 → 304（零传输）
  ├─> 缓存命中 + ETag 未变 → 内存输出（跳过磁盘）
  ├─> 缓存命中 + ETag 变化 → 重新读取 + 更新缓存
  └─> 无缓存 → 磁盘读取 + 懒缓存（≤上限才加入）

详见 静态文件服务 - 缓存控制

---

状态码方法

State

发送自定义状态码响应。

Public Sub State(Code As Long, Text As String, Optional Say As String = "未知状态")

---

State400

400 Bad Request。

Public Sub State400(Optional Say As String)

示例:

If Not IsValidParams Then
    ctx.Response.State400 "参数错误"
End If

---

State401

401 Unauthorized。

Public Sub State401(Optional Say As String)

示例:

If Not IsAuthenticated Then
    ctx.Response.State401 "请先登录"
End If

---

State403

403 Forbidden。

Public Sub State403(Optional Say As String)

示例:

If Not HasPermission Then
    ctx.Response.State403 "没有权限"
End If

---

State404

404 Not Found。

Public Sub State404(Optional Say As String)

示例:

If Not UserExists(userId) Then
    ctx.Response.State404 "用户不存在"
End If

---

State413

413 Payload Too Large。

Public Sub State413(Optional Say As String = "Request Entity Too Large")

说明: 当请求体超过 Server.MaxRequestSize 限制时自动返回此状态码。也可手动调用。

示例:

' 检查上传文件大小
If FileSize > MaxAllowedSize Then
    ctx.Response.State413 "文件大小超过限制"
End If

---

State500

500 Internal Server Error。

Public Sub State500(Optional Say As String)

示例:

On Error GoTo ErrorHandler
' ... 业务逻辑
Exit Sub

ErrorHandler:
    ctx.Response.State500 Err.Description

---

State502

502 Gateway Error。

Public Sub State502(Optional Say As String)

---

配置属性

Header

自定义响应头部字典。

Public Header As New Dictionary

示例:

ctx.Response.Header("X-Custom-Header") = "CustomValue"
ctx.Response.Header("Cache-Control") = "no-cache"

---

CharSet

字符编码（默认 utf-8）。

Public CharSet As String

示例:

ctx.Response.CharSet = "gb2312"

---

ContentType

内容类型。

Public ContentType As String

示例:

ctx.Response.ContentType = "application/xml"

---

Status

HTTP 状态码字符串。

Public Status As String

---

JsonPackFieldNameCode

JSON 包装字段名 - 状态码。

Public JsonPackFieldNameCode As String

默认值: "code"

---

JsonPackFieldNameMsg

JSON 包装字段名 - 消息。

Public JsonPackFieldNameMsg As String

默认值: "msg"

---

JsonPackFieldNameData

JSON 包装字段名 - 数据。

Public JsonPackFieldNameData As String

默认值: "data"

---

JsonPackFieldNameCount

JSON 包装字段名 - 总数。

Public JsonPackFieldNameCount As String

默认值: "count"

示例:

' 自定义 JSON 响应字段名
ctx.Response.JsonPackFieldNameCode = "status"
ctx.Response.JsonPackFieldNameMsg = "message"
ctx.Response.JsonPackFieldNameData = "result"
ctx.Response.JsonPackFieldNameCount = "total"

' 输出: {"status": 0, "message": "OK", "result": {...}, "total": 10}
ctx.Response.Json data, 0, "OK", 10

---

兼容 ASP 的属性

属性	说明
Buffer	缓冲输出
CacheControl	缓存控制
CodePage	代码页
Expires	过期时间
ExpiresAbsolute	绝对过期时间
LCID	区域标识

---

最后更新: 2026-06-22