mirror of
https://github.com/LHY0125/Gobang-Game.git
synced 2026-05-10 02:19:46 +08:00
270 lines
8.2 KiB
Markdown
270 lines
8.2 KiB
Markdown
# 五子棋项目代码架构重构指南
|
|
|
|
## 📋 概述
|
|
|
|
本文档详细记录了五子棋项目在v7.0-v8.0版本中进行的重大代码架构重构，包括重构的目标、实施过程、技术细节和带来的改进。v8.0版本新增了SDL3图形化界面模块，实现了双版本架构设计。
|
|
|
|
## 🎯 重构目标
|
|
|
|
### 主要目标
|
|
1. **代码模块化** - 实现清晰的模块分离和职责划分
|
|
2. **配置统一管理** - 集中管理所有配置参数和宏定义
|
|
3. **全局变量规范化** - 统一管理全局变量，避免散乱分布
|
|
4. **类型定义标准化** - 集中定义所有数据结构和类型
|
|
5. **提升可维护性** - 降低代码耦合度，提高可读性和可维护性
|
|
6. **双版本架构** - (v8.0新增) 实现控制台版本和GUI版本的并行支持
|
|
7. **图形化界面集成** - (v8.0新增) 无缝集成SDL3图形库，提供现代化用户界面
|
|
|
|
### 预期收益
|
|
- 减少代码重复和冗余
|
|
- 提高开发效率和调试便利性
|
|
- 增强代码的可扩展性和可移植性
|
|
- 为后续功能开发奠定坚实基础
|
|
|
|
## 🏗️ 重构实施
|
|
|
|
### 1. 配置参数统一管理
|
|
|
|
#### 重构前状态
|
|
- 配置参数散落在多个头文件中
|
|
- 存在重复定义和不一致的问题
|
|
- 网络相关配置分散在`network.h`中
|
|
- 缺乏统一的配置管理机制
|
|
|
|
#### 重构措施
|
|
- **集中到config.h**：将所有配置宏定义迁移到`config.h`文件
|
|
- **分类管理**：按功能模块对配置参数进行分组
|
|
- **消除重复**：移除重复的宏定义，确保唯一性
|
|
- **标准化命名**：统一配置参数的命名规范
|
|
|
|
#### 配置分类结构
|
|
```c
|
|
// 棋盘配置
|
|
#define BOARD_SIZE 15
|
|
#define MIN_BOARD_SIZE 5
|
|
#define MAX_BOARD_SIZE 25
|
|
|
|
// 游戏模式配置
|
|
#define MODE_HUMAN_VS_AI 1
|
|
#define MODE_HUMAN_VS_HUMAN 2
|
|
#define MODE_NETWORK_BATTLE 3
|
|
|
|
// AI参数配置
|
|
#define DEFAULT_AI_DEPTH 3
|
|
#define MAX_AI_DEPTH 6
|
|
#define AI_TIMEOUT_MS 5000
|
|
|
|
// 网络配置
|
|
#define DEFAULT_PORT 8888
|
|
#define BUFFER_SIZE 1024
|
|
#define MAX_IP_LENGTH 16
|
|
|
|
// 评分参数
|
|
#define SCORE_FIVE 100000
|
|
#define SCORE_LIVE_FOUR 10000
|
|
#define SCORE_RUSH_FOUR 1000
|
|
```
|
|
|
|
### 2. 全局变量统一管理
|
|
|
|
#### 重构前状态
|
|
- 全局变量分散在各个源文件中
|
|
- 缺乏统一的声明和定义管理
|
|
- 变量作用域不清晰
|
|
- 初始化逻辑分散
|
|
|
|
#### 重构措施
|
|
- **创建globals模块**：新建`globals.h`和`globals.c`文件
|
|
- **集中声明**：在`globals.h`中统一声明所有全局变量
|
|
- **集中定义**：在`globals.c`中统一定义和初始化
|
|
- **访问规范化**：通过包含`globals.h`访问全局变量
|
|
|
|
#### 全局变量分类
|
|
```c
|
|
// 游戏状态变量
|
|
extern int current_board[MAX_BOARD_SIZE][MAX_BOARD_SIZE];
|
|
extern int current_player;
|
|
extern int game_over;
|
|
|
|
// 配置变量
|
|
extern GameConfig game_config;
|
|
extern AIConfig ai_config;
|
|
extern NetworkConfig network_config;
|
|
|
|
// 统计变量
|
|
extern GameStats game_stats;
|
|
extern int total_games_played;
|
|
```
|
|
|
|
### 3. 类型定义标准化
|
|
|
|
#### 重构前状态
|
|
- 结构体定义分散在各个头文件中
|
|
- 类型定义不统一
|
|
- 缺乏标准的数据结构规范
|
|
|
|
#### 重构措施
|
|
- **创建type.h**：集中定义所有数据结构和类型
|
|
- **标准化命名**：采用统一的命名规范
|
|
- **逻辑分组**：按功能对类型进行分组
|
|
- **文档化**：为每个类型添加详细注释
|
|
|
|
#### 类型定义结构
|
|
```c
|
|
// 基础类型定义
|
|
typedef enum {
|
|
PLAYER_NONE = 0,
|
|
PLAYER_BLACK = 1,
|
|
PLAYER_WHITE = 2
|
|
} PlayerType;
|
|
|
|
// 游戏配置结构
|
|
typedef struct {
|
|
int board_size;
|
|
int ai_level;
|
|
int enable_forbidden;
|
|
int time_limit;
|
|
} GameConfig;
|
|
|
|
// 网络消息结构
|
|
typedef struct {
|
|
int type;
|
|
int x, y;
|
|
int player;
|
|
char data[256];
|
|
} NetworkMessage;
|
|
```
|
|
|
|
### 4. 网络配置重构
|
|
|
|
#### 具体实施
|
|
1. **迁移宏定义**：将`network.h`中的配置宏移动到`config.h`
|
|
2. **统一命名**：规范网络相关宏的命名
|
|
3. **添加引用**：在`network.h`中添加`#include "config.h"`
|
|
4. **消息类型统一**：将消息类型定义集中管理
|
|
|
|
#### 迁移的配置项
|
|
```c
|
|
// 从network.h迁移到config.h
|
|
#define DEFAULT_PORT 8888
|
|
#define BUFFER_SIZE 1024
|
|
#define MAX_IP_LENGTH 16
|
|
#define MSG_MOVE 1
|
|
#define MSG_CHAT 2
|
|
#define MSG_SURRENDER 3
|
|
#define MSG_DISCONNECT 4
|
|
```
|
|
|
|
## 📊 重构效果评估
|
|
|
|
### 代码质量提升
|
|
- **模块耦合度降低**：各模块职责更加清晰
|
|
- **代码重复减少**：消除了重复的宏定义和类型定义
|
|
- **可读性增强**：统一的命名规范和代码结构
|
|
- **维护性提高**：集中管理使得修改更加便捷
|
|
|
|
### 开发效率提升
|
|
- **配置修改便捷**：只需在一个地方修改配置参数
|
|
- **调试更容易**：全局变量集中管理，状态更清晰
|
|
- **扩展更简单**：标准化的接口和数据结构
|
|
- **错误减少**：统一管理避免了不一致性错误
|
|
|
|
### 性能影响
|
|
- **编译时间**：略有增加（由于更多的头文件包含）
|
|
- **运行时性能**：无显著影响
|
|
- **内存使用**：无显著变化
|
|
- **整体评估**：性能影响微乎其微，收益远大于成本
|
|
|
|
## 🔧 技术细节
|
|
|
|
### 文件结构变化
|
|
|
|
#### 新增文件
|
|
- `type.h` - 类型定义集中文件
|
|
- `globals.h` - 全局变量声明文件
|
|
- `globals.c` - 全局变量定义文件
|
|
|
|
#### 修改文件
|
|
- `config.h` - 扩展为完整的配置管理文件
|
|
- `network.h` - 移除配置定义，添加config.h引用
|
|
- 所有源文件 - 更新头文件包含关系
|
|
|
|
### 编译依赖关系
|
|
|
|
```
|
|
type.h (基础类型)
|
|
↓
|
|
config.h (配置参数)
|
|
↓
|
|
globals.h (全局变量声明)
|
|
↓
|
|
各功能模块头文件
|
|
↓
|
|
源文件实现
|
|
```
|
|
|
|
### 包含关系规范
|
|
|
|
1. **type.h**：被所有需要类型定义的文件包含
|
|
2. **config.h**：被所有需要配置参数的文件包含
|
|
3. **globals.h**：被所有需要访问全局变量的文件包含
|
|
4. **功能模块头文件**：按需包含上述基础头文件
|
|
|
|
## 📝 最佳实践
|
|
|
|
### 配置管理
|
|
1. **新增配置参数**：统一添加到`config.h`的相应分组中
|
|
2. **命名规范**：使用描述性的宏名称，避免缩写
|
|
3. **分组管理**：按功能模块对配置进行逻辑分组
|
|
4. **文档注释**：为每个配置参数添加清晰的注释
|
|
|
|
### 全局变量管理
|
|
1. **声明规范**：在`globals.h`中使用extern声明
|
|
2. **定义规范**：在`globals.c`中进行实际定义和初始化
|
|
3. **访问规范**：通过包含`globals.h`访问，避免重复声明
|
|
4. **初始化管理**：在`globals.c`中集中进行初始化
|
|
|
|
### 类型定义管理
|
|
1. **命名规范**：使用PascalCase命名结构体和枚举
|
|
2. **分组管理**：按功能对类型进行逻辑分组
|
|
3. **文档化**：为每个类型和字段添加详细注释
|
|
4. **版本兼容**：考虑结构体的向后兼容性
|
|
|
|
## 🚀 未来扩展
|
|
|
|
### 短期计划
|
|
1. **配置文件增强**：支持更多配置项的动态加载
|
|
2. **类型安全增强**：添加更多的类型检查和验证
|
|
3. **模块接口标准化**：定义标准的模块接口规范
|
|
|
|
### 长期规划
|
|
1. **插件架构**：基于当前架构实现插件系统
|
|
2. **配置热重载**：支持运行时配置的动态更新
|
|
3. **跨平台适配**：利用统一架构实现跨平台支持
|
|
|
|
## 📚 参考资料
|
|
|
|
### 相关文档
|
|
- [C语言编程规范](https://www.kernel.org/doc/html/latest/process/coding-style.html)
|
|
- [软件架构设计原则](https://en.wikipedia.org/wiki/Software_architecture)
|
|
- [模块化编程最佳实践](https://en.wikipedia.org/wiki/Modular_programming)
|
|
|
|
### 工具推荐
|
|
- **静态分析**：使用cppcheck进行代码质量检查
|
|
- **格式化**：使用clang-format统一代码格式
|
|
- **文档生成**：使用Doxygen生成API文档
|
|
|
|
## 📈 总结
|
|
|
|
v7.0版本的代码架构重构是一次重要的技术升级，通过系统性的重构实现了：
|
|
|
|
✅ **配置参数的统一管理** - 提高了配置的一致性和可维护性
|
|
✅ **全局变量的规范化** - 降低了代码的复杂度和耦合度
|
|
✅ **类型定义的标准化** - 增强了代码的可读性和类型安全
|
|
✅ **模块结构的优化** - 为后续功能扩展奠定了坚实基础
|
|
|
|
这次重构不仅解决了当前的技术债务，更为项目的长期发展提供了良好的架构基础。后续的功能开发将能够更加高效和稳定地进行。
|
|
|
|
---
|
|
|
|
*本文档将随着项目的发展持续更新，记录架构演进的每一个重要节点。* |