📚 课程目录第3章跨平台SDK设计原则

3. 跨平台SDK设计原则

做跨平台PKI SDK，说白了就是一套源码能在Windows、Linux、macOS上通吃。我早期想法很简单——到处都用#ifdef包一圈就行。结果呢？代码变得又臭又硬，改一个平台特性，另外两个平台跟着裂。今天我把核心原则拆成四块讲：抽象层、条件编译、调用封装、可移植细节。

3.1 平台无关抽象层

抽象层是根基。它定义一套纯虚接口，底层实现各自平台去完成。上层代码只依赖接口，不依赖具体平台。我在项目中用过PIMPL惯用法（Pointer to Implementation），头文件里只放一个不透明指针，完整实现全藏到.cpp里。这样编译隔离效果很好，改实现不会触发全量重编译。

核心原则：头文件里不要出现任何平台相关的头、类型、宏。用class PlatformImpl;前向声明，然后通过工厂方法创建实例。

抽象层不要试图“统一”所有平台特性。比如Windows有证书存储区MY、ROOT，Linux用NSS数据库。接口应该提供“枚举存储区”和“按名称访问”，具体怎么映射交给底层的适配器。

3.2 条件编译与宏定义

条件编译逃不掉，但要用得克制。#ifdef _WIN32、#ifdef __linux__——这些宏很常见。我曾经因为把__linux__拼成__linux（少两个下划线），导致整个Linux适配段没被编译，排查了一天。嗯，教训是：

定义统一的平台标识宏，比如PLATFORM_WINDOWS、PLATFORM_LINUX、PLATFORM_MACOS，在构建系统里通过-D传入，不要依赖编译器内置宏。
把条件编译代码抽到独立的平台适配文件中，不要在业务逻辑里到处散落。举个例子，文件路径操作，统一放到path_utils_windows.cpp和path_utils_posix.cpp里，通过构建系统选择编译哪个文件。
所有条件编译块必须配注释，说明当前分支处理哪个平台，哪个特性。

// 示例：条件编译宏的最佳实践
#ifdef PLATFORM_WINDOWS
    // Windows: 使用宽字符路径
    std::wstring toNativePath(const std::string& utf8Path);
#else
    // Linux/macOS: UTF-8路径直接使用
    std::string toNativePath(const std::string& utf8Path);
#endif

3.3 系统调用封装

同样的系统能力，不同平台的API千差万别。比如内存映射文件——Windows用CreateFileMapping+MapViewOfFile，Linux用mmap，macOS两者兼有但细节不同。做封装时，我给自己定了三条规矩：

统一错误码：底层把平台错误转成自定义枚举（Ok、AccessDenied、NotFound），上层不看GetLastError()或errno。
资源生命周期统一：用RAII类包裹句柄或文件描述符。Windows的HANDLE和POSIX的int fd，抽象成FileHandle类，析构时自动关闭。
函数签名对齐：比如“读取文件”接口，参数统一为(void* buffer, size_t size, off_t offset, size_t& bytesRead)，内部调用ReadFile或pread。

注意：不要试图“完全消除”平台差异。比如Windows的I/O完成端口与Linux的epoll，模型不同，强行统一成一种会丢失性能。这时候抽象层只提供“异步通知”订阅能力，底层暴露各自最佳实践。

3.4 可移植性考量

字节序、文件路径、线程模型——这三个是隐藏的炸弹。我列个表，大家可以保存下来当检查清单：

维度	Windows	Linux	macOS
字节序（本机）	小端	小端（x86/ARM）	小端（x86/ARM）
网络序转换函数	`htonl/ntohl`	`htonl/ntohl`	`htonl/ntohl`
文件路径分隔符	`\` 或 `/`（都行）	`/`	`/`
最大路径长度	260（可突破至32k）	4096	1024
线程创建	`CreateThread`	`pthread_create`	`pthread_create`
线程锁	`CRITICAL_SECTION` / `SRWLOCK`	`pthread_mutex_t`	`pthread_mutex_t`

处理方式：

字节序：PKI大量涉及ASN.1编码，其中整数是大端序。无论平台，所有序列化统一用网络序，本机读取时做一次转换。我写过一个小工具函数readUint16BE，内部调用ntohs，跨平台没问题。
文件路径：写一个NormalizePath函数，把/和\统一转成当前平台分隔符。注意Windows下路径C:\与POSIX下/的区别。字面量路径不要硬编码，用path::separator常量。
线程模型：封装两个类：Thread（启动+join）和Mutex（加锁解锁）。Windows下Thread内部用std::thread（C++11后统一），但注意std::thread在MinGW下可能有问题。我建议保留一层底层实现，用#ifdef选择创建方式。

避坑指南：我曾经在Linux下用stat获取文件大小，然后把这个值直接传给Windows下的SetFilePointer。结果文件大小是off_t（64位），而SetFilePointer默认参数是LONG（32位），超过2GB就溢出。一定要用SetFilePointerEx配LARGE_INTEGER。后来我统一封装成int64_t FileSize()，底层各自处理64位兼容。

上面这张图就是我心中的布局：应用层只管调用，抽象层定义契约，中间通过条件编译和系统调用封装做适配，最下面才面对具体操作系统。可移植性考量不是独立的一层，而是贯穿在封装过程中的思考习惯。你想想看，如果每个接口你都问一句“这个在Linux上怎么取路径？这个在macOS上线程安全吗？”，坑会少很多。