C++ 命名空間完整指南：定義、using 指令、巢狀、內聯、匿名與 ADL 參數依賴查找

命名空間解決符號衝突、組織代碼邏輯結構。本文涵蓋定義、using 指令/聲明、巢狀命名空間、內聯命名空間 (版本管理)、匿名命名空間 (內部鏈接)、ADL (Argument-Dependent Lookup) 完整機制。

基本定義與使用

namespace Geometry {
    constexpr double PI = 3.14159;
    double area(double r) { return PI * r * r; }
    namespace Circle { double circumference(double r) { return 2 * PI * r; } }
}

// 使用
Geometry::area(5.0);
using namespace Geometry; // 引入所有符號
area(5.0); // 直接可用
using Geometry::PI; // 僅引入 PI
using Circle = Geometry::Circle; // 命名空間別名 (C++17)

using 指令 vs using 聲明

巢狀命名空間 (C++17 縮寫語法)

// 傳統
namespace A { namespace B { namespace C { int value = 42; } } }
// C++17
namespace A::B::C { int value = 42; }

// 訪問
A::B::C::value;
using namespace A::B::C; // 引入 C 內符號，A、B 不受影響
using namespace A::B;   // 引入 B 及其巢狀 C 符號

內聯命名空間：版本管理神器

namespace Library {
    inline namespace V2 { // 內聯：符號自動提升到父命名空間
        void func() { std::cout << "V2\n"; }
    }
    namespace V1 { // 非內聯：需顯式 Library::V1::func()
        void func() { std::cout << "V1\n"; }
    }
}
// 使用
Library::func(); // 自動調用 V2::func()
// 兼容舊代碼
Library::V1::func(); // 仍可顯式調用 V1

• 標準庫大量使用：std::chrono::literals、std::filesystem (C++17 inline namespace std::filesystem)。
• ABI 兼容：升級庫版本時，新版本放入內聯命名空間，舊版本保留，用戶代碼無需修改即用新版，需舊版者顯式限定。

匿名命名空間：內部鏈接替代 static

// file.cpp
namespace { // 唯一命名空間，每個編譯單元獨立
    int internal_counter = 0;
    void helper() { /* 內部實現 */ }
}
// 外部無法訪問 internal_counter、helper
// 等價於 static int internal_counter; static void helper();

• 優於 static：可包裝類、模板、重載函數，不僅限變數/函數。
• 單元測試友善：測試檔可通過 #include "file.cpp" 訪問 (不推薦生產)。

ADL (Argument-Dependent Lookup) / Koenig 查找

namespace NS {
    struct X {};
    void swap(X&, X&) { std::cout << "NS::swap\n"; } // 自定義 swap
}

int main() {
    NS::X a, b;
    swap(a, b); // 未限定 swap，但 ADL 在 NS 中找到 swap(NS::X&, NS::X&)
    // 等價於 NS::swap(a, b);
}

ADL 查找規則

1. 收集實參類型的關聯命名空間：類所在命名空間、模板參數類型命名空間、基類命名空間、枚舉類型命名空間。
2. 在關聯命名空間中查找同名函數。
3. 與普通查找 (using 指令、全域) 合併，構成候選集，進行重載決議。

ADL 經典應用

• std::swap、std::begin/end、operator<</>>、get/put (ADL 自定義點)。
• 標準庫算法接受自定義類型時，通過 ADL 找到用戶提供的 swap、hash、to_string 等。

ADL 陷阱與防範

namespace Lib {
    struct Widget {};
    void process(Widget); // 庫內部函數
}

void process(int); // 全域重載

int main() {
    Lib::Widget w;
    process(w); // ADL 找到 Lib::process(Widget) ✓
    // 但若全域有 process(Lib::Widget) 會衝突
    // 防範：在調用點用 (void)process(w); 強制普通查找，或 using Lib::process; 明確引入
}

最佳實踐總結

• 頭文件禁用 using namespace，僅用 using N::symbol 或完全限定名。
• 庫設計：公開 API 放在頂層命名空間，實現細節放在 detail 子命名空間。
• 版本演進：內聯命名空間 實現無縫升級。
• 編譯單元內部符號：匿名命名空間。
• 自定義點 (swap, hash, begin) 必須與類型放在同一命名空間 以便 ADL 找到。