# 项目约定规范（接口层 / 实现层）

what every programmer should know about memory

本文档用于统一本项目在 `EngineAPI`、`Components`、`Platform`、`Utilities` 等目录下的设计与编码约定，重点规范“接口层与实现层分离”。

## 1. 分层职责约定

### 1.1 EngineAPI 层（对外契约层）

- 只暴露稳定接口：强类型 ID、句柄类、对外可调用的 API。
- 不暴露内部容器与存储细节，不暴露运行时池结构。
- 允许声明行为，不实现复杂运行逻辑。
- 头文件应可被上层模块直接 include，尽量减少内部依赖。

示例：
- `Engine/EngineAPI/ScriptComponent.h`：仅定义 `script_id` 与 `script::component` 句柄。

### 1.2 Components 层（运行时实现层）

- 实现组件生命周期：`create/remove/update`。
- 管理内部存储：数组、映射、空闲队列、代数校验。
- 对外只通过 API 层句柄交互，不向外泄露内部布局。
- 允许高性能实现细节（如 `erase_unordered`、缓存表、延迟提交）。

示例：
- `Engine/Components/Script.h/.cpp`：实现脚本创建、删除、逐帧更新和注册表逻辑。

### 1.3 Platform 层（平台适配层）

- 只处理操作系统相关对象与流程（如 Win32 `HWND`、消息循环、窗口样式）。
- 上层通过抽象类型访问，不直接依赖平台原生类型。
- 平台特有分支必须受平台宏保护（如 `_WIN64`）。

### 1.4 Utilities 层（通用基础层）

- 提供与业务无关的数学、容器、IO、工具函数。
- 不耦合具体业务组件，不反向依赖高层模块。

## 2. 文件组织约定

### 2.1 命名与位置

- 对外契约放 `EngineAPI`，运行时实现放 `Components`。
- 头文件与实现文件成对组织：`Xxx.h` / `Xxx.cpp`。
- 公共依赖入口统一放在模块公共头（如 `ComponentsCommon.h`）。

### 2.2 include 方向

- 允许 `Components -> EngineAPI` 依赖。
- 禁止 `EngineAPI -> Components` 反向依赖实现细节。
- `Utilities` 不应依赖 `Components` 或 `Platform`。

### 2.3 前向声明优先

- 能前向声明时不直接 include 重头文件。
- 对外头文件避免引入不必要实现依赖，控制编译扇出。

## 3. 类型与句柄约定

### 3.1 强类型 ID

- 所有核心对象 ID 使用强类型封装（`DEFINE_TYPED_ID`）。
- 禁止在模块边界裸传 `u32` 作为对象标识。
- 必须通过 `is_valid` / `generation` 做有效性校验。

### 3.2 句柄对象

- 对外使用轻量句柄（如 `script::component`、`game_entity::entity`）。
- 句柄仅保存 ID，不保存大对象数据。
- 句柄方法可转发到实现层查询真实数据。

## 4. 生命周期与存储约定

### 4.1 创建与删除

- `create` 负责分配 ID、构造实例、建立映射。
- `remove` 必须清理映射、回收槽位、更新空闲队列。
- 必须保证删除后旧句柄不可通过代数校验。

### 4.2 映射一致性

- 使用 `id_mapping` 时必须保证：
  - `id -> 索引` 映射存在且越界受保护；
  - 交换删除后映射及时回填；
  - 无效 ID 显式写回 `invalid_id`。

### 4.3 批处理更新

- 高频写入优先使用缓存并批量提交（如脚本修改 Transform 后统一提交）。
- 帧内缓存必须在提交后清空，避免跨帧污染。

## 5. 脚本系统专项约定

### 5.1 注册机制

- 脚本类型通过统一宏注册（`REGISTER_SCRIPT(TYPE)`）。
- 注册信息至少包含：类型名哈希、工厂函数指针。
- 编辑器模式下可额外导出脚本名列表。

### 5.2 工厂机制

- 统一使用 `script_creator` 创建脚本实例。
- 禁止外部直接 new 并绕过组件创建流程。
- 工厂函数签名保持稳定，避免跨模块 ABI 漂移。

## 6. 注释与文档约定

### 6.1 文件头注释

- 使用 `@file` + `@brief` + `@details`。
- `@details` 需说明职责边界、数据流、关键约束。

### 6.2 函数注释

- 对核心函数标注参数、返回值、副作用。
- 对平台参数表、结构体字段允许保留逐行行尾注释。
- 禁止乱码注释；统一 UTF-8 编码保存。

## 7. 可维护性与扩展性约定

- 先保证接口稳定，再演进实现细节。
- 扩展新组件时，优先复用现有 ID/句柄/生命周期模式。
- 变更跨层关系时必须先更新本规范文档与对应模块分析文档。

## 8. 变更检查清单（提交前）

- 是否保持 `EngineAPI` 与 `Components` 的边界不反转。
- 是否新增了不必要 include 或扩大了依赖扇出。
- 是否破坏了 ID 代数校验与映射一致性。
- 是否补齐了注释并确保无乱码。
- 是否与现有目录结构与命名风格一致。
