C / C++ / 系统课时
稳定公共 API 与版本边界
稳定公共 API 与版本边界
网络库一旦被业务工程依赖,头文件路径、类型名称、配置字段和链接符号就会变成长期契约。本节把公共 API 收敛到少量稳定入口,用 PImpl 隐藏 Reactor、Poller 等实现细节,并用版本号与可见性规则明确什么可以依赖、什么可以继续演进。
学习目标
- 划分稳定公共头文件、扩展接口与内部实现目录
- 用 PImpl 和符号可见性降低 Reactor 重构对 ABI 的影响
- 建立版本号、弃用策略与兼容性检查规则
划清可依赖范围
对外接口最重要的不是文件少,而是边界清晰。业务代码只能包含 include/anystack 下的稳定头文件;src/detail、具体 Poller、Channel、EventLoop 实现都属于私有实现,不能出现在公共函数签名中。

推荐目录保持单向依赖:
include/
└── anystack/
├── rpc/
│ ├── rpc_client.h
│ └── rpc_server.h
└── version.h
src/
├── rpc/
│ ├── rpc_client.cc
│ └── rpc_server.cc
└── detail/
├── reactor.h
├── event_loop.h
└── poller.hdetail 不是暂时公开,而是明确不承诺兼容。即使下游能够通过相对路径强行包含,也不应把这种用法视为受支持行为。
用 PImpl 隐藏 Reactor 细节
公共类如果直接持有 EventLoop、Channel 或具体 EpollPoller,这些类型一旦修改字段、继承关系或头文件依赖,公共头文件与 ABI 都会被连带影响。更稳妥的做法是只暴露业务语义,把实现对象放进私有 Impl。
下面是片段示例,依赖库内已有的 RPC 实现:
#pragma once
#include <cstdint>
#include <memory>
#include <string>
namespace anystack::rpc {
struct ServerOptions {
std::string host = "0.0.0.0";
std::uint16_t port = 9000;
std::uint32_t io_threads = 1;
};
class RpcServer {
public:
explicit RpcServer(ServerOptions options);
~RpcServer();
RpcServer(const RpcServer&) = delete;
RpcServer& operator=(const RpcServer&) = delete;
void start();
void stop();
private:
class Impl;
std::unique_ptr<Impl> impl_;
};
} // namespace anystack::rpc公共头文件里只剩稳定数据类型和稳定动作;Reactor 如何选择 epoll、kqueue,线程模型如何调整,都可以在 Impl 中修改。PImpl 也不能自动保证所有 ABI 都稳定,编译器、标准库 ABI 和关键编译选项变化仍可能造成二进制不兼容,因此还需要明确版本边界。
把配置项当成 API 管理
配置字段进入公共结构体后,就和函数名一样需要兼容管理。稳定能力可以进入 ServerOptions;可能快速变化的能力应放到独立扩展接口;纯内部调优参数则不要公开。
不要把 epoll_max_events、channel_batch_size 这类实现参数暴露给业务,否则未来更换事件模型时仍要背负旧语义。已经发布但准备移除的接口,应先标记弃用,再跨主版本删除。
[[deprecated("use set_request_timeout() instead")]]
void set_timeout_ms(std::uint32_t timeout_ms);这是接口声明片段。验证方式是让仍调用旧接口的下游工程开启编译警告重新构建:旧代码暂时能够继续编译,同时能看到明确的迁移提示,从而为后续删除接口留出过渡期。
用版本和导出规则固定边界
CMake 项目版本至少区分主版本、次版本和修订版本。主版本允许不兼容修改,次版本用于向后兼容的新能力,修订版本用于兼容性修复。动态库还应把 ABI 主版本反映到 SOVERSION。
下面是库侧 CMakeLists.txt 的关键配置片段:
project(anystack_net VERSION 1.4.2 LANGUAGES CXX)
add_library(anystack_net
src/rpc/rpc_client.cc
src/rpc/rpc_server.cc
)
set_target_properties(anystack_net PROPERTIES
VERSION ${PROJECT_VERSION}
SOVERSION ${PROJECT_VERSION_MAJOR}
CXX_VISIBILITY_PRESET hidden
VISIBILITY_INLINES_HIDDEN YES
)
target_include_directories(anystack_net
PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
$<INSTALL_INTERFACE:include>
PRIVATE
${CMAKE_CURRENT_SOURCE_DIR}/src
)这段配置不独立运行。生效后,下游只会继承公共 include 路径,src 不会作为传递包含路径暴露;动态库的 ABI 主版本由 SOVERSION 表达。真正需要跨平台导出的公共符号,可继续配合 GenerateExportHeader 或项目自己的导出宏。
做一次边界自检
在仓库根目录执行下面的命令,确认公共目录没有混入内部 Reactor 头文件:
find include/anystack -type f | sort预期输出类似:
include/anystack/rpc/rpc_client.h
include/anystack/rpc/rpc_server.h
include/anystack/version.h实际文件名可以不同,但结果中不应出现 reactor.h、poller.h、channel.h 等内部实现。发布前还应让独立下游工程只使用安装后的头文件和库完成编译,避免源码仓库中的私有路径碰巧可见而掩盖边界泄漏。
稳定公共 API 的核心不是冻结实现,而是冻结依赖方向:业务只依赖语义明确的公共接口,公共接口通过私有实现吸收 Reactor 的变化;版本号和弃用策略则明确告诉下游,哪些升级可以直接替换,哪些升级需要显式迁移。