C++ API设计疑问：使用void*是否属于不良实践？

这听起来是个非常棒的通用API设计方向——信号/槽模式天然适配“订阅-响应”的场景，能让调用方完全按需定制事件处理逻辑。结合你给出的subscribe接口，我来分享一些实用的优化点和注意事项，帮你的API更健壮、更易用：

核心接口的细节优化 #

• EventEnum参数建议用const引用：你的接口里是EventEnum& ev，但订阅操作通常不需要修改枚举值，改成const EventEnum& ev能避免意外修改，同时保持传递效率：

  RetCallback subscribe(const EventEnum& ev, std::function<void(void*)> fn) const;
  

• 平衡通用性与类型安全：std::function<void(void*)>的签名确实足够通用，但void*的类型不安全是硬伤。可以考虑提供模板重载版本，兼顾两种需求：

  // 保持原通用接口
  RetCallback subscribe(const EventEnum& ev, std::function<void(void*)> fn) const;
  
  // 类型安全的模板重载
  template<typename EventData>
  RetCallback subscribe(const EventEnum& ev, std::function<void(const EventData*)> fn) const {
      // 内部将类型安全的回调包装为void(void*)形式
      return subscribe(ev, [fn](void* data) {
          fn(static_cast<const EventData*>(data));
      });
  }
  

  这样调用方既可以用通用版本做灵活处理，也能通过模板版本获得编译期类型检查，避免错误的类型转换。

EventEnum与事件参数的规范 #

• 明确枚举与参数的对应关系：在公开头文件里给每个EventEnum值添加详细注释，说明该事件触发时void*参数的具体类型，比如：

  enum class EventEnum {
      UserLogin,    ///< 触发时传递const UserInfo*类型参数
      DataUpdated,  ///< 触发时传递const DataPacket*类型参数
      SystemShutdown///< 触发时传递nullptr，无有效参数
  };
  

  这里推荐用enum class强类型枚举，避免隐式转换带来的错误。
• 清晰定义参数的生命周期：必须在文档里明确说明每个事件的void*参数是临时对象还是持久对象，调用方是否需要负责内存管理。比如：UserLogin事件的参数是API内部持有的临时对象，回调执行完毕后会被销毁，调用方不能保存指针后续使用。

RetCallback的设计要点 #

• 明确取消订阅的能力：RetCallback应该是用来管理订阅生命周期的句柄，必须提供清晰的取消订阅方法，比如：

  class RetCallback {
  public:
      void unsubscribe() const; // 取消订阅
      // 可以重载operator()来简化调用
      void operator()() const { unsubscribe(); }
  };
  

  这样调用方在对象销毁或不再需要响应事件时，能及时取消订阅，避免悬空指针或无效回调执行。
• 保证线程安全：如果API会在多线程环境下使用，subscribe、unsubscribe以及事件触发的回调执行都要做线程同步（比如用std::mutex保护订阅列表），避免并发修改导致的崩溃或数据不一致。

公开头文件的最佳实践 #

• 做好头文件防护：用#pragma once或传统的#ifndef宏防护，避免重复包含导致的编译错误。
• 最小化依赖：公开头文件里只保留必要的声明，比如EventEnum的定义、RetCallback的前向声明或类定义，内部实现的细节不要暴露给调用方。比如std::function需要包含<functional>，但不要把内部的订阅列表、锁等实现代码的头文件也包含进来。

示例调用代码 #

给调用方提供简单的使用示例，能降低上手成本：

// 调用方自定义的回调函数
void handleUserLogin(const UserInfo* userInfo) {
    if (userInfo) {
        std::cout << "User " << userInfo->username << " logged in" << std::endl;
    }
}

int main() {
    ApiInstance api;
    // 使用类型安全的模板版本订阅
    auto loginCallback = api.subscribe(EventEnum::UserLogin, handleUserLogin);

    // 业务逻辑...

    // 不再需要时取消订阅
    loginCallback.unsubscribe();
    return 0;
}

内容的提问来源于stack exchange，提问作者Fluffy