138 lines
5.1 KiB
Markdown
138 lines
5.1 KiB
Markdown
# 🧱 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 注释
|
||
- 🧰 新增工具类保持静态类设计，考虑线程安全
|
||
- 📖 键系统支持从配置文件中加载，并支持按模块分组管理 |