命名空间

是什么，为什么存在

C++ 程序会同时使用标准库、第三方库和项目代码。不同代码都可能需要 parse、Status 或 Config 这样的自然名称。命名空间把这些声明放进不同作用域，让 wire::Status 与 storage::Status 可以同时存在。

命名空间是声明区域，不是对象，也不能实例化。它没有 public、private 或 protected 访问控制；知道名称的代码可以使用其中可访问的声明。project::detail 只表达约定，并不会强制外部代码远离实现细节。

命名空间也不是文件夹或构建目标。同一命名空间可以在多个头文件和源文件中继续定义，一个文件也可以包含多个命名空间。文件系统组织与命名空间层次通常保持相近，是为了阅读方便，不是语言要求。

你会在几乎所有 C++ 接口中遇到命名空间。标准库名称位于 std，库通常以组织名或库名作为最外层命名空间，较大的代码库再按领域嵌套。C++17 支持 namespace company::billing { ... } 这种嵌套定义简写。

命名空间解决的是名称归属与查找问题。头文件是否被包含、定义是否满足单一定义规则、符号是否能由链接器找到，仍属于编译和链接模型。把这些问题分开，才能正确解释「编译通过但链接失败」之类的现象。

工作原理

命名空间定义把声明加入某个命名空间作用域。后续再次写出同名定义，会继续打开原来的命名空间，而不是创建另一个同名容器。因此，头文件可以声明 shop::load()，源文件再在 namespace shop { ... } 中提供定义。

命名空间定义只能出现在命名空间作用域，不能写在函数或类的内部。函数内部可以声明命名空间别名，也可以使用 using 声明或指令。这个区别经常出现在模型生成的「为了局部隔离而在函数中创建 namespace」代码里，那种代码无法编译。

限定查找与非限定查找

billing::total 是限定名称：查找从 billing 指定的作用域继续。以 :: 开头的 完全限定名称（fully qualified name） 从全局命名空间开始，例如 ::company::billing::total，不会先尝试当前嵌套作用域中的 company。

没有作用域限定符的 total 使用非限定名称查找。编译器从当前作用域及其语言规定的外层作用域寻找声明。找到候选名称不等于调用已经确定；函数候选还要参与重载决议。

当表达式是非限定函数调用时，编译器还可能执行 参数依赖查找（argument-dependent lookup，ADL） 。参数类型关联的命名空间与类会贡献额外候选，所以 print(parcel) 可以找到与 shipping::Parcel 放在一起的 shipping::print。限定调用 shipping::print(parcel) 不需要 ADL。

ADL 只补充特定形式的函数查找，不是「根据参数猜一个任意名称」。如果普通非限定查找找到类成员、块作用域函数或非函数声明，ADL 还会受到抑制。排查重载问题时，需要分别列出普通查找与 ADL 提供的候选。

using 声明、指令与别名

using 声明（using-declaration） 引入一个指定名称，例如 using metrics::distance;。它让当前作用域可以写 distance(...)，同时仍把决定暴露在一行代码上。函数重载可以作为同名声明组参与查找，但这不等于导入整个命名空间。

using 指令（using-directive） 写作 using namespace metrics;。它让非限定查找考虑该命名空间中的名称，却不会逐个在当前位置声明副本。以后给命名空间增加名称时，原本无歧义的调用可能变成歧义。

命名空间别名给长名称增加短拼写，例如 namespace api = company::platform::api;。别名不复制成员，也不会创建新命名空间；通过别名和原名访问的是同一批声明。别名适合 .cpp 文件或函数中的局部便利，不宜让公共接口依赖调用方自定义的缩写。

未命名与内联命名空间

未命名命名空间（unnamed namespace） 写作 namespace { ... }。其中直接或间接声明的名称具有内部链接，因此属于当前 翻译单元（translation unit） 。同一翻译单元中的多个未命名命名空间定义会继续打开同一个唯一命名空间。

未命名命名空间适合 .cpp 文件中的辅助函数、常量和实现类型。把它放在头文件中时，每个包含该头文件的翻译单元都会获得自己的实体；这可能是有意设计，也可能造成重复状态和类型身份问题。

内联命名空间（inline namespace） 的成员也可以通过外层命名空间进行限定查找。库常用它为当前 API 版本提供短名称，同时保留 library::v1::Type 与 library::v2::Type 这种明确拼写。它不会自动让两个版本保持源码或 ABI 兼容。

示例

下面四个程序依次展示名称隔离、命名空间扩展、ADL，以及未命名与内联命名空间。它们都以 -std=c++23 使用本地 g++ 编译并执行，输出来自实际运行。

隔离同名函数

两个领域都可以使用 fee 这个名称。调用点通过限定名称说明需要哪套规则，并在很小的作用域中给其中一个名称建立别名。

bulk 只是 wholesale 的另一个拼写。它没有自己的 fee，也不会改变函数的类型或链接名称。这里保留限定调用，比同时引入两个 fee 更清楚。

在多处扩展命名空间

第一次定义加入 Order，第二次定义加入 make_order()。随后用 C++17 嵌套语法定义 shop::audit::write()；三段代码最终属于一组连续的命名空间作用域。

#include <iostream>

namespace shop {
struct Order {
    int id;
    int units;
};
}

namespace shop {
Order make_order(int id, int units) {
    return {id, units};
}
}

namespace shop::audit {
void write(const Order& order) {
    std::cout << "order " << order.id
              << ": " << order.units << " units\n";
}
}

int main() {
    const auto order = shop::make_order(42, 3);
    shop::audit::write(order);
}

order 42: 3 units

audit 内部可以把外层 shop 的 Order 写成非限定名称。调用方仍使用 shop::audit::write，因为嵌套命名空间不会像内联命名空间那样把成员自动暴露到外层。

真实项目通常把 Order 与函数声明放在头文件，把函数定义放在源文件。示例写在一个文件中，是为了单独执行；命名空间可以跨文件继续定义，但每个翻译单元仍要看到它所使用的声明。

让 ADL 找到同域操作

shipping::print 与它处理的 Parcel 放在同一个命名空间。main() 中没有 using shipping::print，非限定调用仍能通过参数类型关联到 shipping。

#include <iostream>
#include <string_view>

namespace shipping {
struct Parcel {
    std::string_view route;
    int weight_kg;
};

void print(const Parcel& parcel) {
    std::cout << parcel.route << ": "
              << parcel.weight_kg << " kg\n";
}
}

int main() {
    const shipping::Parcel parcel{"CDG-BER", 12};
    print(parcel);  // ADL 会加入 shipping::print。
}

CDG-BER: 12 kg

如果参数改成与 shipping 无关的内置类型，ADL 就没有这个关联命名空间。把操作与用户定义类型放在同一命名空间，是运算符和许多定制点能够自然工作的基础。

这里也可以显式写 shipping::print(parcel)。是否依赖 ADL 取决于接口契约：普通业务调用通常可以限定，专门设计为可定制的泛型调用则常需保留非限定形式。

选择默认 API 版本

外层 telemetry::format 指向内联的 v2 版本，而旧版本仍可明确访问。文件内部的未命名命名空间保存本翻译单元自己的调用计数。

#include <iostream>
#include <string>

namespace telemetry {
namespace v1 {
std::string format(int value) {
    return "value=" + std::to_string(value);
}
}

inline namespace v2 {
std::string format(int value) {
    return "metric:" + std::to_string(value);
}
}
}

namespace {
int calls = 0;
}

int main() {
    ++calls;
    std::cout << telemetry::format(7) << '\n';
    std::cout << telemetry::v1::format(7) << '\n';
    std::cout << "calls: " << calls << '\n';
}

metric:7
value=7
calls: 1

telemetry::v2::format(7) 也合法。inline 改变的是外层查找与部分关联规则，不是建议编译器内联函数的优化关键字含义；两个用法只是共享了同一个单词。

calls 没有成为 telemetry 的成员。它只在当前翻译单元中提供内部实体，适合实现细节；需要跨文件共享计数时，应在具名命名空间中声明一个明确的外部接口。

陷阱

在头文件中写 using namespace

修复： 头文件使用限定名称。实现函数内部若重复限定明显降低可读性，只引入需要的单个名称，并把声明放在尽可能小的块作用域。

把 detail 当成访问控制

修复： 用类的私有成员维护对象不变量，用未命名命名空间限制 .cpp 内部名称，用模块导出规则控制模块接口。不要把命名空间名称当作安全边界。

在头文件中制造每个翻译单元一份的状态

修复： 先写明状态是每个翻译单元独立，还是全程序共享。共享变量在合适命名空间中使用单一定义，或在 C++17 以后使用符合契约的 inline 变量；独立状态则明确记录这种所有权。

把自己的声明加入 std

修复： 把类型和非成员操作放在自己的命名空间，让 ADL 找到它们。泛型交换先写 using std::swap;，再进行非限定 swap(a, b)，或者使用符合目标标准库接口的 std::ranges::swap。

让限定调用绕过 ADL 定制

修复： 先确认 API 是否把 ADL 定义为定制协议的一部分。定制点按协议使用非限定调用，并用至少一个自定义类型测试；普通调用则优先限定到拥有该操作的命名空间。

在错误的命名空间中提供定义

修复： 让定义使用明确的限定名，或打开与声明完全相同的命名空间。编译并链接一个最小调用方；只对源文件执行 -fsyntax-only 无法发现缺失定义。

延伸阅读

• C++ 工作草案：命名空间
• C++ 工作草案：using 指令
• C++ 工作草案：参数依赖名称查找
• cppreference：命名空间
• cppreference：参数依赖查找