hyperlane属性宏

GITHUB 地址

API 文档

一个用于构建增强功能 HTTP 服务器的过程宏综合集合。该 crate 提供属性宏，简化 HTTP 请求处理、协议验证、响应管理和请求数据提取。

安装

要使用此 crate，可以运行以下命令：

cargo add hyperlane-macros

可用宏

Hyperlane 宏

• #[hyperlane(server: Server)] - 创建一个指定变量名和类型的 Server 实例，并自动注册 crate 中定义的其他钩子和路由。
• #[hyperlane(config: ServerConfig)] - 创建一个指定变量名和类型的 ServerConfig 实例。
• #[hyperlane(var1: Type1, var2: Type2, ...)] - 支持在单次调用中初始化多个实例。

HTTP 方法宏

• #[methods(method1, method2, ...)] - 接受多个 HTTP 方法。
• #[get] - GET 方法处理器。
• #[post] - POST 方法处理器。
• #[put] - PUT 方法处理器。
• #[delete] - DELETE 方法处理器。
• #[patch] - PATCH 方法处理器。
• #[head] - HEAD 方法处理器。
• #[options] - OPTIONS 方法处理器。
• #[connect] - CONNECT 方法处理器。
• #[trace] - TRACE 方法处理器。

协议检查宏

• #[ws] - WebSocket 检查，确保函数仅在 WebSocket 升级请求时执行。
• #[http] - HTTP 检查，确保函数仅在标准 HTTP 请求时执行。
• #[h2c] - HTTP/2 明文检查，确保函数仅在 HTTP/2 明文请求时执行。
• #[http0_9] - HTTP/0.9 检查，确保函数仅在 HTTP/0.9 协议请求时执行。
• #[http1_0] - HTTP/1.0 检查，确保函数仅在 HTTP/1.0 协议请求时执行。
• #[http1_1] - HTTP/1.1 检查，确保函数仅在 HTTP/1.1 协议请求时执行。
• #[http1_1_or_higher] - HTTP/1.1 或更高版本检查，确保函数仅在 HTTP/1.1 或更新协议版本请求时执行。
• #[http2] - HTTP/2 检查，确保函数仅在 HTTP/2 协议请求时执行。
• #[http3] - HTTP/3 检查，确保函数仅在 HTTP/3 协议请求时执行。
• #[tls] - TLS 检查，确保函数仅在 TLS 加密连接时执行。

响应设置宏

• #[response_status_code(code)] - 设置响应状态码（支持字面量和全局常量）。
• #[response_reason_phrase("phrase")] - 设置响应原因短语（支持字面量和全局常量）。
• #[response_header("key", "value")] - 添加响应头（支持字面量和全局常量）。
• #[response_header("key" => "value")] - 设置响应头（支持字面量和全局常量）。
• #[response_body("data")] - 设置响应体（支持字面量和全局常量）。
• #[response_version(version)] - 设置响应 HTTP 版本（支持字面量和全局常量）。
• #[clear_response_headers] - 清除所有响应头。

发送操作宏

• #[try_send] - 尝试在函数执行后发送完整响应（头部和正文）（返回 Result）。
• #[send] - 在函数执行后发送完整响应（头部和正文）（失败时 panic）。
• #[try_send_body] - 尝试在函数执行后仅发送响应正文（返回 Result）。
• #[send_body] - 在函数执行后仅发送响应正文（失败时 panic）。
• #[try_send_body_with_data("data")] - 尝试在函数执行后使用指定数据仅发送响应正文（返回 Result）。
• #[send_body_with_data("data")] - 在函数执行后使用指定数据仅发送响应正文（失败时 panic）。

刷新宏

• #[try_flush] - 尝试在函数执行后刷新响应流以确保立即传输数据（返回 Result）。
• #[flush] - 在函数执行后刷新响应流以确保立即传输数据（失败时 panic）。

中断宏

• #[aborted] - 处理被中断的请求，为提前终止的连接提供清理逻辑。

关闭操作宏

• #[closed] - 处理已关闭的流，为已完成的连接提供清理逻辑。

条件宏

• #[filter(condition)] - 仅当 condition（返回布尔值的代码块）为 true 时继续执行。
• #[reject(condition)] - 仅当 condition（返回布尔值的代码块）为 false 时继续执行。

请求体宏

• #[request_body(variable_name)] - 将原始请求体提取到指定变量中，类型为 RequestBody。
• #[request_body(var1, var2, ...)] - 支持多个请求体变量。
• #[request_body_json(variable_name: type)] - 将请求体解析为 JSON 并存入指定变量和类型。
• #[request_body_json(var1: Type1, var2: Type2, ...)] - 支持多个 JSON 体解析。

属性宏

• #[attribute_option(key => variable_name: type)] - 按键提取特定属性到带类型的变量中（Option 包装）。
• #[attribute_option("key1" => var1: Type1, "key2" => var2: Type2, ...)] - 支持多个属性提取。
• #[attribute(key => variable_name: type)] - 按键提取特定属性到带类型的变量中（缺失时 panic）。
• #[attribute("key1" => var1: Type1, "key2" => var2: Type2, ...)] - 支持多个属性提取。

属性集合宏

• #[attributes(variable_name)] - 获取所有属性作为 HashMap，用于全面访问属性。
• #[attributes(var1, var2, ...)] - 支持多个属性集合。

Panic 数据宏

• #[task_panic_data_option(variable_name)] - 将 panic 数据提取到 Option 包装的变量中。
• #[task_panic_data_option(var1, var2, ...)] - 支持多个 panic 数据变量。
• #[task_panic_data(variable_name)] - 将 panic 数据提取到变量中（缺失时 panic）。
• #[task_panic_data(var1, var2, ...)] - 支持多个 panic 数据变量。

请求错误数据宏

• #[request_error_data_option(variable_name)] - 将请求错误数据提取到 Option 包装的变量中。
• #[request_error_data_option(var1, var2, ...)] - 支持多个请求错误数据变量。
• #[request_error_data(variable_name)] - 将请求错误数据提取到变量中（缺失时 panic）。
• #[request_error_data(var1, var2, ...)] - 支持多个请求错误数据变量。

路由参数宏

• #[route_param_option(key => variable_name)] - 按键提取特定路由参数到变量中（Option 包装）。
• #[route_param_option("key1" => var1, "key2" => var2, ...)] - 支持多个路由参数提取。
• #[route_param(key => variable_name)] - 按键提取特定路由参数到变量中（缺失时 panic）。
• #[route_param("key1" => var1, "key2" => var2, ...)] - 支持多个路由参数提取。

路由参数集合宏

• #[route_params(variable_name)] - 获取所有路由参数作为集合。
• #[route_params(var1, var2, ...)] - 支持多个路由参数集合。

请求查询宏

• #[request_query_option(key => variable_name)] - 从 URL 查询字符串按键提取特定查询参数。
• #[request_query_option("key1" => var1, "key2" => var2, ...)] - 支持多个查询参数提取。
• #[request_query(key => variable_name)] - 从 URL 查询字符串按键提取特定查询参数（缺失时 panic）。
• #[request_query("key1" => var1, "key2" => var2, ...)] - 支持多个查询参数提取。

请求查询集合宏

• #[request_querys(variable_name)] - 获取所有查询参数作为集合。
• #[request_querys(var1, var2, ...)] - 支持多个查询参数集合。

请求头宏

• #[request_header_option(key => variable_name)] - 从请求中按键提取特定 HTTP 头（Option 包装）。
• #[request_header_option(KEY1 => var1, KEY2 => var2, ...)] - 支持多个头提取。
• #[request_header(key => variable_name)] - 从请求中按键提取特定 HTTP 头（缺失时 panic）。
• #[request_header(KEY1 => var1, KEY2 => var2, ...)] - 支持多个头提取。

请求头集合宏

• #[request_headers(variable_name)] - 获取所有 HTTP 头作为集合。
• #[request_headers(var1, var2, ...)] - 支持多个头集合。

请求 Cookie 宏

• #[request_cookie_option(key => variable_name)] - 从请求 Cookie 头按键提取特定 Cookie 值（Option 包装）。
• #[request_cookie_option("key1" => var1, "key2" => var2, ...)] - 支持多个 Cookie 提取。
• #[request_cookie(key => variable_name)] - 从请求 Cookie 头按键提取特定 Cookie 值（缺失时 panic）。
• #[request_cookie("key1" => var1, "key2" => var2, ...)] - 支持多个 Cookie 提取。

请求 Cookie 集合宏

• #[request_cookies(variable_name)] - 从 Cookie 头获取所有 Cookie 作为原始字符串。
• #[request_cookies(var1, var2, ...)] - 支持多个 Cookie 集合。

请求版本宏

• #[request_version(variable_name)] - 将 HTTP 请求版本提取到变量中。
• #[request_version(var1, var2, ...)] - 支持多个请求版本变量。

请求路径宏

• #[request_path(variable_name)] - 将 HTTP 请求路径提取到变量中。
• #[request_path(var1, var2, ...)] - 支持多个请求路径变量。

主机宏

• #[host("hostname")] - 限制函数仅在具有特定 Host 头值的请求时执行。
• #[host("host1", "host2", ...)] - 支持多个主机检查。
• #[reject_host("hostname")] - 拒绝匹配特定 Host 头值的请求。
• #[reject_host("host1", "host2", ...)] - 支持多个主机拒绝。

Referer 宏

• #[referer("url")] - 限制函数仅在具有特定 Referer 头值的请求时执行。
• #[referer("url1", "url2", ...)] - 支持多个 Referer 检查。
• #[reject_referer("url")] - 拒绝匹配特定 Referer 头值的请求。
• #[reject_referer("url1", "url2", ...)] - 支持多个 Referer 拒绝。

钩子宏

• #[prologue_hooks(function_name)] - 在主处理函数前执行指定函数。
• #[epilogue_hooks(function_name)] - 在主处理函数后执行指定函数。
• #[prologue_hooks(method::expression, another::method)] - 支持方法表达式用于高级钩子配置。
• #[epilogue_hooks(method::expression, another::method)] - 支持方法表达式用于高级钩子配置。
• #[task_panic] - 在服务器内发生 panic 时执行函数。
• #[request_error] - 在服务器内发生请求错误时执行函数。
• #[prologue_macros(macro1, macro2, ...)] - 在装饰函数前注入一系列宏。
• #[epilogue_macros(macro1, macro2, ...)] - 在装饰函数后注入一系列宏。

中间件宏

• #[request_middleware] - 将函数注册为请求中间件。
• #[request_middleware(order)] - 将函数注册为指定顺序的请求中间件。
• #[response_middleware] - 将函数注册为响应中间件。
• #[response_middleware(order)] - 将函数注册为指定顺序的响应中间件。
• #[task_panic] - 将函数注册为 panic 钩子。
• #[task_panic(order)] - 将函数注册为指定顺序的 panic 钩子。
• #[request_error] - 将函数注册为请求错误钩子。
• #[request_error(order)] - 将函数注册为指定顺序的请求错误钩子。

流处理宏

• #[http_from_stream] - 使用默认请求配置包装函数体进行 HTTP 流处理。仅当成功从 HTTP 流读取数据时才执行函数体。
• #[http_from_stream(request_config)] - 使用指定请求配置进行 HTTP 流处理。
• #[http_from_stream(variable_name)] - 进行 HTTP 流处理并将数据存储在指定变量名中。
• #[http_from_stream(request_config, variable_name)] - 使用指定请求配置和变量名进行 HTTP 流处理。
• #[http_from_stream(variable_name, request_config)] - 使用指定变量名和请求配置进行 HTTP 流处理（顺序可交换）。
• #[ws_from_stream] - 使用默认请求配置包装函数体进行 WebSocket 流处理。仅当成功从 WebSocket 流读取数据时才执行函数体。
• #[ws_from_stream(request_config)] - 使用指定请求配置进行 WebSocket 流处理。
• #[ws_from_stream(variable_name)] - 进行 WebSocket 流处理并将数据存储在指定变量名中。
• #[ws_from_stream(request_config, variable_name)] - 使用指定请求配置和变量名进行 WebSocket 流处理。
• #[ws_from_stream(variable_name, request_config)] - 使用指定变量名和请求配置进行 WebSocket 流处理（顺序可交换）。

路由宏

• #[route("path")] - 为给定路径注册路由处理器，使用默认服务器（前提：需使用 #[hyperlane(server: Server)] 宏）。

使用提示

• 请求相关宏（数据提取）使用 get 操作——从请求中检索/查询数据。
• 响应相关宏（数据设置）使用 set 操作——分配/配置响应数据。
• 钩子宏 对于支持 order 参数的钩子宏，若未指定 order，则该钩子优先级高于指定了 order 的钩子（仅适用于如 #[request_middleware]、#[response_middleware]、#[task_panic]、#[request_error] 等宏）。
• 多参数支持 大多数数据提取宏支持在单次调用中指定多个参数（例如 #[request_body(var1, var2)]、#[request_query("k1" => v1, "k2" => v2)]），以减少宏重复并提高代码可读性。

许可证

该项目使用 MIT 许可证。详情请参阅 LICENSE 文件。

贡献

欢迎贡献！请提交问题或拉取请求。

联系方式

如有任何问题，请联系作者 [email protected]。

加载中...