yang-pcg 0.2.0

个人使用地图生成
Documentation
# 错误处理指南


## 概述


`yang-pcg` 使用统一的错误类型 `PcgError` 来处理所有可能的错误情况。每个错误都携带丰富的上下文信息,包括阶段名称、随机种子、追踪 ID、字段路径、房间 ID 和分块 ID 等。

## 错误类型


### 错误分类


`PcgError` 按生成阶段分为以下几类:

1. **配置错误** (`Config`) - 错误码: `PCG-CONFIG-001`
   - 配置参数非法、超出范围或存在互斥约束

2. **约束错误** (`Constraint`) - 错误码: `PCG-CONSTRAINT-001`
   - 输入约束彼此冲突或无法满足

3. **拓扑错误** (`Topology`) - 错误码: `PCG-TOPOLOGY-001`
   - 房间图生成失败、关键路径无法构建或房型分配失败

4. **布局错误** (`Layout`) - 错误码: `PCG-LAYOUT-001`
   - 房间边界计算失败、门锚点生成失败或走廊路径无法构建

5. **地形错误** (`Terrain`) - 错误码: `PCG-TERRAIN-001`
   - 房间地形生成失败、连通性验证失败或障碍物布局失败

6. **点位错误** (`Spawn`) - 错误码: `PCG-SPAWN-001`
   - 交互物或敌人点位生成失败、间距验证失败或预算耗尽

7. **导出错误** (`Export`) - 错误码: `PCG-EXPORT-001`
   - 结果序列化、导出或格式转换失败

8. **预算耗尽** (`BudgetExhausted`) - 错误码: `PCG-BUDGET-001`
   - 时间预算、迭代预算或内存预算耗尽

9. **迭代超限** (`IterationLimit`) - 错误码: `PCG-ITERATION-001`
   - 重试次数超过配置上限

10. **数据损坏** (`CorruptedData`) - 错误码: `PCG-CORRUPTED-001`
    - 缓存数据、导入数据或中间结果损坏

11. **能力不可用** (`CapabilityUnavailable`) - 错误码: `PCG-CAPABILITY-001`
    - 请求的功能在当前配置或版本中不可用

## 使用示例


### 基本用法


```rust
use yang_pcg::error::{PcgError, PcgResult};

fn validate_room_count(count: usize) -> PcgResult<()> {
    if count == 0 {
        return Err(PcgError::config_with_field(
            "房间数量不能为 0",
            "room_count"
        ));
    }
    Ok(())
}
```

### 带上下文的错误


```rust
use yang_pcg::error::PcgError;

fn generate_topology(seed: u64, trace_id: &str) -> Result<(), Box<PcgError>> {
    // 生成失败时返回带上下文的错误
    Err(Box::new(PcgError::Topology {
        message: "无法生成关键路径".to_string(),
        stage: Some("topology_generation".to_string()),
        seed: Some(seed),
        trace_id: Some(trace_id.to_string()),
        room_count: Some(5),
        target_room_count: Some(10),
    }))
}
```

### 错误处理


```rust
use yang_pcg::error::PcgError;

fn handle_generation_error(err: Box<PcgError>) {
    // 获取错误码
    println!("错误码: {}", err.error_code());
    
    // 获取生成阶段
    if let Some(stage) = err.stage() {
        println!("发生阶段: {}", stage);
    }
    
    // 获取随机种子
    if let Some(seed) = err.seed() {
        println!("随机种子: {}", seed);
    }
    
    // 获取追踪 ID
    if let Some(trace_id) = err.trace_id() {
        println!("追踪 ID: {}", trace_id);
    }
    
    // 匹配具体错误类型
    match *err {
        PcgError::Config { message, field_path, .. } => {
            println!("配置错误: {}", message);
            if let Some(path) = field_path {
                println!("字段路径: {}", path);
            }
        }
        PcgError::Constraint { message, constraint_type, conflict_details, .. } => {
            println!("约束错误: {}", message);
            if let Some(ctype) = constraint_type {
                println!("约束类型: {}", ctype);
            }
            if let Some(details) = conflict_details {
                println!("冲突详情: {}", details);
            }
        }
        _ => {
            println!("其他错误: {}", err);
        }
    }
}
```

### 便捷方法


为了简化错误创建,`PcgError` 提供了一系列便捷方法:

```rust
use yang_pcg::error::PcgError;

// 创建配置错误
let err = PcgError::config("配置无效");

// 创建配置错误并指定字段路径
let err = PcgError::config_with_field("值超出范围", "room_count.max");

// 创建约束错误
let err = PcgError::constraint("锚点冲突");

// 创建拓扑错误
let err = PcgError::topology("无法生成连通图");

// 创建布局错误
let err = PcgError::layout("房间重叠");

// 创建地形错误
let err = PcgError::terrain("连通性验证失败");

// 创建点位错误
let err = PcgError::spawn("候选点位不足");

// 创建导出错误
let err = PcgError::export("序列化失败");

// 创建预算耗尽错误
let err = PcgError::budget_exhausted("时间预算耗尽", "time");

// 创建迭代超限错误
let err = PcgError::iteration_limit("布局求解失败", 100, 100);

// 创建数据损坏错误
let err = PcgError::corrupted_data("缓存数据损坏");

// 创建能力不可用错误
let err = PcgError::capability_unavailable("运行时分块不可用", "runtime_chunked");
```

## 错误上下文字段


每个错误变体都支持以下上下文字段(根据错误类型不同,可用字段有所差异):

- `message`: 错误描述(必需)
- `stage`: 生成阶段名称
- `seed`: 随机种子
- `trace_id`: 追踪标识
- `field_path`: 字段路径(配置错误)
- `room_id`: 房间 ID
- `chunk_id`: 分块 ID
- `constraint_type`: 约束类型(约束错误)
- `conflict_details`: 冲突详情(约束错误)
- `collision_details`: 碰撞详情(布局错误)
- `strategy`: 地形策略(地形错误)
- `connectivity_failed`: 连通性检查结果(地形错误)
- `spawn_type`: 点位类型(点位错误)
- `candidate_count`: 候选点位数量(点位错误)
- `target_count`: 目标点位数量(点位错误)
- `format`: 导出格式(导出错误)
- `source_error`: 底层错误信息(导出错误)
- `budget_type`: 预算类型(预算耗尽)
- `consumed`: 已消耗量(预算耗尽)
- `limit`: 预算上限(预算耗尽)
- `current_iteration`: 当前迭代次数(迭代超限)
- `max_iteration`: 最大迭代次数(迭代超限)
- `data_type`: 数据类型(数据损坏)
- `expected_version`: 预期版本(数据损坏)
- `actual_version`: 实际版本(数据损坏)
- `capability`: 能力名称(能力不可用)
- `required_version`: 最低要求版本(能力不可用)
- `current_version`: 当前版本(能力不可用)

## 最佳实践


1. **使用便捷方法**:优先使用 `PcgError::config()` 等便捷方法创建错误,而不是直接构造枚举变体。

2. **提供足够的上下文**:在关键路径上创建错误时,尽可能提供 `stage`、`seed`、`trace_id` 等上下文信息。

3. **使用 `?` 操作符**:利用 Rust 的 `?` 操作符简化错误传播。

4. **记录错误日志**:在捕获错误时,使用 `error_code()`、`stage()`、`seed()` 等方法提取关键信息用于日志记录。

5. **错误恢复**:对于可恢复的错误(如迭代超限),考虑实现重试逻辑。

6. **错误聚合**:在批量操作中,考虑收集所有错误而不是在第一个错误时就停止。

## 性能考虑


为了减小 `Result` 类型的栈大小,`PcgResult<T>` 使用 `Box<PcgError>` 而不是直接使用 `PcgError`。这意味着:

- 错误创建时会有一次堆分配
- 错误传播的开销很小
- 符合 Rust 最佳实践,避免 clippy 警告

如果需要在性能关键路径上避免装箱,可以使用 `*_unboxed` 系列方法:

```rust
// 返回 Box<PcgError>
let err = PcgError::config("错误");

// 返回 PcgError(未装箱)
let err = PcgError::config_unboxed("错误");
```

## 需求映射


本错误处理设计满足以下需求:

- **需求 16.1**: 使用 `Result` 类型返回可能失败的操作
- **需求 16.2**: 区分配置错误、约束不满足、能力不可用、预算耗尽、序列化错误和数据损坏错误
- **需求 16.3**: 提供中文描述信息和稳定的机器可读错误码
- **需求 16.4**: 包含足够的上下文,如阶段名称、随机种子、相关房间或相关字段路径
- **需求 16.5**: 支持附带部分调试上下文
- **需求 16.6**: 实现 `std::error::Error` trait(通过 `thiserror` 自动实现)