MonoGame 移植：一文件一类型纪律与文件结构拆分

问题：C++ 移植时"合并"很诱人，但会偏离上游

#

移植初期，为了方便，把功能相近的类型合并到了同一个头文件里：

graphics_resources.hpp  ← 塞了 12 个类（Texture2D/3D/Cube/RenderTarget×3/VertexBuffer/...）
graphics_states.hpp     ← 塞了 6 个类（BlendState/DepthStencilState/...）

看起来"高效"，但有个根本问题：上游 C# 每个类型是独立文件，合并后代码结构与上游对不上。上游更新、对照审查、逐行比对都会变得困难。

确立的纪律

#

每个 C# 文件对应一个 C++ 头文件（一文件一类型），杜绝跨文件合并。

唯一豁免：MathHelper + Random——它们是嵌套且平台无关的 partial 整合（MathHelper.cs 跨文件合并了 Random 相关方法），这类整合允许保留。

拆分怎么做

#

以 graphics_resources.hpp（12 类型）为例，按 C# 源结构拆成独立文件：

原聚合文件改为转发头（只 include 各独立文件，不含任何类型定义），兼容既有引用。

枚举也按 C# 源码结构独立成文件

#

VertexElementUsage 这类枚举同样遵循——独立成 vertex_element_usage.hpp，而不是塞进使用它的类里：

// vertex_element_usage.hpp：独立文件（对应 C# VertexElementUsage.cs）
enum class VertexElementUsage {
    kPosition = 0,
    kColor,
    // ...
};

这样做的另一个好处：避免重复定义——曾有两个文件各自定义了 VertexElementUsage（同命名空间），全量包含时直接 redefinition 编译错误，拆分后从根上消除。

拆分后验证

#

• 21 个平台层基类全部独立成文件
• 34 cpp 编译链接成功（无未定义符号）
• 修复了拆分过程中引入的一个小 bug（转发文件残留的悬空 };）

小结

#

“一文件一类型"不是洁癖，是移植工程的可维护性底线——它让"逐行对照 C# 源码审查"成为可能，也让后续批量更新（上游升级、枚举补充）可以精确到文件。