Cookie 管理详解

简介

cHttpServerCookies 提供完整的 Cookie 管理功能，包括：

• 解析请求中的 Cookie
• 设置响应的 Cookie
• 支持所有标准 Cookie 属性（Domain、Path、Expires、Secure、HttpOnly、SameSite）

核心类

类名	说明
cHttpServerCookies	Cookie 集合管理
cHttpServerCookieAttr	单个 Cookie 属性

Cookie 属性详解

cHttpServerCookieAttr

属性	类型	说明
Value	String	Cookie 值
Domain	String	作用域名
Path	String	作用路径（默认 "/"）
Expires	Variant	过期时间
Secure	Boolean	仅 HTTPS 传输
HttpOnly	Boolean	禁止 JavaScript 访问
SameSite	String	SameSite 策略

快速开始

读取请求 Cookie

Public Sub ShowCookie(ctx As cHttpServerContext)
    ' 检查 Cookie 是否存在
    If ctx.Cookies.Exists("username") Then
        Dim username As String
        username = ctx.Cookies.Cookie("username").Value
        
        ctx.Response.Text "用户名: " & username
    Else
        ctx.Response.Text "未找到 Cookie"
    End If
End Sub

设置响应 Cookie

Public Sub SetCookie(ctx As cHttpServerContext)
    ' 设置简单 Cookie
    ctx.Cookies.Cookie("username").Value = "张三"
    
    ' 设置带过期时间的 Cookie
    With ctx.Cookies.Cookie("token")
        .Value = "abc123"
        .Expires = DateAdd("d", 7, Now)  ' 7天后过期
        .Path = "/"
    End With
    
    ' 设置安全 Cookie
    With ctx.Cookies.Cookie("session")
        .Value = GenerateToken()
        .HttpOnly = True      ' 禁止 JS 访问
        .Secure = True        ' 仅 HTTPS
        .SameSite = "Strict"  ' 防止 CSRF
        .Expires = DateAdd("h", 2, Now)  ' 2小时后过期
    End With
    
    ctx.Response.Json Nothing, 0, "Cookie 已设置"
End Sub

删除 Cookie

Public Sub DeleteCookie(ctx As cHttpServerContext)
    ' 将过期时间设为过去即可删除
    ctx.Cookies.Cookie("username").Expires = DateAdd("d", -1, Now)
    
    ctx.Response.Json Nothing, 0, "Cookie 已删除"
End Sub

完整示例

记住登录功能

' cAuthController.cls

' POST /login
Public Sub Login(ctx As cHttpServerContext)
    Dim username As String, password As String
    Dim remember As Boolean
    
    username = ctx.Request.Form("username")
    password = ctx.Request.Form("password")
    remember = (ctx.Request.Form("remember") = "true")
    
    ' 验证账号密码
    If Not ValidateUser(username, password) Then
        ctx.Response.Json Nothing, 1, "用户名或密码错误"
        Exit Sub
    End If
    
    ' 生成 Token
    Dim token As String
    token = GenerateToken(username)
    
    ' 设置 Session
    ctx.Session("user_id") = GetUserId(username)
    
    ' 设置 Cookie
    With ctx.Cookies.Cookie("auth_token")
        .Value = token
        .Path = "/"
        .HttpOnly = True
        .SameSite = "Lax"
        
        If remember Then
            ' 记住登录：7天
            .Expires = DateAdd("d", 7, Now)
        Else
            ' 不记住：浏览器关闭失效
            .Expires = Empty
        End If
    End With
    
    ctx.Response.Json Nothing, 0, "登录成功"
End Sub

' GET /auto-login
Public Sub AutoLogin(ctx As cHttpServerContext)
    ' 检查 Cookie Token
    If Not ctx.Cookies.Exists("auth_token") Then
        ctx.Response.State401 "未登录"
        Exit Sub
    End If
    
    Dim token As String
    token = ctx.Cookies.Cookie("auth_token").Value
    
    ' 验证 Token
    If Not ValidateToken(token) Then
        ctx.Response.State401 "登录已过期"
        Exit Sub
    End If
    
    ' 自动登录成功
    Dim username As String
    username = GetUsernameFromToken(token)
    
    ctx.Session("user_id") = GetUserId(username)
    
    ctx.Response.Json Nothing, 0, "自动登录成功"
End Sub

' GET /logout
Public Sub Logout(ctx As cHttpServerContext)
    ' 清除 Session
    ctx.Session.Abandon
    
    ' 删除 Cookie
    ctx.Cookies.Cookie("auth_token").Expires = DateAdd("d", -1, Now)
    
    ctx.Response.Json Nothing, 0, "退出成功"
End Sub

多语言支持

Public Sub SetLanguage(ctx As cHttpServerContext)
    Dim lang As String
    lang = ctx.Request.QueryString("lang")
    
    ' 设置语言 Cookie，1年过期
    With ctx.Cookies.Cookie("language")
        .Value = lang
        .Path = "/"
        .Expires = DateAdd("yyyy", 1, Now)
    End With
    
    ctx.Response.Json Nothing, 0, "语言已设置: " & lang
End Sub

Public Sub GetLanguage(ctx As cHttpServerContext)
    Dim lang As String
    
    ' 优先从 Cookie 获取
    If ctx.Cookies.Exists("language") Then
        lang = ctx.Cookies.Cookie("language").Value
    Else
        ' 默认语言
        lang = "zh-CN"
    End If
    
    Dim result As New Scripting.Dictionary
    result("language") = lang
    ctx.Response.Json result
End Sub

SameSite 属性详解

值	说明	场景
Strict	仅同站请求发送 Cookie	高安全性（银行、支付）
Lax	顶级导航时发送，iframe/图片不发送	平衡安全与体验（推荐）
None	所有请求都发送（需配合 Secure）	跨站需求（OAuth）

' Strict - 最严格
ctx.Cookies.Cookie("high_security").SameSite = "Strict"

' Lax - 推荐
ctx.Cookies.Cookie("session").SameSite = "Lax"

' None - 跨站需要
ctx.Cookies.Cookie("oauth_state").SameSite = "None"
ctx.Cookies.Cookie("oauth_state").Secure = True  ' None 必须配合 Secure

Cookie 安全建议

' 安全配置示例
With ctx.Cookies.Cookie("session_id")
    ' 值加密存储
    .Value = Encrypt(sessionValue)
    
    ' 路径限制
    .Path = "/api"  ' 只在 /api 路径下发送
    
    ' 域名限制
    .Domain = ".example.com"  ' 子域共享
    
    ' HTTPS 传输
    .Secure = True
    
    ' 禁止 JS 访问
    .HttpOnly = True
    
    ' 防止 CSRF
    .SameSite = "Strict"
    
    ' 合理过期时间
    .Expires = DateAdd("h", 2, Now)  ' 2小时
End With

---

最后更新: 2026-05-17