模块接口单元与实现单元
什么是模块单元
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 分离,但机制不同。接口单元包含声明(和可选的定义),实现单元提供定义。
// ============================
// 文件: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关键字 - 可以有多个实现单元
- 修改实现单元不需要重新编译依赖模块的代码(只要接口不变)
// ============================
// 多个实现单元
// ============================
// 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;
}模块分区
分区是模块内部的组织方式,用于把一个大模块拆分成多个文件。分区名用冒号 : 分隔。
接口分区
// ============================
// 文件: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();内部分区
内部分区(实现分区)用于在模块内部的不同单元之间共享声明,但不对外导出。
// ============================
// 文件: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; 标记私有模块片段。私有片段中的定义不影响模块的接口——修改私有片段不需要重新编译导入方。
// ============================
// 单文件模块(带私有片段)
// ============================
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 - 分区只能在同一模块内导入
- 私有模块片段只能在单文件模块中使用
- 编译顺序必须遵循依赖关系
编译器支持情况
| 编译器 | 最低支持版本 | 分区支持 | 私有片段支持 |
|---|---|---|---|
| MSVC | 19.28 | 支持 | 支持 |
| GCC | 11.0 | 基本支持 | 支持 |
| Clang | 16.0 | 基本支持 | 支持 |
总结
C++20 模块单元分为四种类型:主接口单元、接口分区、实现单元、内部分区。主接口单元(export module M;)是模块的入口,每个模块只能有一个。接口分区(export module M:Part;)用于拆分大型接口,必须被主接口单元重新导出。实现单元(module M;)提供函数和类的定义,隐式导入主接口单元,不能使用 export。内部分区(module M:Part;)在模块内部的多个单元之间共享代码,但不对外导出。这种分层结构让模块既可以像传统的 .h/.cpp 那样分离接口和实现,又提供了更灵活的内部组织方式。修改实现单元不影响模块接口,因此不需要重新编译依赖方。