# 🧱 Common 公共模块

------

## 📖 概述

Common 模块是项目中最基础、最核心的模块，包含通用工具类、配置文件、扩展方法及基础系统组件。**所有其他模块都应依赖此模块**，务必在拉取其他模块前先行安装。

------

## 📁 功能总览

- ✅ 项目配置管理
- ✅ 单例模式基类（支持非Mono与Mono行为）
- ✅ 常用工具类（加解密、日志、时间、设备信息）
- ✅ 扩展方法（数组、字符串、枚举等）
- ✅ 编辑器工具（自动生成配置文件）
- ✅ GM工具相关支持

------

## ⚙️ 核心系统详解

### 🧩 配置文件系统（GameConfig, NetworkConfig）

📌 通过菜单栏 `SwhiteGames > Create GameConfig` 可在 `Resources/` 目录下自动创建 `GameConfig` 文件，包含以下配置字段：

| 字段名        | 含义说明                                  |
| ------------- | ----------------------------------------- |
| `PackageName` | 游戏包名                                  |
| `IsRelease`   | 是否为正式发布包（关联宏 `GAME_RELEASE`） |
| `EnabledLog`  | 是否启用日志打印                          |

📦 获取配置示例：

```csharp
var enabledLog = ConfigManager.GameConfig?.enabledLog;
var packageName = ConfigManager.GameConfig?.packageName;
```

------


📌 通过菜单栏 `SwhiteGames > Create NetworkConfig` 可在 `Resources/` 目录下自动创建 `NetworkConfig` 文件，包含以下配置字段：

| 字段名        | 含义说明     |
| ------------- |----------|
| `showNetworkLog`  | 是否启用日志打印 |
| `debugHost`   | 测试环境Host |
| `releaseHost` | 正式环境Host |
| `connectionMode`  | 连接模式     |

📦 获取配置示例：

```csharp
var connectionMode = ConfigManager.NetworkConfig?.connectionMode;
var showNetworkLog = ConfigManager.NetworkConfig?.showNetworkLog;
```

------
### 🔁 单例系统

- **SingletonMonoBehaviour**：MonoBehaviour 单例，自动创建 GameObject，跨场景不销毁

```csharp
// MonoBehaviour
public class AudioManager : SingletonMonoBehaviour<AudioManager> { ... }
```

------

### 🛠️ 工具类一览（Helper）

| 类名              | 功能说明                                    |
| ----------------- | ------------------------------------------- |
| `Log`             | ✅日志打印（开发调试利器）                   |
| `Cryptor`         | 🔐 加密解密支持（对称加密）                  |
| `TimeHelper`      | 🕒 时间戳转换与格式化处理                    |
| `DeviceHelper`    | 📱 获取设备唯一标识                          |
| `RandomHelper`    | 🎲 权重随机、随机打乱等                      |
| `SerializeHelper` | 🔄 JSON 序列化 / 反序列化(可使用As<T>()替换) |
| `MD5Helper`       | 🔑 快速生成MD5签名                           |
| `Base64Helper`    | 🧬 Base64编解码                              |

------

### 📌 日志打印统一用法

统一使用 `Log` 工具类进行日志输出，支持彩色分级，正式环境中可自动关闭日志输出。

```csharp
using SGModule.Common.Helper;

Log.Info("标签", "信息内容");     // ✅绿色输出
Log.Warning("标签", "警告内容"); // ⚠️橙色输出
Log.Error("标签", "错误内容");   // ❌红色输出
```

------

### ✨ 扩展方法一览

- **EnumExtensions**：获取枚举描述 `GameState.Ready.GetDescription()`
- **StringExtensions**：空值检查 `str.IsNullOrWhiteSpace()`
- **ObjectExtensions**：类型安全转换 `"123".As<int>()`
- **ListExtensions**：列表随机元素 `items.Random()`
- **ArrayExtensions**：数组相关操作

------

## 🧠 最佳实践

| 模块       | 建议做法                                                     |
| ---------- | ------------------------------------------------------------ |
| 管理器类   | Mono 类继承 `SingletonMonoBehaviour` |
| 日志打印   | 全局使用 `Log` 统一管理，按模块分类                          |
| 类型转换   | 使用 `.As<T>()` 替代传统强转，异常更少                       |
| 加密数据   | 所有敏感数据使用 `Cryptor` 加密后存储                        |
| 时间处理   | 使用 `TimeHelper` 保证时区一致性                             |
| 随机操作   | 使用 `RandomHelper` 替代 `UnityEngine.Random`                |
| 数据键管理 | 通过 `KeyRegistry` 注册和使用，避免硬编码                    |

------

## ⚠️ 注意事项

- ❗ `SingletonMonoBehaviour` 不要手动放入场景，会自动创建
- 🔐 加密密钥需妥善保管，避免泄露
- 🌏 时间处理请注意本地时区与 UTC 的转换
- 🎲 请勿使用 `UnityEngine.Random`，统一使用 `RandomHelper`

------

## 💡 扩展建议

- 🧩 新增扩展方法时，请分类放入 `Extensions/` 并补充完整 XML 注释
- 🧰 新增工具类保持静态类设计，考虑线程安全
- 📖 键系统支持从配置文件中加载，并支持按模块分组管理