variable_name 格式的映射变量在函数作用域...">请求处理宏 | eastspire

请求处理宏

eastspire2025/11/29大约 6 分钟hyperlane-macros

请求处理宏

请求处理宏用于从 HTTP 请求中提取各种数据，包括路径参数、查询参数、请求头、请求体、Cookie 等。这些宏简化了请求数据的处理，使开发者可以专注于业务逻辑。

路径参数提取

#[route_param]

提取指定的路由参数到变量中。

用法

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

#[route("/user/:id")]
struct UserProfile;

impl ServerHook for UserProfile {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[response_body(&format!("User ID: {id:?}"))]
    #[route_param("id" => id)]
    async fn handle(self, ctx: &Context) {}
}

impl UserProfile {
    #[route_param("id" => id)]
    async fn route_param_with_ref_self(&self, ctx: &Context) {}
}

#[route_param("id" => id)]
async fn standalone_route_param_handler(ctx: &Context) {}

多参数用法

#[route("/user/:id/post/:post_id")]
struct UserPost;

impl ServerHook for UserPost {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[response_body(&format!("id: {id:?}, post_id: {post_id:?}"))]
    #[route_param("id" => id, "post_id" => post_id)]
    async fn handle(self, ctx: &Context) {}
}

说明

接受 "key" => variable_name 格式的映射
变量在函数作用域中可用，类型为 Option<String>
支持多个参数，用逗号分隔
路径参数在 URL 路径中定义，如 /user/:id

#[route_params]

提取所有路由参数到集合变量中。

用法

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

#[route("/route_params/:test")]
struct RouteParams;

impl ServerHook for RouteParams {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[response_body(&format!("request route params: {request_route_params:?}"))]
    #[route_params(request_route_params)]
    async fn handle(self, ctx: &Context) {}
}

impl RouteParams {
    #[route_params(request_route_params)]
    async fn route_params_with_ref_self(&self, ctx: &Context) {}
}

#[route_params(request_route_params)]
async fn standalone_route_params_handler(ctx: &Context) {}

多变量用法

#[route("/multi_params/:id")]
struct MultiParams;

impl ServerHook for MultiParams {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[response_body(&format!("params1: {params1:?}, params2: {params2:?}"))]
    #[route_params(params1, params2)]
    async fn handle(self, ctx: &Context) {}
}

说明

接受变量名，包含所有路由参数
变量在函数作用域中可用，类型为集合
支持多个变量名，用逗号分隔
适用于需要访问所有路由参数的场景

查询参数提取

#[request_query]

提取指定的查询参数到变量中。

用法

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

#[route("/request_query")]
struct RequestQuery;

impl ServerHook for RequestQuery {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[prologue_macros(
        request_query("test" => request_query_option),
        response_body(&format!("request query: {request_query_option:?}")),
        send
    )]
    async fn handle(self, ctx: &Context) {}
}

impl RequestQuery {
    #[request_query("test" => request_query_option)]
    async fn request_query_with_ref_self(&self, ctx: &Context) {}
}

#[request_query("test" => request_query_option)]
async fn standalone_request_query_handler(ctx: &Context) {}

多参数用法

#[request_query("k1" => v1, "k2" => v2)]
async fn multi_query_handler(ctx: &Context) {}

说明

接受 "key" => variable_name 格式的映射
变量在函数作用域中可用，类型为 Option<String>
支持多个参数，用逗号分隔
查询参数来自 URL 的查询字符串，如 ?name=value

#[request_querys]

提取所有查询参数到集合变量中。

用法

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

#[route("/request_querys")]
struct RequestQuerys;

impl ServerHook for RequestQuerys {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[prologue_macros(
        request_querys(request_querys),
        response_body(&format!("request querys: {request_querys:?}")),
        send
    )]
    async fn handle(self, ctx: &Context) {}
}

impl RequestQuerys {
    #[request_querys(request_querys)]
    async fn request_querys_with_ref_self(&self, ctx: &Context) {}
}

#[request_querys(request_querys)]
async fn standalone_request_querys_handler(ctx: &Context) {}

多变量用法

#[request_querys(querys1, querys2)]
async fn multi_querys_handler(ctx: &Context) {}

说明

接受变量名，包含所有查询参数
变量在函数作用域中可用，类型为集合
支持多个变量名，用逗号分隔
适用于需要访问所有查询参数的场景

请求头处理

#[request_header]

提取指定的请求头到变量中。

用法

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

#[route("/request_header")]
struct RequestHeader;

impl ServerHook for RequestHeader {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[prologue_macros(
        request_header(HOST => request_header_option),
        response_body(&format!("request header: {request_header_option:?}")),
        send
    )]
    async fn handle(self, ctx: &Context) {}
}

impl RequestHeader {
    #[request_header(HOST => request_header_option)]
    async fn request_header_with_ref_self(&self, ctx: &Context) {}
}

#[request_header(HOST => request_header_option)]
async fn standalone_request_header_handler(ctx: &Context) {}

多头部用法

#[request_header(HOST => host_header, "User-Agent" => user_agent)]
async fn multi_header_handler(ctx: &Context) {}

说明

接受 HEADER_NAME => variable_name 或 "Header-Name" => variable_name 格式
变量在函数作用域中可用，类型为 Option<String>
支持多个头部，用逗号分隔
头部名称不区分大小写

#[request_headers]

提取所有请求头到集合变量中。

用法

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

#[route("/request_headers")]
struct RequestHeaders;

impl ServerHook for RequestHeaders {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[prologue_macros(
        request_headers(request_headers),
        response_body(&format!("request headers: {request_headers:?}")),
        send
    )]
    async fn handle(self, ctx: &Context) {}
}

impl RequestHeaders {
    #[request_headers(request_headers)]
    async fn request_headers_with_ref_self(&self, ctx: &Context) {}
}

#[request_headers(request_headers)]
async fn standalone_request_headers_handler(ctx: &Context) {}

说明

接受变量名，包含所有请求头
变量在函数作用域中可用，类型为集合
适用于需要访问所有请求头的场景

提取指定的 Cookie 值到变量中。

用法

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

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

impl ServerHook for Cookie {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[response_body(&format!("Session cookie: {session_cookie1_option:?}, {session_cookie2_option:?}"))]
    #[request_cookie("test1" => session_cookie1_option, "test2" => session_cookie2_option)]
    async fn handle(self, ctx: &Context) {}
}

impl Cookie {
    #[request_cookie("test1" => session_cookie1_option, "test2" => session_cookie2_option)]
    async fn request_cookie_with_ref_self(&self, ctx: &Context) {}
}

#[request_cookie("test1" => session_cookie1_option, "test2" => session_cookie2_option)]
async fn standalone_request_cookie_handler(ctx: &Context) {}

说明

支持两种语法：
- cookie(key => variable_name) - 提取特定 Cookie
- cookie(variable_name) - 提取所有 Cookie
特定 Cookie 提取时，变量类型为 Option<String>
所有 Cookie 提取时，变量类型为 String
支持多个 Cookie，用逗号分隔

#[request_cookies]

提取所有 Cookie 作为原始字符串到变量中。

用法

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

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

impl ServerHook for Cookies {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[response_body(&format!("All cookies: {cookie_value:?}"))]
    #[request_cookies(cookie_value)]
    async fn handle(self, ctx: &Context) {}
}

impl Cookies {
    #[request_cookies(cookie_value)]
    async fn request_cookies_with_ref_self(&self, ctx: &Context) {}
}

#[request_cookies(cookie_value)]
async fn standalone_request_cookies_handler(ctx: &Context) {}

说明

接受变量名，包含完整的 Cookie 头部值
变量在函数作用域中可用，类型为 String
如果没有 Cookie 头部，变量值为空字符串
适用于需要解析 Cookie 的场景

请求体处理

#[request_body]

提取原始请求体到变量中。

用法

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

#[route("/request_body")]
struct RequestBodyRoute;

impl ServerHook for RequestBodyRoute {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[response_body(&format!("raw body: {raw_body:?}"))]
    #[request_body(raw_body)]
    async fn handle(self, ctx: &Context) {}
}

impl RequestBodyRoute {
    #[request_body(raw_body)]
    async fn request_body_with_ref_self(&self, ctx: &Context) {}
}

#[request_body(raw_body)]
async fn standalone_request_body_handler(ctx: &Context) {}

说明

接受变量名，固定类型为 RequestBody
变量在函数作用域中可用
请求体内容不进行解析或反序列化
适用于处理原始二进制数据或自定义解析

请求元信息

#[request_version]

提取 HTTP 请求版本到变量中。

用法

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

#[route("/request_version")]
struct RequestVersionTest;

impl ServerHook for RequestVersionTest {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[response_body(&format!("HTTP Version: {http_version}"))]
    #[request_version(http_version)]
    async fn handle(self, ctx: &Context) {}
}

impl RequestVersionTest {
    #[request_version(http_version)]
    async fn request_version_with_ref_self(&self, ctx: &Context) {}
}

#[request_version(http_version)]
async fn standalone_request_version_handler(ctx: &Context) {}

说明

接受变量名，包含 HTTP 请求版本
变量在函数作用域中可用，类型为 RequestVersion
表示请求使用的 HTTP 协议版本

#[request_path]

提取 HTTP 请求路径到变量中。

用法

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

#[route("/request_path")]
struct RequestPathTest;

impl ServerHook for RequestPathTest {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[response_body(&format!("Request Path: {request_path}"))]
    #[request_path(request_path)]
    async fn handle(self, ctx: &Context) {}
}

impl RequestPathTest {
    #[request_path(request_path)]
    async fn request_path_with_ref_self(&self, ctx: &Context) {}
}

#[request_path(request_path)]
async fn standalone_request_path_handler(ctx: &Context) {}

说明

接受变量名，包含 HTTP 请求路径
变量在函数作用域中可用，类型为 RequestPath
表示 URL 的路径部分

过滤和验证

#[filter]

基于布尔条件过滤请求。

用法

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

#[route("/unknown_method")]
struct UnknownMethod;

impl ServerHook for UnknownMethod {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[prologue_macros(
        filter(ctx.get_request().await.is_unknown_method()),
        response_body("unknown_method")
    )]
    async fn handle(self, ctx: &Context) {}
}

说明

接受布尔表达式作为参数
只有当表达式返回 true 时才继续执行
用于自定义的请求过滤逻辑

#[reject]

基于布尔条件拒绝请求。

用法

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

#[response_middleware(2)]
struct ResponseMiddleware2;

impl ServerHook for ResponseMiddleware2 {
    async fn new(_ctx: &Context) -> Self {
        Self
    }

    #[prologue_macros(
        reject(ctx.get_request().await.is_ws())
    )]
    async fn handle(self, ctx: &Context) {}
}

说明

接受布尔表达式作为参数
只有当表达式返回 false 时才继续执行
用于拒绝不符合条件的请求

使用建议

数据类型选择：
- 单个值：使用 #[route_param]、#[request_query] 等
- 集合数据：使用 #[route_params]、#[request_querys] 等
- 原始数据：使用 #[request_body]
错误处理：
- 大多数提取宏返回 Option<String>，处理 None 情况
- 提供默认值或错误响应
- 验证数据格式和有效性
性能考虑：
- 只提取需要的数据，避免不必要的处理
- 考虑请求大小对内存的影响
- 大文件上传使用流式处理
安全性：
- 验证用户输入，防止注入攻击
- 限制请求体大小
- 对敏感数据进行适当处理
组合使用：
- 可以同时使用多个提取宏
- 合理安排宏的顺序
- 避免重复提取相同数据