Skip to content

Latest commit

 

History

History
204 lines (161 loc) · 5.34 KB

create_input_optimization.md

File metadata and controls

204 lines (161 loc) · 5.34 KB

create_input 方法优化文档

概述

本文档详细说明了对 InputManager.create_input() 方法的优化改进，包括增强的参数验证、错误处理和返回值结构。

🔧 优化前后对比

原始版本的问题

  1. 参数验证不够全面 - 只检查场景参数，没有验证输入名称和类型
  2. 缺少重复检查 - 不检查输入名称是否已存在
  3. 错误处理简单 - 只有基本的异常捕获
  4. 返回值信息有限 - 只返回 UUID 和场景项 ID
  5. 没有输入类型验证 - 不检查输入类型是否受支持

优化后的改进

  1. ✅ 全面的参数验证
  2. ✅ 智能重复检查
  3. ✅ 增强的错误处理
  4. ✅ 丰富的返回值
  5. ✅ 输入类型验证

📋 详细优化内容

1. 参数验证增强

# 新增参数
check_duplicates: bool = True  # 是否检查重复名称

# 增强的验证逻辑
- 检查输入名称不能为空
- 检查输入类型不能为空
- 验证场景参数的互斥性
- 可选的重复名称检查
- 输入类型支持性验证

2. 智能重复检查

# 检查输入名称是否已存在
if check_duplicates and self.exists(input_name):
    raise ValueError(f"输入名称 '{input_name}' 已存在")

特性：

  • 默认启用重复检查
  • 可通过 check_duplicates=False 禁用
  • 使用现有的 exists() 方法进行检查

3. 输入类型验证

# 验证输入类型是否支持
available_kinds = self.get_input_kinds()
if available_kinds and input_kind not in available_kinds:
    self.logger.warning(f"输入类型 '{input_kind}' 可能不受支持")

特性：

  • 检查输入类型是否在支持列表中
  • 不支持的类型会记录警告但仍然尝试创建
  • 避免因类型检查失败而阻止创建

4. 增强的错误处理

# 具体的异常类型识别
if 'scene' in error_msg and ('not found' in error_msg or '不存在' in error_msg):
    raise OBSResourceNotFoundError(f"场景不存在: {scene_name or scene_uuid}")
elif 'input' in error_msg and ('exists' in error_msg or '已存在' in error_msg):
    raise ValueError(f"输入名称 '{input_name}' 已存在")

改进：

  • 识别特定的 OBS 错误类型
  • 提供更有意义的错误信息
  • 使用适当的异常类型

5. 丰富的返回值结构

# 优化前
return {
    'input_uuid': result.get('inputUuid', ''),
    'scene_item_id': result.get('sceneItemId', 0)
}

# 优化后
return {
    'input_uuid': input_uuid,
    'scene_item_id': scene_item_id,
    'input_name': input_name,      # 新增
    'input_kind': input_kind,      # 新增
    'success': True                # 新增
}

新增字段：

  • input_name: 输入名称
  • input_kind: 输入类型
  • success: 创建是否成功

6. 改进的日志记录

# 调试信息
self.logger.debug(f"创建输入请求参数: {request_params}")

# 详细的成功信息
self.logger.info(f"成功创建输入 '{input_name}' (UUID: {input_uuid}, 场景项ID: {scene_item_id})")

# 警告信息
self.logger.warning(f"创建输入 '{input_name}' 的响应为空或无效")

🧪 测试覆盖

测试用例

  1. 基本创建功能 - 验证正常创建流程
  2. 参数验证 - 测试各种无效参数
  3. 重复名称检查 - 测试重复检查功能
  4. 返回值结构 - 验证返回值的完整性
  5. 输入类型验证 - 测试类型验证功能

测试结果

测试结果: 5/5 通过
✅ 基本创建功能 测试通过
✅ 参数验证 测试通过  
✅ 重复名称检查 测试通过
✅ 返回值结构 测试通过
✅ 输入类型验证 测试通过

📖 使用示例

基本使用

result = obs.inputs.create_input(
    input_name="我的文本源",
    input_kind="text_gdiplus_v3",
    scene_name="主场景",
    input_settings={"text": "Hello World!"}
)

if result['success']:
    print(f"创建成功: {result['input_uuid']}")
else:
    print("创建失败")

禁用重复检查

result = obs.inputs.create_input(
    input_name="可能重复的名称",
    input_kind="text_gdiplus_v3",
    scene_name="主场景",
    check_duplicates=False  # 禁用重复检查
)

使用场景 UUID

result = obs.inputs.create_input(
    input_name="新输入源",
    input_kind="image_source",
    scene_uuid="scene-uuid-123",
    input_settings={"file": "image.png"}
)

🎯 最佳实践

  1. 总是检查返回值的 success 字段
  2. 使用有意义的输入名称
  3. 验证输入类型是否受支持
  4. 适当处理异常情况
  5. 在生产环境中启用重复检查

🔄 向后兼容性

  • 所有原有参数保持不变
  • 新增参数都有默认值
  • 返回值结构向后兼容（新增字段）
  • 异常类型可能有变化（更具体）

📝 注意事项

  1. 输入类型验证：只是警告，不会阻止创建
  2. 重复检查：默认启用，可以禁用
  3. 错误处理：更具体的异常类型
  4. 日志级别：增加了 debug 和 warning 级别的日志
  5. 性能影响：增加了一些验证步骤，但影响很小

🚀 运行测试

# 运行优化后的测试
py -3.11 tests/test_create_input_optimized.py

这些优化使 create_input 方法更加健壮、用户友好，并提供了更好的错误处理和调试信息。