C / C++ / 系统课时

稳定公共 API 与版本边界

稳定公共 API 与版本边界

网络库一旦被业务工程依赖,头文件路径、类型名称、配置字段和链接符号就会变成长期契约。本节把公共 API 收敛到少量稳定入口,用 PImpl 隐藏 Reactor、Poller 等实现细节,并用版本号与可见性规则明确什么可以依赖、什么可以继续演进。

学习目标

  • 划分稳定公共头文件、扩展接口与内部实现目录
  • 用 PImpl 和符号可见性降低 Reactor 重构对 ABI 的影响
  • 建立版本号、弃用策略与兼容性检查规则

划清可依赖范围

对外接口最重要的不是文件少,而是边界清晰。业务代码只能包含 include/anystack 下的稳定头文件;src/detail、具体 Poller、Channel、EventLoop 实现都属于私有实现,不能出现在公共函数签名中。

公共 API 与内部 Reactor 的边界

推荐目录保持单向依赖:

text
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.h

detail 不是暂时公开,而是明确不承诺兼容。即使下游能够通过相对路径强行包含,也不应把这种用法视为受支持行为。

用 PImpl 隐藏 Reactor 细节

公共类如果直接持有 EventLoop、Channel 或具体 EpollPoller,这些类型一旦修改字段、继承关系或头文件依赖,公共头文件与 ABI 都会被连带影响。更稳妥的做法是只暴露业务语义,把实现对象放进私有 Impl。

下面是片段示例,依赖库内已有的 RPC 实现:

cpp
#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 这类实现参数暴露给业务,否则未来更换事件模型时仍要背负旧语义。已经发布但准备移除的接口,应先标记弃用,再跨主版本删除。

cpp
[[deprecated("use set_request_timeout() instead")]]
void set_timeout_ms(std::uint32_t timeout_ms);

这是接口声明片段。验证方式是让仍调用旧接口的下游工程开启编译警告重新构建:旧代码暂时能够继续编译,同时能看到明确的迁移提示,从而为后续删除接口留出过渡期。

用版本和导出规则固定边界

CMake 项目版本至少区分主版本、次版本和修订版本。主版本允许不兼容修改,次版本用于向后兼容的新能力,修订版本用于兼容性修复。动态库还应把 ABI 主版本反映到 SOVERSION。

下面是库侧 CMakeLists.txt 的关键配置片段:

cmake
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 头文件:

bash
find include/anystack -type f | sort

预期输出类似:

text
include/anystack/rpc/rpc_client.h
include/anystack/rpc/rpc_server.h
include/anystack/version.h

实际文件名可以不同,但结果中不应出现 reactor.h、poller.h、channel.h 等内部实现。发布前还应让独立下游工程只使用安装后的头文件和库完成编译,避免源码仓库中的私有路径碰巧可见而掩盖边界泄漏。

稳定公共 API 的核心不是冻结实现,而是冻结依赖方向:业务只依赖语义明确的公共接口,公共接口通过私有实现吸收 Reactor 的变化;版本号和弃用策略则明确告诉下游,哪些升级可以直接替换,哪些升级需要显式迁移。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

稳定公共 API 与版本边界

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通