跳至主要內容

HTTP 方法宏

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

HTTP 方法宏

HTTP 方法宏用于限制函数只能在特定的 HTTP 请求方法下执行。这些宏确保只有使用相应 HTTP 方法的请求才会触发函数执行，其他方法将被过滤掉。

#[get]

限制函数仅在 HTTP GET 请求时执行。

用法

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

#[route("/get")]
struct Get;

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

    #[prologue_macros(get, response_body("get"))]
    async fn handle(self, ctx: &Context) {}
}

impl Get {
    #[get]
    async fn get_with_ref_self(&self, ctx: &Context) {}
}

#[get]
async fn standalone_get_handler(ctx: &Context) {}

说明

  • 无参数
  • 直接应用于接受 &Context 参数的异步函数
  • 只有 GET 请求会触发函数执行

#[post]

限制函数仅在 HTTP POST 请求时执行。

用法

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

#[route("/post")]
struct Post;

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

    #[prologue_macros(post, response_body("post"))]
    async fn handle(self, ctx: &Context) {}
}

impl Post {
    #[post]
    async fn post_with_ref_self(&self, ctx: &Context) {}
}

#[post]
async fn standalone_post_handler(ctx: &Context) {}

说明

  • 无参数
  • 用于处理 POST 请求，通常包含请求体数据
  • 适用于表单提交、API 数据提交等场景

#[put]

限制函数仅在 HTTP PUT 请求时执行。

用法

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

#[route("/put")]
struct Put;

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

    #[prologue_macros(put, response_body("put"))]
    async fn handle(self, ctx: &Context) {}
}

impl Put {
    #[put]
    async fn put_with_ref_self(&self, ctx: &Context) {}
}

#[put]
async fn standalone_put_handler(ctx: &Context) {}

说明

  • 无参数
  • 用于完整的资源更新操作
  • PUT 请求通常包含要替换的完整资源数据

#[delete]

限制函数仅在 HTTP DELETE 请求时执行。

用法

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

#[route("/delete")]
struct Delete;

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

    #[prologue_macros(delete, response_body("delete"))]
    async fn handle(self, ctx: &Context) {}
}

impl Delete {
    #[delete]
    async fn delete_with_ref_self(&self, ctx: &Context) {}
}

#[delete]
async fn standalone_delete_handler(ctx: &Context) {}

说明

  • 无参数
  • 用于资源删除操作
  • 通常不需要请求体，通过 URL 路径标识要删除的资源

#[patch]

限制函数仅在 HTTP PATCH 请求时执行。

用法

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

#[route("/patch")]
struct Patch;

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

    #[prologue_macros(patch, response_body("patch"))]
    async fn handle(self, ctx: &Context) {}
}

impl Patch {
    #[patch]
    async fn patch_with_ref_self(&self, ctx: &Context) {}
}

#[patch]
async fn standalone_patch_handler(ctx: &Context) {}

说明

  • 无参数
  • 用于部分资源更新操作
  • PATCH 请求通常只包含要修改的字段

限制函数仅在 HTTP HEAD 请求时执行。

用法

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

#[route("/head")]
struct Head;

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

    #[prologue_macros(head, response_body("head"))]
    async fn handle(self, ctx: &Context) {}
}

impl Head {
    #[head]
    async fn head_with_ref_self(&self, ctx: &Context) {}
}

#[head]
async fn standalone_head_handler(ctx: &Context) {}

说明

  • 无参数
  • HEAD 请求只返回响应头，不返回响应体
  • 用于获取资源的元信息而不传输实际内容

#[options]

限制函数仅在 HTTP OPTIONS 请求时执行。

用法

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

#[route("/options")]
struct Options;

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

    #[prologue_macros(options, response_body("options"))]
    async fn handle(self, ctx: &Context) {}
}

impl Options {
    #[options]
    async fn options_with_ref_self(&self, ctx: &Context) {}
}

#[options]
async fn standalone_options_handler(ctx: &Context) {}

说明

  • 无参数
  • 用于 CORS 预检请求
  • 返回服务器支持的 HTTP 方法和其他选项

#[connect]

限制函数仅在 HTTP CONNECT 请求时执行。

用法

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

#[route("/connect")]
struct Connect;

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

    #[prologue_macros(connect, response_body("connect"))]
    async fn handle(self, ctx: &Context) {}
}

impl Connect {
    #[connect]
    async fn connect_with_ref_self(&self, ctx: &Context) {}
}

#[connect]
async fn standalone_connect_handler(ctx: &Context) {}

说明

  • 无参数
  • 用于建立网络连接的隧道
  • 常用于 HTTPS 代理场景

#[trace]

限制函数仅在 HTTP TRACE 请求时执行。

用法

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

#[route("/trace")]
struct Trace;

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

    #[prologue_macros(trace, response_body("trace"))]
    async fn handle(self, ctx: &Context) {}
}

impl Trace {
    #[trace]
    async fn trace_with_ref_self(&self, ctx: &Context) {}
}

#[trace]
async fn standalone_trace_handler(ctx: &Context) {}

说明

  • 无参数
  • 用于诊断和调试，回显收到的请求
  • 出于安全考虑，生产环境通常禁用 TRACE 方法

#[methods]

允许函数处理多种 HTTP 方法。

用法

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

#[route("/get_post")]
struct GetPost;

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

    #[prologue_macros(
        http,
        methods(get, post),
        response_body("get_post")
    )]
    async fn handle(self, ctx: &Context) {}
}

impl GetPost {
    #[methods(get, post)]
    async fn methods_with_ref_self(&self, ctx: &Context) {}
}

#[methods(get, post)]
async fn standalone_methods_handler(ctx: &Context) {}

说明

  • 接受逗号分隔的 HTTP 方法名称列表（小写）
  • 应用于接受 &Context 参数的异步函数
  • 支持同时处理多种 HTTP 方法的场景

参数格式

#[methods(get, post)]           // 支持 GET 和 POST
#[methods(get, post, put)]       // 支持 GET、POST 和 PUT
#[methods(get, post, put, delete)] // 支持 GET、POST、PUT 和 DELETE

使用建议

  1. RESTful API 设计：根据资源操作选择合适的 HTTP 方法

    • GET：查询资源
    • POST：创建资源
    • PUT：完整更新资源
    • PATCH：部分更新资源
    • DELETE：删除资源

  2. 安全性考虑：确保使用正确的方法验证和权限控制

  3. 错误处理：为不支持的 HTTP 方法返回适当的 405 Method Not Allowed 响应

  4. 组合使用：可以与其他宏组合使用，如协议检查、参数提取等

  5. 性能优化：HTTP 方法过滤在请求处理早期进行，避免不必要的计算

最近更新:
贡献者: 尤雨东