开启警告转错误时，C++代码废弃的最佳实践是什么？

在启用警告转错误的大型C++项目里，直接用[[deprecated]]确实会触发构建失败，全局禁用错误转换又会导致警告泛滥。下面是几个在实际项目中验证过的可行方案：

1. 局部控制废弃警告的错误级别 #

不要全局放开-Wno-error=deprecated-declarations，而是针对特定模块、文件甚至代码块单独设置：

• 在构建系统（如CMake）中，给仍在调用旧API的过渡模块添加私有编译选项：

  target_compile_options(legacy_module PRIVATE -Wno-error=deprecated-declarations)
  

• 对于单个文件，在编译命令中单独追加该选项；或者在代码里用编译器指令局部控制：

  #pragma GCC diagnostic push
  #pragma GCC diagnostic ignored "-Werror=deprecated-declarations"
  // 调用旧API的代码块
  old_api();
  #pragma GCC diagnostic pop
  

这样核心新代码仍保持严格的警告转错误，只有过渡代码会产生警告，不会干扰全局构建日志。

2. 自定义废弃宏，分阶段启用 #

自己封装废弃宏，替代直接使用[[deprecated]]，根据项目的过渡阶段调整宏的行为：

• 过渡初期：宏仅包含注释或运行时日志，不触发编译警告，避免影响现有构建：

  #define MY_DEPRECATED(msg)
  // 或者带运行时警告
  #define MY_DEPRECATED(msg) do { \
      static bool warned = false; \
      if (!warned) { \
          LOG_WARN("Deprecated API: " msg); \
          warned = true; \
      } \
  } while(0)
  

• 过渡中期：将宏替换为[[deprecated]]，但配合头文件中的局部诊断控制，让调用方触发警告但不影响头文件自身编译：

  #pragma GCC diagnostic push
  #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
  #define MY_DEPRECATED(msg) [[deprecated(msg)]]
  #pragma GCC diagnostic pop
  
  MY_DEPRECATED("Use new_api() instead") void old_api();
  

• 过渡后期：将宏改为触发编译错误（比如结合#error），强制清理剩余的旧API调用。

3. 用静态分析工具批量定位并修复调用点 #

先不急于启用[[deprecated]]，而是用静态分析工具（如Clang-Tidy）找出所有旧API的调用点，批量处理：

• 自定义Clang-Tidy规则，标记所有调用旧API的位置；
• 结合代码重构工具（如Clang的重构功能），自动将旧API调用替换为新API；
• 待大部分调用点修复完成后，再启用[[deprecated]]并保持警告转错误，此时剩余的警告极少，容易排查处理。

4. 版本化API，隔离新旧实现 #

将旧API封装到单独的命名空间或版本化头文件中，通过编译宏控制是否启用旧API支持：

// api_v1.h
#ifdef ENABLE_LEGACY_API
namespace api::v1 {
    void old_api();
}
#endif

// api_v2.h
namespace api::v2 {
    void new_api();
}

给仍需要旧API的模块添加-DENABLE_LEGACY_API编译选项，同时给这些模块单独禁用废弃警告的错误转换；其他模块默认不开启该宏，无法访问旧API，自然不会触发相关问题。随着过渡推进，逐步移除ENABLE_LEGACY_API的使用。

5. 运行时警告+可选编译时错误 #

对于无法短期替换的旧API，优先在运行时输出警告（比如通过项目的日志系统），同时提供编译选项让开发者可以强制触发错误：

• 默认状态下，旧API仅在运行时打印一次警告，不影响编译；
• 当需要强制清理旧API时，开启-DENFORCE_DEPRECATED_ERRORS编译宏，此时将[[deprecated]]的警告转为错误，强制修复剩余调用点。

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