模块接口单元与实现单元 ​

什么是模块单元 ​

C++20 中,包含模块声明的翻译单元叫做模块单元(Module Unit)。模块单元按两个维度分类:是否是接口(interface vs implementation)、是否是分区(partition vs non-partition)。这两个维度正交组合,产生四种模块单元类型。

四种模块单元 ​

类型声明形式能否导出能否被模块外导入数量限制
主接口单元export module M;能能(import M;)每个模块恰好一个
接口分区单元export module M:Part;能不能(只能模块内导入)可以多个
实现单元module M;不能不能可以多个
内部分区单元module M:Part;不能不能(只能模块内导入)可以多个

核心区别:

  • 接口单元(有 export):可以导出声明,构成模块的公开接口
  • 实现单元(无 export):不能导出声明,只提供实现

接口与实现分离 ​

模块接口单元和实现单元的分离类似于传统的 .h / .cpp 分离,但机制不同。接口单元包含声明(和可选的定义),实现单元提供定义。

cpp
// ============================
// 文件:mathlib.cppm(主接口单元)
// ============================
export module mathlib;  // 主接口单元

// 导出函数声明(不含定义)
export int add(int a, int b);
export int subtract(int a, int b);
export int multiply(int a, int b);
export double divide(double a, double b);

// 导出类声明
export class Calculator {
public:
    Calculator();
    int compute(int a, int b) const;
    void reset();
private:
    int last_result_;
};

// ============================
// 文件:mathlib.cpp(实现单元)
// ============================
module mathlib;  // 实现单元,隐式导入主接口单元

// 不需要再写 export,直接提供函数定义
int add(int a, int b) {
    return a + b;
}

int subtract(int a, int b) {
    return a - b;
}

int multiply(int a, int b) {
    return a * b;
}

double divide(double a, double b) {
    if (b == 0.0) return 0.0;
    return a / b;
}

// 类成员函数的定义
Calculator::Calculator() : last_result_(0) {}

int Calculator::compute(int a, int b) const {
    return a + b;
}

void Calculator::reset() {
    last_result_ = 0;
}

// ============================
// 文件:main.cpp(使用方)
// ============================
import mathlib;

#include <iostream>

int main() {
    std::cout << add(3, 4) << std::endl;

    Calculator calc;
    std::cout << calc.compute(10, 20) << std::endl;

    return 0;
}

实现单元的特点 ​

实现单元用 module M;(不带 export)声明。它有几个重要特性:

  • 隐式导入主接口单元——不需要也不能写 import M;
  • 可以访问主接口单元中所有导出的声明
  • 不能使用 export 关键字
  • 可以有多个实现单元
  • 修改实现单元不需要重新编译依赖模块的代码(只要接口不变)
cpp
// ============================
// 多个实现单元
// ============================

// mathlib_basic.cpp(实现单元1)
module mathlib;

int add(int a, int b) { return a + b; }
int subtract(int a, int b) { return a - b; }

// mathlib_advanced.cpp(实现单元2)
module mathlib;

int multiply(int a, int b) { return a * b; }
double divide(double a, double b) {
    if (b == 0.0) return 0.0;
    return a / b;
}

模块分区 ​

分区是模块内部的组织方式,用于把一个大模块拆分成多个文件。分区名用冒号 : 分隔。

接口分区 ​

cpp
// ============================
// 文件:graphics-shapes.cppm(接口分区)
// ============================
export module graphics:shapes;  // 模块 graphics 的接口分区 shapes

export struct Circle {
    double radius;
    double area() const;
};

export struct Rectangle {
    double width, height;
    double area() const;
};

// ============================
// 文件:graphics-colors.cppm(接口分区)
// ============================
export module graphics:colors;  // 模块 graphics 的接口分区 colors

export struct Color {
    unsigned char r, g, b, a;
};

export Color make_color(unsigned char r, unsigned char g, unsigned char b);

// ============================
// 文件:graphics.cppm(主接口单元)
// ============================
export module graphics;

// 主接口单元必须导入并重新导出所有接口分区
export import :shapes;
export import :colors;

// 也可以在主接口单元中添加更多导出
export void initialize_graphics();

内部分区 ​

内部分区(实现分区)用于在模块内部的不同单元之间共享声明,但不对外导出。

cpp
// ============================
// 文件:graphics-internal.cpp(内部分区)
// ============================
module graphics:internal;  // 内部分区,不能导出

// 这些声明只在模块内部可见
constexpr double PI = 3.14159265358979;

double clamp(double value, double min_val, double max_val) {
    if (value < min_val) return min_val;
    if (value > max_val) return max_val;
    return value;
}

// ============================
// 文件:graphics-impl.cpp(实现单元)
// ============================
module graphics;

import :internal;  // 导入内部分区,获得 PI 和 clamp

// 使用内部分区中的声明来实现接口
double Circle::area() const {
    return PI * radius * radius;
}

double Rectangle::area() const {
    return width * height;
}

Color make_color(unsigned char r, unsigned char g, unsigned char b) {
    return Color{r, g, b, 255};
}

void initialize_graphics() {
    // 初始化逻辑...
}

各单元之间的可见性关系 ​

从 \ 到主接口单元的导出接口分区的导出内部分区的声明实现单元的内部声明
模块外部可见(通过 import M)可见(通过主接口重新导出)不可见不可见
实现单元可见(隐式导入)可见(需要 import :Part)可见(需要 import :Part)不可见(各实现单元独立)
接口分区不可见(除非显式导入)可见(需要 import :Part)可见(需要 import :Part)不可见

私有模块片段 ​

当整个模块只有一个翻译单元时,可以用 module : private; 标记私有模块片段。私有片段中的定义不影响模块的接口——修改私有片段不需要重新编译导入方。

cpp
// ============================
// 单文件模块(带私有片段)
// ============================
export module simple_math;

// 接口部分
export int factorial(int n);
export int fibonacci(int n);

// 私有模块片段——修改这里不影响导入方
module : private;

int factorial(int n) {
    int result = 1;
    for (int i = 2; i <= n; ++i) {
        result *= i;
    }
    return result;
}

int fibonacci(int n) {
    if (n <= 1) return n;
    int a = 0, b = 1;
    for (int i = 2; i <= n; ++i) {
        int next = a + b;
        a = b;
        b = next;
    }
    return b;
}

私有模块片段的限制:只能在不包含分区的单文件模块中使用。如果模块有分区或多个翻译单元,不能使用私有模块片段。

编译顺序 ​

模块的编译顺序必须遵循依赖关系:

1. 内部分区(如果被接口分区依赖)
2. 接口分区
3. 主接口单元
4. 实现单元
5. 导入模块的外部翻译单元

接口单元必须在实现单元之前编译,被导入的分区必须在导入它的单元之前编译。

适用场景 ​

  • 大型模块拆分:用接口分区和内部分区组织代码
  • 接口/实现分离:接口单元声明 API,实现单元提供定义
  • 模块内部共享:用内部分区在不同实现文件间共享辅助函数
  • 单文件小模块:用私有模块片段在一个文件中完成接口和实现的分离

常见问题 ​

实现单元需要写 import M 吗?

不需要,也不能写。实现单元(module M;)会隐式导入主接口单元。如果你写了 import M;,编译器会报错。

接口分区必须被主接口单元重新导出吗?

标准要求所有接口分区都必须被主接口单元直接或间接地 export import。如果有接口分区没被重新导出,程序是非良构的(编译器不一定报错)。

可以有多个实现单元吗?

可以。一个模块可以有任意数量的实现单元(module M;),它们共享主接口单元的声明。

内部分区和实现单元有什么区别?

内部分区有名字(:PartName),可以被其他模块单元通过 import :PartName 导入。普通实现单元没有名字,不能被其他单元导入。内部分区适合在多个实现文件之间共享代码。

修改实现单元需要重新编译导入方吗?

不需要,只要接口没变。这是接口/实现分离的核心好处。

注意事项 ​

  • 每个命名模块必须有且仅有一个主接口单元
  • 实现单元不能使用 export
  • 实现单元隐式导入主接口单元,不要重复写 import M;
  • 所有接口分区必须在主接口单元中被 export import
  • 内部分区不能被 export import
  • 分区只能在同一模块内导入
  • 私有模块片段只能在单文件模块中使用
  • 编译顺序必须遵循依赖关系

编译器支持情况 ​

编译器最低支持版本分区支持私有片段支持
MSVC19.28支持支持
GCC11.0基本支持支持
Clang16.0基本支持支持

总结 ​

C++20 模块单元分为四种类型:主接口单元、接口分区、实现单元、内部分区。主接口单元(export module M;)是模块的入口,每个模块只能有一个。接口分区(export module M:Part;)用于拆分大型接口,必须被主接口单元重新导出。实现单元(module M;)提供函数和类的定义,隐式导入主接口单元,不能使用 export。内部分区(module M:Part;)在模块内部的多个单元之间共享代码,但不对外导出。这种分层结构让模块既可以像传统的 .h/.cpp 那样分离接口和实现,又提供了更灵活的内部组织方式。修改实现单元不影响模块接口,因此不需要重新编译依赖方。