Zigbook
Chapter 31Networking Http And Json

网络、HTTP 与 JSON

概览

本章从本地文件与线程提升到套接字，使用 Zig 的std.net与std.http在进程间有序传输数据。背景参见net.zig。我们将构建一个最小回环服务器、探索握手，并在其上叠加 HTTP/JSON 工作流以展示这些组件如何组合。

Zig 0.15.2 的 I/O 重设计移除了旧式缓冲助手，因此我们将采用现代的std.Io.Reader/std.Io.Writer接口，并在必要时演示如何手动管理分帧。参见Reader.zig与v0.15.2。

网络栈架构

在编写套接字代码之前，理解std.net如何融入 Zig 标准库架构至关重要。下图展示了从高层网络 API 到系统调用的完整分层：

graph TB subgraph "User Code" APP[Application Code] end subgraph "High-Level APIs (lib/std)" FS["std.fs<br/>(fs.zig)"] NET["std.net<br/>(net.zig)"] PROCESS["std.process<br/>(process.zig)"] FMT["std.fmt<br/>(fmt.zig)"] HEAP["std.heap<br/>(heap.zig)"] end subgraph "Mid-Level Abstractions" POSIX["std.posix<br/>(posix.zig)<br/>Cross-platform POSIX API"] OS["std.os<br/>(os.zig)<br/>OS-specific wrappers"] MEM["std.mem<br/>(mem.zig)<br/>Memory utilities"] DEBUG["std.debug<br/>(debug.zig)<br/>Stack traces, assertions"] end subgraph "Platform Layer" LINUX["std.os.linux<br/>(os/linux.zig)<br/>Direct syscalls"] WINDOWS["std.os.windows<br/>(os/windows.zig)<br/>Win32 APIs"] WASI["std.os.wasi<br/>(os/wasi.zig)<br/>WASI APIs"] LIBC["std.c<br/>(c.zig)<br/>C interop"] end subgraph "System Layer" SYSCALL["System Calls"] KERNEL["Operating System"] end APP --> FS APP --> NET APP --> PROCESS APP --> FMT APP --> HEAP FS --> POSIX NET --> POSIX PROCESS --> POSIX FMT --> MEM HEAP --> MEM POSIX --> OS OS --> LIBC OS --> LINUX OS --> WINDOWS OS --> WASI DEBUG --> OS LINUX --> SYSCALL WINDOWS --> SYSCALL WASI --> SYSCALL LIBC --> SYSCALL SYSCALL --> KERNEL

该分层设计与第 28 章的文件系统架构相映：std.net提供高层、可移植的网络抽象（Address、Stream、Server），经由std.posix实现跨平台 POSIX 套接字兼容，再分派到平台特定实现——Linux 下为直接系统调用（socket、bind、listen、accept），Windows 下为 Win32 Winsock API。调用Address.listen()时，请求按层穿越：std.net.Address → std.posix.socket() → std.os.linux.socket()（或std.os.windows.WSASocketW()）→ 内核。这也解释了为何 WASI 构建在套接字操作上失败——多数运行时的 WASI 层并不支持套接字。理解该架构有助于你推理错误处理（错误自系统调用冒泡）、调试平台特定问题，并就 libc 链接做出更具可移植性的决策。

学习目标

本模块的目标围绕std.net中的网络原语及其之上的 HTTP 栈（Server.zig、Client.zig）。你将学习如何：

  • 使用std.net.Address.listen构建回环服务，及时接受连接，并通过std.Thread.ResetEvent协调就绪。
  • 使用新的std.Io.Reader助手实现按换行的分帧，替代已弃用的缓冲适配器。
  • 调用std.http.Client.fetch、捕获响应流，并使用std.json工具解析 JSON 载荷。json.zig

套接字基元

std.net提供跨平台 TCP 原语，镜像 POSIX 套接字生命周期，并与 Zig 的错误语义与资源管理集成。结合std.Thread.ResetEvent可在无需轮询的情况下将服务器线程的就绪与客户端同步。ResetEvent.zig

回环握手演示

下例绑定到127.0.0.1、接受单个客户端，并回显其接收的修剪后文本行。因 Zig 的 reader API 不再提供便捷的行读取器，示例使用Reader.takeByte实现readLine助手，演示如何直接构建该功能。

Zig
const std = @import("std");

//  传递给服务器线程的参数，使其能够准确接受一个客户端并进行回复。
const ServerTask = struct {
    server: *std.net.Server,
    ready: *std.Thread.ResetEvent,
};

//  从 `std.Io.Reader` 中读取单行，并移除末尾的换行符。
//  如果在读取任何字节之前流结束，则返回 `null`。
fn readLine(reader: *std.Io.Reader, buffer: []u8) !?[]const u8 {
    var len: usize = 0;
    while (true) {
        // 尝试从流中读取单个字节
        const byte = reader.takeByte() catch |err| switch (err) {
            error.EndOfStream => {
                // 流结束：如果没有读取到数据则返回 null，否则返回已读取到的内容
                if (len == 0) return null;
                return buffer[0..len];
            },
            else => return err,
        };

        // 遇到换行符时完成读取行
        if (byte == '\n') return buffer[0..len];
        // 跳过回车符以处理 Unix (\n) 和 Windows (\r\n) 两种换行符
        if (byte == '\r') continue;

        // 防止缓冲区溢出
        if (len == buffer.len) return error.StreamTooLong;
        buffer[len] = byte;
        len += 1;
    }
}

// / 阻塞等待单个客户端，回显客户端发送的内容，然后退出。
fn serveOne(task: ServerTask) void {
    // 通知主线程服务器线程已进入接受循环。
    // 这种同步机制防止客户端在服务器准备好之前尝试连接。
    task.ready.set();

    // 阻塞直到客户端连接；优雅地处理连接错误
    const connection = task.server.accept() catch |err| {
        std.debug.print("accept failed: {s}\n", .{@errorName(err)});
        return;
    };
    // 确保此函数退出时连接已关闭
    defer connection.stream.close();

    // 设置一个缓冲读取器以接收来自客户端的数据
    var inbound_storage: [128]u8 = undefined;
    var net_reader = connection.stream.reader(&inbound_storage);
    const conn_reader = net_reader.interface();

    // 使用自定义的行读取逻辑从客户端读取一行
    var line_storage: [128]u8 = undefined;
    const maybe_line = readLine(conn_reader, &line_storage) catch |err| {
        std.debug.print("receive failed: {s}\n", .{@errorName(err)});
        return;
    };

    // 处理连接在未发送数据的情况下关闭的情况
    const line = maybe_line orelse {
        std.debug.print("connection closed before any data arrived\n", .{});
        return;
    };

    // 清理接收行中任何尾随的空白字符
    const trimmed = std.mem.trimRight(u8, line, "\r\n");

    // 构建一个回显服务器观察到的内容的响应消息
    var response_storage: [160]u8 = undefined;
    const response = std.fmt.bufPrint(&response_storage, "server observed \"{s}\"\n", .{trimmed}) catch |err| {
        std.debug.print("format failed: {s}\n", .{@errorName(err)});
        return;
    };

    // 使用缓冲写入器将响应发送回客户端
    var outbound_storage: [128]u8 = undefined;
    var net_writer = connection.stream.writer(&outbound_storage);
    net_writer.interface.writeAll(response) catch |err| {
        std.debug.print("write error: {s}\n", .{@errorName(err)});
        return;
    };
    // 确保所有缓冲数据在连接关闭前传输
    net_writer.interface.flush() catch |err| {
        std.debug.print("flush error: {s}\n", .{@errorName(err)});
        return;
    };
}

pub fn main() !void {
    // 初始化分配器以满足动态内存需求
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // 在 127.0.0.1 上创建一个回环服务器，使用操作系统分配的端口（端口 0）
    const address = try std.net.Address.parseIp("127.0.0.1", 0);
    var server = try address.listen(.{ .reuse_address = true });
    defer server.deinit();

    // 创建一个同步原语以协调服务器就绪状态
    var ready = std.Thread.ResetEvent{};
    // 启动服务器线程，该线程将接受并处理一个连接
    const server_thread = try std.Thread.spawn(.{}, serveOne, .{ServerTask{
        .server = &server,
        .ready = &ready,
    }});
    // 确保服务器线程在 main() 退出前完成
    defer server_thread.join();

    // 阻塞直到服务器线程发出已到达 accept() 的信号
    // 这可以防止客户端过早尝试连接的竞态条件
    ready.wait();

    // 检索动态分配的端口号并作为客户端连接
    const port = server.listen_address.in.getPort();
    var stream = try std.net.tcpConnectToHost(allocator, "127.0.0.1", port);
    defer stream.close();

    // 使用缓冲写入器向服务器发送测试消息
    var outbound_storage: [64]u8 = undefined;
    var client_writer = stream.writer(&outbound_storage);
    const payload = "ping over loopback\n";
    try client_writer.interface.writeAll(payload);
    // 强制传输缓冲数据
    try client_writer.interface.flush();

    // 使用缓冲读取器接收服务器的响应
    var inbound_storage: [128]u8 = undefined;
    var client_reader = stream.reader(&inbound_storage);
    const client_reader_iface = client_reader.interface();
    var reply_storage: [128]u8 = undefined;
    const maybe_reply = try readLine(client_reader_iface, &reply_storage);
    const reply = maybe_reply orelse return error.EmptyReply;
    // 移除服务器回复中任何尾随的空白字符
    const trimmed = std.mem.trimRight(u8, reply, "\r\n");

    // 使用缓冲写入器将结果显示到标准输出以提高效率
    var stdout_storage: [256]u8 = undefined;
    var stdout_state = std.fs.File.stdout().writer(&stdout_storage);
    const out = &stdout_state.interface;
    try out.writeAll("loopback handshake succeeded\n");
    try out.print("client received: {s}\n", .{trimmed});
    // 确保在程序退出前所有输出可见
    try out.flush();
}
运行
Shell
$ zig run 01_loopback_ping.zig
输出
Shell
loopback handshake succeeded
client received: server observed "ping over loopback"

std.Thread.ResetEvent提供低成本的门闩，用于宣告服务器线程已到达accept，确保客户端连接尝试不会抢先。

显式管理分帧

读取一行需要了解新 reader 接口如何交付字节：takeByte一次产出一个字节并报告error.EndOfStream，我们据此转换为null（无数据）或已完成的切片。该手动分帧促使你思考协议边界而非依赖隐式缓冲读取器，也呼应了 0.15.2 I/O 重设计的意图。

Zig 中的 HTTP 流水线

有了套接字，我们可以更进一步：Zig 标准库提供完全用 Zig 实现的 HTTP 服务器与客户端，使你无需第三方依赖即可提供端点与发起请求。

从回环监听器提供 JSON

下一示例中的服务器线程以std.http.Server包装已接受的流，解析一个请求并输出精简的 JSON。注意我们预渲染响应到固定缓冲区，使request.respond能准确标注内容长度。Writer.zig

使用抓取与解码

配套客户端使用std.http.Client.fetch执行 GET 请求，通过固定 writer 收集正文并使用std.json.parseFromSlice解码为强类型结构。该流程可扩展为跟随重定向、流式大载荷或协商 TLS，具体取决于你的需求。static.zig

Zig
const std = @import("std");

//  传递给 HTTP 服务器线程的参数，使其能够响应单个请求。
const HttpTask = struct {
    server: *std.net.Server,
    ready: *std.Thread.ResetEvent,
};

//  最小化的 HTTP 处理程序：接受一个客户端，用 JSON 文档回复，然后退出。
fn serveJson(task: HttpTask) void {
    // 通知主线程服务器线程已进入接受循环。
    // 这种同步机制防止客户端在服务器准备好之前尝试连接。
    task.ready.set();

    // 阻塞直到客户端连接；优雅地处理连接错误
    const connection = task.server.accept() catch |err| {
        std.debug.print("accept failed: {s}\n", .{@errorName(err)});
        return;
    };
    // 确保此函数退出时连接已关闭
    defer connection.stream.close();

    // 分配用于接收 HTTP 请求和发送 HTTP 响应的缓冲区
    var recv_buffer: [4096]u8 = undefined;
    var send_buffer: [4096]u8 = undefined;
    // 为 TCP 连接创建缓冲读取器和写入器
    var conn_reader = connection.stream.reader(&recv_buffer);
    var conn_writer = connection.stream.writer(&send_buffer);
    // 使用缓冲连接接口初始化 HTTP 服务器状态机
    var server = std.http.Server.init(conn_reader.interface(), &conn_writer.interface);

    // 解析 HTTP 请求头（方法、路径、版本等）
    var request = server.receiveHead() catch |err| {
        std.debug.print("receive head failed: {s}\n", .{@errorName(err)});
        return;
    };

    // 定义 JSON 响应有效负载的形状
    const Body = struct {
        service: []const u8,
        message: []const u8,
        method: []const u8,
        path: []const u8,
        sequence: u32,
    };

    // 构建一个回显请求详细信息给客户端的响应
    const payload = Body{
        .service = "loopback-api",
        .message = "hello from Zig HTTP server",
        .method = @tagName(request.head.method), // 将 HTTP 方法枚举转换为字符串
        .path = request.head.target, // 回显请求的路径
        .sequence = 1,
    };

    // 为 JSON 编码的响应体分配缓冲区
    var json_buffer: [256]u8 = undefined;
    // 创建一个固定大小的写入器，写入我们的缓冲区
    var body_writer = std.Io.Writer.fixed(json_buffer[0..]);
    // 将有效负载结构序列化为 JSON 格式
    std.json.Stringify.value(payload, .{}, &body_writer) catch |err| {
        std.debug.print("json encode failed: {s}\n", .{@errorName(err)});
        return;
    };
    // 获取包含实际写入的 JSON 字节的切片
    const body = std.Io.Writer.buffered(&body_writer);

    // 发送 HTTP 200 响应，包含 JSON 正文和适当的 Content-Type 头
    request.respond(body, .{
        .extra_headers = &.{
            .{ .name = "content-type", .value = "application/json" },
        },
    }) catch |err| {
        std.debug.print("respond failed: {s}\n", .{@errorName(err)});
        return;
    };
}

pub fn main() !void {
    // 初始化分配器以满足动态内存需求（HTTP 客户端需要分配）
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // 在 127.0.0.1 上创建一个回环服务器，使用操作系统分配的端口（端口 0）
    const address = try std.net.Address.parseIp("127.0.0.1", 0);
    var server = try address.listen(.{ .reuse_address = true });
    defer server.deinit();

    // 创建一个同步原语以协调服务器就绪状态
    var ready = std.Thread.ResetEvent{};
    // 启动服务器线程，该线程将接受并处理一个 HTTP 请求
    const server_thread = try std.Thread.spawn(.{}, serveJson, .{HttpTask{
        .server = &server,
        .ready = &ready,
    }});
    // 确保服务器线程在 main() 退出前完成
    defer server_thread.join();

    // 阻塞直到服务器线程发出已到达 accept() 的信号
    // 这可以防止客户端过早尝试连接的竞态条件
    ready.wait();

    // 检索客户端连接的动态分配端口号
    const port = server.listen_address.in.getPort();

    // 使用我们的分配器初始化 HTTP 客户端
    var client = std.http.Client{ .allocator = allocator };
    defer client.deinit();

    // 构造 HTTP 请求的完整 URL
    var url_buffer: [64]u8 = undefined;
    const url = try std.fmt.bufPrint(&url_buffer, "http://127.0.0.1:{d}/stats", .{port});

    // 分配缓冲区以接收 HTTP 响应体
    var response_buffer: [512]u8 = undefined;
    // 创建一个固定大小的写入器，将捕获响应
    var response_writer = std.Io.Writer.fixed(response_buffer[0..]);

    // 执行带有自定义 User-Agent 头部的 HTTP GET 请求
    const fetch_result = try client.fetch(.{
        .location = .{ .url = url },
        .response_writer = &response_writer, // 写入响应体的位置
        .headers = .{
            .user_agent = .{ .override = "zigbook-demo/0.15.2" },
        },
    });

    // 获取包含实际响应体字节的切片
    const body = std.Io.Writer.buffered(&response_writer);

    // 定义 JSON 响应的预期结构
    const ResponseShape = struct {
        service: []const u8,
        message: []const u8,
        method: []const u8,
        path: []const u8,
        sequence: u32,
    };

    // 将 JSON 响应解析为类型化的结构体
    var parsed = try std.json.parseFromSlice(ResponseShape, allocator, body, .{});
    // 释放 JSON 解析期间分配的内存
    defer parsed.deinit();

    // 设置一个缓冲写入器以高效地将结果输出到标准输出
    var stdout_storage: [256]u8 = undefined;
    var stdout_state = std.fs.File.stdout().writer(&stdout_storage);
    const out = &stdout_state.interface;
    // 显示 HTTP 响应状态码
    try out.print("status: {d}\n", .{@intFromEnum(fetch_result.status)});
    // 显示解析后的 JSON 字段
    try out.print("service: {s}\n", .{parsed.value.service});
    try out.print("method: {s}\n", .{parsed.value.method});
    try out.print("path: {s}\n", .{parsed.value.path});
    try out.print("message: {s}\n", .{parsed.value.message});
    // 确保在程序退出前所有输出可见
    try out.flush();
}
运行
Shell
$ zig run 02_http_fetch_and_json.zig
输出
Shell
status: 200
service: loopback-api
method: GET
path: /stats
message: hello from Zig HTTP server

Client.fetch默认保持连接并自动复用池中的套接字。若你提供固定 writer，而缓冲区过小则返回error.WriteFailed。请为预期载荷预留足够容量，或回退为由分配器支撑的 writer。

JSON 工具要点

std.json.Stringify与std.json.parseFromSlice使你在发射或消费 JSON 文本时仍然停留在类型化的 Zig 数据中，前提是注意分配策略。示例中，我们使用std.Io.Writer.fixed构建正文以避免堆活动，并在完成后通过Parsed.deinit()释放解析结果。Stringify.zig

理解 Writer 抽象

HTTP 响应生成与 JSON 序列化都依赖 Zig 的 Writer 接口。下图展示了 writer 抽象及其关键实现：

graph TB WRITER["Writer"] subgraph "Writer Types" FIXED["fixed(buffer)"] ALLOC["Allocating"] DISCARD["Discarding"] end WRITER --> FIXED WRITER --> ALLOC WRITER --> DISCARD subgraph "Write Methods" PRINT["print(fmt, args)"] PRINTVAL["printValue(specifier, options, value, depth)"] PRINTINT["printInt(value, base, case, options)"] WRITEBYTE["writeByte(byte)"] WRITEALL["writeAll(bytes)"] end WRITER --> PRINT WRITER --> PRINTVAL WRITER --> PRINTINT WRITER --> WRITEBYTE WRITER --> WRITEALL

Writer 抽象为输出操作提供统一接口，主要有三种实现策略。固定缓冲 writer（std.Io.Writer.fixed(buffer)）写入预分配缓冲区，当缓冲区满时返回error.WriteFailed——HTTP 示例用它以零堆分配构建响应正文。分配型 writer通过分配器动态增长缓冲，适合无上限输出，如大型 JSON 文档的流式序列化。丢弃型 writer只计字节不存储，适合在真正写入前计算内容长度。写方法在各实现间保持一致：writeAll写原始字节，print做格式化输出，writeByte写单字节，printInt做数值格式化。当你调用std.json.stringify(value, .{}, writer)时，JSON 序列化器并不关心writer是固定、分配还是丢弃——它只调用writeAll，具体细节由 writer 实现处理。这也是本章提到“为预期载荷预留容量或回退为由分配器支撑的 writer”的原因——你在有界固定缓冲（快速、无分配、可能溢出）与动态分配缓冲（灵活、有堆开销、无上限）之间做选择。

注意与警示

  • TCP 回环服务器仍会在accept处阻塞当前线程；面向单线程构建时，必须基于builtin.single_threaded分支以避免 spawn。builtin.zig
  • HTTP 客户端在首次发起 HTTPS 请求时会重新扫描系统信任存储；若你提供自有证书包，请相应切换client.next_https_rescan_certs。
  • 新的 I/O API 暴露原始缓冲，因此在跨请求复用固定 writer 与 reader 之前，请确保其容量足够。

练习

  • Extend the loopback handshake to accept multiple clients by storing handles in a slice and joining them after broadcasting a shutdown message. Thread.zig
  • Add a --head flag to the HTTP example that issues a HEAD request and prints the negotiated headers, inspecting Response.head for metadata.
  • Replace the manual readLine helper with Reader.discardDelimiterLimit to compare behaviour and error handling under the new I/O contracts.

Caveats, alternatives, edge cases

  • Not every Zig target supports sockets; WASI builds, for instance, will fail during Address.listen, so guard availability by inspecting the target OS tag.
  • TLS requests require a certificate bundle; embed one with Client.ca_bundle when running in environments without system stores (CI, containers, early boot environments).
  • std.json.parseFromSlice loads the whole document into memory; for large payloads prefer the streaming std.json.Scanner API to process tokens incrementally. Scanner.zig

Summary

  • std.net and std.Io.Reader give you the raw tools to accept connections, manage framing, and synchronise readiness across threads in a predictable way.
  • std.http.Server and std.http.Client sit naturally atop std.net, providing composable building blocks for REST-style services without external dependencies.
  • std.json rounds out the story by turning on-wire data into typed structs and back, keeping ownership explicit so you can choose between fixed buffers and heap-backed writers.

Help make this chapter better.

Found a typo, rough edge, or missing explanation? Open an issue or propose a small improvement on GitHub.

Open issueView repository