C++23 预期类型（std::expected）：在 C++ 底层链路开发中利用代数数据类型优雅地处理非异常错误流

C++23 预期类型（std::expected）：在 C++ 底层链路开发中利用代数数据类型优雅地处理非异常错误流

在 C++ 的世界里，错误处理一直是一个核心而复杂的话题。特别是在底层链路开发、嵌入式系统、网络协议栈或高性能计算等领域，对错误的处理不仅要求健壮性，还对性能、确定性和资源管理有着严苛的要求。传统的异常机制在这些场景下往往因其运行时开销、非局部跳转以及对资源清理的潜在影响而受到限制。错误码虽然性能开销小，但容易被忽略，且无法很好地传达错误的具体上下文。C++23 引入的 std::expected 类型，正是为了解决这一痛点，它提供了一种基于代数数据类型（ADT）的优雅方案，用于处理那些“非异常”的、预期的错误流。

本次讲座将深入探讨 std::expected 的设计理念、使用方法，并结合底层链路开发的具体场景，展示如何利用它来构建更清晰、更安全、性能更优的 C++ 代码。

一、引言：C++ 低层链路开发中的错误处理挑战

底层链路开发，顾名思义，通常涉及直接与硬件交互、解析原始数据流、实现通信协议等。这类开发环境的特点往往包括：

1. 资源受限： 内存、CPU 周期都可能非常宝贵。
2. 实时性/确定性要求： 许多操作需要在严格的时间窗口内完成，不可预测的延迟是不可接受的。
3. 高可靠性： 错误可能导致系统崩溃或数据损坏，必须得到妥善处理。
4. 复杂的数据格式与协议： 解析、序列化往往是核心任务，其中充满了各种可能失败的条件。

在这样的背景下，错误处理不仅仅是“如何报告错误”，更是“如何高效且安全地处理错误”。

传统的错误处理方法及其局限性：

• 异常（throw/catch）：
  • 优点： 能够将错误处理逻辑与正常业务逻辑分离，通过栈展开自动清理资源。
  • 缺点： 运行时开销相对较高，尤其是在 throw 路径上（涉及栈展开、异常对象构造、查找 handler 等）。在底层或高性能代码中，这种开销可能是无法接受的。异常的非局部跳转特性也使得控制流难以预测，可能与某些实时操作系统的调度策略冲突。此外，异常机制主要用于处理 异常情况，即那些很少发生且无法正常恢复的错误。而底层开发中，许多错误（如数据包校验失败、设备忙）是 预期之内 的情况，应该作为正常控制流的一部分来处理。
• 错误码（int 或 enum 返回值）：
  • 优点： 性能开销极低，控制流明确。
  • 缺点：
    • 易被忽略： 调用方可能忘记检查返回值。
    • 返回值污染： 函数的返回值被错误码占用，实际结果需要通过指针或引用参数返回，导致接口设计复杂。
    • 信息不足： 简单的错误码往往无法提供足够的上下文信息来诊断问题。
    • 样板代码： 大量的 if (error_code != SUCCESS) 检查使得代码冗长且降低可读性。
• std::optional<T> (C++17)：
  • 优点： 明确表示一个值可能存在或不存在，避免了使用 nullptr 或特殊值来表示“无”。
  • 缺点： std::optional 只能表达“有值”或“无值”，但无法表达“无值的原因”。例如，一个解析函数返回 std::optional<Packet>，如果返回空，我们不知道是因为数据不足、校验失败还是格式错误。

这些方法的局限性促使 C++ 社区寻求一种更优雅、更适合处理“非异常错误流”的解决方案。这种方案需要兼具错误码的性能优势和异常的表达能力，同时强制调用方处理错误。代数数据类型（ADT）正是提供这种能力的基础。

二、代数数据类型与错误处理范式

在深入 std::expected 之前，我们有必要理解其背后的数学概念——代数数据类型（Algebraic Data Types, ADTs）。ADTs 是一种强大的数据建模工具，它允许我们通过两种基本构造来定义复杂的数据结构：

1. 积类型（Product Types）： 类似于数学中的笛卡尔积，表示一个值是由多个其他类型的值组合而成的。C++ 中的 struct、class、std::tuple 都是积类型的体现。例如，一个 Point 类型可以由 x 和 y 两个 double 值组成。

   struct Point {
       double x;
       double y;
   }; // Point 是 double 和 double 的积类型

2. 和类型（Sum Types）： 类似于数学中的集合并集，表示一个值可以是多种类型中的 某一种。C++ 中的 std::variant (C++17)、std::optional (C++17) 以及即将到来的 std::expected (C++23) 都是和类型的实现。它们表示一个变量在运行时可能持有不同类型的值。例如，一个 Shape 可以是 Circle 或 Square。

   struct Circle { double radius; };
   struct Square { double side; };
   using Shape = std::variant<Circle, Square>; // Shape 是 Circle 和 Square 的和类型

std::expected<T, E> 作为和类型：

std::expected<T, E> 本质上是一个特殊的和类型，它表示一个操作的结果要么是一个类型为 T 的 成功值，要么是一个类型为 E 的 错误值。这种二元性完美地契合了函数可能成功或失败的场景，并强制程序员在编译期和运行时同时考虑这两种可能性。

它不像 std::variant<T, E> 那样通用，std::expected 专门为“成功或失败”这一特定语义优化，并提供了更符合这种语义的成员函数和操作符。

错误处理的范式演进：

范式	优点	缺点	适用场景
错误码	性能开销低，控制流明确	易被忽略，返回值污染，信息不足，样板代码多	性能极高要求，错误种类少且简单
异常	逻辑分离，自动资源清理，信息丰富	性能开销高，非局部跳转，控制流难预测，不适用于预期错误	真正的异常情况，复杂错误处理，无需实时
std::optional	明确值可能缺失	无法表达缺失原因	值可能不存在，但不存在的原因不重要
std::expected	明确成功/失败，强制处理，信息丰富，性能好	相比 std::optional 略复杂，需要定义错误类型	预期错误，低层链路，高性能，高可靠性

std::expected 旨在结合错误码的低开销和异常的表达能力，成为处理“非异常错误流”的黄金标准。

三、C++23 std::expected 登场

std::expected<T, E> 是 C++23 标准库中引入的一个模板类，用于表示一个可能包含 T 类型值或 E 类型错误的类型。它的设计灵感来源于函数式编程中的 Result 类型，旨在提供一种安全、显式且高效的错误处理机制。

核心概念：

• 一个 std::expected<T, E> 对象在任何时候都只包含 T 类型的值（表示成功）或 E 类型的错误（表示失败），而不能同时包含两者，也不能两者都不包含。
• T 是成功时携带的值的类型。如果操作不需要返回任何值，可以使用 void（即 std::expected<void, E>）。
• E 是失败时携带的错误的类型。它通常是一个枚举（enum class）或一个结构体（struct），用于提供详细的错误信息。E 必须是完整类型且不能是 void。

语法与基本用法：

#include <iostream>
#include <expected> // C++23
#include <string>
#include <vector>
#include <stdexcept> // for std::runtime_error

// 1. 定义错误类型
enum class ParseError {
    InvalidInput,
    TooShort,
    ChecksumMismatch,
    UnknownError
};

// 重载 operator<< 以便打印 ParseError
std::ostream& operator<<(std::ostream& os, ParseError err) {
    switch (err) {
        case ParseError::InvalidInput: return os << "InvalidInput";
        case ParseError::TooShort: return os << "TooShort";
        case ParseError::ChecksumMismatch: return os << "ChecksumMismatch";
        case ParseError::UnknownError: return os << "UnknownError";
    }
    return os << "UnknownError"; // Should not be reached
}

// 假设我们有一个函数，尝试将字符串解析为整数
// 它可能成功返回一个整数，也可能返回一个 ParseError
std::expected<int, ParseError> parse_integer(const std::string& s) {
    if (s.empty()) {
        return std::unexpected(ParseError::InvalidInput);
    }
    try {
        size_t pos;
        int value = std::stoi(s, &pos);
        if (pos != s.length()) {
            return std::unexpected(ParseError::InvalidInput); // 字符串中含有非数字字符
        }
        // 模拟一个校验和错误，例如，如果数字是偶数，我们假设它校验失败
        if (value % 2 == 0) {
            return std::unexpected(ParseError::ChecksumMismatch);
        }
        return value; // 成功时，直接返回 T 类型的值
    } catch (const std::out_of_range& /*oor*/) {
        return std::unexpected(ParseError::InvalidInput); // 数字太大或太小
    } catch (const std::invalid_argument& /*ia*/) {
        return std::unexpected(ParseError::InvalidInput); // 非数字输入
    }
}

void basic_usage_example() {
    std::cout << "--- Basic Usage Example ---" << std::endl;

    // 成功案例
    std::expected<int, ParseError> result1 = parse_integer("123");
    if (result1.has_value()) {
        std::cout << "Parsed '123' successfully: " << result1.value() << std::endl;
        // 或者使用 * 运算符
        std::cout << "Using operator*: " << *result1 << std::endl;
    } else {
        std::cout << "Failed to parse '123': " << result1.error() << std::endl;
    }

    // 失败案例：空字符串
    std::expected<int, ParseError> result2 = parse_integer("");
    if (result2.has_value()) {
        std::cout << "Parsed '' successfully: " << result2.value() << std::endl;
    } else {
        std::cout << "Failed to parse '': " << result2.error() << std::endl;
    }

    // 失败案例：非数字字符
    std::expected<int, ParseError> result3 = parse_integer("abc");
    if (result3.has_value()) {
        std::cout << "Parsed 'abc' successfully: " << result3.value() << std::endl;
    } else {
        std::cout << "Failed to parse 'abc': " << result3.error() << std::endl;
    }

    // 失败案例：校验和失败 (偶数)
    std::expected<int, ParseError> result4 = parse_integer("124");
    if (result4.has_value()) {
        std::cout << "Parsed '124' successfully: " << result4.value() << std::endl;
    } else {
        std::cout << "Failed to parse '124': " << result4.error() << std::endl;
    }

    // `value()` 方法：如果包含错误，会抛出 `std::bad_expected_access` 异常
    std::expected<int, ParseError> result5 = parse_integer("hello");
    try {
        std::cout << "Attempting to get value from failed result: " << result5.value() << std::endl;
    } catch (const std::bad_expected_access<ParseError>& e) {
        std::cout << "Caught expected exception when calling value() on error: " << e.error() << std::endl;
    }

    // `value_or()`：提供一个默认值，避免抛出异常
    int parsed_val = parse_integer("42").value_or(-1); // 42会因为是偶数而失败，返回-1
    std::cout << "Parsed '42' with value_or: " << parsed_val << std::endl;

    parsed_val = parse_integer("43").value_or(-1);
    std::cout << "Parsed '43' with value_or: " << parsed_val << std::endl;
}

关键成员函数和操作符：

| 方法/操作符 | 描述 “`

#include <iostream>
#include <expected> // C++23
#include <string>
#include <vector>
#include <stdexcept> // For std::out_of_range, std::invalid_argument
#include <numeric>   // For std::accumulate (for checksum)

// --- 辅助输出函数，用于打印错误类型 ---
enum class ParseError {
    InvalidInput,
    TooShort,
    ChecksumMismatch,
    UnknownProtocolVersion,
    ConfigurationError,
    DeviceBusy,
    Timeout,
    HardwareFault,
    InvalidCommand,
    BufferOverflow
};

std::ostream& operator<<(std::ostream& os, ParseError err) {
    switch (err) {
        case ParseError::InvalidInput: return os << "ParseError::InvalidInput";
        case ParseError::TooShort: return os << "ParseError::TooShort";
        case ParseError::ChecksumMismatch: return os << "ParseError::ChecksumMismatch";
        case ParseError::UnknownProtocolVersion: return os << "ParseError::UnknownProtocolVersion";
        case ParseError::ConfigurationError: return os << "ParseError::ConfigurationError";
        case ParseError::DeviceBusy: return os << "ParseError::DeviceBusy";
        case ParseError::Timeout: return os << "ParseError::Timeout";
        case ParseError::HardwareFault: return os << "ParseError::HardwareFault";
        case ParseError::InvalidCommand: return os << "ParseError::InvalidCommand";
        case ParseError::BufferOverflow: return os << "ParseError::BufferOverflow";
    }
    return os << "ParseError::Unknown";
}

// ----------------------------------------------------------------------------------------------------
// IV. 在低层链路开发中应用 `std::expected`
// ----------------------------------------------------------------------------------------------------

// 场景一：数据帧解析
// --------------------

// 模拟一个简单的数据帧结构
struct DataFrameHeader {
    uint8_t  protocol_version; // 协议版本
    uint16_t length;           // 数据体长度
    uint16_t checksum;         // 校验和
};

struct DataFrame {
    DataFrameHeader header;
    std::vector<uint8_t> payload;
};

// 解析原始字节数据为 DataFrame
std::expected<DataFrame, ParseError> parse_frame(const std::vector<uint8_t>& raw_data) {
    const size_t MIN_FRAME_SIZE = sizeof(DataFrameHeader);

    if (raw_data.size() < MIN_FRAME_SIZE) {
        return std::unexpected(ParseError::TooShort);
    }

    // 假设是小端序，这里简单地直接映射，实际中需要字节序转换
    const DataFrameHeader* header_ptr = reinterpret_cast<const DataFrameHeader*>(raw_data.data());
    DataFrameHeader header = *header_ptr;

    // 模拟字节序转换 (实际生产代码会使用更健壮的转换函数)
    header.length = (header.length >> 8) | (header.length << 8); // 简单大小端转换
    header.checksum = (header.checksum >> 8) | (header.checksum << 8); // 简单大小端转换

    if (header.protocol_version != 0x01) { // 假设只支持协议版本 0x01
        return std::unexpected(ParseError::UnknownProtocolVersion);
    }

    if (raw_data.size() < MIN_FRAME_SIZE + header.length) {
        return std::unexpected(ParseError::TooShort); // 数据体长度不足
    }

    // 计算实际校验和 (这里只是一个简单的求和校验，实际会更复杂)
    uint16_t calculated_checksum = 0;
    for (size_t i = 0; i < MIN_FRAME_SIZE - sizeof(uint16_t); ++i) { // 头部除校验和部分
        calculated_checksum += raw_data[i];
    }
    for (size_t i = MIN_FRAME_SIZE; i < MIN_FRAME_SIZE + header.length; ++i) { // 数据体部分
        calculated_checksum += raw_data[i];
    }

    if (calculated_checksum != header.checksum) {
        // 实际场景中，CRC-CCITT、CRC32 等更复杂的校验算法更常见
        return std::unexpected(ParseError::ChecksumMismatch);
    }

    DataFrame frame;
    frame.header = header;
    frame.payload.assign(raw_data.begin() + MIN_FRAME_SIZE,
                         raw_data.begin() + MIN_FRAME_SIZE + header.length);
    return frame;
}

void frame_parsing_example() {
    std::cout << "n--- Data Frame Parsing Example ---" << std::endl;

    // 示例数据：
    // Version: 0x01
    // Length: 0x0002 (2 bytes payload)
    // Checksum: (0x01 + 0x00 + 0x02 + 0x03 + 0x04) = 0x0A (little-endian: 0x0A00)
    // Payload: 0x03, 0x04
    std::vector<uint8_t> valid_data = {
        0x01, // protocol_version
        0x02, 0x00, // length (little-endian 0x0002)
        0x0A, 0x00, // checksum (little-endian 0x000A)
        0x03, 0x04  // payload
    };

    auto frame_result = parse_frame(valid_data);
    if (frame_result.has_value()) {
        const auto& frame = frame_result.value();
        std::cout << "Successfully parsed frame:" << std::endl;
        std::cout << "  Version: " << static_cast<int>(frame.header.protocol_version) << std::endl;
        std::cout << "  Length: " << frame.header.length << std::endl;
        std::cout << "  Checksum: " << frame.header.checksum << std::endl;
        std::cout << "  Payload: ";
        for (uint8_t byte : frame.payload) {
            std::cout << std::hex << static_cast<int>(byte) << " ";
        }
        std::cout << std::dec << std::endl;
    } else {
        std::cout << "Failed to parse frame: " << frame_result.error() << std::endl;
    }

    // 错误示例：数据过短
    std::vector<uint8_t> short_data = {0x01, 0x02, 0x00};
    frame_result = parse_frame(short_data);
    if (!frame_result.has_value()) {
        std::cout << "Failed to parse short data: " << frame_result.error() << std::endl;
    }

    // 错误示例：校验和不匹配
    std::vector<uint8_t> bad_checksum_data = {
        0x01, 0x02, 0x00, // header
        0xFF, 0x00, // wrong checksum
        0x03, 0x04  // payload
    };
    frame_result = parse_frame(bad_checksum_data);
    if (!frame_result.has_value()) {
        std::cout << "Failed to parse bad checksum data: " << frame_result.error() << std::endl;
    }

    // 错误示例：未知协议版本
    std::vector<uint8_t> unknown_version_data = {
        0x02, // protocol_version (unknown)
        0x02, 0x00,
        0x0A, 0x00,
        0x03, 0x04
    };
    frame_result = parse_frame(unknown_version_data);
    if (!frame_result.has_value()) {
        std::cout << "Failed to parse unknown version data: " << frame_result.error() << std::endl;
    }
}

// 场景二：设备通信命令
// ------------------------

// 模拟设备命令和响应
enum class CommandType {
    READ_STATUS,
    WRITE_CONFIG,
    REBOOT
};

struct Command {
    CommandType type;
    std::vector<uint8_t> payload; // 命令参数
};

struct Response {
    uint8_t status_code; // 设备返回的状态码
    std::vector<uint8_t> data; // 响应数据
};

// 模拟设备接口
class DeviceDriver {
public:
    DeviceDriver(bool is_initialized = true) : initialized_(is_initialized), busy_(false) {}

    // 模拟发送命令并接收响应
    std::expected<Response, ParseError> send_command(const Command& cmd) {
        if (!initialized_) {
            return std::unexpected(ParseError::ConfigurationError); // 设备未初始化
        }
        if (busy_) {
            return std::unexpected(ParseError::DeviceBusy); // 设备忙
        }

        // 模拟通信延迟和结果
        busy_ = true;
        // std::this_thread::sleep_for(std::chrono::milliseconds(50)); // 实际中会有延迟

        std::expected<Response, ParseError> result;
        switch (cmd.type) {
            case CommandType::READ_STATUS: {
                if (cmd.payload.empty()) { // 假设读取状态不需要payload
                    result = Response{0x00, {0x01, 0x02, 0x03}}; // 成功，返回一些状态数据
                } else {
                    result = std::unexpected(ParseError::InvalidCommand);
                }
                break;
            }
            case CommandType::WRITE_CONFIG: {
                if (cmd.payload.size() == 4) { // 假设写入配置需要4字节
                    result = Response{0x00, {}}; // 成功
                } else {
                    result = std::unexpected(ParseError::InvalidCommand);
                }
                break;
            }
            case CommandType::REBOOT: {
                // 模拟一个随机的重启失败
                if (rand() % 10 < 3) { // 30% 几率重启失败
                    result = std::unexpected(ParseError::HardwareFault);
                } else {
                    result = Response{0x00, {}}; // 成功
                }
                break;
            }
            default:
                result = std::unexpected(ParseError::InvalidCommand);
                break;
        }
        busy_ = false;
        return result;
    }

private:
    bool initialized_;
    bool busy_;
};

void device_command_example() {
    std::cout << "n--- Device Communication Commands Example ---" << std::endl;

    DeviceDriver driver(true); // 已初始化设备
    DeviceDriver uninitialized_driver(false); // 未初始化设备

    // 尝试向未初始化设备发送命令
    auto uninit_res = uninitialized_driver.send_command({CommandType::READ_STATUS, {}});
    if (!uninit_res.has_value()) {
        std::cout << "Uninitialized driver error: " << uninit_res.error() << std::endl;
    }

    // 成功读取状态
    auto read_status_res = driver.send_command({CommandType::READ_STATUS, {}});
    if (read_status_res.has_value()) {
        std::cout << "Read status successful. Status code: "
                  << static_cast<int>(read_status_res->status_code)
                  << ", Data size: " << read_status_res->data.size() << std::endl;
    } else {
        std::cout << "Read status failed: " << read_status_res.error() << std::endl;
    }

    // 写入配置 (成功)
    auto write_config_res = driver.send_command({CommandType::WRITE_CONFIG, {0x01, 0x02, 0x03, 0x04}});
    if (write_config_res.has_value()) {
        std::cout << "Write config successful. Status code: "
                  << static_cast<int>(write_config_res->status_code) << std::endl;
    } else {
        std::cout << "Write config failed: " << write_config_res.error() << std::endl;
    }

    // 写入配置 (参数错误)
    write_config_res = driver.send_command({CommandType::WRITE_CONFIG, {0x01, 0x02}});
    if (!write_config_res.has_value()) {
        std::cout << "Write config with invalid payload failed: " << write_config_res.error() << std::endl;
    }

    // 模拟设备忙
    // (需要多线程或异步操作来真正模拟，这里简化为连续调用)
    // driver.busy_ = true; // 假设设备在外部被设置为忙
    // auto busy_res = driver.send_command({CommandType::READ_STATUS, {}});
    // if (!busy_res.has_value()) {
    //     std::cout << "Device busy test: " << busy_res.error() << std::endl;
    // }
    // driver.busy_ = false;

    // 重启设备 (可能失败)
    for (int i = 0; i < 5; ++i) {
        auto reboot_res = driver.send_command({CommandType::REBOOT, {}});
        if (reboot_res.has_value()) {
            std::cout << "Reboot attempt " << i + 1 << ": Successful." << std::endl;
        } else {
            std::cout << "Reboot attempt " << i + 1 << ": Failed with error: " << reboot_res.error() << std::endl;
        }
    }
}

// 场景三：网络协议栈处理 (简化版 IP 包头解析)
// ---------------------------------------------

struct IPv4Header {
    uint8_t version_ihl;    // Version (4 bits) + IHL (4 bits)
    uint8_t tos;            // Type of Service
    uint16_t total_length;  // Total Length
    uint16_t id;            // Identification
    uint16_t frag_offset;   // Flags (3 bits) + Fragment Offset (13 bits)
    uint8_t ttl;            // Time to Live
    uint8_t protocol;       // Protocol
    uint16_t checksum;      // Header Checksum
    uint32_t src_ip;        // Source IP Address
    uint32_t dst_ip;        // Destination IP Address
};

struct IPPacket {
    IPv4Header header;
    std::vector<uint8_t> payload;
};

// 模拟计算 IP 头校验和 (简化版，实际为RFC 791定义的Internet Checksum)
uint16_t calculate_ip_checksum(const uint8_t* data, size_t len) {
    uint32_t sum = 0;
    const uint16_t* ptr = reinterpret_cast<const uint16_t*>(data);
    while (len > 1) {
        sum += *ptr++;
        len -= 2;
    }
    if (len == 1) {
        sum += *reinterpret_cast<const uint8_t*>(ptr);
    }
    while (sum >> 16) {
        sum = (sum & 0xFFFF) + (sum >> 16);
    }
    return static_cast<uint16_t>(~sum);
}

std::expected<IPPacket, ParseError> process_ip_packet(const std::vector<uint8_t>& packet_data) {
    if (packet_data.size() < sizeof(IPv4Header)) {
        return std::unexpected(ParseError::TooShort);
    }

    const IPv4Header* header_ptr = reinterpret_cast<const IPv4Header*>(packet_data.data());
    IPv4Header header = *header_ptr;

    // 模拟字节序转换 (实际需要 ntohs/ntohl)
    header.total_length = (header.total_length >> 8) | (header.total_length << 8);
    header.id = (header.id >> 8) | (header.id << 8);
    header.frag_offset = (header.frag_offset >> 8) | (header.frag_offset << 8);
    header.checksum = (header.checksum >> 8) | (header.checksum << 8);
    header.src_ip = (header.src_ip >> 24) | ((header.src_ip << 8) & 0x00FF0000) | ((header.src_ip >> 8) & 0x0000FF00) | (header.src_ip << 24);
    header.dst_ip = (header.dst_ip >> 24) | ((header.dst_ip << 8) & 0x00FF0000) | ((header.dst_ip >> 8) & 0x0000FF00) | (header.dst_ip << 24);

    uint8_t version = (header.version_ihl >> 4) & 0x0F;
    uint8_t ihl = header.version_ihl & 0x0F; // Internet Header Length in 4-byte words
    size_t header_length_bytes = ihl * 4;

    if (version != 4) { // 只处理 IPv4
        return std::unexpected(ParseError::UnknownProtocolVersion);
    }
    if (header_length_bytes < sizeof(IPv4Header)) { // IHL 至少为 5 (20字节)
        return std::unexpected(ParseError::InvalidInput); // IHL过小
    }
    if (packet_data.size() < header_length_bytes) {
        return std::unexpected(ParseError::TooShort); // 实际数据不足以包含整个头部
    }
    if (header.total_length > packet_data.size()) {
        return std::unexpected(ParseError::TooShort); // 声明的总长度大于实际接收到的数据
    }

    // 校验和验证 (跳过校验和字段本身进行计算)
    std::vector<uint8_t> header_for_checksum_calc(packet_data.begin(), packet_data.begin() + header_length_bytes);
    // 临时将校验和字段清零，以便计算
    *reinterpret_cast<uint16_t*>(&header_for_checksum_calc[offsetof(IPv4Header, checksum)]) = 0;
    uint16_t calculated_checksum = calculate_ip_checksum(header_for_checksum_calc.data(), header_length_bytes);

    if (calculated_checksum != header.checksum) {
        return std::unexpected(ParseError::ChecksumMismatch);
    }

    IPPacket ip_packet;
    ip_packet.header = header;
    ip_packet.payload.assign(packet_data.begin() + header_length_bytes,
                             packet_data.begin() + header.total_length); // payload根据total_length截取

    return ip_packet;
}

// 辅助函数：将IP地址从uint32_t转换为点分十进制字符串
std::string ip_to_string(uint32_t ip) {
    return std::to_string((ip >> 24) & 0xFF) + "." +
           std::to_string((ip >> 16) & 0xFF) + "." +
           std::to_string((ip >> 8) & 0xFF) + "." +
           std::to_string(ip & 0xFF);
}

void network_protocol_example() {
    std::cout << "n--- Network Protocol Stack Processing Example (IP) ---" << std::endl;

    // 模拟一个简单有效的 IPv4 包 (20字节头 + 4字节 payload)
    // Version=4, IHL=5 (20 bytes), Total Length=24, Protocol=6 (TCP), Src IP=127.0.0.1, Dst IP=127.0.0.1
    // Checksum will be calculated by the test data
    std::vector<uint8_t> valid_ip_packet_data = {
        0x45, 0x00, // Version=4, IHL=5, TOS=0
        0x00, 0x18, // Total Length=24 (0x0018)
        0x12, 0x34, // ID=0x1234
        0x00, 0x00, // Flags=0, Fragment Offset=0
        0x40,       // TTL=64
        0x06,       // Protocol=6 (TCP)
        0x00, 0x00, // Header Checksum (placeholder, will be calculated)
        0x7F, 0x00, 0x00, 0x01, // Source IP: 127.0.0.1
        0x7F, 0x00, 0x00, 0x01, // Destination IP: 127.0.0.1
        // Payload (4 bytes)
        0xDE, 0xAD, 0xBE, 0xEF
    };

    // 计算并插入正确的校验和 (模拟发送方行为)
    std::vector<uint8_t> header_for_checksum_calc(valid_ip_packet_data.begin(), valid_ip_packet_data.begin() + 20);
    *reinterpret_cast<uint16_t*>(&header_for_checksum_calc[10]) = 0; // Clear checksum field
    uint16_t correct_checksum = calculate_ip_checksum(header_for_checksum_calc.data(), 20);
    valid_ip_packet_data[10] = (correct_checksum >> 8) & 0xFF; // MSB
    valid_ip_packet_data[11] = correct_checksum & 0xFF;       // LSB

    auto ip_packet_result = process_ip_packet(valid_ip_packet_data);

    if (ip_packet_result.has_value()) {
        const auto& packet = ip_packet_result.value();
        std::cout << "Successfully parsed IP Packet:" << std::endl;
        std::cout << "  Version: " << static_cast<int>((packet.header.version_ihl >> 4) & 0x0F) << std::endl;
        std::cout << "  IHL: " << static_cast<int>(packet.header.version_ihl & 0x0F) * 4 << " bytes" << std::endl;
        std::cout << "  Total Length: " << packet.header.total_length << " bytes" << std::endl;
        std::cout << "  Protocol: " << static_cast<int>(packet.header.protocol) << std::endl;
        std::cout << "  Source IP: " << ip_to_string(packet.header.src_ip) << std::endl;
        std::cout << "  Destination IP: " << ip_to_string(packet.header.dst_ip) << std::endl;
        std::cout << "  Payload size: " << packet.payload.size() << " bytes" << std::endl;
    } else {
        std::cout << "Failed to process IP packet: " << ip_packet_result.error() << std::endl;
    }

    // 错误示例：数据过短
    std::vector<uint8_t> short_ip_packet = {0x45, 0x00, 0x00, 0x18, 0x12, 0x34, 0x00, 0x00, 0x40, 0x06}; // 只有10字节
    ip_packet_result = process_ip_packet(short_ip_packet);
    if (!ip_packet_result.has_value()) {
        std::cout << "Failed to process short IP packet: " << ip_packet_result.error() << std::endl;
    }

    // 错误示例：校验和不匹配
    std::vector<uint8_t> bad_checksum_ip_packet = valid_ip_packet_data;
    bad_checksum_ip_packet[10] = 0xFF; // 故意修改校验和
    ip_packet_result = process_ip_packet(bad_checksum_ip_packet);
    if (!ip_packet_result.has_value()) {
        std::cout << "Failed to process IP packet with bad checksum: " << ip_packet_result.error() << std::endl;
    }

    // 错误示例：非IPv4版本
    std::vector<uint8_t> ipv6_packet = valid_ip_packet_data;
    ipv6_packet[0] = 0x60; // Version 6
    ip_packet_result = process_ip_packet(ipv6_packet);
    if (!ip_packet_result.has_value()) {
        std::cout << "Failed to process IPv6 packet (expected IPv4): " << ip_packet_result.error() << std::endl;
    }
}

// 场景四：资源管理与初始化
// ----------------------------

// 模拟硬件句柄
class HardwareHandle {
public:
    explicit HardwareHandle(int id) : id_(id) {
        std::cout << "Hardware ID " << id_ << " acquired." << std::endl;
    }
    ~HardwareHandle() {
        std::cout << "Hardware ID " << id_ << " released." << std::endl;
    }
    void do_work() const {
        std::cout << "Hardware ID " << id_ << " is working." << std::endl;
    }
private:
    int id_;
};

// 模拟硬件初始化函数
std::expected<HardwareHandle, ParseError> initialize_hardware(int device_id, bool simulate_failure = false) {
    if (simulate_failure) {
        if (device_id == 100) {
            return std::unexpected(ParseError::HardwareFault); // 模拟特定设备故障
        } else if (device_id == 200) {
            return std::unexpected(ParseError::ConfigurationError); // 模拟配置错误
        }
    }
    // 假设初始化成功
    return HardwareHandle(device_id); // 返回一个值，会调用HardwareHandle的构造函数
}

void resource_management_example() {
    std::cout << "n--- Resource Management and Initialization Example ---" << std::endl;

    // 成功初始化
    auto handle1_result = initialize_hardware(1);
    if (handle1_result.has_value()) {
        handle1_result->do_work(); // 使用 -> 运算符访问内部值
    } else {
        std::cout << "Failed to initialize hardware 1: " << handle1_result.error() << std::endl;
    }
    // handle1_result 超出作用域，HardwareHandle 会被析构

    std::cout << "---" << std::endl;

    // 模拟硬件故障
    auto handle2_result = initialize_hardware(100, true);
    if (handle2_result.has_value()) {
        handle2_result->do_work();
    } else {
        std::cout << "Failed to initialize hardware 100: " << handle2_result.error() << std::endl;
    }
    // handle2_result 包含错误，没有 HardwareHandle 对象被创建和管理

    std::cout << "---" << std::endl;

    // 模拟配置错误
    auto handle3_result = initialize_hardware(200, true);
    if (handle3_result.has_value()) {
        handle3_result->do_work();
    } else {
        std::cout << "Failed to initialize hardware 200: " << handle3_result.error() << std::endl;
    }
}

// ----------------------------------------------------------------------------------------------------
// V. `std::expected` 的高级用法与模式
// ----------------------------------------------------------------------------------------------------

// 链式操作与 Monadic 风格
// ---------------------------

// 假设我们有多个步骤，每个步骤都可能失败
std::expected<int, ParseError> step1_read_raw_value(const std::string& input) {
    if (input.length() < 2) return std::unexpected(ParseError::TooShort);
    try {
        return std::stoi(input.substr(0, 2)); // 读取前两位
    } catch (...) {
        return std::unexpected(ParseError::InvalidInput);
    }
}

std::expected<double, ParseError> step2_validate_and_convert(int raw_value) {
    if (raw_value < 10 || raw_value > 99) { // 假设范围是 10-99
        return std::unexpected(ParseError::InvalidInput);
    }
    return static_cast<double>(raw_value) / 10.0; // 转换为浮点数
}

std::expected<std::string, ParseError> step3_format_result(double processed_value) {
    if (processed_value < 0) { // 假设结果不能是负数
        return std::unexpected(ParseError::InvalidInput);
    }
    return "Processed: " + std::to_string(processed_value);
}

void monadic_chaining_example() {
    std::cout << "n--- Monadic Chaining Example ---" << std::endl;

    // 成功链
    auto final_result_success = step1_read_raw_value("42abcd")
        .and_then(step2_validate_and_convert)
        .and_then(step3_format_result);

    if (final_result_success.has_value()) {
        std::cout << "Chained success: " << final_result_success.value() << std::endl;
    } else {
        std::cout << "Chained failure: " << final_result_success.error() << std::endl;
    }

    // 失败链 (step1 失败)
    auto final_result_fail1 = step1_read_raw_value("a") // TooShort
        .and_then(step2_validate_and_convert)
        .and_then(step3_format_result);

    if (final_result_fail1.has_value()) {
        std::cout << "Chained success: " << final_result_fail1.value() << std::endl;
    } else {
        std::cout << "Chained failure (step1): " << final_result_fail1.error() << std::endl;
    }

    // 失败链 (step2 失败)
    auto final_result_fail2 = step1_read_raw_value("05efgh") // InvalidInput (value < 10)
        .and_then(step2_validate_and_convert)
        .and_then(step3_format_result);

    if (final_result_fail2.has_value()) {
        std::cout << "Chained success: " << final_result_fail2.value() << std::endl;
    } else {
        std::cout << "Chained failure (step2): " << final_result_fail2.error() << std::endl;
    }

    // `transform` 和 `transform_error`
    auto transformed_result = step1_read_raw_value("30")
        .transform([](int val) { return val * 2; }) // 成功时，将 30 转换为 60
        .transform_error([](ParseError err) { // 失败时，将错误转换为更通用的 std::string
            return "Error occurred: " + std::string(std::to_string(static_cast<int>(err)));
        });

    if (transformed_result.has_value()) {
        std::cout << "Transformed value: " << transformed_result.value() << std::endl;
    } else {
        std::cout << "Transformed error: " << transformed_result.error() << std::endl;
    }

    auto transformed_error_result = step1_read_raw_value("X")
        .transform([](int val) { return val * 2; })
        .transform_error([](ParseError err) {
            return "Error occurred: " + std::string(std::to_string(static_cast<int>(err)));
        });
    if (transformed_error_result.has_value()) {
        std::cout << "Transformed value: " << transformed_error_result.value() << std::endl;
    } else {
        std::cout << "Transformed error: " << transformed_error_result.error() << std::endl;
    }
}

// 错误类型细化与聚合
// --------------------
#include <variant>

// 更细致的错误结构体
struct DetailedParseError {
    ParseError code;
    std::string context;
    int line_number = -1; // 例如，在文件解析中
};

std::ostream& operator<<(std::ostream& os, const DetailedParseError& err) {
    return os << "DetailedParseError: " << err.code << " at line " << err.line_number << ", Context: " << err.context;
}

std::expected<int, DetailedParseError> parse_complex_data(const std::string& data, int line = 0) {
    if (data.length() < 5) {
        return std::unexpected(DetailedParseError{ParseError::TooShort, "Data too short for header", line});
    }
    if (data.substr(0, 2) != "0x") {
        return std::unexpected(DetailedParseError{ParseError::InvalidInput, "Missing '0x' prefix", line});
    }
    try {
        return std::stoi(data.substr(2), nullptr, 16);
    } catch (const std::exception& e) {
        return std::unexpected(DetailedParseError{ParseError::InvalidInput, "Invalid hex format: " + std::string(e.what()), line});
    }
}

void detailed_error_example() {
    std::cout << "n--- Detailed Error Type Example ---" << std::endl;

    auto res1 = parse_complex_data("0xAF", 10);
    if (res1.has_value()) {
        std::cout << "Parsed '0xAF' successfully: " << res1.value() << std::endl;
    } else {
        std::cout << "Failed to parse '0xAF': " << res1.error() << std::endl;
    }

    auto res2 = parse_complex_data("AF", 20); // Missing 0x
    if (!res2.has_value()) {
        std::cout << "Failed to parse 'AF': " << res2.error() << std::endl;
    }

    auto res3 = parse_complex_data("0xGZ", 30); // Invalid hex
    if (!res3.has_value()) {
        std::cout << "Failed to parse '0xGZ': " << res3.error() << std::endl;
    }
}

// `std::expected<void, E>` 示例
std::expected<void, ParseError> perform_action(bool succeed) {
    if (succeed) {
        std::cout << "Action performed successfully." << std::endl;
        return {}; // Return an empty std::expected<void, E> to indicate success
    } else {
        std::cout << "Action failed." << std::endl;
        return std::unexpected(ParseError::DeviceBusy);
    }
}

void expected_void_example() {
    std::cout << "n--- std::expected<void, E> Example ---" << std::endl;

    auto result_void1 = perform_action(true);
    if (result_void1.has_value()) {
        std::cout << "Void action success handler." << std::endl;
    } else {
        std::cout << "Void action failed handler: " << result_void1.error() << std::endl;
    }

    auto result_void2 = perform_action(false);
    if (result_void2.has_value()) {
        std::cout << "Void action success handler." << std::endl;
    } else {
        std::cout << "Void action failed handler: " << result_void2.error() << std::endl;
    }
}

// --- Main function to run all examples ---
int main() {
    std::srand(static_cast<unsigned int>(std::time(nullptr)));

    basic_usage_example();
    frame_parsing_example();
    device_command_example();
    network_protocol_example();
    resource_management_example();
    monadic_chaining_example();
    detailed_error_example();
    expected_void_example();

    return 0;
}

四、在低层链路开发中应用 std::expected

std::expected 在底层链路开发中尤为适用，因为它能够以零开销或接近零开销的方式，清晰地表达操作的成功或失败，并携带具体的错误信息。这使得开发者能够编写出既高性能又安全的代码。

场景一：数据帧解析

在网络通信或串行通信中，数据通常以帧（Frame）的形式传输。解析这些原始字节流是底层开发的核心任务。一个解析函数可能会遇到多种错误：数据长度不足、协议版本不匹配、CRC 校验失败、字段值无效等。

parse_frame(const std::vector<uint8_t>& raw_data) -> std::expected<DataFrame, ParseError>

上述代码中的 parse_frame 函数展示了如何利用 std::expected 来处理这些情况。DataFrame 包含了成功解析后的数据，而 ParseError 枚举则详细说明了解析失败的原因。

优点：

• 强制错误处理： 调用 parse_frame 的代码必须检查 std::expected 的状态，确保不会遗漏错误。
• 错误信息丰富： ParseError 枚举提供了比简单布尔值或通用错误码更具体的失败原因。
• 性能： std::expected 通常是栈分配的，没有动态内存分配，也没有异常处理的栈展开开销。

场景二：设备通信命令

与硬件设备通信是底层开发的另一个常见任务。例如，发送一个命令到传感器并接收其响应。命令的发送和响应的接收都可能失败：设备无响应、超时、设备返回错误状态码、协议版本不匹配等。

send_command(CommandType cmd, const Payload& p) -> std::expected<Response, DeviceError>

在 DeviceDriver 示例中，send_command 方法返回 std::expected<Response, ParseError>。Response 包含设备成功响应的数据和状态码，而 ParseError 则涵盖了通信层面和设备内部可能发生的错误。

优点：

• 清晰的接口： 函数签名清晰地表明了它可能返回成功响应或一个错误。
• 状态管理： 设备驱动可以根据 std::expected 返回的错误类型，采取不同的恢复策略（例如，DeviceBusy 可以重试，HardwareFault 可能需要更高级别的干预）。
• 避免全局状态： 不依赖于 errno 等全局变量，使得代码更具线程安全性和可重入性。

场景三：网络协议栈处理

构建或处理网络协议栈是典型的底层任务。例如，解析一个 IP 数据包。这涉及到对字节流的精确解析、校验和计算和验证、字段合法性检查等。

process_ip_packet(const std::vector<uint8_t>& packet_data) -> std::expected<IPPacket, NetworkError>

process_ip_packet 示例展示了 IPv4 包头的解析。在解析过程中，它检查了数据包长度、IP 版本、IHL 字段、总长度以及最重要的校验和。任何一步的失败都会导致返回一个带有具体 ParseError 的 std::unexpected 对象。

优点：

• 协议健壮性： 在解析的每一步都强制进行错误检查，确保即使面对恶意或损坏的数据包也能安全处理。
• 诊断能力： 不同的 ParseError 值可以帮助网络工程师快速定位问题，例如是数据包损坏 (ChecksumMismatch) 还是格式错误 (InvalidInput)。
• 流水线处理： 可以结合 and_then 等链式操作，构建复杂的多层协议解析流水线。

场景四：资源管理与初始化

在底层系统中，初始化硬件、分配特定内存区域或获取独占资源是常见的操作，这些操作也可能失败（例如，硬件不存在、驱动程序加载失败、权限不足、资源已被占用）。

initialize_hardware() -> std::expected<HardwareHandle, InitError>

initialize_hardware 函数返回 std::expected<HardwareHandle, ParseError>。成功时，它返回一个 HardwareHandle 对象，这个对象通过 RAII 机制管理硬件资源的生命周期。失败时，它返回一个 ParseError，指出初始化失败的原因。

优点：

• RAII 兼容： std::expected 完美支持 RAII。当 std::expected 包含一个 T 类型的值时，T 对象的生命周期由 std::expected 管理。如果 std::expected 包含错误，T 对象根本不会被构造，从而避免了资源泄露或无效资源句柄的问题。
• 明确的初始化结果： 调用方清晰地知道初始化是成功获得了句柄还是失败并得到了错误信息。
• 避免裸指针/特殊值： 无需使用 nullptr 或其他特殊值来表示初始化失败，接口更清晰。

五、std::expected 的高级用法与模式

1. 链式操作与 Monadic 风格

std::expected 提供了类似于 std::optional 的 monadic 操作，这使得处理一系列可能失败的操作变得非常优雅和函数式。

• and_then(F f)： 如果 *this 包含一个值，则调用 f，并将 f 的结果包装在新的 std::expected 中返回。如果 *this 包含错误，则短路并直接返回该错误。这对于将多个可能失败的操作串联起来非常有用。
• transform(F f)： 如果 *this 包含一个值，则调用 f 并将 f 的结果（转换为新的成功值类型）包装在新的 std::expected 中返回。如果 *this 包含错误，则短路并直接返回该错误。transform 用于转换成功值。
• or_else(F f)： 如果 *this 包含一个错误，则调用 f，并将 f 的结果（转换为新的 std::expected 类型）包装在新的 std::expected 中返回。如果 *this 包含一个值，则短路并直接返回该值。or_else 用于错误恢复或处理。
• transform_error(F f)： 如果 *this 包含一个错误，则调用 f 并将 f 的结果（转换为新的错误类型）包装在新的 std::expected 中返回。如果 *this 包含一个值，则短路并直接返回该值。transform_error 用于转换错误类型。

上述 monadic_chaining_example 演示了如何将 step1_read_raw_value、step2_validate_and_convert 和 step3_format_result 这三个可能失败的步骤通过 and_then 串联起来，形成一个清晰的数据处理流水线。任何一步失败，整个链条都会短路，并返回第一个遇到的错误。

这种风格极大地减少了嵌套的 if-else 语句，提高了代码的可读性和维护性。

2. 错误类型细化与聚合

std::expected 的错误类型 E 可以是任意非 void 类型。为了提供更丰富的错误信息，我们可以：

• 使用 enum class： 提供离散的错误代码，简单高效。
• 使用 struct： 包含错误代码、错误消息字符串、源文件/行号、时间戳等上下文信息，便于调试。

• 使用 std::variant<E1, E2, ...>： 当一个函数可能返回多种不同类型的错误时，可以使用 std::variant 将它们聚合起来。例如，一个网络操作可能返回 NetworkError 或 ProtocolError。

  // 假设有更底层的错误类型
  enum class NetworkLayerError { Timeout, ConnectionLost };
  enum class ApplicationLayerError { InvalidRequest, InternalServerError };
  
  using MyAggregatedError = std::variant<NetworkLayerError, ApplicationLayerError>;
  
  std::expected<Response, MyAggregatedError> send_request_and_process_response() {
      // ...
      if (/* network error */) {
          return std::unexpected(NetworkLayerError::Timeout);
      }
      if (/* app error */) {
          return std::unexpected(ApplicationLayerError::InvalidRequest);
      }
      return Response{};
  }

  在处理时，可以使用 std::visit 来优雅地处理不同类型的错误。

3. 与现有错误处理机制的结合

• 何时仍使用异常？ 对于真正的 异常情况（即程序无法从根本上恢复的错误，如内存耗尽 std::bad_alloc，严重的逻辑错误 std::logic_error），异常仍然是合适的选择。std::expected 用于处理 预期之内 的、可恢复的或需要明确处理的错误。

• 包装传统错误码： 可以将老的 C 风格 API 返回的错误码包装进 std::expected，从而在 C++ 新代码中获得 std::expected 的所有优势。

  // 假设一个旧的C API
  int legacy_read_sensor(int* out_value); // 返回 0 成功，-1 失败
  
  std::expected<int, int> read_sensor_modern() {
      int value;
      if (legacy_read_sensor(&value) == 0) {
          return value;
      } else {
          return std::unexpected(-1); // 包装为错误码 -1
      }
  }

4. 性能考量

std::expected 的设计目标之一就是高性能。

• 零开销抽象： 在大多数情况下，std::expected<T, E> 的大小与 std::variant<T, E> 相似，通常是 sizeof(T) 和 sizeof(E) 中较大的一个，再加上一个 bool 标志位。它通常是栈分配的，没有动态内存分配，因此没有堆分配的开销。
• 无异常开销： 与异常机制相比，std::expected 避免了栈展开、异常对象构造和异常处理表查找的开销。在错误路径是常见情况的场景中，这能带来显著的性能提升。
• 分支预测： has_value() 检查会引入分支。在错误非常罕见（即分支预测器总是预测 has_value() 为真）的情况下，性能影响很小。如果错误路径频繁，可能会导致分支预测失败，但其开销仍远低于异常。

5. 与 std::optional 的协同

std::expected 和 std::optional 都是和类型，但用途不同：

• std::optional<T>：表示“可能存在一个 T 类型的值，或者没有值”。它不提供“为什么没有值”的信息。
• std::expected<T, E>：表示“有一个 T 类型的值，或者有一个 E 类型的错误”。它明确提供错误原因。

选择哪一个取决于语义：

• 如果一个函数的结果是“要么是一个值，要么没有值，但没有值的原因并不重要或由上下文隐含”，则使用 std::optional。
• 如果一个函数的结果是“要么是一个值，要么是一个明确的错误原因”，则使用 std::expected。

它们也可以组合使用，例如 std::expected<std::optional<T>, E> 表示“操作成功，但结果可能为空”或“操作失败并有错误”。

六、实践中的考量与最佳实践

1. 错误类型设计：

   • 明确性： 错误类型 E 应该清晰地表达失败的原因。使用 enum class 提供具体的错误代码，或使用 struct 包含更多上下文信息。
   • 粒度： 错误粒度要适中。过于笼统的错误（如 UnknownError）会降低诊断效率；过于细致的错误可能导致类型爆炸。
   • 可组合性： 考虑使用 std::variant 聚合不同模块或不同层级的错误类型，以便在更高级别的函数中统一处理。
   • 可打印性： 为错误类型重载 operator<<，方便日志记录和调试。

2. 避免裸 value() 调用：

   • result.value() 在 `result