C++ 回调接口设计和二进制兼容详细

C++ 回调接口设计和二进制兼容详细攻略

概述

在 C++ 编程过程中，回调接口是常用的设计模式。它能够实现模块之间的解耦，提高代码的复用性和可读性。当接口发生变化时，需要注意二进制兼容性，以免出现不兼容的情况。

本攻略将介绍如何在设计回调接口时考虑到二进制兼容性问题。

接口设计

函数签名的选择

在设计回调接口时，我们需要考虑到其使用场景，确定接口的函数签名。在选择函数签名时需要考虑以下因素：

• 输入参数：需要确定回调需要传递的参数
• 输出参数：回调需要返回的参数
• 返回值类型：回调函数的返回值类型

比如：

using Callback = std::function<void(int, double)>;

上述代码定义了一个回调函数类型 Callback，该函数需要接受一个 int 类型和一个 double 类型的参数，无返回值。

对接口进行版本控制

接口的修改可能会影响到调用方的程序，为了避免对调用方产生不兼容的影响，我们需要对接口进行版本控制。

一种常见的方法是对接口添加版本号。比如：

struct CallbackData {
    int version;   // 接口版本
    int value1;
    double value2;
};
using Callback = std::function<int(const CallbackData&)>;

上述代码定义了一个回调函数类型 Callback，该函数需要接受一个包含版本号和值的结构体类型 CallbackData，返回一个 int 类型的值。

处理默认参数

默认参数是很常见的情况，在处理回调函数的默认参数时，我们可以考虑在结构体中添加一个参数来记录是否为默认参数，如下所示：

struct CallbackData {
    int version;    // 接口版本
    int value1;
    double value2;
    bool isDefault; // 是否为默认参数
    CallbackData(int v1, double v2, bool _isDefault = false)
        : version(1), value1(v1), value2(v2), isDefault(_isDefault) {}
};
using Callback = std::function<int(const CallbackData&)>;

二进制兼容性

不更改接口函数签名

在不更改已有接口函数签名的情况下，我们需要考虑修改接口的数据结构的情况。

当我们在修改一个结构体的时候，添加了新的字段时，需要确保添加的字段都有默认值。这样做可以保证旧版本的代码能够正常运行，即使用了旧版本的代码调用新版本的代码时将自动适配默认值。

比如：

// v1 版本结构体定义
struct CallbackData_v1 {
    int version;   // 接口版本
    int value1;
    double value2;
};

// v2 版本结构体定义
struct CallbackData_v2 {
    int version;   // 接口版本
    int value1;
    double value2;
    bool isDefault = false; // 新增字段，并默认为 false
};
using Callback = std::function<int(const CallbackData_v2&)>;

更改接口函数签名

当我们需要更改接口函数签名时，我们可以采用以下两种方法：

通过重载实现兼容性

在重构代码时可以通过重载函数的方式来保证代码的二进制兼容性。

比如：

// v1 版本接口定义
void RegisterCallback(std::function<void(int, double)> callback);

// v2 版本接口定义
void RegisterCallback(std::function<void(int, double, bool)> callback);

使用适配器模式

使用适配器模式转换回调参数，以符合旧版本接口的参数格式。

比如：

// 新版本回调接口
void NewCallback(int a, double b, bool c);

// 将新版本回调接口转换为旧版本格式
void OldCallback(int a, double b) {
    NewCallback(a, b, false);
}

示例说明

示例一：文件系统监控

比如我们需要在文件系统中注册一个回调函数，用于监测文件的变化。在该场景中，我们可以定义如下的回调接口：

struct FileChangeData {
    std::string fileName;   // 文件名
    int fileSize;           // 文件大小
    bool isDeleted;         // 是否被删除
};
using FileChangeCallback = std::function<void(const FileChangeData&)>;

当文件系统中的某个文件的大小或是否被删除发生改变时，我们可以通过调用该回调函数来进行监听。

若在未来需要进行修改，为了保证二进制兼容性，我们可以在结构体中添加一个版本号字段，并且为新增字段提供默认值：

struct FileChangeData_v2 {
    int version = 2;        // 接口版本
    std::string fileName;   // 文件名
    int fileSize;           // 文件大小
    bool isDeleted;         // 是否被删除
    bool isDirectory = false;   // 是否是目录，新增字段
};
using FileChangeCallback = std::function<void(const FileChangeData_v2&)>;

示例二：网络库客户端

假设我们正在开发一个网络库，并需要对外提供一个注册回调函数的接口，以便用户能够监听任务的执行情况。在该场景中，我们可以定义如下的回调接口：

struct TaskCompleteData {
    int taskId;         // 任务ID
    std::string result; // 任务执行结果
};
using TaskCompleteCallback = std::function<void(const TaskCompleteData&)>;

当有任务完成时，我们可以通过调用该回调函数来通知用户。

若在未来需要进行修改，为了保证二进制兼容性，我们可以通过重载的方式来实现版本兼容：

// v1 版本
void RegisterTaskCompleteCallback(std::function<void(int, const std::string&)> callback);

// v2 版本
void RegisterTaskCompleteCallback(std::function<void(const TaskCompleteData&)> callback);

在注册二进制兼容性的回调接口时，我们可以通过以上方法来满足开发需求。