# 命名空间

Source: https://codewiki.com/zh/cpp/namespaces/

> - **what**: 命名空间（namespace）把类型、函数和对象名称放进具名作用域，避免无关代码争用同一个全局名称。
> - **trap**: `using namespace` 会让非限定查找接触整片名称；放进头文件后，包含者也会继承这项影响。
> - **fix**: 公共接口使用限定名称，局部代码优先使用单名称 `using` 声明；需要定制点时，明确检查参数依赖查找（ADL）。

## 是什么，为什么存在

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` 文件或函数中的局部便利，不宜让公共接口依赖调用方自定义的缩写。

| 写法 | 影响 | 合适范围 |
| --- | --- | --- |
| `metrics::distance(a, b)` | 明确限定每次使用 | 公共接口、头文件和容易冲突的代码 |
| `using metrics::distance` | 引入一个名称或重载组 | 小型函数作用域 |
| `using namespace metrics` | 让非限定查找考虑整个命名空间 | 很窄、无歧义的实现作用域 |
| `namespace mt = metrics` | 为同一命名空间提供短名称 | 局部实现中的长限定路径 |

### 未命名与内联命名空间

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

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

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

## 示例

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

### 隔离同名函数

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

<!-- quick -->

```cpp
// file: qualified_names.cpp
#include <iomanip>
#include <iostream>

namespace retail {
double fee(double amount) {
    return amount * 0.02;
}
}

namespace wholesale {
double fee(double amount) {
    return amount * 0.01 + 4.0;
}
}

int main() {
    const double order = 250.0;
    namespace bulk = wholesale;

    std::cout << std::fixed << std::setprecision(2);
    std::cout << "retail: " << retail::fee(order) << '\n';
    std::cout << "wholesale: " << bulk::fee(order) << '\n';
}
```

```text
retail: 5.00
wholesale: 6.50
```

<!-- /quick -->

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

### 在多处扩展命名空间

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

```cpp
// file: namespace_extension.cpp
#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);
}
```

```text
order 42: 3 units
```

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

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

### 让 ADL 找到同域操作

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

```cpp
// file: adl_print.cpp
#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。
}
```

```text
CDG-BER: 12 kg
```

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

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

### 选择默认 API 版本

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

```cpp
// file: inline_version.cpp
#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';
}
```

```text
metric:7
value=7
calls: 1
```

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

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

## 陷阱

### 在头文件中写 `using namespace`

> **陷阱:** 头文件中的 `using namespace std;` 或其他指令会影响每个包含位置之后的非限定查找。添加新的库重载或包含另一个头文件后，原有调用可能产生歧义，错误却出现在包含者的代码里。

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

### 把 `detail` 当成访问控制

> **陷阱:** `library::detail` 是命名约定，不是私有区域。生成代码有时把敏感状态放入具名的 `detail` 命名空间，再假定调用方无法访问或修改它。

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

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

> **陷阱:** 头文件里的未命名命名空间变量会在每个翻译单元中产生独立实体。一个源文件递增的计数，另一个源文件可能永远看不到；排查时却会看到完全相同的源码拼写。

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

### 把自己的声明加入 `std`

> **陷阱:** 向 `std` 添加函数、类型或重载通常会让程序行为未定义。标准只为少数、带明确条件的用户定义类型特化留下许可，不能把这条例外扩展成通用定制机制。

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

### 让限定调用绕过 ADL 定制

> **陷阱:** 泛型代码直接调用 `std::swap(a, b)`，可能绕过与参数类型放在同一命名空间的定制重载。相反，任意业务调用都依赖非限定查找，又会让候选集合难以预测。

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

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

> **陷阱:** 头文件声明了 `acme::load()`，生成的源文件却定义了全局 `load()`，或误放进 `acme::detail`。两个函数可以分别通过编译，调用原声明时才出现未定义引用。

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

<!-- deep -->

## 翻译单元、头文件与链接

翻译单元是一个源文件经过预处理后的结果，包括展开进来的头文件内容。编译器通常分别编译每个翻译单元，再由链接器解析具有相应链接的实体。命名空间作用域可以跨翻译单元继续，但一个翻译单元不会自动看见另一个文件中的声明。

具名命名空间本身不会把成员变成「已导出 API」，也不会统一决定所有成员的链接。函数、变量、模板、`const` 对象和 `inline` 实体各自仍遵守对应声明规则。接口设计应同时回答名称属于哪里、声明对谁可见、定义出现几次。

头文件通常在具名命名空间中提供声明。非 `inline` 函数的一个定义放在源文件中，并在相同命名空间下实现。需要在多个翻译单元中定义的函数或变量，必须使用语言允许多处相同定义的机制，并继续满足单一定义规则。

未命名命名空间会给其中名称内部链接，但不会让头文件内容只处理一次。头文件每被一个翻译单元包含一次，预处理后的定义就属于那个翻译单元。状态副本、地址比较和依赖类型身份的代码都可能因此产生意外。

命名空间与 C++20 模块可以同时使用。命名空间组织名称并参与查找；模块控制哪些声明被导出以及代码如何跨模块单元可见。把代码移入模块并不会自动消除名称冲突，把代码放入命名空间也不会获得模块的可见性边界。

| 现象 | 优先检查 |
| --- | --- |
| 编译成功但出现未定义引用 | 声明与定义的完全限定名称是否一致 |
| 加入头文件后调用变得歧义 | 新的声明、`using` 指令与 ADL 候选 |
| 两个源文件看到不同计数 | 头文件是否创建了内部链接实体 |
| `detail` 成员被外部调用 | 代码是否误把命名约定当成访问控制 |

## 全局命名空间与显式限定

所有具名命名空间最终都嵌套在全局命名空间中。全局命名空间没有可写在声明中的名称，但可以用前导 `::` 明确从它开始查找。普通库代码很少需要这种写法，名称遮蔽严重的模板或嵌套作用域中才会偶尔使用。

`::name` 与 `namespace_name::name` 都属于限定查找，起点不同。前者只从全局命名空间开始，后者先解析左侧的命名空间名称。若当前作用域也声明了一个叫 `company` 的类型或变量，`::company::api` 可以排除这种遮蔽。

前导 `::` 不是「调用链接器」的语法，也不会改变实体的链接。它只约束源码层面的名称查找。能否链接仍取决于程序是否提供匹配定义，以及构建是否把相应目标文件或库交给链接器。

全局命名空间中的业务名称最容易发生碰撞。兼容 C 的入口、`main` 和少数平台接口可能必须留在全局作用域，其余项目声明通常应放进稳定的最外层命名空间。

## 公共 API 的命名空间所有权

最外层命名空间通常代表长期稳定的库或组织身份。`utils`、`common` 和 `core` 太容易与依赖项重名，也没有说明所有者。选择能在组合多个库时仍然明确的名称，比给每个函数加缩写前缀更可靠。

嵌套层次应表达概念归属，而不是机械复制目录树。目录可以因构建和团队调整而移动，公共类型的完全限定名称却会出现在调用源码、诊断、文档以及许多 ABI 的符号中。每增加一层，都应有读者能理解的稳定含义。

参数与返回类型会把命名空间名称带进公共签名。即使函数本身通过别名暴露，调用方仍可能在类型注解、特化和诊断中看到原始类型。因此，命名空间别名适合迁移辅助，却不能假装类型真正属于另一个命名空间。

重命名公共命名空间通常是源码破坏性变更，在常见 ABI 上也可能改变符号。迁移时可以暂时提供别名或转发声明，但要检查 ADL、特化位置和两个版本同时出现时的歧义；简单文本替换不足以证明兼容。

一个实用的接口测试是：在没有全局 `using` 指令的文件中同时包含该库和一个具有常见名称的独立库，然后编译真实调用。这个测试能较早暴露全局名称泄漏、过宽的指令与依赖包含顺序的代码。

## `using` 的时间与作用域

命名空间的 `using` 声明会引入该声明点通过限定查找找到的声明。以后给源命名空间增加同名函数重载时，早先的 `using` 声明通常不会自动取得新重载。模板的部分特化等规则有专门例外，不能用「总是快照」概括所有实体。

`using` 指令的行为不同。它让非限定查找考虑被指名命名空间，因此之后加入该命名空间的声明也可能影响调用。大型头文件中真正棘手的地方不是少写了几个限定符，而是候选集合会随包含顺序和库演进变化。

块作用域中的 `using` 声明只影响该块及语言规定的嵌套作用域。把它放到最靠近重复调用的函数中，可以限制读者追踪名称来源的范围。命名空间作用域的 `using` 则影响更广，需要像接口声明一样审查。

命名空间别名也服从作用域。它绑定到已有命名空间，不能像原命名空间那样被「重新打开」，也不能在同一作用域中改为另一个目标。要添加成员，必须定义原命名空间，而不是试图把别名写在新的命名空间定义中。

## ADL、隐藏友元与定制点

ADL 的关联集合来自函数实参类型。类类型会带来其关联类与命名空间，模板实参还可能扩展集合；基础类型本身不会提供关联命名空间。精确规则比「查找参数所在命名空间」更细，复杂重载应以编译器诊断和标准规则核对。

隐藏友元是在类定义中首次声明并定义的非成员友元函数。普通限定查找可能看不到它，但以该类对象作为实参的调用可以通过 ADL 找到。比较运算符常采用这种写法，因为函数只应在至少一个操作数属于该类型时进入候选集。

这项机制能减少无关候选，也容易被错误重构破坏。模型可能把非限定表达式改成 `namespace_name::operator==(...)`，却没有注意该隐藏友元不能这样找到。审查此类修改时，要用实际运算符表达式或约定的定制点调用测试，而不是只搜索函数拼写。

经典 `swap` 协议先把 `std::swap` 作为后备候选引入当前作用域，再进行非限定调用。这样，普通类型可以使用标准实现，带有同命名空间重载的用户类型则可由 ADL 选择更合适的操作。不要通过向 `std` 添加普通重载来模拟这项协议。

内联命名空间也参与 ADL 的关联规则：关联集合包含内联命名空间时会加入其外层命名空间，包含外层命名空间时也会加入其中的内联命名空间。这使版本化类型与外层定制操作能够配合，但也可能扩大候选集合。

## 内联命名空间与版本边界

内联命名空间让当前版本的成员可以写成 `library::Widget`，同时保留明确的 `library::v2::Widget`。旧版本放在普通嵌套命名空间后，调用方必须写出 `library::v1::Widget`。两种类型即使类名相同，也属于不同命名空间成员。

常见 ABI 会把命名空间层级编码进符号名，所以版本命名空间可以让不同实现的符号共存。不过，C++ 语言标准不规定某种名称修饰格式。库是否保证二进制兼容，仍要由目标 ABI、对象布局、调用约定和发布策略共同决定。

改变哪个版本带 `inline` 会改变外层名称解析到的 API。它适合在受控发布中选择默认版本，不适合作为无成本升级开关。源码重新编译、旧二进制加载和两个版本对象互操作是三个不同问题，需要分别测试。

版本命名空间也不该代替清晰的弃用策略。仍支持旧版本时，应说明头文件、库文件和符号保留期限；删除旧版本时，构建或链接失败应当是预期迁移信号，而不是依赖偶然的重载结果。

<!-- /deep -->

[检查点: cpp/namespaces](https://codewiki.com/zh/cpp/namespaces/#checkpoint)

## 延伸阅读

- [C++ 工作草案：命名空间](https://eel.is/c++draft/basic.namespace)
- [C++ 工作草案：`using` 指令](https://eel.is/c++draft/namespace.udir)
- [C++ 工作草案：参数依赖名称查找](https://eel.is/c++draft/basic.lookup.argdep)
- [cppreference：命名空间](https://en.cppreference.com/w/cpp/language/namespace)
- [cppreference：参数依赖查找](https://en.cppreference.com/w/cpp/language/adl)