---
title: "HTTP 配置与进阶使用"
---

> Documentation Index
> Fetch the complete documentation index at: https://openarkstudio.github.io/arknet/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP 配置与进阶使用

[客户端](/arknet/zh/features/http/client)与[服务端](/arknet/zh/features/http/server)示例提供完整的启动、收发与关闭程序。以下配置在相应对象启动前应用，除非另有说明。

## 消息、回调与所有权

客户端接收 `response<string_body>&`；服务端接收 Session 引用和
`request<string_body>&`。引用只在回调期间有效，保留前必须复制或移动。
接受入队的发送持有序列化消息至完成，调用方之后修改原对象不会改变排队消息。

修改 body 后调用 `prepare_payload()`，或明确配置 chunked 拆包。
写完成统计 HTTP 线上字节，包括头部；不代表对端已收到或处理请求。
立即拒绝和已入队完成遵循[公共发送约定](/arknet/zh/concepts/sending)。

## Keep-Alive 与流水线

同一连接可连续排队多个请求。客户端按请求顺序匹配响应，跳过信息响应后报告
最终响应。服务端应用必须按请求顺序发送响应。路由框架的同步处理自然保持顺序；
将业务移到其他线程后，需要恢复响应顺序再发送。

HEAD 响应没有 body，可用 `empty_body` 响应声明表示资源的 Content-Length。
需要 EOF 的响应在写完后关闭连接，后续排队发送以取消完成。
服务端收到 `Expect: 100-continue` 时，先发送信息响应再等 body。

## 上限与错误

启动前配置 `set_http_header_limit(bytes)` 和 `set_http_body_limit(bytes)`。
默认分别为 8192 字节和 16 MiB。读取中修改上限从下一条消息的解析器生效。
解析／拆包错误和超限消息会关闭连接。404 等状态是正常 HTTP 响应，
业务应检查 `response.result()`。

连接错误通过 `bind_disconnect` 和回调线程中的 `get_last_error()` 检查。
一次性请求可以关闭自动重连。重连不会自动重放业务请求。

## HTTPS 服务端与客户端

开启 `ARKNET_ENABLE_SSL=ON` 后，对[服务端](/arknet/zh/features/http/server)和[客户端](/arknet/zh/features/http/client)完整程序作以下修改，即可用于 HTTPS。保留请求与响应回调、回显验证和关闭代码。以下公开测试证书与私钥只用于本地测试；部署时应使用实际服务的证书和 CA 信任。证书路径及 mTLS 配置见 [TLS 示例](/arknet/zh/features/tls/configuration)。

在服务端程序中，将头文件替换为 `<arknet/http/https_server.hpp>`，并将服务端声明替换为：

```cpp
arknet::https_server server;
server.set_cert_file("", "tests/certs/server.pem", "tests/certs/server-key.pem", "");
if (arknet::get_last_error())
{
    std::cerr << arknet::get_last_error().message() << '\n';
    return 1;
}
```

改用 `server.start("127.0.0.1", 8443)` 监听，并将输出 URL 改为 `https://localhost:8443/echo`。

在客户端程序中，将头文件替换为 `<arknet/http/https_client.hpp>`，并将客户端声明替换为：

```cpp
arknet::https_client client;
arknet::error_code error;
client.load_verify_file("tests/certs/ca.pem", error);
if (error)
{
    std::cerr << error.message() << '\n';
    return 1;
}
```

改用 `client.start("localhost", 8443)` 连接，并将请求 `Host` 字段设为 `"localhost:8443"`。连接名称决定 DNS/IP 身份校验；HTTP Host 头不会改变 TLS 身份。客户端默认校验证书链和连接名称。在仓库根目录运行程序，以便解析测试证书路径。

## 自定义 Session

自定义 Session 继承 `http_session_t<MySession>`，
交给 `http_server_t<MySession>`；HTTPS 提供对应的 `https_*` 形式。
[HTTP 测试](https://github.com/OpenArkStudio/arknet/blob/main/tests/http.cpp)
覆盖独立 raw 对端的 chunked、HEAD、上限、Expect 和流水线。

## 路由与业务处理

[`http_router`](/arknet/zh/guides/http-routing) 提供方法／路径分发与中间件。
路由回调在接收 lane 同步执行。较长 CPU 或阻塞任务需要应用工作池、
有界业务排队和响应排序，见 [IO 模型](/arknet/zh/concepts/io-models)。

Source: https://openarkstudio.github.io/arknet/zh/features/http/configuration/index.mdx