...">响应处理宏 | eastspire
跳至主要內容

响应处理宏

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

响应处理宏

响应处理宏用于配置和管理 HTTP 响应，包括设置响应头、响应体、状态码、协议版本等。这些宏简化了响应的构建和发送过程。

响应头管理

#[response_header]

设置或替换 HTTP 响应头。

用法

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

#[route("/response")]
struct Response;

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

    #[prologue_macros(
        response_header(SERVER => HYPERLANE),
        response_header("X-Add-Header", "add-value"),
        response_header("X-Set-Header" => "set-value")
    )]
    async fn handle(self, ctx: &Context) {}
}

impl Response {
    #[response_header("X-Custom" => "value")]
    async fn response_header_with_ref_self(&self, ctx: &Context) {}
}

#[response_header("X-Custom" => "value")]
async fn standalone_response_header_handler(ctx: &Context) {}

说明

  • 接受头部名称和值，可以是字符串字面量或全局常量
  • 支持两种语法：
    • "key", "value" - 设置头部
    • "key" => "value" - 替换头部
  • 应用于接受 &Context 参数的异步函数
  • 支持常量值：response_header(SERVER => HYPERLANE)

常用响应头

#[response_header("Content-Type", "application/json")]
#[response_header("Cache-Control", "no-cache")]
#[response_header("Access-Control-Allow-Origin", "*")]
#[response_header("X-Frame-Options", "DENY")]

#[clear_response_headers]

清除所有响应头。

用法

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

#[route("/clear_headers")]
struct ClearHeaders;

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

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

impl ClearHeaders {
    #[clear_response_headers]
    async fn clear_response_headers_with_ref_self(&self, ctx: &Context) {}
}

#[clear_response_headers]
async fn standalone_clear_response_headers_handler(ctx: &Context) {}

说明

  • 无参数
  • 清除所有已设置的响应头
  • 通常在设置自定义头部前使用
  • 适用于需要完全控制响应头的场景

响应体处理

#[response_body]

设置 HTTP 响应体内容。

用法

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

const RESPONSE_DATA: &str = "{\"status\": \"success\"}";

#[route("/response")]
struct Response;

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

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

impl Response {
    #[response_body(&RESPONSE_DATA)]
    async fn response_body_with_ref_self(&self, ctx: &Context) {}
}

#[response_body("standalone response body")]
async fn standalone_response_body_handler(ctx: &Context) {}

动态内容

#[response_body(&format!("User: {}, Age: {}", name, age))]
async fn dynamic_response_handler(ctx: &Context, name: &str, age: u32) {}

JSON 响应

#[response_body(&serde_json::to_string(&json_response).unwrap())]
async fn json_response_handler(ctx: &Context) {}

说明

  • 接受字符串字面量或全局常量
  • 支持动态内容生成
  • 应用于接受 &Context 参数的异步函数
  • 适用于各种内容类型：HTML、JSON、文本等

响应状态管理

#[response_status_code]

设置 HTTP 响应状态码。

用法

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

const CUSTOM_STATUS_CODE: i32 = 200;

#[route("/response")]
struct Response;

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

    #[response_status_code(CUSTOM_STATUS_CODE)]
    async fn handle(self, ctx: &Context) {}
}

impl Response {
    #[response_status_code(CUSTOM_STATUS_CODE)]
    async fn response_status_code_with_ref_self(&self, ctx: &Context) {}
}

#[response_status_code(200)]
async fn standalone_response_status_code_handler(ctx: &Context) {}

常用状态码

#[response_status_code(200)]  // OK
#[response_status_code(201)]  // Created
#[response_status_code(400)]  // Bad Request
#[response_status_code(401)]  // Unauthorized
#[response_status_code(403)]  // Forbidden
#[response_status_code(404)]  // Not Found
#[response_status_code(500)]  // Internal Server Error

说明

  • 接受数字 HTTP 状态码或全局常量
  • 应用于接受 &Context 参数的异步函数
  • 配置响应的状态码部分
  • 常与响应体和头部配合使用

#[response_reason]

设置 HTTP 响应原因短语。

用法

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

const CUSTOM_REASON: &str = "Accepted";

#[route("/response")]
struct Response;

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

    #[response_reason(CUSTOM_REASON)]
    async fn handle(self, ctx: &Context) {}
}

impl Response {
    #[response_reason(CUSTOM_REASON)]
    async fn response_reason_with_ref_self(&self, ctx: &Context) {}
}

#[response_reason("Custom Reason")]
async fn standalone_response_reason_handler(ctx: &Context) {}

说明

  • 接受字符串字面量或全局常量
  • 应用于接受 &Context 参数的异步函数
  • 配置状态码对应的原因短语
  • 通常使用标准原因短语，但也支持自定义

#[response_version]

设置 HTTP 响应协议版本。

用法

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

#[route("/response")]
struct Response;

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

    #[prologue_macros(
        response_status_code(200),
        response_version(HttpVersion::HTTP1_1),
        response_header(SERVER => HYPERLANE)
    )]
    async fn handle(self, ctx: &Context) {}
}

impl Response {
    #[response_version(HttpVersion::HTTP1_1)]
    async fn response_version_with_ref_self(&self, ctx: &Context) {}
}

#[response_version(HttpVersion::HTTP1_1)]
async fn standalone_response_version_handler(ctx: &Context) {}

说明

  • 接受 HttpVersion 枚举值
  • 应用于接受 &Context 参数的异步函数
  • 配置响应使用的 HTTP 协议版本
  • 通常与请求版本保持一致

响应发送控制

#[send]

自动发送完整响应（头部和体）。

用法

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

#[route("/send")]
struct SendTest;

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

    #[epilogue_macros(send)]
    async fn handle(self, ctx: &Context) {}
}

impl SendTest {
    #[send]
    async fn send_with_ref_self(&self, ctx: &Context) {}
}

#[send]
async fn standalone_send_handler(ctx: &Context) {}

说明

  • 无参数
  • 确保响应（头部和体）在函数完成后自动发送
  • 应用于接受 &Context 参数的异步函数
  • 适用于标准的 HTTP 响应场景

#[send_body]

自动发送仅响应体。

用法

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

#[route("/send_body")]
struct SendBodyTest;

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

    #[epilogue_macros(send_body)]
    async fn handle(self, ctx: &Context) {}
}

impl SendBodyTest {
    #[send_body]
    async fn send_body_with_ref_self(&self, ctx: &Context) {}
}

#[send_body]
async fn standalone_send_body_handler(ctx: &Context) {}

说明

  • 无参数
  • 确保只有响应体在函数完成后自动发送
  • 头部分开处理
  • 应用于接受 &Context 参数的异步函数

#[send_with_data]

发送带有指定数据的完整响应。

用法

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

#[route("/send_with_data")]
struct SendWithData;

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

    #[epilogue_macros(send_with_data("Hello, World!"))]
    async fn handle(self, ctx: &Context) {}
}

impl SendWithData {
    #[send_with_data("Hello, World!")]
    async fn send_with_data_with_ref_self(&self, ctx: &Context) {}
}

#[send_with_data("data")]
async fn standalone_send_with_data_handler(ctx: &Context) {}

说明

  • 接受要发送的数据
  • 确保响应（头部和体）在函数完成后自动发送
  • 使用指定的数据作为响应内容
  • 应用于接受 &Context 参数的异步函数

#[send_body_with_data]

发送带有指定数据的响应体。

用法

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

#[route("/send_body_with_data")]
struct SendBodyWithData;

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

    #[epilogue_macros(send_body_with_data("Response body content"))]
    async fn handle(self, ctx: &Context) {}
}

说明

  • 接受要发送的数据
  • 确保只有响应体在函数完成后自动发送
  • 使用指定的数据作为响应体内容
  • 头部分开处理

#[send_once]

确保响应只发送一次。

用法

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

#[route("/send_once")]
struct SendOnceTest;

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

    #[epilogue_macros(send_once)]
    async fn handle(self, ctx: &Context) {}
}

impl SendOnceTest {
    #[send_once]
    async fn send_once_with_ref_self(&self, ctx: &Context) {}
}

#[send_once]
async fn standalone_send_once_handler(ctx: &Context) {}

说明

  • 无参数
  • 确保响应只发送一次，防止多次响应传输
  • 适用于单次响应场景
  • 应用于接受 &Context 参数的异步函数

#[send_once_with_data]

发送带有指定数据的单次响应。

用法

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

#[route("/send_once_with_data")]
struct SendOnceWithData;

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

    #[epilogue_macros(send_once_with_data("One-time response"))]
    async fn handle(self, ctx: &Context) {}
}

impl SendOnceWithData {
    #[send_once_with_data("One-time response")]
    async fn send_once_with_data_with_ref_self(&self, ctx: &Context) {}
}

#[send_once_with_data("data")]
async fn standalone_send_once_with_data_handler(ctx: &Context) {}

说明

  • 接受要发送的数据
  • 确保响应只发送一次，使用指定数据
  • 防止多次响应传输
  • 应用于接受 &Context 参数的异步函数

响应流控制

#[flush]

刷新响应流。

用法

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

#[route("/flush")]
struct FlushTest;

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

    #[epilogue_macros(flush)]
    async fn handle(self, ctx: &Context) {}
}

impl FlushTest {
    #[flush]
    async fn flush_with_ref_self(&self, ctx: &Context) {}
}

#[flush]
async fn standalone_flush_handler(ctx: &Context) {}

说明

  • 无参数
  • 确保响应流被刷新，立即传输数据
  • 强制发送任何缓冲的响应数据
  • 应用于接受 &Context 参数的异步函数
  • 适用于需要立即响应的场景

响应场景示例

REST API 响应

#[route("/api/users/:id")]
struct GetUser;

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

    #[prologue_macros(
        route_param("id" => user_id),
        http,
        methods(get)
    )]
    #[epilogue_macros(
        response_status_code(200),
        response_header("Content-Type", "application/json"),
        response_body(&format!("{{\"id\": {}, \"name\": \"John\"}}", user_id.unwrap_or_default())),
        send
    )]
    async fn handle(self, ctx: &Context) {}
}

错误响应

#[route("/error")]
struct ErrorHandler;

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

    #[epilogue_macros(
        response_status_code(404),
        response_reason("Not Found"),
        response_body("{{\"error\": \"Resource not found\"}}"),
        send
    )]
    async fn handle(self, ctx: &Context) {}
}

重定向响应

#[route("/redirect")]
struct RedirectHandler;

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

    #[epilogue_macros(
        response_status_code(302),
        response_reason("Found"),
        response_header("Location", "/new-location"),
        response_body("Redirecting..."),
        send
    )]
    async fn handle(self, ctx: &Context) {}
}

使用建议

  1. 响应设计原则：

    • 保持响应一致性
    • 使用合适的 HTTP 状态码
    • 提供清晰的错误信息
    • 遵循 RESTful 设计原则

  2. 性能优化：

    • 合理使用缓存头部
    • 压缩大型响应
    • 使用流式传输处理大数据
    • 避免不必要的头部设置

  3. 安全性考虑：

    • 设置安全相关的响应头
    • 避免泄露敏感信息
    • 使用 HTTPS 传输敏感数据
    • 验证响应内容

  4. 错误处理：

    • 提供详细的错误信息
    • 使用标准的错误格式
    • 记录错误日志
    • 提供错误恢复机制

  5. 兼容性：

    • 考虑客户端的协议支持
    • 提供降级方案
    • 测试不同客户端的兼容性
    • 使用标准的 HTTP 特性
最近更新:
贡献者: 尤雨东