Hyperlane-框架入门[20261006024703]

Github开源项目
0 阅读1分钟

Hyperlane 框架入门

项目代码：github.com/hyperlane-d…

简介

Hyperlane 是一个轻量级、高性能、跨平台的 Rust HTTP 服务器库，构建于 Tokio 之上。它为使用 Rust 构建 Web 应用和 API 提供了强大而灵活的基础。无论你是在创建简单的 REST API 还是复杂的 Web 服务，Hyperlane 都提供了高效完成任务所需的工具和性能。

Hyperlane 的独特之处在于它在不牺牲性能的前提下，专注于提升开发者的生产力。该库提供了两种互补的 API：一种直接的编程式 API，以及一种基于派生宏的 API，可以减少样板代码。这种双轨方式意味着你可以选择最适合项目和编码偏好的风格。

核心特性

Hyperlane 内置了丰富的特性，使其成为 Rust Web 开发的优秀选择：

  • 轻量且快速：基于 Tokio 异步运行时构建，Hyperlane 提供了卓越的性能。在关闭 Keep-Alive 的基准测试中，Hyperlane 达到了 51,031 QPS，优于 Tokio（49,555）、Rocket（49,345）和 Gin（40,149）。
  • 跨平台：在不同操作系统上无缝运行。
  • 中间件系统：灵活的中间件架构，用于请求和响应处理。
  • 属性宏：派生宏可以消除样板代码，使代码更具声明式风格。
  • WebSocket 支持：内置的 WebSocket 升级处理。
  • SSE（服务器推送事件）：原生支持向客户端流式推送事件。
  • 灵活的路由：支持静态路由、动态路径参数和基于正则的路由。
  • Cookie 管理：完整的 Cookie 支持，采用构建器模式。
  • 优雅停机：干净的服务器关闭能力。
  • 多服务支持：并发运行多个服务器实例。

性能基准

Hyperlane 的性能已经过严格的基准测试，与主流框架的对比结果如下：

框架关闭 Keep-Alive (QPS)开启 Keep-Alive (QPS)
Hyperlane51,031334,888
Tokio49,555340,130
Rocket49,345298,945
Gin40,149242,570

在 100 万请求的 ab 测试中（开启 Keep-Alive），Hyperlane 达到了 316,211 QPS，展示了其高效处理海量工作负载的能力。

安装

使用 Cargo 可以轻松地将 Hyperlane 添加到你的 Rust 项目中：

cargo add hyperlane

此命令会将 Hyperlane 作为依赖添加到你的 Cargo.toml 文件中。请确保项目中已引入 Tokio 运行时，因为 Hyperlane 基于 Tokio 构建。

第一个服务器

让我们创建一个简单的 HTTP 服务器来了解基本用法。以下是一个服务器正常运行所需的最简代码：

#[tokio::main]
async fn main() {
    let mut server: Server = Server::default();
    let server_control_hook: ServerControlHook = server.run().await.unwrap_or_default();
    server_control_hook.wait().await;
}

就这样！只需几行代码，你就拥有了一个功能完整的 HTTP 服务器。让我们逐行分析：

  1. #[tokio::main] — 这个属性宏初始化 Tokio 异步运行时，Hyperlane 依赖它来处理并发连接。
  2. Server::default() — 使用默认配置（监听 127.0.0.1:80）创建一个新的服务器实例。
  3. server.run().await — 异步启动服务器，返回一个 ServerControlHook。
  4. server_control_hook.wait().await — 保持服务器运行，直到显式关闭。

服务器创建方式

Hyperlane 提供了多种创建服务器的方式，让你可以灵活配置应用：

默认服务器

最简单的方式使用默认设置：

let mut server: Server = Server::default();
let server_control_hook: ServerControlHook = server.run().await.unwrap_or_default();
server_control_hook.wait().await;

从 ServerConfig 创建

如需更多控制，可以从 ServerConfig 创建服务器：

let server_config: ServerConfig = ServerConfig::default();
let mut server: Server = Server::from(server_config);

从 RequestConfig 创建

也可以从 RequestConfig 创建服务器：

let request_config: RequestConfig = RequestConfig::default();
let mut server: Server = Server::from(request_config);

属性宏风格

Hyperlane 支持使用属性宏的声明式编程风格。这种方式可以让你的代码更简洁、更具表达力：

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

#[hyperlane(server: Server)]
#[hyperlane(server_config: ServerConfig)]
#[tokio::main]
async fn main() {
    server_config.set_nodelay(Some(false));
    server.server_config(server_config);
    let server_control_hook: ServerControlHook = server.run().await.unwrap_or_default();
    server_control_hook.wait().await;
}

在这种风格中，#[hyperlane(server: Server)] 和 #[hyperlane(server_config: ServerConfig)] 宏会自动将 server 和 server_config 变量注入到 main 函数中。然后你可以在运行服务器之前直接对其进行配置。

项目结构

对于较大的 Hyperlane 项目，良好的目录结构有助于维护代码质量：

├── application/controller/domain/exception/mapper/middleware/model/repository/service/utils/view
├── bootstrap/application/framework
├── config/application/framework
├── plugin/database/env/logger/mysql/postgresql/process/redis
├── resources/docker/env/sql/static/templates

这种结构将关注点分离到逻辑层中：

  • application/：包含应用逻辑，包括控制器、领域模型、服务和中间件。
  • bootstrap/：应用引导和初始化代码。
  • config/：配置管理。
  • plugin/：插件集成，用于数据库、日志记录和其他外部服务。
  • resources/：静态资源、模板、Docker 配置和 SQL 文件。

推荐工具

Hyperlane 生态系统包含多个有用的配套工具：

  • hyperlane-utils：Hyperlane 应用的实用函数
  • hyperlane-log：日志支持
  • hyperlane-time：时间工具
  • hyperlane-broadcast：广播能力
  • hyperlane-plugin-websocket：增强的 WebSocket 插件
  • utoipa：OpenAPI 文档支持
  • http-request：HTTP 请求工具
  • server-manager：服务器管理工具
  • urlencoding：URL 编解码
  • chunkify：数据分块工具

下一步

现在你已经对 Hyperlane 有了基本了解，接下来可以探索更高级的主题：

  • 服务器配置：了解如何微调服务器设置，如地址、nodelay 和 TTL。
  • 中间件系统：了解如何拦截和处理请求与响应。
  • 路由：设置 URL 路由，包括静态、动态和基于正则的路由。
  • 请求处理：从传入请求中提取数据，包括头部、查询参数和请求体内容。
  • 响应构建：构建并发送带有正确状态码和头部的 HTTP 响应。

本系列的后续文章将详细介绍每个主题。

总结

Hyperlane 为在 Rust 中构建高性能 Web 应用提供了坚实的基础。其简单的 API、强大的属宏和出色的性能，使其成为希望构建 Web 服务的开发者的理想选择。只需几行代码，你就可以运行一个生产就绪的 HTTP 服务器，灵活的架构允许你从简单的 API 扩展到复杂的 Web 应用。

在下一篇文章中，我们将深入探讨服务器配置，了解如何自定义 Hyperlane 服务器以获得最佳性能和功能。

项目代码：github.com/hyperlane-d…

avatar
文章
阅读
粉丝