用 Rust 从零实现 HTTP 服务器:只用 TcpStream
大多数人对 HTTP 的理解停在这一层:
GET /index.html HTTP/1.1。再往下问"响应怎么分块、连接什么时候关",就开始含糊了。
这篇不引入任何 HTTP 框架,只用 std::net::TcpStream 从头写。写完一遍,HTTP 协议里那些"看起来是规范细节"的东西,会变成你能一眼看出的工程约束。
HTTP/1.1 报文长什么样
请求:
GET /api/users?page=1 HTTP/1.1\r\n
Host: example.com\r\n
Accept: application/json\r\n
Content-Length: 13\r\n
\r\n
{"a": "b"}响应:
HTTP/1.1 200 OK\r\n
Content-Type: application/json\r\n
Content-Length: 15\r\n
\r\n
{"ok": true}三条规则先记住:
- 行结束符是
\r\n,不是\n——虽然实践中两者都接受 - 头部和 body 之间有一个空行(
\r\n\r\n) - body 长度由头部决定,不能靠"读到连接关闭"来判断(keep-alive 下连接不会关)
第一步:把字节流读成报文
难点在第 3 条:TCP 是字节流,没有消息边界。一次 read 可能返回半个头部,也可能带上整个 body 加下一个请求的前半段。
所以要分两阶段读:
use std::io::{BufRead, BufReader, Read};
use std::net::TcpStream;
pub struct Request {
pub method: String,
pub path: String,
pub version: String,
pub headers: Vec<(String, String)>,
pub body: Vec<u8>,
}
pub fn read_request(stream: &mut TcpStream) -> std::io::Result<Option<Request>> {
let mut reader = BufReader::new(stream);
// 阶段一:逐行读到空行,拿到请求行 + 头部
let mut request_line = String::new();
if reader.read_line(&mut request_line)? == 0 {
return Ok(None); // 客户端关闭了连接
}
let mut headers = Vec::new();
loop {
let mut line = String::new();
if reader.read_line(&mut line)? == 0 {
break;
}
let trimmed = line.trim_end_matches(['\r', '\n']);
if trimmed.is_empty() {
break; // 空行 = 头部结束
}
if let Some((k, v)) = trimmed.split_once(':') {
headers.push((k.trim().to_string(), v.trim().to_string()));
}
}
// 阶段二:按 Content-Length 精确读 body
let content_length = headers
.iter()
.find(|(k, _)| k.eq_ignore_ascii_case("content-length"))
.and_then(|(_, v)| v.parse::<usize>().ok())
.unwrap_or(0);
let mut body = vec![0u8; content_length];
if content_length > 0 {
reader.read_exact(&mut body)?;
}
// 解析请求行
let parts: Vec<&str> = request_line.trim().split_whitespace().collect();
if parts.len() != 3 {
return Err(std::io::Error::new(
std::io::ErrorKind::InvalidData,
"malformed request line",
));
}
Ok(Some(Request {
method: parts[0].to_string(),
path: parts[1].to_string(),
version: parts[2].to_string(),
headers,
body,
}))
}关键在 read_exact:先根据 Content-Length 知道要读多少字节,再精确读——这才保证了不会多读下一个请求的数据。
TCP 没有消息边界,所以任何基于 TCP 的协议都必须在应用层定义"读多少"。HTTP 用 Content-Length 或 chunked 编码来做这件事。
\r\n 的坑
上面 trim_end_matches(['\r', '\n']) 同时处理了两种行尾。为什么要宽容?
因为现实里有客户端只发 \n。严格按规范应该拒绝,但宽容读取、严格写入(Postel 定律)在实现 HTTP 服务器时通常更实用。
但对响应,必须严格用 \r\n:
fn write_response(stream: &mut TcpStream, mut resp: Response) -> std::io::Result<()> {
let mut out = Vec::new();
write!(out, "HTTP/1.1 {} {}\r\n", resp.status, reason_phrase(resp.status))?;
// 自动补 Content-Length
resp.headers.push(("Content-Length".into(), resp.body.len().to_string()));
for (k, v) in &resp.headers {
write!(out, "{k}: {v}\r\n")?;
}
out.extend_from_slice(b"\r\n"); // 空行
out.extend_from_slice(&resp.body);
stream.write_all(&out)
}Content-Length 必须和 body 实际长度一致。 不一致的话,客户端要么读不完整等待超时,要么多读到下一个响应的数据——这是最隐蔽的一类 bug。
chunked 编码:长度未知时怎么办
Content-Length 有个硬伤:你必须先知道 body 有多长。
但流式场景下这个前提不成立:代理转发一个实时日志流、服务端渲染大表格、SSE 推送——数据是边生成边发的。
HTTP/1.1 的解法是 Transfer-Encoding: chunked。body 被切成若干块,每块前面标长度,最后用一个 0 长度块结束:
HTTP/1.1 200 OK\r\n
Transfer-Encoding: chunked\r\n
\r\n
5\r\n
Hello\r\n
6\r\n
World\r\n
0\r\n
\r\n实现时每一块单独发:
pub fn write_chunk(stream: &mut TcpStream, data: &[u8]) -> std::io::Result<()> {
write!(stream, "{:x}\r\n", data.len())?; // 长度用十六进制
stream.write_all(data)?;
stream.write_all(b"\r\n")
}
pub fn end_chunks(stream: &mut TcpStream) -> std::io::Result<()> {
stream.write_all(b"0\r\n\r\n")
}长度是十六进制,不是十进制。 写错的话客户端会解析出完全错误的长度,症状是"响应卡住然后乱码"。
读取时反过来:先读一行当长度,读到 0 就结束:
fn read_chunked(reader: &mut BufReader<TcpStream>) -> std::io::Result<Vec<u8>> {
let mut body = Vec::new();
loop {
let mut len_line = String::new();
reader.read_line(&mut len_line)?;
let len = usize::from_str_radix(len_line.trim(), 16)
.map_err(|_| std::io::Error::new(std::io::ErrorKind::InvalidData, "bad chunk len"))?;
if len == 0 {
reader.read_line(&mut String::new())?; // 吃掉结尾空行
break;
}
let mut chunk = vec![0u8; len];
reader.read_exact(&mut chunk)?;
body.extend_from_slice(&chunk);
reader.read_line(&mut String::new())?; // 吃掉 chunk 后的 \r\n
}
Ok(body)
}keep-alive:什么时候关连接
HTTP/1.1 默认是长连接(keep-alive)。同一个连接上可以连续发多个请求,避免反复握手。
这对服务器意味着:处理完一个请求后,不能立刻关连接,要回去继续读下一个请求。
fn handle_connection(mut stream: TcpStream) -> std::io::Result<()> {
// 设置读超时,防止空闲连接永久占用线程
stream.set_read_timeout(Some(std::time::Duration::from_secs(30)))?;
loop {
let req = match read_request(&mut stream) {
Ok(Some(req)) => req,
Ok(None) => return Ok(()), // 客户端正常关闭
Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => return Ok(()), // 超时
Err(e) => return Err(e),
};
// 判断是否要关闭连接
let close = should_close(&req);
let resp = route(&req)?;
write_response(&mut stream, resp)?;
if close {
return Ok(());
}
}
}判断连接是否关闭,规则有优先级:
fn should_close(req: &Request) -> bool {
let connection = header(req, "connection").unwrap_or("");
match (req.version.as_str(), connection.to_lowercase().as_str()) {
// HTTP/1.0 默认短连接,除非显式 keep-alive
("HTTP/1.0", "keep-alive") => false,
("HTTP/1.0", _) => true,
// HTTP/1.1 默认长连接,除非显式 close
("HTTP/1.1", "close") => true,
("HTTP/1.1", _) => false,
_ => true,
}
}HTTP/1.0 和 1.1 的默认行为是相反的。 这个差异在自研代理里经常被搞错,症状是"老客户端每次都重连"或"连接永远不释放"。
内容长度和连接语义的联动
这里有一个容易忽略的联动:如果响应既没有 Content-Length 也没有 Transfer-Encoding,客户端只能靠"连接关闭"来判断 body 结束。
意思是:
有 Content-Length -> 可以 keep-alive
有 Transfer-Encoding -> 可以 keep-alive
都没有 -> 必须 Connection: close三者不能全都不给还宣称 keep-alive。 否则客户端会一直等连接关闭,造成请求挂死。
fn finalize(resp: &mut Response, close: bool) {
if resp.headers.iter().any(|(k, _)| k.eq_ignore_ascii_case("transfer-encoding")) {
// chunked,不用加 Content-Length
} else {
resp.headers.push(("Content-Length".into(), resp.body.len().to_string()));
}
if close {
resp.headers.push(("Connection".into(), "close".into()));
}
}请求行和路径解析
GET /api/users?page=1&size=10 HTTP/1.1 这一行里要拆三样东西:
pub struct Uri {
pub path: String,
pub query: Vec<(String, String)>,
}
pub fn parse_uri(raw: &str) -> Uri {
let (path, query_str) = raw.split_once('?').unwrap_or((raw, ""));
let query = query_str
.split('&')
.filter(|s| !s.is_empty())
.filter_map(|pair| pair.split_once('='))
.map(|(k, v)| (percent_decode(k), percent_decode(v)))
.collect();
Uri { path: percent_decode(path), query }
}必须做百分号解码:/search?q=%E4%B8%AD%E6%96%87 里的 %E4%B8%AD 是 "中" 的 UTF-8 编码。
fn percent_decode(s: &str) -> String {
let bytes = s.as_bytes();
let mut out = Vec::with_capacity(bytes.len());
let mut i = 0;
while i < bytes.len() {
if bytes[i] == b'%' && i + 2 < bytes.len() {
if let Ok(b) = u8::from_str_radix(&s[i + 1..i + 3], 16) {
out.push(b);
i += 3;
continue;
}
}
out.push(bytes[i]);
i += 1;
}
String::from_utf8_lossy(&out).into_owned()
}所有涉及路径和查询参数的地方,都必须先解码再用。 一个常见的路径穿越漏洞(
/../etc/passwd)就来自"解码之后没再做规范化校验"。
路由:最简单的前缀匹配
fn route(req: &Request) -> std::io::Result<Response> {
let uri = parse_uri(&req.path);
match (req.method.as_str(), uri.path.as_str()) {
("GET", "/") => Ok(Response::text(200, "hello, http")),
("GET", "/health") => Ok(Response::text(200, "ok")),
("POST", "/echo") => Ok(Response {
status: 200,
headers: vec![("Content-Type".into(), "application/octet-stream".into())],
body: req.body.clone(),
}),
_ => Ok(Response::text(404, "not found")),
}
}路由本身不是重点,重点是它拿到的 req 是已经完整解析过的——路径解码了,body 读全了。
与异步版本的关系
上面的实现是阻塞的:一个线程处理一个连接。要处理一万个连接,得配合前面写的异步运行时。
但协议解析这部分是完全一样的。异步版本只是把:
read_request(&mut stream) // 阻塞换成
read_request_async(&mut stream).await // 注册到 reactor解析逻辑(找空行、算 Content-Length、解析 chunked)一字不改。
这也是"先写阻塞版"的价值:协议的正确性和并发模型无关。 先把协议写对,再考虑怎么并发,问题会清楚得多。
结论
一个能跑的 HTTP 服务器,核心是这几条:
TCP 没有边界,必须靠 Content-Length 或 chunked 才知读多少;响应头长度必须和 body 一致;1.0 默认短连接、1.1 默认长连接;没有长度信息就不能宣称 keep-alive;路径和查询参数必须解码。
写完之后再看 hyper,你会发现它做的正是这些事——只是加了零拷贝、SIMD 解析、更完善的状态机,以及一整套 trait 抽象。协议的骨架,还是这几十行。