C++ 公共 API 的最佳实践是什么？
我正在开发一个具有多个命名空间的 C++ 项目，每个命名空间都有多个对象。一些对象具有相同的名称，但位于不同的命名空间中。目前，每个对象都有自己的 .cpp 文件和 .h 文件。我不知道如何措辞...创建第二个 .h 文件以仅公开公共 API 是否合适？它们应该是每个命名空间或每个对象或某个其他范围的 .h 文件吗？为 C++ 库创建公共 API 的最佳实践是什么？
感谢您的帮助， 陈兹
【问题讨论】：
有时在每个 .cpp 和 .h 文件对中拥有一个类并将命名空间层次结构作为目录层次结构有时会很方便。
例如，如果你有这个类：
namespace stuff {
namespace important {
class SecretPassword
{
...
};
}
}
那么它将在两个文件中：
/stuff/important/SecretPassword.cpp
/stuff/important/SecretPassword.h
另一种可能的布局可能是：
/src/stuff/important/SecretPassword.cpp
/include/stuff/important/SecretPassword.h
【讨论】：
生日，
一个建议是看一看C++ 的Handle-Body 习语，有时也被称为柴郡猫。这是包含成语的James Coplien's original paper。
这是一种众所周知的将公共 API 与实现分离的方法。
HTH
【讨论】：
我会说最好由你决定，这是“图书馆”的类型。
您的 API 是否提供一个“操作”？还是只处理一种抽象的“数据类型”？这方面的例子是 zlib 和 libpng。两者都只有一个标头，提供执行库所需的一切。
如果您的库是一个不相关（甚至相关）类的集合，这些类的目标是否相同，则为每个子集提供其自己的标头。主要的例子就是 boost。
【讨论】：
这是我习惯做的事情：
“有些对象名称相同，但在不同的命名空间中”
这就是命名空间存在的原因。
“创建第二个 .h 文件以仅公开公共 API 是否合适？”
您始终应该只公开公共 API。但是公开公共 API 意味着什么？如果只是标头，那么由于公共 API 依赖于私有 API，因此私有 API 无论如何都会包含在公共 API 中。公开一个公共 API 用一个宏标记公共函数/类（在 Windows 的情况下将公共函数导出到符号表；并且可能很快就会被 Unix 系统采用）。所以你应该定义一个像 MYLIB_API 或 MYLIB_DECLSPEC 这样的宏，只需检查一些现有的库和 MS declspec 文档。足够了，通常非公共 API 将保存在子目录中，因此它不会涉及库的用户。
“它们应该是每个命名空间或每个对象或某个其他范围的 .h 文件吗？”
我更喜欢 Java 风格，每个标头一个 public 类。我发现以这种方式编写的库比那些混合文件和结构名称的库更干净和可读。但是在某些情况下，我会打破这条规则，尤其是在模板方面。在这种情况下，我会给出#warning 消息以不直接包含标头，并在 cmets 中仔细解释发生了什么。
【讨论】：
大反响 LiraNuna。
您是为应用程序还是库提供 API？
应用程序 API 通常只提供查询应用程序状态或尝试更改该状态的方法。在这种情况下，您通常会在单独的头文件中拥有单独的接口声明。然后，您的对象将实现此接口来处理 API 请求。
库通常会公开可重复使用的对象。在这种情况下，一般来说，你的 API 就是头文件中的公共方法。
【讨论】：
我同意文档所说的 - 每个文件一个类。 99.9% 的时间！
另外，考虑使用什么文件名。在不同的目录中拥有多个同名的标头通常是个坏主意，即使它们包含的类很可能位于不同的命名空间中。
特别是如果这是一个公共 API，您可能无法控制库的用户定义的包含路径，因此构建可能会找到错误的路径。调整包含路径的顺序绝对不是我推荐的解决方案！
我们使用Namespace-Class.h 的命名约定来明确标识文件中的类。
【讨论】：
#include "Mylib-Graphics-Formats-JpegLoader.h" 或 #include "mylib/graphics/formats/JpegLoader.h" 之间有什么区别？您仍然需要以某种方式输入完整的“路径”吗？
mylib 的位置，那么您就没有歧义了。但是你不能总是保证用户会做正确的事（或者你可以保证他们会做错的事！）。