254 lines
7.0 KiB
Markdown
254 lines
7.0 KiB
Markdown
# API配置系统使用说明
|
||
|
||
## 概述
|
||
|
||
API配置系统是一个完全基于JSON配置文件的API接口管理系统，支持多环境配置、动态参数替换、热重载等功能。
|
||
|
||
## 系统特点
|
||
|
||
- ✅ **完全配置化**：所有API接口配置都存储在JSON文件中
|
||
- ✅ **多环境支持**：支持开发、测试、生产环境切换
|
||
- ✅ **动态参数**：支持运行时参数替换
|
||
- ✅ **热重载**：支持配置文件热重载
|
||
- ✅ **向后兼容**：保持原有API调用方式不变
|
||
- ✅ **配置验证**：提供完整的配置验证功能
|
||
|
||
## 配置文件结构
|
||
|
||
### 配置文件位置
|
||
```
|
||
Assets/StreamingAssets/DataConfig/api_config.json
|
||
```
|
||
|
||
### 配置文件格式
|
||
```json
|
||
{
|
||
"Version": "1.0.0",
|
||
"Description": "API接口配置文件",
|
||
"CurrentEnvironment": "开发环境",
|
||
"Environments": [
|
||
{
|
||
"Environment": "开发环境",
|
||
"BaseUrl": "http://172.16.1.127:8080",
|
||
"DefaultTimeout": 30,
|
||
"DefaultRetryCount": 3,
|
||
"IsEnabled": true,
|
||
"Description": "开发环境配置"
|
||
}
|
||
],
|
||
"Endpoints": [
|
||
{
|
||
"Name": "GetProSimulationExaminationQueryById",
|
||
"Description": "获取任务书和流程",
|
||
"UrlTemplate": "{BaseUrl}/member/proSimulationExamination/queryById?id={PaperId}",
|
||
"Method": "GET",
|
||
"RequireAuth": true,
|
||
"Timeout": 30,
|
||
"RetryCount": 3,
|
||
"IsEnabled": true,
|
||
"Parameters": []
|
||
}
|
||
],
|
||
"GlobalParameters": [
|
||
{
|
||
"Name": "DefaultTimeout",
|
||
"Value": "30",
|
||
"Description": "默认超时时间（秒）",
|
||
"IsRequired": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 1. 初始化配置管理器
|
||
|
||
在游戏启动时初始化API配置管理器：
|
||
|
||
```csharp
|
||
// 在GameLauncher.cs中添加
|
||
MotionEngine.CreateModule<ApiConfigManager>();
|
||
|
||
// 初始化配置管理器
|
||
var apiConfigManager = MotionEngine.GetModule<ApiConfigManager>();
|
||
apiConfigManager.Initialize(enableHotReload: true, hotReloadInterval: 30f);
|
||
```
|
||
|
||
### 2. 使用API接口
|
||
|
||
#### 方式一：使用原有方式（推荐）
|
||
```csharp
|
||
// 获取API URL
|
||
string url = ApiUrls.TransitInventory.GetProSimulationExaminationQueryById;
|
||
|
||
// 发送请求
|
||
string response = await MotionEngine.GetModule<WebRequestManager>().GetTextAsync(url, token);
|
||
```
|
||
|
||
#### 方式二：使用配置管理器
|
||
```csharp
|
||
// 获取API URL
|
||
var configManager = MotionEngine.GetModule<ApiConfigManager>();
|
||
string url = configManager.GetApiUrl("GetProSimulationExaminationQueryById");
|
||
|
||
// 带动态参数
|
||
var dynamicParams = new Dictionary<string, string>
|
||
{
|
||
["CustomParam"] = "value"
|
||
};
|
||
string urlWithParams = configManager.GetApiUrl("GetProSimulationExaminationQueryById", dynamicParams);
|
||
```
|
||
|
||
### 3. 切换环境
|
||
|
||
```csharp
|
||
var configManager = MotionEngine.GetModule<ApiConfigManager>();
|
||
configManager.SwitchEnvironment(ApiEnvironment.测试环境);
|
||
```
|
||
|
||
## 配置编辑器
|
||
|
||
### 打开编辑器
|
||
在Unity菜单栏选择：`工具 -> API配置编辑器`
|
||
|
||
### 编辑器功能
|
||
- 📝 **环境配置**：配置不同环境的基础URL和参数
|
||
- 🔧 **API接口配置**：配置各个API接口的详细信息
|
||
- ⚙️ **全局参数**：配置全局参数
|
||
- ✅ **配置验证**：验证配置的完整性和正确性
|
||
- 💾 **保存配置**：将配置保存到JSON文件
|
||
|
||
## 配置说明
|
||
|
||
### 环境配置
|
||
- **Environment**：环境名称（开发环境/测试环境/生产环境）
|
||
- **BaseUrl**：基础URL地址
|
||
- **DefaultTimeout**：默认超时时间（秒）
|
||
- **DefaultRetryCount**：默认重试次数
|
||
- **IsEnabled**：是否启用该环境
|
||
- **Description**：环境描述
|
||
|
||
### API接口配置
|
||
- **Name**：接口名称（必须唯一）
|
||
- **Description**：接口描述
|
||
- **UrlTemplate**：URL模板，支持占位符
|
||
- **Method**：HTTP方法（GET/POST/PUT/DELETE等）
|
||
- **RequireAuth**：是否需要认证
|
||
- **Timeout**：超时时间（秒）
|
||
- **RetryCount**：重试次数
|
||
- **IsEnabled**：是否启用该接口
|
||
- **Parameters**：接口特定参数
|
||
|
||
### URL模板占位符
|
||
- `{BaseUrl}`：基础URL
|
||
- `{PaperId}`：试卷ID（自动从GlobalDataStorage获取）
|
||
- `{ExamRoomId}`：考场ID（自动从GlobalDataStorage获取）
|
||
- `{IpAddress}`：IP地址（自动从GlobalDataStorage获取）
|
||
- `{CustomParam}`：自定义参数（通过dynamicParams传入）
|
||
|
||
### 全局参数
|
||
- **Name**：参数名称
|
||
- **Value**：参数值
|
||
- **Description**：参数描述
|
||
- **IsRequired**：是否必需
|
||
|
||
## 配置验证
|
||
|
||
系统会自动验证配置的完整性：
|
||
|
||
### 验证项目
|
||
- ✅ 配置文件格式正确性
|
||
- ✅ 环境配置完整性
|
||
- ✅ API接口配置完整性
|
||
- ✅ 参数配置正确性
|
||
- ✅ URL模板格式正确性
|
||
- ✅ 重复配置检查
|
||
|
||
### 验证结果
|
||
- 🟢 **验证通过**：配置正确，可以正常使用
|
||
- 🟡 **警告**：配置有潜在问题，但不影响使用
|
||
- 🔴 **错误**：配置有严重问题，需要修复
|
||
|
||
## 热重载功能
|
||
|
||
### 启用热重载
|
||
```csharp
|
||
apiConfigManager.Initialize(enableHotReload: true, hotReloadInterval: 30f);
|
||
```
|
||
|
||
### 热重载机制
|
||
- 系统会定期检查配置文件是否被修改
|
||
- 检测到修改后自动重新加载配置
|
||
- 支持运行时动态修改配置
|
||
|
||
### 注意事项
|
||
- 热重载仅在开发环境建议使用
|
||
- 生产环境建议关闭热重载以提高性能
|
||
|
||
## 错误处理
|
||
|
||
### 常见错误
|
||
1. **配置文件不存在**
|
||
- 错误：`API配置文件不存在：xxx/api_config.json`
|
||
- 解决：确保配置文件存在于正确位置
|
||
|
||
2. **配置验证失败**
|
||
- 错误：`API配置验证失败`
|
||
- 解决：使用配置编辑器验证并修复配置
|
||
|
||
3. **接口未找到**
|
||
- 错误：`未找到API接口配置：xxx`
|
||
- 解决：检查接口名称是否正确，或添加缺失的接口配置
|
||
|
||
### 备用方案
|
||
当配置系统出现问题时，系统会自动使用原有的硬编码方式作为备用方案，确保系统正常运行。
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 配置文件管理
|
||
- 将配置文件纳入版本控制
|
||
- 为不同环境创建不同的配置文件
|
||
- 定期备份配置文件
|
||
|
||
### 2. 接口命名规范
|
||
- 使用有意义的接口名称
|
||
- 保持命名一致性
|
||
- 避免使用特殊字符
|
||
|
||
### 3. 环境管理
|
||
- 开发环境：用于本地开发测试
|
||
- 测试环境：用于集成测试
|
||
- 生产环境：用于正式部署
|
||
|
||
### 4. 安全考虑
|
||
- 生产环境的敏感信息不要硬编码
|
||
- 使用环境变量或加密配置
|
||
- 定期更新认证信息
|
||
|
||
## 迁移指南
|
||
|
||
### 从硬编码迁移到配置化
|
||
|
||
1. **备份现有代码**
|
||
2. **创建配置文件**：使用配置编辑器创建初始配置
|
||
3. **逐步迁移**：逐个接口迁移到配置系统
|
||
4. **测试验证**：确保所有接口正常工作
|
||
5. **清理代码**：移除硬编码的URL
|
||
|
||
### 兼容性说明
|
||
- 原有的API调用方式完全兼容
|
||
- 无需修改现有业务代码
|
||
- 可以逐步迁移，无需一次性完成
|
||
|
||
## 技术支持
|
||
|
||
如果遇到问题，请检查：
|
||
1. 配置文件格式是否正确
|
||
2. 配置文件路径是否正确
|
||
3. 配置验证是否通过
|
||
4. 日志输出中的错误信息
|
||
|
||
---
|
||
|
||
**注意**：本系统完全依赖JSON配置文件，不再支持硬编码的默认配置。请确保配置文件存在且格式正确。 |