跳至主要內容

宏参考手册

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

宏参考手册

本手册提供了 hyperlane-macros 中所有宏的快速参考和分类索引。

📋 宏分类索引

🌐 HTTP 方法宏

宏名称功能描述参数用法示例
#[get]限制 GET 请求无#[get] async fn handler(ctx: &Context) {}
#[post]限制 POST 请求无#[post] async fn handler(ctx: &Context) {}
#[put]限制 PUT 请求无#[put] async fn handler(ctx: &Context) {}
#[delete]限制 DELETE 请求无#[delete] async fn handler(ctx: &Context) {}
#[patch]限制 PATCH 请求无#[patch] async fn handler(ctx: &Context) {}
#[head]限制 HEAD 请求无#[head] async fn handler(ctx: &Context) {}
#[options]限制 OPTIONS 请求无#[options] async fn handler(ctx: &Context) {}
#[connect]限制 CONNECT 请求无#[connect] async fn handler(ctx: &Context) {}
#[trace]限制 TRACE 请求无#[trace] async fn handler(ctx: &Context) {}
#[methods]多种 HTTP 方法方法列表#[methods(get, post)] async fn handler(ctx: &Context) {}

🔗 协议版本宏

宏名称功能描述参数用法示例
#[http]标准 HTTP 请求无#[http] async fn handler(ctx: &Context) {}
#[http0_9]HTTP/0.9 协议无#[http0_9] async fn handler(ctx: &Context) {}
#[http1_0]HTTP/1.0 协议无#[http1_0] async fn handler(ctx: &Context) {}
#[http1_1]HTTP/1.1 协议无#[http1_1] async fn handler(ctx: &Context) {}
#[http1_1_or_higher]HTTP/1.1+无#[http1_1_or_higher] async fn handler(ctx: &Context) {}
#[http2]HTTP/2 协议无#[http2] async fn handler(ctx: &Context) {}
#[http3]HTTP/3 协议无#[http3] async fn handler(ctx: &Context) {}
#[h2c]HTTP/2 Cleartext无#[h2c] async fn handler(ctx: &Context) {}
#[tls]TLS 加密请求无#[tls] async fn handler(ctx: &Context) {}
#[ws]WebSocket 升级无#[ws] async fn handler(ctx: &Context) {}

📥 请求处理宏

宏名称功能描述参数用法示例
#[route_param]路径参数提取映射列表#[route_param("id" => id)] async fn handler(ctx: &Context) {}
#[route_params]所有路径参数变量列表#[route_params(params)] async fn handler(ctx: &Context) {}
#[request_query]查询参数提取映射列表#[request_query("name" => name)] async fn handler(ctx: &Context) {}
#[request_querys]所有查询参数变量列表#[request_querys(querys)] async fn handler(ctx: &Context) {}
#[request_header]请求头提取映射列表#[request_header(HOST => host)] async fn handler(ctx: &Context) {}
#[request_headers]所有请求头变量列表#[request_headers(headers)] async fn handler(ctx: &Context) {}
#[request_cookie]Cookie 提取映射列表#[request_cookie("sid" => session)] async fn handler(ctx: &Context) {}
#[request_cookies]所有 Cookie变量列表#[request_cookies(cookies)] async fn handler(ctx: &Context) {}
#[request_body]请求体提取变量名#[request_body(body)] async fn handler(ctx: &Context) {}
#[request_version]HTTP 版本变量名#[request_version(version)] async fn handler(ctx: &Context) {}
#[request_path]请求路径变量名#[request_path(path)] async fn handler(ctx: &Context) {}
#[filter] / #[reject]条件过滤布尔表达式#[filter(condition)] async fn handler(ctx: &Context) {}

📤 响应处理宏

宏名称功能描述参数用法示例
#[response_header]设置响应头头部映射#[response_header("Content-Type", "json")] async fn handler(ctx: &Context) {}
#[clear_response_headers]清除所有响应头无#[clear_response_headers] async fn handler(ctx: &Context) {}
#[response_body]设置响应体内容#[response_body("Hello")] async fn handler(ctx: &Context) {}
#[response_status_code]设置状态码状态码#[response_status_code(200)] async fn handler(ctx: &Context) {}
#[response_reason]设置原因短语短语#[response_reason("OK")] async fn handler(ctx: &Context) {}
#[response_version]设置响应版本版本#[response_version(HttpVersion::HTTP1_1)] async fn handler(ctx: &Context) {}
#[send]发送完整响应无#[send] async fn handler(ctx: &Context) {}
#[send_body]仅发送响应体无#[send_body] async fn handler(ctx: &Context) {}
#[send_with_data]发送带数据响应数据#[send_with_data("data")] async fn handler(ctx: &Context) {}
#[send_body_with_data]发送带数据响应体数据#[send_body_with_data("data")] async fn handler(ctx: &Context) {}
#[send_once]单次响应无#[send_once] async fn handler(ctx: &Context) {}
#[flush]刷新响应流无#[flush] async fn handler(ctx: &Context) {}

🔧 中间件和钩子宏

宏名称功能描述参数用法示例
#[hyperlane]定义服务器实例类型映射#[hyperlane(server: Server)] async fn main() {}
#[route]注册路由路径#[route("/path")] struct Handler;
#[request_middleware]请求中间件优先级#[request_middleware(1)] struct Middleware;
#[response_middleware]响应中间件优先级#[response_middleware(1)] struct Middleware;
#[panic_hook]Panic 钩子优先级#[panic_hook(1)] struct Hook;
#[prologue_hooks]前置钩子函数列表#[prologue_hooks(fn1, fn2)] async fn handler(ctx: &Context) {}
#[epilogue_hooks]后置钩子函数列表#[epilogue_hooks(fn1, fn2)] async fn handler(ctx: &Context) {}
#[prologue_macros]前置宏组合宏列表#[prologue_macros(get, response_body("ok"))] async fn handler(ctx: &Context) {}

🚀 高级功能宏

宏名称功能描述参数用法示例
#[host]主机验证主机值#[host("example.com")] async fn handler(ctx: &Context) {}
#[reject_host]拒绝无主机无#[reject_host] async fn handler(ctx: &Context) {}
#[referer]Referer 验证URL#[referer("https://example.com")] async fn handler(ctx: &Context) {}
#[reject_referer]拒绝 RefererURL#[reject_referer("https://bad.com")] async fn handler(ctx: &Context) {}
#[aborted]中止请求处理无#[aborted] async fn handler(ctx: &Context) {}
#[closed]关闭连接处理无#[closed] async fn handler(ctx: &Context) {}
#[ws_from_stream]WebSocket 流无#[ws_from_stream] async fn handler(ctx: &Context) {}
#[stream]流处理包装缓冲区大小#[stream(1024)] async fn handler(ctx: &Context) {}
#[inject]依赖注入类型映射#[inject(service: Service)] async fn handler(ctx: &Context) {}

📝 最佳实践

1. 宏组合原则

  • 前置宏 (#[prologue_macros]): 验证、过滤、数据提取
  • 后置宏 (#[epilogue_macros]): 响应设置、数据发送、清理

2. 性能优化

  • 使用 #[http1_1_or_higher] 获得更好的性能
  • 合理设置 #[stream] 的缓冲区大小
  • 避免在中间件中进行耗时操作

3. 安全考虑

  • 始终验证输入数据
  • 设置适当的安全响应头
  • 实现 #[panic_hook] 处理异常

4. 可维护性

  • 保持宏的简洁性
  • 合理组织中间件优先级
  • 提供清晰的错误响应
  • 编写完整的测试覆盖
最近更新:
贡献者: 尤雨东