Cookie 操作

提示

hyperlane 框架提供了完整的 Cookie 处理功能，支持请求和响应中的 Cookie 操作。

请求 Cookie 操作

获取请求所有 Cookie

// 尝试获取请求所有 Cookie
let cookies: Option<Cookies> = ctx.get_request().try_get_cookies();
// 获取请求所有 Cookie（获取不到则panic）
let cookies: Option<Cookies> = ctx.get_request().get_cookies();

获取请求特定 Cookie

// 尝试获取请求特定 Cookie
let cookie_value: Option<CookieValue> = ctx.get_request().try_get_cookie("session_id");
// 获取请求特定 Cookie（获取不到则panic）
let cookie_value: CookieValue = ctx.get_request().get_cookie("session_id");

提示

Cookie 名称通常是自定义的，所以使用字符串字面量。但对于标准的请求头操作，建议使用框架常量。

响应 Cookie 操作

设置响应 Cookie

使用字符串直接设置

ctx.get_mut_response().set_header(SET_COOKIE, "session_id=abc123; Path=/; HttpOnly");

使用 CookieBuilder 构建

let cookie_value: String = CookieBuilder::new("session_id", "abc123")
    .set_path("/")
    .http_only()
    .build();
ctx.get_mut_response().set_header(SET_COOKIE, &cookie_value);

设置多个 Cookie

let session_cookie: String = CookieBuilder::new("session_id", "abc123")
    .set_max_age(3600)
    .set_path("/")
    .http_only()
    .secure()
    .build();

let pref_cookie: String = CookieBuilder::new("user_pref", "dark_mode")
    .set_max_age(86400)
    .set_path("/")
    .build();

ctx.get_mut_response()
    .add_header(SET_COOKIE, &session_cookie)
    .add_header(SET_COOKIE, &pref_cookie);

属性宏写法

提示

可以使用 #[request_cookie] 或 #[try_get_request_cookie] 属性宏提取请求 Cookie。

获取特定 Cookie（安全方式）

use hyperlane::*;
use hyperlane_macros::*;

#[route("/cookie")]
struct CookieRoute;

impl ServerHook for CookieRoute {
    async fn new(_: &mut Stream, _: &mut Context) -> Self {
        Self
    }

    #[response_body(&format!("Session cookie: {session_cookie1_option:?}, {session_cookie2_option:?}"))]
    #[try_get_request_cookie("test1" => session_cookie1_option, "test2" => session_cookie2_option)]
    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        Status::Continue
    }
}

获取特定 Cookie（不安全方式，获取失败会 Panic）

use hyperlane::*;
use hyperlane_macros::*;

#[route("/cookie")]
struct CookieRoute;

impl ServerHook for CookieRoute {
    async fn new(_: &mut Stream, _: &mut Context) -> Self {
        Self
    }

    #[response_body(&format!("Session cookie: {session_cookie1}, {session_cookie2}"))]
    #[request_cookie("test1" => session_cookie1, "test2" => session_cookie2)]
    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        Status::Continue
    }
}

获取所有 Cookie 字符串

提示

可以使用 #[request_cookies] 属性宏获取所有 Cookie 作为原始字符串。

use hyperlane::*;
use hyperlane_macros::*;

#[route("/cookies")]
struct CookiesRoute;

impl ServerHook for CookiesRoute {
    async fn new(_: &mut Stream, _: &mut Context) -> Self {
        Self
    }

    #[request_cookies(cookie_value)]
    async fn handle(self, stream: &mut Stream, ctx: &mut Context) -> Status {
        // cookie_value is available as String
        Status::Continue
    }
}

CookieBuilder 方法

基本构建

let cookie: String = CookieBuilder::new("name", "value").build();

设置属性

let cookie: String = CookieBuilder::new("session", "token123")
    .set_expires("Wed, 21 Oct 2025 07:28:00 GMT")
    .set_domain("example.com")
    .set_same_site("Strict")
    .set_max_age(3600)
    .set_path("/")
    .secure()
    .http_only()
    .build();

解析现有 Cookie

let cookie_builder: CookieBuilder = CookieBuilder::parse("name=value; Path=/; HttpOnly");
let rebuilt_cookie: String = cookie_builder.build();

基本使用示例

会话管理

// 响应设置Cookie
let session_cookie: String = CookieBuilder::new("session", "token123")
    .set_max_age(3600)
    .http_only()
    .secure()
    .build();
ctx.get_mut_response().set_header(SET_COOKIE, &session_cookie);
// 请求读取Cookie
if let Some(session) = ctx.get_request().try_get_cookie("session") {}

清除 Cookie

let clear_cookie: String = CookieBuilder::new("session", "")
    .set_max_age(0)
    .build();
ctx.get_mut_response().set_header(SET_COOKIE, &clear_cookie);

加载中...