216 lines
6.1 KiB
Markdown
216 lines
6.1 KiB
Markdown
# KARDS 引擎API一致性检查报告
|
||
|
||
## 1. 概述
|
||
|
||
本报告分析了KARDS战斗引擎中不同模块和版本之间API接口的一致性问题，并提供修复建议。
|
||
|
||
## 2. 主要发现的不一致问题
|
||
|
||
### 2.1 引擎类参数不一致
|
||
|
||
**问题描述**: 不同引擎版本的构造函数参数不统一
|
||
|
||
**当前引擎BattleEngine**:
|
||
```python
|
||
def __init__(self, player1_name: str, player2_name: str, debug_mode: bool = False)
|
||
```
|
||
|
||
**历史引擎版本**:
|
||
```python
|
||
# GameEngineV2/V3
|
||
def __init__(self, player1_id: str, player2_id: str)
|
||
|
||
# GameEngine
|
||
def __init__(self, player1_id: str, player2_id: str)
|
||
```
|
||
|
||
**影响**:
|
||
- 测试代码中混用`player_id`字符串和整数参数
|
||
- 部分测试使用字符串参数调用BattleEngine方法
|
||
|
||
### 2.2 部署接口不统一
|
||
|
||
**BattleEngine (当前主引擎)**:
|
||
```python
|
||
def deploy_unit_to_support(self, unit: Unit, player_id: int, position: Optional[int] = None)
|
||
```
|
||
|
||
**其他引擎版本存在的接口**:
|
||
```python
|
||
# GameEngineV2
|
||
def deploy_unit_to_front(self, unit: Unit, player_id: str)
|
||
|
||
# GameEngine
|
||
def deploy_unit(self, unit: Unit, player_id: str, line_type, position: int)
|
||
|
||
# test_system.py中发现
|
||
engine.deploy_unit(panzer, "Germany", LineType.FRONT, 2)
|
||
```
|
||
|
||
**不一致点**:
|
||
1. 参数类型：`int` vs `str` for player_id
|
||
2. 参数顺序和数量不同
|
||
3. 不同的方法名称
|
||
|
||
### 2.3 移动接口不统一
|
||
|
||
**BattleEngine**:
|
||
```python
|
||
def move_unit(self, unit_id: UUID, target_position: tuple, player_id: int)
|
||
```
|
||
|
||
**其他版本**:
|
||
```python
|
||
# GameEngineV2
|
||
def move_unit_to_front(self, unit_id: UUID) # 缺少player_id参数
|
||
```
|
||
|
||
### 2.4 攻击接口不统一
|
||
|
||
**BattleEngine**:
|
||
```python
|
||
def attack_target(self, attacker_id: UUID, target_id: Union[UUID, str], player_id: int)
|
||
```
|
||
|
||
**其他版本**:
|
||
```python
|
||
# GameEngine
|
||
def attack_unit(self, attacker_id: UUID, target_id: UUID) # 缺少player_id参数
|
||
```
|
||
|
||
## 3. 测试代码中的不一致使用
|
||
|
||
### 3.1 player_id参数类型混用
|
||
|
||
**发现的问题**:
|
||
```python
|
||
# 正确用法 (BattleEngine)
|
||
engine.deploy_unit_to_support(unit, 0)
|
||
engine.move_unit(unit.id, (LineType.FRONT, 0), 0)
|
||
|
||
# 错误用法 - 使用字符串
|
||
engine.deploy_unit_to_support(german_inf, "Germany") # 应该是整数0
|
||
engine.move_unit(german_inf.id, (LineType.FRONT, 0), "Germany") # 应该是整数0
|
||
```
|
||
|
||
**影响文件**:
|
||
- `tests/unit/test_battle_engine.py`
|
||
- `tests/integration/test_corrected_battlefield.py`
|
||
- `tests/integration/test_new_battlefield.py`
|
||
|
||
### 3.2 不存在的方法调用
|
||
|
||
**发现的过时方法调用**:
|
||
```python
|
||
# 这些方法在当前BattleEngine中不存在
|
||
engine.deploy_unit_to_front(german_infantry, "Germany")
|
||
engine.move_unit_to_front(sherman.id)
|
||
engine.deploy_unit(panzer, "Germany", LineType.FRONT, 2)
|
||
engine.attack_unit(p51.id, bf109.id)
|
||
```
|
||
|
||
## 4. CommandParser中的接口使用
|
||
|
||
**当前状态**: CommandParser正确使用了BattleEngine的API
|
||
```python
|
||
# command_parser.py - 正确用法
|
||
result = self.engine.deploy_unit_to_support(unit, player_id, position)
|
||
result = self.engine.move_unit(unit.id, (line_type, target_pos), self.engine.active_player)
|
||
result = self.engine.attack_target(attacker.id, target_id, self.engine.active_player)
|
||
```
|
||
|
||
## 5. 修复建议
|
||
|
||
### 5.1 立即修复项
|
||
|
||
#### A. 修复测试代码中的参数类型错误
|
||
```python
|
||
# 需要修改的文件和模式
|
||
# tests/unit/test_battle_engine.py
|
||
- engine.move_unit(german_inf.id, (LineType.FRONT, 0), "Germany")
|
||
+ engine.move_unit(german_inf.id, (LineType.FRONT, 0), 0)
|
||
|
||
- engine.attack_target(american_gi.id, german_inf.id, "USA")
|
||
+ engine.attack_target(american_gi.id, german_inf.id, 1)
|
||
|
||
# 其他相关测试文件类似修改
|
||
```
|
||
|
||
#### B. 创建player_id映射函数
|
||
```python
|
||
# 在测试辅助函数中添加
|
||
def get_player_id(player_name: str) -> int:
|
||
"""将玩家名称转换为player_id"""
|
||
mapping = {"Germany": 0, "USA": 1}
|
||
return mapping.get(player_name, 0)
|
||
```
|
||
|
||
### 5.2 长期规范化建议
|
||
|
||
#### A. 统一引擎接口
|
||
1. **保持BattleEngine作为主接口**
|
||
2. **废弃其他引擎版本**，移至archive目录
|
||
3. **标准化参数类型**：使用`int`作为player_id
|
||
|
||
#### B. 接口版本控制
|
||
```python
|
||
# 为向后兼容添加适配层
|
||
class BattleEngine:
|
||
def deploy_unit_to_support(self, unit: Unit, player_id: Union[int, str], position: Optional[int] = None):
|
||
if isinstance(player_id, str):
|
||
# 兼容性转换
|
||
player_id = {"Germany": 0, "USA": 1}.get(player_id, 0)
|
||
# 继续原有逻辑
|
||
```
|
||
|
||
#### C. 创建统一的测试基类
|
||
```python
|
||
class BaseEngineTest:
|
||
def setUp(self):
|
||
self.engine = BattleEngine("Germany", "USA")
|
||
|
||
def deploy_unit(self, unit: Unit, player_name: str):
|
||
player_id = 0 if player_name == "Germany" else 1
|
||
return self.engine.deploy_unit_to_support(unit, player_id)
|
||
```
|
||
|
||
## 6. API验证清单
|
||
|
||
### 6.1 核心API一致性检查
|
||
- [x] **BattleEngine**: 接口定义明确且一致
|
||
- [x] **CommandParser**: 正确使用BattleEngine接口
|
||
- [ ] **测试代码**: 存在参数类型不匹配问题
|
||
- [ ] **历史引擎**: 接口不兼容，需要废弃或适配
|
||
|
||
### 6.2 参数验证
|
||
- [x] **player_id类型**: BattleEngine使用`int`，与文档一致
|
||
- [x] **返回值格式**: 统一使用`{"success": bool, ...}`格式
|
||
- [x] **错误处理**: 统一返回详细错误信息
|
||
- [ ] **测试参数**: 部分测试使用错误的参数类型
|
||
|
||
## 7. 推荐修复优先级
|
||
|
||
### P0 (立即修复)
|
||
1. 修复`test_battle_engine.py`中的参数类型错误
|
||
2. 移除对不存在方法的调用
|
||
|
||
### P1 (短期修复)
|
||
1. 创建测试辅助函数统一参数转换
|
||
2. 更新所有相关测试文件
|
||
|
||
### P2 (长期优化)
|
||
1. 清理历史引擎代码
|
||
2. 建立API版本控制机制
|
||
3. 创建完整的接口测试套件
|
||
|
||
## 8. 结论
|
||
|
||
当前BattleEngine的API接口设计是一致和完整的，主要问题集中在：
|
||
|
||
1. **测试代码使用了错误的参数类型** (字符串 vs 整数)
|
||
2. **历史引擎版本接口不兼容**，应该移除或归档
|
||
3. **部分测试调用了不存在的方法**
|
||
|
||
通过修复测试代码中的参数错误和移除历史引擎依赖，可以实现完全的API一致性。
|
||
|
||
**总体评估**: API设计良好，需要的是测试代码的修正而非接口重构。 |