yang-base 0.2.1

个人使用构建后端服务器
Documentation
# Request 结构体使用指南

## 概述

`Request` 结构体用于封装 Action 系统的 HTTP 请求信息,包括请求体、请求头、查询参数和路径参数。

## 基本用法

### 创建请求

```rust
use yang_base::action::Request;
use serde_json::json;

// 创建带有请求体的请求
let request = Request::new(json!({
    "username": "alice",
    "email": "alice@example.com"
}));

// 创建空请求
let empty_request = Request::default();
```

### 添加请求头

```rust
// 单个请求头
let request = Request::new(json!({}))
    .header("Content-Type", "application/json")
    .header("User-Agent", "MyApp/1.0");

// 批量添加请求头
use std::collections::HashMap;

let mut headers = HashMap::new();
headers.insert("Content-Type".to_string(), "application/json".to_string());
headers.insert("Authorization".to_string(), "Bearer token123".to_string());

let request = Request::new(json!({}))
    .headers(headers);
```

### 添加查询参数

```rust
// 单个查询参数
let request = Request::new(json!({}))
    .query("page", "1")
    .query("limit", "10")
    .query("sort", "name");

// 批量添加查询参数
let mut query = HashMap::new();
query.insert("page".to_string(), "1".to_string());
query.insert("limit".to_string(), "10".to_string());

let request = Request::new(json!({}))
    .queries(query);
```

### 添加路径参数

```rust
// 单个路径参数
let request = Request::new(json!({}))
    .path_param("id", "123")
    .path_param("action", "update");

// 批量添加路径参数
let mut path_params = HashMap::new();
path_params.insert("id".to_string(), "123".to_string());
path_params.insert("action".to_string(), "update".to_string());

let request = Request::new(json!({}))
    .path_params(path_params);
```

## 高级用法

### 链式调用

```rust
let request = Request::new(json!({
    "username": "alice",
    "password": "secret"
}))
.header("Content-Type", "application/json")
.header("Authorization", "Bearer token123")
.query("page", "1")
.query("limit", "10")
.path_param("id", "123");
```

### 提取 Token

```rust
// 从 Authorization 头提取 Bearer Token
let request = Request::new(json!({}))
    .header("Authorization", "Bearer my_secret_token");

if let Some(token) = request.token() {
    println!("Token: {}", token); // 输出: Token: my_secret_token
}
```

### 获取参数值

```rust
let request = Request::new(json!({}))
    .header("Content-Type", "application/json")
    .query("page", "1")
    .path_param("id", "123");

// 获取请求头
assert_eq!(request.get_header("Content-Type"), Some("application/json"));

// 获取查询参数
assert_eq!(request.get_query("page"), Some("1"));

// 获取路径参数
assert_eq!(request.get_path_param("id"), Some("123"));
```

## 完整示例

```rust
use yang_base::action::Request;
use serde_json::json;

fn main() {
    // 创建一个完整的请求
    let request = Request::new(json!({
        "user": {
            "name": "Alice",
            "age": 30,
            "roles": ["admin", "user"]
        },
        "metadata": {
            "timestamp": 1234567890,
            "source": "web"
        }
    }))
    .header("Content-Type", "application/json")
    .header("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")
    .header("User-Agent", "MyApp/1.0")
    .query("page", "1")
    .query("limit", "20")
    .query("sort", "created_at")
    .path_param("plugin", "user")
    .path_param("module", "profile")
    .path_param("action", "update");

    // 使用请求
    println!("请求体: {:?}", request.body);
    println!("Token: {:?}", request.token());
    println!("页码: {:?}", request.get_query("page"));
    println!("插件: {:?}", request.get_path_param("plugin"));
}
```

## 注意事项

1. **Token 提取**:`token()` 方法只支持 `Bearer` 格式的 Token,格式为 `Authorization: Bearer <token>`
2. **大小写敏感**:请求头名称支持 `Authorization` 和 `authorization` 两种形式
3. **参数覆盖**:重复添加同名参数会覆盖之前的值
4. **链式调用**:所有添加方法都返回 `Self`,支持链式调用
5. **默认值**:使用 `Request::default()` 创建的请求,body 为 `serde_json::Value::Null`

## 与 Action 系统集成

在 Action 系统中,Request 通常通过 ActionContext 传递:

```rust
use yang_base::action::Request;
use yang_base::error::BaseError;

async fn my_action(context: ActionContext) -> Result<ApiResponse, BaseError> {
    // 从 context 获取 request
    let request = &context.request;
    
    // 提取 Token
    let token = request.token()
        .ok_or(BaseError::Unauthorized)?;
    
    // 获取查询参数
    let page = request.get_query("page")
        .unwrap_or("1");
    
    // 访问请求体
    let username = request.body["username"]
        .as_str()
        .ok_or(BaseError::ParamMissing("username".to_string()))?;
    
    // ... 处理业务逻辑 ...
    
    Ok(ApiResponse::success(json!({"status": "ok"}), "操作成功"))
}
```