1 HTTP 数据结构

两个类均提供了

generate 成员函数，用于从请求/响应结构生成 HTTP 格式的字符串，在调用此方法后可直接通过 Socket 发送数据
parse 静态成员函数，用于从 HTTP 格式的字符串解析出请求/响应结构，在接收到 Socket 原始数据后可调用此方法进行解析

rm::Response 还提供了多种简化生成响应的成员函数，如 send、json、redirect 等。

2 HTTP 请求工具

3 Web 后端框架

RMVL 提供了后端应用框架 rm::async::Webapp ，以及负责传输层监听的 rm::async::HttpServer 和 rm::async::HttpsServer 。设计参考 Express JS，具体来说，Webapp 负责路由与中间件，服务器对象负责 HTTP 或 HTTPS 监听，同一个 Webapp 可以交给不同类型的服务器。

3.1 HTTP 服务器

rm::async::Webapp 和 rm::Router 提供了 GET、POST、DELETE 等相关方法用于定义路由，并且 rm::async::Webapp 可以使用 use 方法挂载中间件或挂载由 rm::Router 定义的子路由。

// demo.cpp
#include <rmvl/io/netapp.hpp>
 
using namespace rm;
 
int main(int argc, char *argv[]) {
    if (argc < 2) {
        printf("Usage: %s <port>\n", argv[0]);
        return 1;
    }
 
    uint16_t port = static_cast<uint16_t>(std::atoi(argv[1]));
 
    async::IOContext io_context{};
 
    // 创建后端应用
    async::Webapp app(io_context);
    async::HttpServer server(app);
 
    // 定义路由：以 GET 方法响应根路径请求
    app.get("/", [](const Request &req, Response &res) {
        res.send("<html><body><h1>Hello, World!</h1></body></html>");
    });
    // 定义路由：重定向示例
    app.get("/test", [](const Request &req, Response &res) {
        res.redirect("/");
    });
 
    // 创建子路由
    auto api_router = Router{};
 
    // 定义子路由：以 GET 方法响应根路径请求
    api_router.get("/", [](const Request &req, Response &res) {
        res.json({
            {"key", "value"},
            {"message", "This is a test API."},
        });
    });
    // 定义子路由：以 GET 方法响应 /name/:name 路径请求
    api_router.get("/name/:name", [](const Request &req, Response &res) {
        auto name = req.params.at("name");
        res.json({
            {"greeting", "Hello, " + name + "!"},
        });
    });
 
    // 使用 CORS 中间件允许跨域请求
    app.use(cors());
 
    // 挂载路由至 /api 路径
    app.use("/api", api_router);
 
    // 监听指定端口
    server.listen(port, [&]() {
        printf("Server is running on port %d\n", port);
    });
 
    // 生成协程任务并执行
    co_spawn(io_context, &async::HttpServer::spin, &server);
    io_context.run();
}

可以简单使用以下命令行进行编译

g++ demo.cpp -std=c++20 -I /usr/local/include/RMVL -l rmvl_io -l rmvl_core -o demo

# 如果使用的是 Windows 系统，可能需要额外链接 ws2_32 库

注解: 当然，也可以自行编写 CMakeLists.txt 文件，采用 CMake 构建系统进行构建，具体的 CMakeLists.txt 内容可参考如下内容：

cmake_minimum_required(VERSION 3.16)

project(Demo)

find_package(RMVL REQUIRED)

rmvl_add_exe(

  demo

  SOURCES demo.cpp

  DEPENDS io

)

编译后，在终端输入

./demo 8080

即可创建 Web 后端服务，并且监听 8080 端口，可以使用 curl 工具或浏览器访问 http://localhost:8080/ 来测试服务器。

curl -s "http://localhost:8080"

会得到如下输出：

<html><body><h1>Hello, World!</h1></body></html>

注解: rm::async::Webapp 虽然也提供了 listen 方法，但该方法仅用于快速测试，实际生产环境推荐使用 rm::async::HttpServer 或 rm::async::HttpsServer 进行监听。

WebSocket 支持

rm::async::Webapp 支持通过 ws 方法注册 WebSocket 路由。WebSocket 路由的回调函数是一个协程函数，在 HTTP Upgrade 握手成功后被调用，回调中可以通过 rm::async::WebSocket 的 recv 和 send 方法接收、发送文本消息。

下面的例子创建了一个简单的 Echo WebSocket 服务，客户端向 /ws/echo 发送文本消息后，服务端会原样返回。

// ws_demo.cpp
#include <rmvl/io/netapp.hpp>
 
using namespace rm;
 
int main(int argc, char *argv[]) {
    if (argc < 2) {
        printf("Usage: %s <port>\n", argv[0]);
        return 1;
    }
 
    uint16_t port = static_cast<uint16_t>(std::atoi(argv[1]));
 
    async::IOContext io_context{};
    async::Webapp app(io_context);
    async::HttpServer server(app);
 
    app.get("/", [](const Request &, Response &res) {
        res.send("WebSocket echo server is running.");
    });
 
    app.ws("/ws/echo", [](async::WebSocket &ws, const Request &) -> async::Task<> {
        while (ws.is_open()) {
            std::string msg = co_await ws.recv();
            if (msg.empty())
                break;
            co_await ws.send(msg);
        }
    });
 
    server.listen(port, [&]() {
        printf("WebSocket server is running on port %d\n", port);
    });
 
    co_spawn(io_context, &async::HttpServer::spin, &server);
    io_context.run();
}

编译方式与前面的 HTTP 服务示例相同。运行后，可以使用 wscat 等 WebSocket 客户端进行测试：

./ws_demo 8080

wscat -c "ws://127.0.0.1:8080/ws/echo"

在客户端输入任意文本并回车，即可看到服务端返回相同的文本内容。

WebSocket 路由同样支持路径参数，参数会写入 Request::params，例如：

app.ws("/ws/:room", [](async::WebSocket &ws, const Request &req) -> async::Task<> {
    const auto room = req.params.at("room");
    while (ws.is_open()) {
        std::string msg = co_await ws.recv();
        if (msg.empty())
            break;
        co_await ws.send("[" + room + "] " + msg);
    }
});

注解: 当前 WebSocket 接口面向文本消息，recv 在连接关闭或收到关闭帧时返回空字符串；若业务需要发送空字符串，请在应用层自行约定消息格式。

3.2 HTTPS 服务器

HTTPS 与 HTTP 使用相同的 Webapp，只需要将 rm::async::HttpServer 替换为 rm::async::HttpsServer ，并提供服务端的 rm::SSLContext 即可，示例代码如下：

async::IOContext io_context{};
async::Webapp app(io_context);
 
app.get("/", [](const Request &, Response &res) {
    res.send("Hello, HTTPS!");
});
 
SSLContext ssl_context = SSLContext::server();
if (!ssl_context.load_cert("server.crt", "server.key")) {
    printf("%s\n", ssl_context.lasterr().c_str());
    return 1;
}
 
async::HttpsServer server(app, ssl_context);
server.listen(8443, [] {
    printf("HTTPS server is listening on 8443\n");
});
 
co_spawn(io_context, &async::HttpsServer::spin, &server);
io_context.run();

SSLContext 必须比 HttpsServer 和所有活动 TLS 连接存活得更久。证书自动续期后，需要重新加载 SSLContext 或重启/重载服务进程，才能让新连接使用更新后的证书。使用命令行直接编译 HTTPS 程序时，还需要链接 OpenSSL 的 ssl 和 crypto 库；使用 CMake 链接 rmvl_io 目标时会自动传递该依赖。

测试自签名证书时可以使用：

curl -k "https://127.0.0.1:8443/"

对于 wss，即 TLS 加密的 WebSocket，若使用 HTTPS 服务器，WebSocket 路由的注册方式不变，只需要将服务端换成 rm::async::HttpsServer，客户端使用 wss:// 地址连接即可。