Day 73: std.uri模块：URI解析与构建

1. 引言：统一资源标识符

URI（Uniform Resource Identifier）是用于标识互联网上资源的字符串，我们通常称之为URL（Uniform Resource Locator）。无论是访问网页、调用API端点还是连接数据库，我们都在与URI打交道。

一个URI由多个部分组成，例如协议（scheme）、主机（host）、路径（path）、查询参数（query）和片段（fragment）。手动、正确地解析和构建这些字符串既繁琐又容易出错。Zig的std.uri模块提供了一套健壮的工具来处理这些任务。

2. 解析URI：std.uri.parse

std.uri.parse函数接收一个URI字符串，并返回一个Uri结构体。这个结构体包含了URI的所有组成部分，每个部分都是一个可选的（?[]const u8）切片，直接指向原始输入字符串的相应部分，避免了不必要的内存分配。

const std = @import("std");
const Uri = std.Uri;

pub fn main() !void {
    const uri_string = "https://ziglang.org/documentation/master/?query=string#functions";

    const uri = try Uri.parse(uri_string);

    std.debug.print("Scheme: {?s}\n", . { uri.scheme });
    std.debug.print("Host: {?s}\n", . { uri.host });
    std.debug.print("Path: {?s}\n", . { uri.path });
    std.debug.print("Query: {?s}\n", . { uri.query });
    std.debug.print("Fragment: {?s}\n", . { uri.fragment });
}

输出：

Scheme: https
Host: ziglang.org
Path: /documentation/master/
Query: query=string
Fragment: functions

3. 百分比编码：percentEncode

在URI中，某些字符（如空格、&、=）具有特殊含义，如果它们作为数据出现在路径或查询参数中，就必须进行百分比编码（Percent Encoding），例如将空格编码为%20。

std.uri.percentEncode函数可以为你处理这个过程。

const std = @import("std");

pub fn main() !void {
    var buffer: [100]u8 = undefined;
    const input = "hello world & zig";

    // `percent_sets.query` 定义了在查询字符串中需要编码的字符集
    const encoded = std.uri.percentEncode(buffer[0..], input, .query);

    std.debug.print("Encoded: {s}\n", . { encoded });
    // 输出: Encoded: hello%20world%20&%20zig
}

同样，percentDecode可以执行反向操作。

4. 示例：构建一个带查询参数的HTTP URI

Uri结构体也可以用于构建URI。你可以填充其字段，然后使用uri.serialize()将其转换为字符串。

const std = @import("std");
const Uri = std.Uri;

pub fn main() !void {
    var uri = Uri{
        .scheme = "https",
        .host = "api.example.com",
        .path = "/v1/users",
        .query = "id=123&format=json",
    };

    var buffer: [256]u8 = undefined;
    const uri_string = try uri.serialize(buffer[0..]);

    std.debug.print("Serialized URI: {s}\n", . { uri_string });
}

5. 实践练习：解析查询参数

编写一个函数parseQuery(query: []const u8) !std.StringHashMap([]const u8)，它接收一个查询字符串（如"key1=val1&key2=val2"），并将其解析为一个HashMap。你需要处理&分隔符和=，并对键和值进行百分比解码。

6. 常见问题

• 如何处理国际化域名（IDN）？ std.uri本身不直接处理Punycode（用于在DNS系统中表示Unicode的编码）。你需要使用专门的库来将国际化域名转换为std.uri可以处理的ASCII格式。

• 路径（path）和片段（fragment）的区别是什么？ 路径指向服务器上的一个资源（例如一个HTML文件）。片段（由#引入）则指向该资源内部的一个特定部分（例如HTML文件中的一个锚点）。片段部分通常只由客户端（浏览器）处理，不会发送到服务器。

• RFC 3986 URI的解析和构建遵循一系列复杂的规则，这些规则在RFC 3986中定义。std.uri模块的目标是严格遵守这个规范，以确保与其他系统的互操作性。

7. 总结：与std.path的关系

std.uri专注于处理完整的URI，特别是其与网络相关的部分（协议、主机、端口）。而std.path（我们将在下一节介绍）则更专注于处理文件系统路径的通用操作（如连接路径、获取目录名），它不关心协议或主机。

std.uri是任何进行网络编程的Zig应用程序不可或缺的工具。通过提供一个安全、高效且符合标准的URI处理器，它让你能够自信地与Web进行交互，而不必陷入手动字符串操作的泥潭。