在C++项目里直接调用系统API时，代码常常被#ifdef _WIN32和#else割裂，句柄类型一会是HANDLE，一会是int文件描述符，错误码也要分别用GetLastError和errno获取。系统API封装就是在这些原始接口之上增加一层抽象，把平台相关的类型、函数和资源管理方式收拢到可替换的实现里。它并不改变底层系统调用本身，而是让调用方通过统一的C++类或函数完成操作，从而降低跨平台维护成本，提升代码可测试性。
封装层最常见的形态是一个个资源管理类或服务接口。它可以薄到只把CreateFile包成File::open，也可以厚到把文件映射、目录监控、权限检查等概念都纳入统一模型。厚度取决于项目的实际需求：如果只在一个平台运行，薄封装就能显著改善内存安全；如果需要支持多平台，接口设计和条件编译组织就变得更重要。
一、平台差异带来的直接问题
不同操作系统对同一个资源的表达方式差别很大。以文件为例，Windows使用HANDLE表示文件句柄，出错的调用会返回INVALID_HANDLE_VALUE，并通过GetLastError获取错误码；Linux则用int文件描述符，失败返回-1，错误码放在全局的errno里。如果业务代码直接调用这些API，每个文件操作都要写两套逻辑，或者用条件编译把平台分支塞在一起。
这种写法带来的不只是代码量翻倍。条件编译会掩盖真正的执行路径，编译器只能检查当前平台的分支，另一个平台的语法错误往往要等到切换环境才能暴露。更深层的问题是资源释放方式不统一：有些句柄用CloseHandle，有些用close，有些对象还需要专门的销毁函数。一旦某个分支漏掉释放逻辑，就会出现只在特定平台复现的内存泄漏或句柄泄漏。
系统API封装首先解决的就是资源生命周期问题。通过构造函数获取资源、析构函数释放资源，调用方不需要记住每个平台的清理函数。即使仍然需要在实现文件里写条件编译，平台差异也被限制在很小的范围，不会蔓延到业务逻辑中。
二、RAII封装与Pimpl隔离
C++的RAII机制非常适合封装系统API。把句柄放进类的私有成员中，在构造函数里执行open或create，在析构函数里执行对应的关闭操作，就能保证无论函数正常返回还是抛出异常，资源都会被回收。下面是一个文件类的接口示例：
class File {
public:
explicit File(const std::string& path);
~File();
File(const File&) = delete;
File& operator=(const File&) = delete;
size_t read(void* buffer, size_t size);
void write(const void* buffer, size_t size);
private:
class Impl;
Impl* impl_;
};
这里Impl是一个前置声明的内部类，真正的数据成员放在实现文件里。对于Windows版本，Impl可能包含HANDLE handle_；对于Linux版本，它可能只保存int fd_。使用Pimpl的好处是头文件里不会出现任何平台相关的类型，上层代码不需要包含<windows.h>或<unistd.h>。修改某个平台的实现时，也不会触发依赖该头文件的大范围重新编译。
Pimpl还方便做单元测试。测试代码可以建立一个File接口的模拟实现，把真实系统调用替换成内存中的数据，从而测试业务逻辑而不依赖于真实文件系统。如果接口直接暴露平台句柄，这种替换会困难得多。当然，Pimpl会引入一次额外的堆分配和间接调用，对于纳秒级热路径可能不适合，但绝大多数文件、进程、套接字操作的开销远大于这次间接调用。
三、错误码映射与异常策略
系统调用的错误报告机制差异很大，封装层必须把它们统一成一种上层代码容易处理的形式。C++标准库提供std::error_code和std::system_error，很适合作为中间表示。可以把GetLastError的值转成std::error_code，把errno转成std::error_code，然后根据项目风格决定抛出异常还是返回错误码。
std::error_code platform_error() {
#ifdef _WIN32
return std::error_code(::GetLastError(), std::system_category());
#else
return std::error_code(errno, std::generic_category());
#endif
}
如果选择异常策略，通常会在错误发生时抛出std::system_error，并在消息中附带原始错误码和可读信息。这样调用方可以统一写try和catch，而不用关心当前平台。返回错误码的策略则更适合对异常禁用或实时性要求较高的项目，C++17之后还可以使用std::optional或std::expected风格来携带结果和错误。
无论采用哪种策略，都不建议直接在封装层打印日志或调用exit。封装层应当只负责转换和传递错误，把是否终止、是否重试、是否忽略的决定权留给业务代码。过度处理错误会让封装库变得难以在不同场景中复用。
四、跨平台封装的落地思路
跨平台封装的组织方式一般有两种：条件编译和目录分离。条件编译写起来直观，但实现文件会随着平台数量增加而膨胀；目录分离则把同一接口的不同实现放到win32/、posix/、macos/等子目录，由构建系统决定编译哪些源文件。中大型项目更推荐目录分离，因为它让每个平台的实现文件保持短小，也便于按平台进行代码审查。
接口设计时要注意抽象粒度。太薄会让平台差异漏到上层，太厚则会导致接口复杂、学习成本高。比较好的做法是先找出业务真正用到的能力，例如文件读写只需要read、write、seek、size四个操作，就不要把ioctl或DeviceIoControl暴露出来。进程管理可以抽象出Process类，内部封装CreateProcess或fork加exec，但对外只提供启动、等待、终止等方法。
性能方面，封装层不应成为瓶颈。虚函数调用、Pimpl间接访问、错误码构造等开销相比于系统调用本身通常可以忽略。需要警惕的是在封装层做不必要的内存拷贝，例如把接收缓冲区先复制到std::string再返回。保持与底层API相似的缓冲区语义，能避免无谓的数据移动。只要抽象边界设计得当，C++系统API封装可以在不牺牲性能的前提下，大幅降低跨平台开发的复杂度。