# 错误处理集成指南

本文档介绍 how to 使用 `anycms-core` 的 thiserror 错误处理功能。

## 概述

`anycms-core` 现在提供了完整的错误处理集成，支持：

- **ErrorCode**: 标准化的错误码枚举，自动映射到 HTTP 状态码
- **ApiError**: 简单的 API 错误类型
- **AppError**: 通用的应用错误类型（使用 thiserror）
- **IntoApiResult trait**: 便捷的 Result 转换

## 核心类型

### ErrorCode

```rust
pub enum ErrorCode {
    Success = 0,
    BadRequest = 400,
    Unauthorized = 401,
    Forbidden = 403,
    NotFound = 404,
    Conflict = 409,
    ValidationError = 422,
    InternalError = 500,
    // ...
}
```

### ApiError

简单直接的错误类型：

```rust
use anycms_core::{ApiError, ErrorCode};

// 使用错误码
let err = ApiError::new(ErrorCode::NotFound, "User not found");

// 使用便捷方法
let err = ApiError::not_found("User not found");
let err = ApiError::bad_request("Invalid email");
let err = ApiError::unauthorized("Please login");
```

### AppError

使用 thiserror 的通用错误类型：

```rust
use anycms_core::AppError;
use thiserror::Error;

#[derive(Error, Debug)]
enum MyError {
    #[error("Database error: {0}")]
    Database(String),
}

// 自动转换
let result: Result<User, MyError> = ...;
let api_result: ApiResult<User> = result.into(); // 自动转换为 ApiResult
```

## 使用模式

### 模式 1: 使用 ApiError

```rust
use anycms_core::{ApiResult, ApiError};

async fn get_user(id: u32) -> Result<User, UserServiceError> {
    // ...
}

#[get("/users/{id}")]
async fn handler(path: web::Path<u32>) -> ApiResult<User> {
    let user_id = path.into_inner();

    get_user(user_id)
        .await
        .map(|user| ApiResult::value(user))
        .unwrap_or_else(|e| ApiError::from(e).into())
}
```

### 模式 2: 使用 IntoApiResult trait

```rust
use anycms_core::{ApiResult, ApiError, IntoApiResult};

async fn find_user(id: u32) -> Result<User, UserServiceError> {
    // ...
}

#[get("/users/{id}")]
async fn handler(path: web::Path<u32>) -> ApiResult<User> {
    let user_id = path.into_inner();

    find_user(user_id)
        .await
        .into_api_result_with(|| {
            ApiError::not_found(format!("User {} not found", user_id))
        })
}
```

### 模式 3: 自定义错误类型

```rust
use thiserror::Error;
use anycms_core::{ApiError, ApiResult};

#[derive(Error, Debug)]
enum UserServiceError {
    #[error("User {0} not found")]
    UserNotFound(u32),

    #[error("Email {0} already exists")]
    EmailAlreadyExists(String),
}

impl From<UserServiceError> for ApiError {
    fn from(err: UserServiceError) -> Self {
        match err {
            UserServiceError::UserNotFound(id) => {
                ApiError::not_found(format!("User {} not found", id))
            }
            UserServiceError::EmailAlreadyExists(email) => {
                ApiError::conflict(format!("Email {} already registered", email))
            }
        }
    }
}

// 使用
async fn handler() -> ApiResult<User> {
    find_user(1)
        .await
        .map(|user| ApiResult::value(user))
        .unwrap_or_else(|e| ApiError::from(e).into())
}
```

### 模式 4: Early Return

```rust
#[post("/users")]
async fn create_user(data: web::Json<CreateUserRequest>) -> ApiResult<User> {
    // 验证
    let validation = validate_email(&data.email).await;
    if let Err(e) = validation {
        return ApiError::from(e).into();
    }

    // 检查冲突
    if email_exists(&data.email).await {
        return ApiError::conflict("Email already registered").into();
    }

    // 创建用户
    let user = create_user(data).await;
    ApiResult::value(user)
}
```

## HTTP 状态码自动映射

当使用 ApiError 或 AppError 时，HTTP 状态码会自动根据错误码设置：

```rust
ApiError::not_found(...)      // HTTP 404
ApiError::bad_request(...)    // HTTP 400
ApiError::unauthorized(...)   // HTTP 401
ApiError::forbidden(...)      // HTTP 403
ApiError::validation(...)     // HTTP 422
ApiError::conflict(...)       // HTTP 409
ApiError::internal(...)       // HTTP 500
```

## 完整示例

查看 `examples/error_handling_demo.rs` 了解所有错误处理模式。

运行示例：

```bash
cargo run --example error_handling_demo --features actix
```

测试不同错误类型：

```bash
# 成功
curl http://localhost:8080/users/1

# 404 Not Found
curl http://localhost:8080/users/999

# HTTP 状态码演示
curl http://localhost:8080/error-demo/not_found    # 404
curl http://localhost:8080/error-demo/bad_request  # 400
curl http://localhost:8080/error-demo/conflict     # 409
```

## 最佳实践

1. **定义领域特定的错误类型**：使用 thiserror 定义业务错误
2. **实现 From<YourError> for ApiError**：统一转换路径
3. **使用语义化的错误码**：选择正确的 ErrorCode
4. **提供清晰的错误消息**：帮助客户端理解问题
5. **记录内部错误**：使用日志记录详细信息，但只向客户端返回友好消息

## 迁移指南

### 从旧的 ApiResult::failure 迁移

**之前：**
```rust
ApiResult::<User>::failure("User not found")
```

**现在：**
```rust
ApiError::not_found("User not found").into()
```

### 从 match 语句迁移

**之前：**
```rust
match get_user(id).await {
    Some(user) => ApiResult::value(user),
    None => ApiResult::<User>::failure("Not found"),
}
```

**现在：**
```rust
get_user(id)
    .await
    .ok_or_else(|| ApiError::not_found("User not found"))
    .into_api_result()
```
