命名空间与链接

1. 学习目标

本章节遵循 Bloom 认知分类法（Bloom’s Taxonomy）组织学习目标，使读者能够循序渐进地掌握 C++ 命名空间（namespace）与链接性（linkage）两大密切相关的核心机制，并具备在生产环境中设计、分析、评估大型程序组织方案的能力。命名空间与链接性是 C++ 程序架构的基石——前者解决名称冲突，后者决定跨翻译单元（translation unit）的符号可见性，二者共同决定了头文件、源文件、库、模块的边界与组合方式。

1.1 Remember（记忆）

• R1：复述命名空间的完整语法骨架：namespace optional-name { declarations }，并能说明命名空间定义、别名（alias）、匿名形式、内联形式（inline）四种变体的写法。
• R2：背出 ISO/IEC 14882:2020 中命名空间的定义位置：§9.8.1 [namespace.pre] 与 §9.8.2 [namespace.def]；链接性的定义位置：§6.6 [basic.link]。
• R3：列出三种链接性（linkage）分类：无链接（no linkage）、内部链接（internal linkage）、外部链接（external linkage），并说明模块链接（module linkage，C++20 新增）的语义。
• R4：记住 C++11/14/17/20/23 五代标准对命名空间与链接性的主要增补：内联命名空间（C++11）、嵌套命名空间简写（C++17）、namespace fs = std::filesystem 别名标准化、模块（C++20）、export using（C++20）、命名空间级 using enum（C++20）。
• R5：背出 using 声明（using-declaration）与 using 指令（using-directive）的本质区别：前者引入单个名称，后者引入整个命名空间的”软注入”，仅作用于当前作用域的名称查找。

1.2 Understand（理解）

• U1：解释”翻译单元”的完整定义：一个源文件（.cpp）加上所有直接或间接包含的头文件，经过预处理后形成的单一编译输入。
• U2：阐明”内部链接”与”外部链接”在目标文件层面的差异：内部链接符号不进入目标文件的符号表（或标记为局部），外部链接符号进入符号表供链接器解析。
• U3：描述参数依赖查找（ADL，Argument-Dependent Lookup）的完整规则：未限定名函数调用时，编译器除了在当前作用域查找外，还会在所有实参类型所在的命名空间中查找候选函数。
• U4：解释”匿名命名空间”为何等价于 static 修饰但语义更广——static 不能修饰类与模板，匿名命名空间可以应用于所有实体。
• U5：阐明”内联命名空间”的”透明性”——其成员被”注入”到外层命名空间，外层可以直接访问，无需写 v2::，便于版本管理与 ABI 兼容。

1.3 Apply（应用）

• A1：使用嵌套命名空间简写（C++17）定义 company::product::module::v2 的多层命名空间结构。
• A2：使用匿名命名空间为 .cpp 文件中的内部辅助函数提供内部链接，替代传统的 static 修饰。
• A3：使用内联命名空间实现版本化库 API，默认暴露新版本，老版本通过显式命名空间访问。
• A4：使用 using 声明将基类的重载函数引入派生类，避免名称遮蔽（name hiding）。

1.4 Analyze（分析）

• An1：分析 using namespace 在头文件中使用的危害：污染所有包含该头文件的翻译单元，可能引发名称冲突、ADL 意外匹配、重载决议歧义。
• An2：分析 extern "C" 的作用机制：禁用 C++ 名称修饰（name mangling），使函数符号符合 C 链接约定，便于与 C 库互操作。
• An3：对比匿名命名空间与 static 修饰在 .cpp 文件中的差异：可应用范围、模板特化、类型可见性、ODR（One Definition Rule）影响。
• An4：分析 C++20 模块系统对传统头文件-源文件模型的影响：模块接口单元（interface unit）、实现单元、分区、全局模块片段（global module fragment）。

1.5 Evaluate（评价）

• E1：评价给定大型项目的命名空间设计在层级深度、名称长度、版本管理、内部细节隔离上的表现，给出 1-10 分的工程化评分。
• E2：判断在以下场景中应选用 static、匿名命名空间、内联命名空间、extern "C" 中的哪一种，给出决策树。
• E3：评估”在头文件中使用匿名命名空间”对 ODR 的影响，并给出修复方案。

1.6 Create（创造）

• C1：设计一个完整的版本化库命名空间结构，支持多版本并存、ABI 兼容、用户自定义类型的 ADL 扩展点。
• C2：实现一个基于 extern "C" 的 C/C++ 互操作层，封装回调函数、错误码、字符串传递、内存所有权约定。
• C3：设计一个插件系统，利用外部链接与 extern "C" 实现运行期动态库加载与符号解析。

2. 历史动机与发展脉络

2.1 史前时代：C 语言的全局命名空间（pre-1998）

C 语言没有命名空间概念，所有全局标识符共享同一个命名空间。大型项目中不可避免地出现名称冲突——两个库都定义 read、write、open、close 等通用函数名时，链接器无法区分。C 语言的应对策略是命名约定（naming convention）：

/* C 语言时代：靠前缀避免名称冲突 */
int sqlite3_open(const char* filename, sqlite3** db);
int sqlite3_close(sqlite3* db);
int curl_easy_init(void);
int curl_easy_cleanup(void* handle);

这种”前缀全局名”的方案丑陋但有效，被 POSIX、Win32、SQLite、libcurl 等大量 C 库广泛采用。C++ 早期（带类的 C 时代）继承了这一痛点。

2.2 C++98：命名空间诞生

C++98（ISO/IEC 14882:1998）引入命名空间，从根本上解决了全局命名空间污染问题：

// C++98：命名空间隔离名称
namespace mylib {
    class File { /* ... */ };
    void open(const std::string& path) { /* ... */ }
}

mylib::File f;
mylib::open("data.txt");

C++98 的命名空间特性：

1. 基本定义：namespace name { ... }。
2. 嵌套命名空间：namespace a { namespace b { ... } }。
3. 命名空间别名：namespace alias = original;。
4. using 声明：using mylib::File; 引入单个名称。
5. using 指令：using namespace mylib; 软注入整个命名空间。
6. 匿名命名空间：namespace { ... } 提供内部链接。
7. extern "C"：禁用名称修饰，用于 C 互操作。
8. ADL：参数依赖查找规则确立。

2.3 C++11：内联命名空间

C++11（ISO/IEC 14882:2011，N2536 提案）引入内联命名空间（inline namespace），从根本上解决了版本化库的痛点：

// C++11：内联命名空间实现版本管理
namespace mylib {
    inline namespace v2 {
        void process();  // 新版本
    }
    namespace v1 {
        void process();  // 老版本
    }
}

mylib::process();       // 默认调用 v2::process
mylib::v1::process();   // 显式调用老版本

内联命名空间的核心价值：库作者可以在新版本中标记 inline namespace v2，老用户代码无需修改即可使用新版本；同时保留 v1 命名空间供显式访问老版本。这对 ABI 兼容、bug 修复、特性演进至关重要。

C++11 同时规范了 constexpr、static thread_local 等链接性相关的存储类说明符。

2.4 C++14：完善与稳定

C++14 对命名空间与链接性的改动较少，主要是：

1. constexpr 函数隐式 inline：内联函数的链接性规则统一。
2. 变量模板：变量模板的链接性规则明确化。
3. std::launder：与对象生存期相关的链接性细化。

2.5 C++17：嵌套命名空间简写

C++17（P1094 提案）引入嵌套命名空间的简写语法，减少了多层嵌套的样板代码：

// C++17 之前
namespace a { namespace b { namespace c {
    void func();
}}}

// C++17 简写
namespace a::b::c {
    void func();
}

C++17 同时引入：

1. 命名空间级 using enum：允许将枚举值注入到命名空间。
2. inline 变量：与内联函数类似，避免头文件中定义变量的 ODR 违规。
3. [[maybe_unused]]、[[nodiscard]]、[[fallthrough]] 属性在命名空间中的标准化。

2.6 C++20：模块系统革命

C++20（P1102、P1779 提案）引入模块系统，从根本上改变了头文件-源文件模型：

// 模块接口单元 (.cppm)
export module mylib;

export namespace mylib {
    void public_api();
}

// 模块实现单元 (.cpp)
module mylib;
namespace mylib {
    void public_api() { /* 实现 */ }
    void internal_helper() { /* 内部，不导出 */ }
}

// 使用方
import mylib;
mylib::public_api();

模块系统的关键改进：

1. 编译加速：模块接口编译一次后缓存，避免重复解析头文件。
2. 宏隔离：模块不会传递宏定义，避免污染。
3. 语义导入：编译器解析模块接口的语义，而非预处理文本。
4. 模块链接：引入新的链接性类型——模块链接（module linkage），仅在模块内部可见，跨模块不可见。
5. export using：允许将导入的名称重新导出。

C++20 同时引入：

1. namespace fs = std::filesystem; 别名的广泛使用。
2. std::ranges、std::views 等新命名空间。
3. concepts 与命名空间的交互：concept 必须在命名空间中定义。

2.7 C++23：完善与扩展

C++23 对命名空间与链接性的小幅度完善：

1. if consteval：与链接性无直接关系，但影响编译期函数的可见性。
2. static operator()：无状态调用对象的链接性规则。
3. std::expected、std::print 等新标准库命名空间。
4. std::mdspan：多维数组视图的命名空间结构。

2.8 C++26：反射与静态分析

C++26 提案中与命名空间相关的方向：

1. 反射（P2996）：允许在编译期枚举命名空间的成员、查询属性、生成代码。
2. 模式匹配：与命名空间的集成。
3. Contracts：契约检查与链接性的交互。
4. std::meta：反射命名空间的标准化。

2.9 时间线总结表

3. 形式化定义

3.1 ISO/IEC 14882 中的命名空间定义

ISO/IEC 14882:2020 §9.8.1 [namespace.pre] 第 1 段：

A namespace is an optionally-named declarative region for the declaration of namespaces, types, functions, objects, and templates.

（命名空间是一个可选命名的声明区域，用于声明命名空间、类型、函数、对象与模板。）

ISO/IEC 14882:2020 §9.8.2 [namespace.def] 给出命名空间定义的形式化语法：

namespace-definition:
    named-namespace-definition
    unnamed-namespace-definition
    nested-namespace-definition

named-namespace-definition:
    inline_opt namespace attribute-specifier-seq_opt identifier { namespace-body }

unnamed-namespace-definition:
    inline_opt namespace attribute-specifier-seq_opt { namespace-body }

nested-namespace-definition:
    namespace enclosing-namespace-specifier_opt :: identifier { namespace-body }

enclosing-namespace-specifier:
    identifier
    enclosing-namespace-specifier :: identifier

namespace-body:
    declaration-seq_opt

3.2 命名空间成员的定义形式

ISO/IEC 14882:2020 §9.8.2.1 [namespace.def.general] 第 2 段：

Every namespace-definition shall appear in the enclosing namespace that contains the namespace being defined or in a scope reachable from the enclosing namespace.

（每个命名空间定义必须出现在包含被定义命名空间的封闭命名空间中，或在该封闭命名空间可达的作用域中。）

关键规则：

1. 命名空间可以分散定义——同一个命名空间名可以在多个文件中重复定义。
2. 命名空间成员可以在命名空间外部定义，但必须通过限定名（qualified-id）。
3. 命名空间是开放的（open）——可以随时添加新成员。

3.3 链接性的形式化定义

ISO/IEC 14882:2020 §6.6 [basic.link] 第 2 段：

A name is said to have linkage when it might denote the same object, reference, function, type, template, namespace, or value as a name introduced in another scope.

（当一个名称可能表示与另一个作用域中引入的名称相同的对象、引用、函数、类型、模板、命名空间或值时，称该名称具有链接性。）

ISO/IEC 14882:2020 §6.6.2 [basic.link.general] 第 3 段定义了四种链接性：

linkage:
    no linkage
    internal linkage
    module linkage
    external linkage

3.4 无链接（No Linkage）

ISO/IEC 14882:2020 §6.6.3 [basic.link.no_linkage]：

A name has no linkage when it might denote the same object, reference, function, type, enumerator, template, or value as a name introduced in another scope, but only within the same translation unit.

（当名称仅在当前翻译单元内可能表示相同的对象、引用、函数、类型、枚举值、模板或值时，称该名称无链接。）

无链接的典型场景：

1. 局部变量（int x = 0; 在函数内部）。
2. 块作用域中的类型（using IntVec = std::vector<int>; 在函数内部）。
3. 块作用域中的静态变量（static int counter = 0; 在函数内部——这里的 static 是”静态存储期”，不是”内部链接”）。

3.5 内部链接（Internal Linkage）

ISO/IEC 14882:2020 §6.6.4 [basic.link.internal]：

A name has internal linkage when it might denote the same object, reference, function, type, template, or value as a name introduced in another scope within the same translation unit.

（当名称可能在同一翻译单元内的另一个作用域中引入的名称表示相同的对象、引用、函数、类型、模板或值时，称该名称具有内部链接。）

具有内部链接的实体：

1. 显式 static 修饰的全局变量与函数。
2. 匿名命名空间中的所有实体。
3. const 限定且未 extern 的全局变量（C++ 继承自 C，但 C 中 const 默认外部链接）。
4. constexpr 修饰的全局变量（隐式 const，因此内部链接）。
5. 匿名联合（anonymous union）。
6. 模板的非类型参数中的内部链接表达式。

3.6 模块链接（Module Linkage，C++20）

ISO/IEC 14882:2020 §6.6.5 [basic.link.module]：

A name has module linkage when it might denote the same object, reference, function, type, template, or value as a name introduced in another scope within the same module unit or in another module unit of the same module.

（当名称可能在同一模块单元或同一模块的另一模块单元的另一个作用域中引入的名称表示相同的对象、引用、函数、类型、模板或值时，称该名称具有模块链接。）

模块链接是 C++20 引入的新链接性类型，介于内部链接与外部链接之间。模块内部的所有非导出实体具有模块链接，跨模块不可见，但模块内部各单元（接口单元、实现单元、分区）可见。

3.7 外部链接（External Linkage）

ISO/IEC 14882:2020 §6.6.6 [basic.link.external]：

A name has external linkage when it might denote the same object, reference, function, type, template, namespace, or value as a name introduced in another scope in another translation unit.

（当名称可能在另一个翻译单元的另一个作用域中引入的名称表示相同的对象、引用、函数、类型、模板、命名空间或值时，称该名称具有外部链接。）

具有外部链接的实体：

1. 非模板、非 static 的全局函数。
2. 非 static 的全局变量（包括 extern 声明的）。
3. 类名（class、struct、union）。
4. 枚举名。
5. 模板名。
6. 命名空间名。
7. inline 函数与 inline 变量。
8. thread_local 变量（但需 extern 声明跨翻译单元共享）。

3.8 extern "C" 的形式化语义

ISO/IEC 14882:2020 §9.8.3 [namespace.link] 第 1 段：

Some “C” language linkage specifications can be written in C++ by use of the extern "C" linkage specification.

（某些”C”语言链接性规范可以通过使用 extern "C" 链接性规范在 C++ 中书写。）

形式化语法：

linkage-specification:
    extern string-literal { declaration-seq_opt }
    extern string-literal declaration

extern "C" 的核心效果：

1. 禁用 C++ 名称修饰（name mangling），使函数符号符合 C 链接约定。
2. 函数名在目标文件中以原始名出现（如 _function_name），而非修饰后的名（如 _ZN5mylib8functionEv）。
3. 全局对象名同样符合 C 约定。
4. 类型不受 extern "C" 影响——C++ 类型仍然是 C++ 类型。

3.9 ADL 的形式化规则

ISO/IEC 14882:2020 §6.5.4 [basic.lookup.argdep]：

When the postfix-expression in a function call is an unqualified-id, other namespaces not considered during the usual unqualified lookup may be searched, and in those namespaces, namespace-scope friend function or function template declarations not otherwise visible may be found.

（当函数调用中的后缀表达式是未限定标识符时，可以搜索在通常未限定查找中未考虑的其他命名空间，在这些命名空间中，可能找到原本不可见的命名空间作用域友元函数或函数模板声明。）

ADL 的搜索规则：

1. 对于每个实参类型 T，收集其关联命名空间（associated namespace）。
2. 关联命名空间包括：
   • 类类型的定义所在的命名空间。
   • 类的基类所在的命名空间。
   • 模板类型实参的命名空间。
   • 内层命名空间（如果实参类型在内联命名空间中）。
3. 在所有关联命名空间中查找候选函数。

3.10 内联命名空间的形式化语义

ISO/IEC 14882:2020 §9.8.2.2 [namespace.inline]：

Members of an inline namespace can be used in most respects as though they were members of the enclosing namespace.

（内联命名空间的成员在大多数情况下可以像封闭命名空间的成员一样使用。）

具体语义：

1. 内联命名空间的成员对外层命名空间”透明”——外层可直接访问。
2. ADL 搜索时，内联命名空间被纳入外层命名空间的关联命名空间。
3. 显式特化时，内联命名空间的成员被视为外层命名空间成员。
4. using namespace outer 时，内联命名空间的成员也被引入。

4. 理论推导与原理解析

4.1 名称查找的完整流程

C++ 的名称查找（name lookup）是一个复杂的多阶段过程，理解命名空间与链接性的关键在于掌握查找流程。完整的查找流程：

阶段 1：未限定查找（Unqualified Lookup）

当使用未限定名（如 func(x)）时，编译器从当前作用域开始，向外层作用域逐层查找，直到找到名称为止：

namespace outer {
    void f(int);

    namespace inner {
        void f(double);

        void g() {
            f(3.14);  // 找到 outer::inner::f(double)，不继续查找 outer::f
        }
    }
}

阶段 2：限定查找（Qualified Lookup）

当使用限定名（如 std::cout）时，编译器仅在指定的命名空间中查找：

std::vector<int> v;  // 仅在 std 中查找 vector

阶段 3：ADL（参数依赖查找）

对于未限定的函数调用，编译器在完成阶段 1 后，再根据实参类型进行 ADL：

namespace mylib {
    struct Point { double x, y; };
    double distance(const Point&, const Point&);  // 在 mylib 中定义
}

mylib::Point p1, p2;
double d = distance(p1, p2);  // ADL 找到 mylib::distance

4.2 链接性的底层实现

链接性的底层实现由编译器与链接器协作完成：

目标文件符号表

每个翻译单元编译后生成目标文件（.o 或 .obj），目标文件包含：

1. 代码段（.text）：函数代码。
2. 数据段（.data / .bss）：全局变量。
3. 符号表（symbol table）：所有外部链接符号的名称与地址。
4. 重定位表（relocation table）：需要链接器填充的地址引用。

内部链接符号：不进入符号表，或标记为局部符号（local symbol）。其他翻译单元无法引用。

外部链接符号：进入符号表，标记为全局符号（global symbol）。链接器解析跨翻译单元的引用。

名称修饰（Name Mangling）

C++ 编译器对外部链接的函数与变量进行名称修饰，将函数签名（参数类型、const 性质、命名空间、类作用域）编码到符号名中：

namespace mylib {
    void func(int x, double y);
    // GCC 修饰后：_ZN5mylib4funcEid
    // MSVC 修饰后：?func@mylib@@YA(XHN@Z)
}

修饰规则：

1. _ZN 前缀（GCC/Clang）。
2. 命名空间名长度 + 名称。
3. 函数名长度 + 名称。
4. E 结束作用域。
5. 参数类型编码（i=int, d=double, …）。

extern "C" 禁用修饰：

extern "C" void func(int x, double y);
// GCC 修饰后：func（无修饰）
// MSVC 修饰后：_func

4.3 匿名命名空间的内部链接机制

匿名命名空间的成员具有内部链接，其实现机制是：

// 源代码
namespace {
    int internal_var = 42;
    void internal_func() {}
}

// 编译器内部等价于
namespace __unique_name_$LINENUMBER {
    int internal_var = 42;
    void internal_func() {}
}
using namespace __unique_name_$LINENUMBER;

编译器为每个翻译单元的匿名命名空间生成一个唯一的内部名（如 __unique_name_$1、__unique_name_$2），并通过 using namespace 将成员引入全局命名空间。由于每个翻译单元的内部名不同，跨翻译单元引用会失败，从而实现内部链接。

匿名命名空间优于 static 的地方：

1. 可应用于类型：static 不能修饰类定义，匿名命名空间可以。
2. 可应用于模板：static 不能修饰模板，匿名命名空间可以。
3. 可应用于模板特化：完整特化需要内部链接时，只能用匿名命名空间。
4. 语义统一：同一翻译单元内的所有内部链接实体使用统一机制。

4.4 内联命名空间的透明性

内联命名空间的”透明性”实现机制：

// 源代码
namespace mylib {
    inline namespace v2 {
        void process();
    }
}

编译器将 v2::process 视为 mylib::process 的别名，对外层命名空间的查找规则透明。具体表现：

1. mylib::process() 直接找到 v2::process。
2. ADL 搜索 mylib 时，自动搜索 v2。
3. using namespace mylib 时，process 被引入。
4. 显式特化 mylib::process 时，实际特化 v2::process。

内联命名空间的核心用途：

1. 版本管理：默认暴露新版本，保留老版本。
2. ABI 兼容：旧代码无需重编译即可使用新版本。
3. 平台特化：根据编译期条件选择不同实现。

4.5 ADL 的设计动机与陷阱

ADL 的设计动机是让运算符重载（operator overloading）自然工作：

namespace mylib {
    struct Vec {
        double x, y, z;
    };
    Vec operator+(const Vec& a, const Vec& b) {
        return {a.x + b.x, a.y + b.y, a.z + b.z};
    }
}

mylib::Vec a, b;
auto c = a + b;  // ADL 找到 mylib::operator+

如果不使用 ADL，用户必须写 mylib::operator+(a, b)，非常笨拙。ADL 让运算符重载自然工作，但也带来陷阱：

陷阱 1：意外的 ADL 匹配

namespace lib {
    struct Data {};
    void process(const Data&);  // 不希望被外部使用
}

namespace app {
    struct Data : lib::Data {};

    void process(const Data& d) {
        process(d);  // 递归调用！本意是调用 lib::process
    }
}

陷阱 2：模板代码中的 ADL 不可控

template<typename T>
void wrapper(T x) {
    process(x);  // process 来自哪里？依赖 T 的关联命名空间
}

4.6 using 指令的”软注入”语义

using namespace mylib; 不是”复制所有成员到当前作用域”，而是”软注入”——仅在名称查找时考虑 mylib 的成员：

namespace lib {
    int x = 1;
}

void f() {
    int x = 2;
    using namespace lib;
    std::cout << x << std::endl;  // 输出 2，局部 x 遮蔽 lib::x
}

这与 using lib::x;（硬注入）不同：

void g() {
    // using lib::x;  // 编译错误：与局部 x 冲突
    int x = 2;
}

4.7 extern "C" 与 ABI 稳定性

extern "C" 不仅用于 C 互操作，还用于跨编译器 ABI 稳定性：

// plugin_api.h
#ifdef __cplusplus
extern "C" {
#endif

typedef struct {
    int width;
    int height;
} Image;

Image* create_image(int w, int h);
void destroy_image(Image* img);

#ifdef __cplusplus
}
#endif

extern "C" 的关键约束：

1. 不能重载——C 不支持函数重载。
2. 不能是成员函数——C 没有类成员。
3. 不能是模板——C 没有模板。
4. 参数与返回值必须是 C 兼容类型（POD 类型）。
5. 异常规格——C 函数不能抛出 C++ 异常（需 noexcept）。

4.8 C++20 模块链接的语义

C++20 模块系统引入”模块链接”，介于内部链接与外部链接之间：

// mylib.cppm（模块接口单元）
export module mylib;

// 导出实体（外部链接，跨模块可见）
export void public_api();

// 模块链接实体（仅模块内部可见）
void internal_helper();

// 内部链接实体（仅当前翻译单元可见）
static int counter = 0;
namespace { int unused = 0; }

模块链接的语义：

1. 模块内部所有非导出实体具有模块链接。
2. 跨模块引用模块链接实体失败。
3. 模块内部各单元（接口单元、实现单元、分区）可互相引用。
4. 模块链接实体不污染全局命名空间。

5. 代码示例与实战详解

5.1 命名空间基础

// C++17：命名空间基础
#include <iostream>
#include <string>

namespace math {
    constexpr double PI = 3.14159265358979323846;
    constexpr double E = 2.71828182845904523536;

    // 命名空间内的函数
    int add(int a, int b) { return a + b; }
    double multiply(double a, double b) { return a * b; }

    // 嵌套命名空间
    namespace trig {
        double sin(double x) { /* 实现 */ return x; }
        double cos(double x) { /* 实现 */ return 1.0; }
    }
}

// 使用限定名访问
void demo_qualified() {
    std::cout << math::PI << std::endl;
    std::cout << math::add(1, 2) << std::endl;
    std::cout << math::trig::sin(0.5) << std::endl;
}

// using 声明：引入单个名称
void demo_using_declaration() {
    using math::PI;
    using math::add;
    std::cout << PI << std::endl;        // 直接使用
    std::cout << add(3, 4) << std::endl;
}

// using 指令：引入整个命名空间（不推荐在头文件中使用）
void demo_using_directive() {
    using namespace math;
    std::cout << PI << std::endl;
    std::cout << add(5, 6) << std::endl;
    std::cout << trig::sin(1.0) << std::endl;
}

int main() {
    demo_qualified();
    demo_using_declaration();
    demo_using_directive();
    return 0;
}

5.2 C++17 嵌套命名空间简写

// C++17 之前：繁琐的嵌套
namespace company {
    namespace product {
        namespace module {
            namespace v2 {
                class Service {};
            }
        }
    }
}

// C++17 简写
namespace company::product::module::v2 {
    class Service {};
}

// 也可以内联某些层级
namespace company::product::module {
    inline namespace v2 {
        class ServiceV2 {};
    }
    namespace v1 {
        class ServiceV1 {};
    }
}

5.3 命名空间别名

// 长命名空间别名
namespace very_long_library_name::details::implementation {
    void helper() {}
}

namespace shortcut = very_long_library_name::details::implementation;
shortcut::helper();

// 标准库别名（C++17 起广泛使用）
namespace fs = std::filesystem;
namespace chrono = std::chrono;
namespace rv = std::views;

// 模板命名空间别名（C++14）
template<typename T>
using Vec = std::vector<T>;

// 别名在模板元编程中的应用
template<typename Iterator>
using value_type_t = typename std::iterator_traits<Iterator>::value_type;

5.4 匿名命名空间

// translation_unit.cpp
#include <iostream>

// 匿名命名空间：内部链接
namespace {
    int internal_counter = 0;  // 仅当前翻译单元可见

    void log_internal(const std::string& msg) {
        std::cout << "[internal] " << msg << std::endl;
    }

    // 可以定义类型（static 不能修饰类）
    class InternalHelper {
    public:
        void do_work() { log_internal("working"); }
    };

    // 可以定义模板（static 不能修饰模板）
    template<typename T>
    T identity(T x) { return x; }
}

// 显式 static 的等价形式（仅适用于函数与变量）
static int another_counter = 0;
static void another_helper() {}

// 推荐使用匿名命名空间，而非 static
// 因为匿名命名空间语义统一，可应用于所有实体

void public_function() {
    internal_counter++;
    log_internal("called");
    InternalHelper helper;
    helper.do_work();
}

5.5 内联命名空间与版本管理

// library.h
#include <iostream>

namespace mylib {

// 当前版本（v3）标记为 inline，对外层命名空间透明
inline namespace v3 {
    class Renderer {
    public:
        void render() { std::cout << "v3 render" << std::endl; }
        // 新增特性
        void render_with_shaders() { std::cout << "v3 shaders" << std::endl; }
    };
}

// 老版本 v2（保留供显式访问）
namespace v2 {
    class Renderer {
    public:
        void render() { std::cout << "v2 render" << std::endl; }
    };
}

// 最老版本 v1
namespace v1 {
    class Renderer {
    public:
        void render() { std::cout << "v1 render" << std::endl; }
    };
}

}  // namespace mylib

// 使用方
void versioned_usage() {
    // 默认使用 v3
    mylib::Renderer r3;
    r3.render();
    r3.render_with_shaders();

    // 显式使用老版本
    mylib::v2::Renderer r2;
    r2.render();

    mylib::v1::Renderer r1;
    r1.render();
}

5.6 参数依赖查找（ADL）

#include <iostream>
#include <algorithm>

namespace mylib {

struct Point {
    double x, y;
};

// 在 Point 所在的命名空间定义自由函数
double distance(const Point& a, const Point& b) {
    return std::hypot(a.x - b.x, a.y - b.y);
}

// 运算符重载（ADL 的主要用途）
Point operator+(const Point& a, const Point& b) {
    return {a.x + b.x, a.y + b.y};
}

std::ostream& operator<<(std::ostream& os, const Point& p) {
    return os << "(" << p.x << ", " << p.y << ")";
}

class Buffer {
public:
    Buffer() = default;
    Buffer(const Buffer&) = default;
    Buffer& operator=(const Buffer&) = default;
};

// 自定义 swap（ADL 找到）
void swap(Buffer& a, Buffer& b) noexcept {
    std::cout << "mylib::swap called" << std::endl;
    // 实际交换实现
}

}  // namespace mylib

void adl_demo() {
    mylib::Point p1{0, 0}, p2{3, 4};
    // ADL 自动找到 mylib::distance、mylib::operator+、mylib::operator<<
    std::cout << distance(p1, p2) << std::endl;  // 无需 mylib:: 前缀
    auto p3 = p1 + p2;
    std::cout << p3 << std::endl;

    // swap 的惯用法：using std::swap; swap(a, b);
    mylib::Buffer a, b;
    using std::swap;
    swap(a, b);  // ADL 找到 mylib::swap，否则使用 std::swap
}

5.7 extern "C" 与 C 互操作

// c_api.h（C 与 C++ 兼容头文件）
#ifndef C_API_H
#define C_API_H

#ifdef __cplusplus
extern "C" {
#endif

typedef struct {
    int width;
    int height;
    unsigned char* data;
} Image;

Image* image_create(int width, int height);
void image_destroy(Image* img);
int image_get_pixel(const Image* img, int x, int y);
void image_set_pixel(Image* img, int x, int y, int value);

#ifdef __cplusplus
}
#endif

#endif  // C_API_H

// c_api.cpp（C++ 实现）
#include "c_api.h"
#include <cstdlib>

extern "C" {

Image* image_create(int width, int height) {
    Image* img = static_cast<Image*>(std::malloc(sizeof(Image)));
    if (!img) return nullptr;
    img->width = width;
    img->height = height;
    img->data = static_cast<unsigned char*>(std::calloc(width * height, sizeof(unsigned char)));
    return img;
}

void image_destroy(Image* img) {
    if (img) {
        std::free(img->data);
        std::free(img);
    }
}

int image_get_pixel(const Image* img, int x, int y) {
    if (!img || !img->data) return -1;
    return img->data[y * img->width + x];
}

void image_set_pixel(Image* img, int x, int y, int value) {
    if (!img || !img->data) return;
    img->data[y * img->width + x] = static_cast<unsigned char>(value);
}

}  // extern "C"

5.8 using 声明与继承

// using 声明将基类函数引入派生类
class Base {
public:
    void process(int value) { std::cout << "Base::process(int)" << std::endl; }
    void process(double value) { std::cout << "Base::process(double)" << std::endl; }
    void process(const std::string& value) { std::cout << "Base::process(string)" << std::endl; }
};

// 错误：直接定义 Derived::process 会遮蔽所有 Base::process 重载
// class Derived : public Base {
// public:
//     void process(const std::string& value) { ... }  // 遮蔽 Base::process(int/double)
// };

// 正确：使用 using 声明引入所有重载
class Derived : public Base {
public:
    using Base::process;  // 引入所有 Base::process 重载

    void process(const std::string& value) {
        std::cout << "Derived::process(string)" << std::endl;
    }
};

void test() {
    Derived d;
    d.process(42);          // Base::process(int)
    d.process(3.14);         // Base::process(double)
    d.process("hello");      // Derived::process(string)
}

// using 声明改变访问级别
class PrivateBase {
public:
    void public_method() {}
protected:
    void protected_method() {}
};

class PublicDerived : private PrivateBase {  // 私有继承
public:
    using PrivateBase::public_method;      // 改为 public
    using PrivateBase::protected_method;   // 改为 public（原本 protected）
};

5.9 命名空间与模板特化

// 模板特化必须在原命名空间中
namespace mylib {

template<typename T>
struct Traits;  // 主模板声明

// 在命名空间内特化
template<>
struct Traits<int> {
    static constexpr const char* name = "int";
    static constexpr std::size_t size = sizeof(int);
};

}  // namespace mylib

// 错误：不能在其他命名空间中特化
// namespace other {
//     template<>
//     struct mylib::Traits<double> {};  // 编译错误
// }

// 正确：在原命名空间中特化（使用命名空间重新打开）
namespace mylib {
    template<>
    struct Traits<double> {
        static constexpr const char* name = "double";
        static constexpr std::size_t size = sizeof(double);
    };
}

// 偏特化同理
namespace mylib {
    template<typename T>
    struct Traits<T*> {
        static constexpr const char* name = "pointer";
    };
}

5.10 C++20 模块基础

// mylib.cppm（模块接口单元）
export module mylib;

import <iostream>;
import <string>;

// 导出的命名空间
export namespace mylib {

class Service {
public:
    void run() {
        std::cout << "Service running" << std::endl;
        internal_helper();  // 调用模块内部函数
    }
};

void public_function();

}  // namespace mylib

// 模块内部函数（不导出，模块链接）
namespace mylib {
    void internal_helper() {
        std::cout << "internal helper" << std::endl;
    }
}

// mylib_impl.cpp（模块实现单元）
module mylib;

namespace mylib {
    void public_function() {
        std::cout << "public function" << std::endl;
        internal_helper();
    }
}

// main.cpp（使用方）
import mylib;

int main() {
    mylib::Service s;
    s.run();
    mylib::public_function();
    // mylib::internal_helper();  // 错误：模块链接，不可见
    return 0;
}

6. 跨语言对比

6.1 与 Java 包的对比

Java 的包（package）与 C++ 命名空间在概念上相似，但实现机制截然不同：

// Java：包对应文件系统目录
package com.company.product.module;

public class Service {
    public void run() { /* ... */ }
}

// 使用方
import com.company.product.module.Service;
// 或
import com.company.product.module.*;  // 仅导入类型，不导入函数

Service s = new Service();
s.run();

Java 包的关键差异：

1. 包名必须与目录路径一致——com.company.Service 必须位于 com/company/Service.java。
2. 包级私有访问——不写访问修饰符的成员仅同包可见，类似 C++ 的”友元命名空间”概念（C++ 无此特性）。
3. 无函数级别的导入——Java 函数必须属于类，不存在”命名空间级自由函数”。
4. 无内联命名空间——版本管理依赖构建工具（Maven、Gradle）。

6.2 与 Python 模块的对比

Python 的模块（module）与包（package）基于文件系统：

# mylib/service.py（模块）
class Service:
    def run(self):
        print("Service running")

def public_function():
    print("public function")

def _internal_helper():  # 下划线前缀表示"内部"
    print("internal")

# mylib/__init__.py（包初始化）
from .service import Service, public_function

# 使用方
from mylib import Service, public_function
# 或
from mylib.service import Service
# 或
import mylib
mylib.Service()

Python 的关键差异：

1. 模块即文件——每个 .py 文件自动成为一个模块。
2. __all__ 控制导出——__all__ = ["Service", "public_function"] 显式声明导出内容。
3. 下划线约定——_internal 表示”内部”，__private 表示”私有”（名称改写）。
4. 动态导入——importlib.import_module("mylib.service") 运行期导入。

6.3 与 Rust 模块的对比

Rust 的模块系统与 C++ 命名空间在设计哲学上更为接近：

// lib.rs
pub mod math {
    pub const PI: f64 = 3.14159265358979;

    pub fn add(a: i32, b: i32) -> i32 { a + b }

    pub mod trig {
        pub fn sin(x: f64) -> f64 { x }  // 简化实现
    }

    // 私有函数（默认私有）
    fn internal_helper() {}
}

// 使用方
use mylib::math::{PI, add};
use mylib::math::trig::sin;

fn main() {
    println!("{} {} {}", PI, add(1, 2), sin(0.5));
}

Rust 的关键差异：

1. 默认私有——Rust 模块成员默认不可见，必须显式 pub 才能公开。
2. pub use 重导出——可以将子模块的成员”提升”到父模块。
3. crate 根——每个 crate 有一个根模块。
4. pub(crate) 可见性——仅 crate 内部可见，类似 C++ 的模块链接。
5. super、self、crate 关键字——相对路径导航。

6.4 与 C# 命名空间的对比

C# 的命名空间与 C++ 最为相似：

// C#
namespace Company.Product.Module {
    public class Service {
        public void Run() { /* ... */ }
    }

    public static class MathLib {
        public static int Add(int a, int b) => a + b;
    }
}

// 使用方
using Company.Product.Module;

class Program {
    static void Main() {
        var s = new Service();
        s.Run();
        int result = MathLib.Add(1, 2);
    }
}

C# 的关键差异：

1. 程序集（assembly）——编译单元是 .dll/.exe，跨程序集引用通过 using + 程序集引用。
2. internal 访问修饰符——仅程序集内部可见，类似 C++ 的模块链接。
3. using static——导入静态成员，C++ 无此特性。
4. 命名空间别名限定——global::System.Console 确保从全局命名空间开始查找。

6.5 与 Go 包的对比

Go 语言使用”包（package）“概念，与 C++ 命名空间差异较大：

// mylib/math.go
package mylib

import "math"

const PI = math.Pi

func Add(a, b int) int { return a + b }

// 首字母大写 = 导出，首字母小写 = 内部
func internalHelper() {}

// 使用方
package main

import (
    "fmt"
    "company.com/mylib"
)

func main() {
    fmt.Println(mylib.PI)
    fmt.Println(mylib.Add(1, 2))
}

Go 的关键差异：

1. 包即目录——同一目录下的所有 .go 文件必须属于同一个包。
2. 首字母大小写控制导出——大写=导出，小写=内部，无需 pub 关键字。
3. 无嵌套包——Go 包是扁平的，目录层级仅用于组织。
4. internal 目录约定——internal/ 目录下的包仅父目录可访问，类似 C++ 的模块链接。

7. 常见陷阱与反模式

7.1 在头文件中使用 using namespace

反模式：

// bad_header.h
#pragma once
#include <iostream>

using namespace std;  // 反模式：污染所有包含此头文件的翻译单元

void helper() {
    cout << "hello" << endl;  // 看似方便，实则危险
}

危害：

1. 所有包含此头文件的翻译单元都被污染，std 命名空间的所有名称进入全局作用域。
2. 用户自定义类型可能与 std 中的类型冲突（如 std::count、std::distance、std::data）。
3. ADL 可能意外匹配 std 中的函数。
4. 升级 C++ 标准版本时，新加入的 std 名称可能引发新的冲突。

正确做法：

// good_header.h
#pragma once
#include <iostream>

void helper() {
    std::cout << "hello" << std::endl;  // 显式限定
}

7.2 在头文件中使用匿名命名空间

反模式：

// bad_header.h
#pragma once

namespace {
    int counter = 0;  // 反模式：每个包含此头文件的翻译单元都有独立副本

    void init() { counter = 0; }
}

class Service {
public:
    void run() { counter++; }  // 使用匿名命名空间的 counter
};

危害：

1. 每个包含此头文件的翻译单元都有独立的 counter，导致数据不一致。
2. 目标文件体积膨胀——每个翻译单元都有一份副本。
3. 链接器可能警告”未使用的符号”。

正确做法：

// good_header.h
#pragma once

class Service {
public:
    void run();
private:
    static int counter_;  // 声明，定义在 .cpp 中
};

// good_source.cpp
#include "good_header.h"

int Service::counter_ = 0;  // 外部链接定义

void Service::run() { counter_++; }

7.3 ODR 违规：内联函数中的内部链接变量

反模式：

// bad_header.h
#pragma once

inline int get_counter() {
    static int counter = 0;  // 反模式：内联函数中的静态变量
    return ++counter;
}

危害：

1. 虽然语法合法（C++11 起内联函数的静态变量保证线程安全），但所有翻译单元共享同一个 counter，可能导致意外行为。
2. 在 C++03 中，这是 ODR 违规——每个翻译单元的内联函数应有相同的定义，但静态变量的地址可能不同。

正确做法：

// good_header.h
#pragma once

inline int& counter_ref() {
    static int counter = 0;  // 返回引用，确保跨翻译单元一致
    return counter;
}

inline int get_counter() {
    return ++counter_ref();
}

7.4 ADL 意外匹配

反模式：

namespace lib {
    struct Data {};

    // 不希望被外部使用的函数
    void process(const Data&) { /* 内部实现 */ }
}

namespace app {
    struct MyData : lib::Data {};

    void process(const MyData&) { /* 应用层处理 */ }

    void use() {
        MyData d;
        process(d);  // 意图调用 app::process

        // 但如果 MyData 有从 lib::Data 继承，ADL 可能同时找到 lib::process
        // 重载决议可能产生歧义
    }
}

正确做法：

// 明确限定，避免 ADL
void use() {
    MyData d;
    app::process(d);  // 显式调用 app::process
}

7.5 跨翻译单元的 static 变量不一致

反模式：

// config.h
#pragma once

static int config_value = 42;  // 反模式：每个翻译单元独立副本

// file1.cpp
#include "config.h"
void f1() { config_value = 100; }

// file2.cpp
#include "config.h"
void f2() { std::cout << config_value << std::endl; }  // 输出 42，而非 100

正确做法：

// config.h
#pragma once

extern int config_value;  // 声明

// config.cpp
int config_value = 42;  // 定义，外部链接

7.6 extern "C" 的误用

反模式：

// bad_api.h
extern "C" {

// 错误：extern "C" 函数不能重载
int process(int x);
int process(double x);  // 编译错误：C 链接不支持重载

// 错误：extern "C" 函数不能是模板
template<typename T>
T identity(T x);  // 编译错误：C 链接不支持模板

// 错误：extern "C" 函数不能是成员函数
class Service {
public:
    extern "C" void run();  // 编译错误
};

// 错误：参数类型必须是 POD
extern "C" void process(std::string s);  // 警告：非 POD 类型跨 ABI 不安全

}

7.7 内联命名空间的滥用

反模式：

// 反模式：内联命名空间不应用于分类组织
namespace mylib {
    inline namespace utils {  // 不应该用 inline
        void helper() {}
    }
    inline namespace core {   // 不应该用 inline
        void process() {}
    }
}

危害：

1. utils 与 core 的成员都被注入到 mylib，失去组织意义。
2. 重载决议可能产生意外歧义。

正确用法：内联命名空间仅用于版本管理。

7.8 命名空间嵌套过深

反模式：

namespace company {
    namespace department {
        namespace team {
            namespace project {
                namespace module {
                    namespace v2 {
                        class Service {};  // 使用时需写 6 层限定名
                    }
                }
            }
        }
    }
}

正确做法：

// 限制嵌套深度，通常不超过 3 层
namespace company::project::v2 {
    class Service {};
}

// 或使用别名
namespace service = company::department::team::project::module::v2;

8. 工程实践

8.1 库的命名空间设计

一个成熟的库应当遵循以下命名空间设计原则：

// 推荐：库的命名空间结构
namespace mylib {

// 公共 API
namespace core {
    class Engine;
    class Service;
    void initialize();
    void shutdown();
}

// 版本化 API
inline namespace v3 {
    class Renderer;
    class Shader;
}

namespace v2 {
    class Renderer;  // 老版本
}

// 内部实现细节（用户不应直接使用）
namespace detail {
    template<typename T>
    void implementation_detail(T&& x) { /* ... */ }

    namespace platform {
        void platform_specific_init();
    }
}

// 工具与辅助
namespace util {
    class Logger;
    class Timer;
    namespace math {
        constexpr double PI = 3.14159265358979;
    }
}

// 类型与概念
namespace concepts {
    // C++20 concepts
    template<typename T>
    concept Renderable = requires(T t) { t.render(); };
}

}  // namespace mylib

设计原则：

1. 顶层命名空间：使用库名（mylib），避免公司前缀（除非必要）。
2. 模块分组：用子命名空间组织功能模块（core、util、detail）。
3. 版本管理：使用内联命名空间管理版本（v3、v2）。
4. 内部细节隔离：detail 命名空间标识实现细节，用户不应直接使用。
5. 嵌套深度：通常不超过 3 层，避免冗长限定名。

8.2 头文件保护

// 推荐：使用 #pragma once 或 include guard
#pragma once

namespace mylib {

class Service {
public:
    Service();
    ~Service();

    void run();

private:
    // PIMPL 习语：隐藏实现细节
    struct Impl;
    std::unique_ptr<Impl> impl_;
};

}  // namespace mylib

8.3 PIMPL 习语与编译防火

PIMPL（Pointer to IMPLementation）习语通过前向声明与指针隐藏实现细节，减少头文件依赖：

// service.h
#pragma once
#include <memory>

namespace mylib {

class Service {
public:
    Service();
    ~Service();  // 必须在 .cpp 中定义（因为 unique_ptr 需要完整类型）

    Service(Service&&) noexcept;
    Service& operator=(Service&&) noexcept;

    void run();
    void configure(int option);

private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};

}  // namespace mylib

// service.cpp
#include "service.h"
#include <iostream>

namespace mylib {

struct Service::Impl {
    int option = 0;
    std::string config;

    void internal_work() {
        std::cout << "internal work, option=" << option << std::endl;
    }
};

Service::Service() : impl_(std::make_unique<Impl>()) {}
Service::~Service() = default;
Service::Service(Service&&) noexcept = default;
Service& Service::operator=(Service&&) noexcept = default;

void Service::run() {
    impl_->internal_work();
}

void Service::configure(int option) {
    impl_->option = option;
}

}  // namespace mylib

PIMPL 的优势：

1. 编译防火：修改 Impl 结构不需要重新编译所有依赖者。
2. ABI 稳定：Service 类的大小固定（一个指针），修改 Impl 不影响 ABI。
3. 隐藏实现：私有成员不在头文件中暴露。

8.4 跨平台命名空间设计

// 推荐：使用条件编译与内联命名空间实现跨平台
namespace mylib {

// 平台选择
#if defined(_WIN32)
    inline namespace windows {
        namespace detail {
            using handle_type = void*;
            handle_type create_native_handle();
        }
    }
#elif defined(__linux__)
    inline namespace linux {
        namespace detail {
            using handle_type = int;
            handle_type create_native_handle();
        }
    }
#else
    #error "Unsupported platform"
#endif

// 公共 API 与平台无关
class Service {
public:
    void run();
private:
    detail::handle_type handle_;
};

}  // namespace mylib

8.5 版本化库的迁移策略

// 推荐：版本化库的渐进式迁移
namespace mylib {

// 老版本标记为 deprecated
namespace [[deprecated("Use v3 instead")]] v1 {
    class Service {
    public:
        void run() { /* 老实现 */ }
    };
}

// 当前版本（v2）保持 inline 一段时间
inline namespace v2 {
    class Service {
    public:
        void run() { /* 当前实现 */ }
    };
}

// 新版本（v3）准备中，暂不 inline
namespace v3 {
    class Service {
    public:
        void run() { /* 新实现 */ }
        void run_async();  // 新特性
    };
}

}  // namespace mylib

// 迁移步骤：
// 1. 发布 v3 命名空间，鼓励用户尝试
// 2. 收集反馈，修复问题
// 3. 将 v3 标记为 inline，v2 标记为 deprecated
// 4. 最终移除 v1，将 v2 移入 deprecated

8.6 C/C++ 互操作最佳实践

// c_api.h：C 兼容头文件
#ifndef MYLIB_C_API_H
#define MYLIB_C_API_H

#ifdef __cplusplus
extern "C" {
#endif

// 不透明句柄（opaque handle）
typedef struct mylib_service mylib_service;

// 生命周期管理
mylib_service* mylib_service_create();
void mylib_service_destroy(mylib_service* svc);

// 操作
int mylib_service_run(mylib_service* svc);
int mylib_service_configure(mylib_service* svc, int option);

// 错误处理
typedef enum {
    MYLIB_OK = 0,
    MYLIB_ERROR_INVALID_ARGUMENT = 1,
    MYLIB_ERROR_OUT_OF_MEMORY = 2,
    MYLIB_ERROR_INTERNAL = 3
} mylib_error_code;

const char* mylib_error_string(mylib_error_code code);

#ifdef __cplusplus
}  // extern "C"
#endif

#endif  // MYLIB_C_API_H

// c_api.cpp：C++ 实现
#include "c_api.h"
#include "service.h"  // C++ 实现
#include <new>

extern "C" {

struct mylib_service {
    mylib::Service cpp_service;
};

mylib_service* mylib_service_create() {
    try {
        auto* svc = new mylib_service();
        return svc;
    } catch (...) {
        return nullptr;
    }
}

void mylib_service_destroy(mylib_service* svc) {
    delete svc;
}

int mylib_service_run(mylib_service* svc) {
    if (!svc) return MYLIB_ERROR_INVALID_ARGUMENT;
    try {
        svc->cpp_service.run();
        return MYLIB_OK;
    } catch (const std::bad_alloc&) {
        return MYLIB_ERROR_OUT_OF_MEMORY;
    } catch (...) {
        return MYLIB_ERROR_INTERNAL;
    }
}

}  // extern "C"

8.7 模块化迁移（C++20）

// 推荐：渐进式迁移到 C++20 模块
// 第一步：保留头文件接口，内部使用模块
// mylib_legacy.h（兼容头文件）
#pragma once

namespace mylib {
    class Service {
    public:
        void run();
    };
}

// mylib_module.cppm（模块接口单元）
export module mylib;

import <iostream>;

export namespace mylib {

class Service {
public:
    void run() {
        std::cout << "Service running" << std::endl;
        internal_helper();
    }
};

}  // export namespace mylib

namespace mylib {
    void internal_helper() {
        std::cout << "internal" << std::endl;
    }
}

// 第二步：逐步替换头文件包含为模块导入
// 旧代码：#include "mylib.h"
// 新代码：import mylib;

8.8 命名约定与团队规范

推荐命名约定：

// 1. 库名作为顶层命名空间
namespace mylib {

// 2. 子模块用小写
namespace core {}
namespace util {}
namespace detail {}  // 实现细节

// 3. 版本用 v + 数字
inline namespace v3 {}
namespace v2 {}

// 4. 类型用 PascalCase
class HttpClient {}
struct ConfigData {}

// 5. 函数与变量用 snake_case
void send_request();
int connection_timeout;

// 6. 常量用 UPPER_SNAKE_CASE
constexpr int MAX_CONNECTIONS = 100;

// 7. 模板参数用 PascalCase 或 T/U
template<typename ElementType>
class Container {}

// 8. 宏用 UPPER_SNAKE_CASE（尽量避免使用宏）
#define MYLIB_VERSION_MAJOR 3

9. 案例分析

9.1 案例一：标准库的命名空间结构

C++ 标准库的命名空间结构是命名空间设计的典范：

namespace std {

// 核心组件直接位于 std
template<typename T> class vector;
template<typename T> class unique_ptr;
template<typename T> class shared_ptr;
class string;
class ostream;

// 子命名空间组织功能模块
namespace filesystem {
    class path;
    class directory_iterator;
}

namespace chrono {
    class system_clock;
    class steady_clock;
    using namespace literals::chrono_literals;
}

namespace ranges {
    namespace views {
        inline constexpr auto filter = /* ... */;
    }
}

namespace literals {
    namespace chrono_literals {
        constexpr chrono::seconds operator""s(unsigned long long);
    }
    namespace string_literals {
        std::string operator""s(const char*, std::size_t);
    }
}

// 实现细节（非标准）
namespace detail {  // 或 __detail、_VSTD
    template<typename T>
    void implementation_detail(T&&);
}

}  // namespace std

// 使用方
std::vector<int> v;
std::filesystem::path p;
std::chrono::seconds s(5);
using namespace std::literals;
auto s2 = 5s;  // chrono::seconds
auto str = "hello"s;  // std::string

设计分析：

1. 顶层 std：所有标准库内容位于 std，避免污染全局命名空间。
2. 子命名空间：功能模块（filesystem、chrono、ranges）组织相关类型。
3. 字面量命名空间：literals 组织用户定义字面量，通过 using namespace 启用。
4. 内联命名空间：chrono_literals 在 chrono 中是内联的，using namespace std::chrono 时自动启用。
5. 版本管理：标准库通过内联命名空间管理 ABI 兼容（如 std::__1 在 libc++ 中）。

9.2 案例二：Boost 库的命名空间设计

Boost 库是 C++ 库命名空间设计的参考标准：

namespace boost {

// 每个子库有独立命名空间
namespace filesystem {
    class path;
    class directory_entry;
}

namespace asio {
    namespace ip {
        class tcp;
        class udp;
    }
    class io_context;
}

// 版本管理较少使用，依赖库的演进
namespace program_options {
    class variables_map;
    class options_description;
}

// 实现细节
namespace detail {
    template<typename T>
    void implementation_detail(T&&);
}

}  // namespace boost

// 使用方
boost::filesystem::path p;
boost::asio::io_context ctx;
boost::asio::ip::tcp::socket sock(ctx);

设计分析：

1. 扁平化：Boost 子库各自管理命名空间，避免过度嵌套。
2. 模块独立：每个子库（filesystem、asio、program_options）是独立的库，可以单独使用。
3. 跨平台：Boost 通过命名空间隔离平台特化。

9.3 案例三：插件系统的外部链接设计

设计一个支持运行期加载的插件系统：

// plugin_api.h（插件接口，extern "C" 保证 ABI 稳定）
#ifndef PLUGIN_API_H
#define PLUGIN_API_H

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

// 插件接口版本
typedef struct {
    int major;
    int minor;
    int patch;
} plugin_version;

// 插件接口
typedef struct {
    plugin_version (*get_version)(void);
    const char* (*get_name)(void);
    int (*initialize)(void);
    void (*shutdown)(void);
    int (*process)(const char* input, char* output, size_t output_size);
} plugin_interface;

// 插件入口函数签名
typedef plugin_interface* (*plugin_create_fn)(void);
typedef void (*plugin_destroy_fn)(plugin_interface*);

// 插件入口函数名约定
#define PLUGIN_CREATE_SYMBOL  "plugin_create"
#define PLUGIN_DESTROY_SYMBOL "plugin_destroy"

#ifdef __cplusplus
}
#endif

#endif  // PLUGIN_API_H

// my_plugin.cpp（插件实现，C++）
#include "plugin_api.h"
#include <string>
#include <iostream>

namespace my_plugin {

class MyPlugin {
public:
    plugin_version get_version() {
        return {1, 0, 0};
    }

    const char* get_name() {
        return "My Awesome Plugin";
    }

    int initialize() {
        std::cout << "[MyPlugin] initialized" << std::endl;
        return 0;
    }

    void shutdown() {
        std::cout << "[MyPlugin] shutdown" << std::endl;
    }

    int process(const char* input, char* output, size_t output_size) {
        std::string result = std::string("processed: ") + input;
        if (result.size() >= output_size) return -1;
        std::copy(result.begin(), result.end(), output);
        output[result.size()] = '\0';
        return 0;
    }
};

// 全局插件实例
static MyPlugin g_plugin;
static plugin_interface g_interface;

}  // namespace my_plugin

// extern "C" 入口点
extern "C" {

plugin_interface* plugin_create() {
    my_plugin::g_interface.get_version = [](void) -> plugin_version {
        return my_plugin::g_plugin.get_version();
    };
    my_plugin::g_interface.get_name = [](void) -> const char* {
        return my_plugin::g_plugin.get_name();
    };
    my_plugin::g_interface.initialize = [](void) -> int {
        return my_plugin::g_plugin.initialize();
    };
    my_plugin::g_interface.shutdown = [](void) {
        my_plugin::g_plugin.shutdown();
    };
    my_plugin::g_interface.process = [](const char* input, char* output, size_t output_size) -> int {
        return my_plugin::g_plugin.process(input, output, output_size);
    };
    return &my_plugin::g_interface;
}

void plugin_destroy(plugin_interface* iface) {
    // 静态实例，无需释放
    (void)iface;
}

}  // extern "C"

// plugin_loader.cpp（加载器，使用 dlopen/LoadLibrary）
#include "plugin_api.h"
#include <iostream>
#include <string>

#ifdef _WIN32
#include <windows.h>
#else
#include <dlfcn.h>
#endif

class PluginLoader {
public:
    PluginLoader(const std::string& path) : handle_(nullptr), interface_(nullptr) {
#ifdef _WIN32
        handle_ = LoadLibraryA(path.c_str());
#else
        handle_ = dlopen(path.c_str(), RTLD_LAZY);
#endif
        if (!handle_) {
            std::cerr << "Failed to load plugin: " << path << std::endl;
            return;
        }

        auto create_fn = (plugin_create_fn)resolve(PLUGIN_CREATE_SYMBOL);
        if (!create_fn) return;

        interface_ = create_fn();
    }

    ~PluginLoader() {
        if (interface_ && handle_) {
            auto destroy_fn = (plugin_destroy_fn)resolve(PLUGIN_DESTROY_SYMBOL);
            if (destroy_fn) destroy_fn(interface_);
        }
        if (handle_) {
#ifdef _WIN32
            FreeLibrary((HMODULE)handle_);
#else
            dlclose(handle_);
#endif
        }
    }

    plugin_interface* operator->() { return interface_; }
    explicit operator bool() const { return interface_ != nullptr; }

private:
    void* resolve(const char* name) {
#ifdef _WIN32
        return GetProcAddress((HMODULE)handle_, name);
#else
        return dlsym(handle_, name);
#endif
    }

    void* handle_;
    plugin_interface* interface_;
};

int main() {
    PluginLoader loader("./my_plugin.dll");  // 或 .so
    if (!loader) {
        std::cerr << "Failed to load plugin" << std::endl;
        return 1;
    }

    auto version = loader->get_version();
    std::cout << "Plugin version: " << version.major << "."
              << version.minor << "." << version.patch << std::endl;
    std::cout << "Plugin name: " << loader->get_name() << std::endl;

    if (loader->initialize() != 0) {
        std::cerr << "Initialization failed" << std::endl;
        return 1;
    }

    char output[256];
    if (loader->process("hello", output, sizeof(output)) == 0) {
        std::cout << "Result: " << output << std::endl;
    }

    loader->shutdown();
    return 0;
}

设计分析：

1. ABI 稳定：extern "C" 接口保证跨编译器、跨版本 ABI 稳定。
2. C++ 实现：插件内部使用 C++ 实现，通过适配层转换为 C 接口。
3. 运行期加载：dlopen/LoadLibrary 实现运行期动态加载，无需重编译主程序。
4. 版本协商：get_version 接口允许加载器检查插件版本兼容性。
5. 错误隔离：C 接口不允许异常泄漏，所有错误通过返回码传递。

9.4 案例四：版本化库的迁移

设计一个版本化库，支持多版本并存与平滑迁移：

// versioned_lib.h
#pragma once
#include <iostream>

namespace mylib {

// 最老版本（v1），标记为 deprecated
namespace [[deprecated("Use v2 or later")]] v1 {
    class Service {
    public:
        void run() { std::cout << "v1::Service::run" << std::endl; }
        // v1 的 API 有缺陷
    };
}

// 当前版本（v2），标记为 inline
inline namespace v2 {
    class Service {
    public:
        void run() { std::cout << "v2::Service::run" << std::endl; }
        void run_async() { std::cout << "v2::Service::run_async" << std::endl; }
    };
}

// 新版本（v3），准备中
namespace v3 {
    class Service {
    public:
        void run() { std::cout << "v3::Service::run" << std::endl; }
        void run_async() { std::cout << "v3::Service::run_async" << std::endl; }
        void run_with_timeout(int ms) {  // 新特性
            std::cout << "v3::Service::run_with_timeout(" << ms << ")" << std::endl;
        }
    };
}

}  // namespace mylib

// 使用方
void legacy_usage() {
    // 老代码，使用 v1
    mylib::v1::Service s;
    s.run();  // 编译警告：deprecated
}

void current_usage() {
    // 当前代码，使用默认版本（v2）
    mylib::Service s;
    s.run();
    s.run_async();
}

void experimental_usage() {
    // 尝试新版本（v3）
    mylib::v3::Service s;
    s.run();
    s.run_async();
    s.run_with_timeout(1000);
}

// 迁移流程：
// 1. 发布 v3，鼓励用户尝试
// 2. 收集反馈，修复问题
// 3. 将 v3 标记为 inline，v2 标记为 deprecated
// 4. 最终移除 v1

9.5 案例五：C++/C 混合项目的链接管理

一个典型的 C++/C 混合项目，需要正确管理链接性：

// utils.h（C++ 头文件）
#pragma once

namespace utils {

// 内联函数（外部链接，定义在头文件中）
inline int fast_abs(int x) {
    return x < 0 ? -x : x;
}

// constexpr 变量（C++17 起隐式 inline，外部链接）
inline constexpr int MAX_SIZE = 1024;

// 函数声明（定义在 .cpp 中，外部链接）
void log_message(const char* msg);

// 内部工具函数（匿名命名空间，内部链接）
namespace {
    inline int internal_helper(int x) { return x * 2; }
}

}  // namespace utils

// utils.cpp
#include "utils.h"
#include <cstdio>

namespace utils {

void log_message(const char* msg) {
    std::printf("[utils] %s\n", msg);
}

}  // namespace utils

// legacy_c.h（C 兼容头文件）
#ifndef LEGACY_C_H
#define LEGACY_C_H

#ifdef __cplusplus
extern "C" {
#endif

void c_log_message(const char* msg);

#ifdef __cplusplus
}
#endif

#endif

// legacy_c.c（C 源文件）
#include "legacy_c.h"
#include <stdio.h>

void c_log_message(const char* msg) {
    printf("[c] %s\n", msg);
}

// main.cpp
#include "utils.h"
#include "legacy_c.h"

int main() {
    utils::log_message("hello from C++");  // 外部链接
    c_log_message("hello from C");          // extern "C"
    int x = utils::fast_abs(-42);           // 内联函数
    int y = utils::MAX_SIZE;                // 内联变量
    int z = utils::internal_helper(21);     // 匿名命名空间（内部链接）
    return 0;
}

链接性分析：

10. 练习与参考答案

10.1 练习一：命名空间基础

题目：给定以下代码，指出所有错误并修复。

#include <iostream>

namespace a {
    int x = 1;
    namespace b {
        int x = 2;
        int y = 3;
    }
}

int main() {
    using namespace a;
    using namespace a::b;
    std::cout << x << std::endl;  // 期望输出？
    return 0;
}

参考答案：

代码存在歧义错误。using namespace a; 引入 a::x，using namespace a::b; 引入 a::b::x，两者都叫 x，导致 std::cout << x 存在歧义。

修复方案：

int main() {
    using namespace a;
    using namespace a::b;
    std::cout << a::x << std::endl;      // 显式限定，输出 1
    std::cout << a::b::x << std::endl;   // 显式限定，输出 2
    std::cout << y << std::endl;         // 无歧义，输出 3
    return 0;
}

10.2 练习二：ADL 分析

题目：给定以下代码，分析每次 swap 调用实际调用的是哪个函数。

#include <algorithm>
#include <utility>

namespace mylib {
    class Buffer {};

    void swap(Buffer&, Buffer&) { /* 自定义实现 */ }
}

void test() {
    mylib::Buffer a, b;
    std::swap(a, b);        // (1)
    using std::swap;
    swap(a, b);             // (2)
    using namespace std;
    swap(a, b);             // (3)
}

参考答案：

• (1) std::swap(a, b)：显式限定，调用 std::swap，内部可能调用 mylib::swap（如果 std::swap 实现使用 ADL）。
• (2) swap(a, b)：惯用法 using std::swap; swap(a, b);，ADL 优先匹配 mylib::swap（因为实参类型是 mylib::Buffer）。
• (3) swap(a, b)：using namespace std 后，std::swap 进入候选，但 ADL 仍找到 mylib::swap，重载决议选择更匹配的 mylib::swap。

推荐写法：使用 (2) 的惯用法，这是 C++ 标准推荐的自定义 swap 调用方式。

10.3 练习三：链接性判断

题目：判断以下每个实体的链接性（无链接/内部链接/外部链接）。

// header.h
#pragma once

int global_var;                    // (1)
static int file_local_var;         // (2)
const int const_var = 42;          // (3)
constexpr int constexpr_var = 42; // (4)
inline int inline_var = 42;       // (5)

void function();                   // (6)
static void static_function();    // (7)
inline void inline_function() {}  // (8)

namespace {
    int anon_var;                  // (9)
    void anon_function() {}        // (10)
}

class Class {};                    // (11)
namespace ns { void ns_func(); }   // (12)

extern "C" void c_function();      // (13)

void function() {                  // (14) 定义
    int local_var;                 // (15)
    static int static_local;       // (16)
}

参考答案：

10.4 练习四：匿名命名空间 vs static

题目：以下两段代码有何差异？哪种更推荐？

// 代码 A
namespace {
    class Helper {
    public:
        void do_work() {}
    };

    template<typename T>
    T identity(T x) { return x; }

    int counter = 0;
}

// 代码 B
static class Helper {
public:
    void do_work() {}
} helper_instance;

static int counter = 0;
// static template<typename T> T identity(T x);  // 错误：static 不能修饰模板

参考答案：

差异：

1. 代码 A 可以定义类型（class Helper）并具有内部链接。
2. 代码 B 中 static class Helper 是一个静态对象实例，而非类定义——static 不能修饰类定义。
3. 代码 A 可以定义模板（identity），代码 B 不能——static 不能修饰模板。
4. 代码 A 的类定义可用于声明变量：Helper h;；代码 B 只有一个 helper_instance 实例。

推荐：使用代码 A（匿名命名空间），因为：

1. 语义统一——同一翻译单元内的所有内部链接实体使用相同机制。
2. 可应用于所有实体——类型、模板、函数、变量。
3. 现代风格——C++ 标准与风格指南（如 Google C++ Style Guide）推荐使用匿名命名空间。

10.5 练习五：extern "C" 重载

题目：为什么以下代码编译错误？

extern "C" {
    int process(int x);
    int process(double x);  // 编译错误
}

参考答案：

C 语言不支持函数重载——同名函数只能有一个。extern "C" 禁用 C++ 名称修饰，使函数符号为 process（无参数信息），因此两个 process 重载会产生相同的符号，导致链接冲突。

解决方法：

extern "C" {
    int process_int(int x);
    int process_double(double x);
}

// 或使用 C++ 链接（不使用 extern "C"），但这会丧失 ABI 稳定性
int process(int x);
int process(double x);

10.6 练习六：内联命名空间与 ABI

题目：以下代码在升级版本时，如何保证二进制兼容性？

// v1.0
namespace mylib {
    class Service {
    public:
        void run();
    };
}

// v2.0：想修改 Service 的实现
namespace mylib {
    class Service {
    public:
        void run();
        void run_async();  // 新增
    };
}

参考答案：

直接修改 Service 类可能导致 ABI 不兼容——新增虚函数、修改成员布局都会破坏二进制兼容性。推荐使用内联命名空间管理版本：

// v1.0（发布时）
namespace mylib {
    inline namespace v1 {
        class Service {
        public:
            void run();
        };
    }
}

// v2.0（升级时）
namespace mylib {
    namespace v1 {
        class Service {  // 老版本，保留
        public:
            void run();
        };
    }

    inline namespace v2 {  // 新版本，标记为 inline
        class Service {
        public:
            void run();
            void run_async();
        };
    }
}