实战案例 - HTTP 服务器设计与最小实现

这一章的目标，不是带你做一个“可直接上线的完整 Web 服务器”，而是帮助你建立一个更重要的判断：

一个最小 HTTP 服务器，真正需要解决哪些问题？

如果你第一次接触 Zig 中的网络编程，很容易把注意力全部放在某个具体 API 上：怎么监听端口、怎么 accept、怎么 read、怎么 write。
但对教程读者来说，更重要的其实是先看清下面这些设计约束：

服务器要维护什么最小状态？
一次连接的生命周期如何组织？
请求读取和请求解析分别是什么问题？
响应生成应该放在哪一层？
哪些地方是“教学简化”，哪些地方在真实工程里必须继续补上？

⚠️ 阅读提醒

本章涉及的网络与 I/O 接口属于 Zig 0.16.0-dev 语境下较容易变化的区域。
因此，本章更适合被理解为：

设计导向的最小服务器原型

版本敏感 API 背景下的结构化阅读示例

帮助你建立“连接 → 请求 → 响应 → 关闭”主流程直觉的教学案例

请不要把文中的每个接口签名都当成长期稳定不变的规范。
真正落地时，应结合你本地 Zig 版本和标准库源码核对细节。

先明确：这一章不试图解决什么？

这是一个同步、最小解析、固定文本响应的教学原型，不涉及 keep-alive、分块传输、TLS 等生产特性。

一个最小 HTTP 服务器到底在做什么？

从结构上看，一个最小 HTTP 服务器通常只需要完成 5 件事：

监听端口
接受连接
读取请求的起始数据
根据请求路径生成响应
写回响应并关闭连接

这个流程已经能把服务器端最核心的资源边界暴露出来：

监听套接字何时创建、何时释放
每个连接何时接受、何时关闭
请求缓冲区由谁持有
响应字符串由谁分配、由谁释放
错误出现时，哪些资源必须仍然被清理

这一章的实现约束

为了保持案例的教学价值，我们先明确采用以下约束。

1. 同步处理模型

一次只处理一个连接，不引入线程池或事件循环。

这样做的目的不是说“同步模型最好”，而是为了先把连接生命周期讲清楚。

2. 只做最小请求解析

我们只关心请求行里的：

方法
路径

这意味着我们不会实现：

完整请求头解析
请求体读取
chunked 编码
完整 HTTP 语法校验

3. 响应内容保持最简单

只返回几个固定文本：

/ 返回欢迎页
/api 返回简单 JSON 文本
其他路径返回 404

4. 把网络 API 当背景，不当主角

本章的主角是服务器的结构和资源模型，不是某个开发版接口名。

为什么要先从同步模型开始？

很多读者一看到“服务器”，就会自然联想到：

多线程
高并发
异步 I/O
事件循环
reactor / proactor

这些主题当然重要，但如果你一开始就把它们全部叠上来，往往反而会看不清基础问题。

先从同步模型开始，有几个好处：

更容易理解连接生命周期
更容易看清请求读取和响应写回的位置
更容易识别资源释放责任
更容易区分“网络编程问题”和“并发编程问题”

这正是为什么本章不直接追求“高性能服务器”，而是先追求“结构清楚”。

设计草图：先看结构，再看代码

下面是本章希望你建立的最小结构图：

Server
├── init()                初始化监听地址与上下文
├── start()               启动监听循环
├── handleConnection()    处理单个连接
└── generateResponse()    根据路径生成响应文本

这个结构有几个教学上的好处：

init() 负责“启动前准备”
start() 负责“整体循环”
handleConnection() 负责“一次请求-响应交互”
generateResponse() 负责“业务逻辑最小分发”

这样做的核心价值不是“面向对象”，而是：

把不同层次的问题拆开。

否则你很容易把监听、读取、解析、拼响应、写回、清理全部塞进一个函数，最后既不利于理解，也不利于扩展。

概念性最小原型

下面这段代码更适合作为结构示意来阅读。
请重点关注：

主循环在哪里
连接关闭发生在哪里
请求是如何被最小解析的
响应是如何集中生成的

而不要把它理解成“已经覆盖完整 HTTP 细节的实现”。

const std = @import("std");

const Server = struct {
    address: std.Io.net.Ip4Address,
    allocator: std.mem.Allocator,
    io: std.Io,

    const Self = @This();

    fn init(allocator: std.mem.Allocator, io: std.Io, port: u16) Self {
        return .{
            .address = .{
                .bytes = .{ 0, 0, 0, 0 },
                .port = port,
            },
            .allocator = allocator,
            .io = io,
        };
    }

    fn start(self: *Self) !void {
        var listener = try self.address.listen(self.io, .{
            .reuse_port = true,
        });
        defer listener.deinit(self.io);

        std.debug.print("server listening on port {d}\n", .{self.address.getPort()});

        while (true) {
            const stream = try listener.accept(self.io);
            try self.handleConnection(stream);
        }
    }

    fn handleConnection(self: *Self, stream: std.Io.net.Stream) !void {
        defer stream.close(self.io);

        var buf: [4096]u8 = undefined;
        var rdr = stream.reader(self.io, &buf);
        const reader: *std.Io.Reader = &rdr.interface;

        const maybe_line = reader.takeDelimiter('\n');
        if (maybe_line == null) return;
        const line = maybe_line.? orelse return;
        _ = line;

        // 正文略：请求解析与响应生成逻辑见下方讲解
    }
};

pub fn main(init: std.process.Init) !void {
    var gpa: std.heap.DebugAllocator(.{}) = .init;
    defer _ = gpa.deinit();

    var server = Server.init(gpa.allocator(), init.io, 8080);
    try server.start();
}