anycms-core 0.4.0

# anycms-core

支持多种 Rust Web 框架的统一 API 响应库。

## 特性

- **框架无关的核心**：`ApiResult<T>` 结构独立于任何 Web 框架工作
- **多框架支持**：内置 actix-web 和 axum 集成
- **Feature flags**：按需使用 - 零未使用的依赖
- **灵活的响应格式**：支持单值、列表、分页、错误码和额外元数据

## 安装

在 `Cargo.toml` 中添加：

```toml
[dependencies]
anycms-core = "0.3"
```

### Feature Flags

- `actix` (默认)：启用 actix-web 集成
- `axum`：启用 axum 集成
- `full`：启用所有框架集成

#### 示例

```toml
# 默认（仅 actix-web）
anycms-core = "0.3"

# 仅 axum
anycms-core = { version = "0.3", features = ["axum"] }

# 两个框架都启用
anycms-core = { version = "0.3", features = ["full"] }
```

## 项目结构

```
src/
├── lib.rs              # 库入口，带 feature 条件导出
├── result.rs           # 核心 ApiResult<T> 定义（框架无关）
├── pagination.rs       # 分页元数据结构
└── frameworks/
    ├── mod.rs          # 框架模块声明
    ├── actix.rs        # actix-web 集成 (Responder trait)
    └── axum.rs         # axum 集成 (IntoResponse trait)
```

## 架构设计

该库采用清晰的关注点分离设计：

1. **核心层** ([result.rs](src/result.rs), [pagination.rs](src/pagination.rs))
   - 包含数据结构和构建器方法
   - 零框架依赖
   - 无论启用哪个 feature 都会编译

2. **框架层** ([frameworks/](src/frameworks/))
   - 实现框架特定的 trait
   - 基于 feature flags 条件编译
   - 相互隔离，避免冲突

## 使用方法

### Actix-web

```rust
use actix_web::{get, web};
use anycms_core::{ApiResult, ResultPagination};

#[get("/users")]
async fn list_users() -> ApiResult<User> {
    let users = fetch_users().await;
    let pagination = ResultPagination::new(100, 1, 10);

    ApiResult::list(users)
        .with_pagination(pagination)
        .with_extra("has_more", serde_json::json!(true))
}
```

### Axum

```rust
use axum::{extract::Json, routing::get};
use anycms_core::{ApiResult, ResultPagination};

async fn list_users() -> ApiResult<User> {
    let users = fetch_users().await;
    let pagination = ResultPagination::new(100, 1, 10);

    ApiResult::list(users)
        .with_pagination(pagination)
        .with_extra("has_more", serde_json::json!(true))
}
```

## 示例

运行演示示例：

```bash
# Actix-web 演示
cargo run --example actix_demo --features actix

# Axum 演示
cargo run --example axum_demo --features axum

# 检查示例
cargo check --examples --all-features
```

## API 响应格式

该库使用统一的 `data` 字段来处理单值和列表响应：

### 成功响应（单值）

```json
{
  "success": true,
  "data": { "id": 1, "name": "张三" }
}
```

### 成功响应（列表）

```json
{
  "success": true,
  "data": [
    { "id": 1, "name": "张三" },
    { "id": 2, "name": "李四" }
  ],
  "pagination": {
    "total": 100,
    "page": 1,
    "pageSize": 10,
    "currentPage": 1
  }
}
```

### 空成功响应

```json
{
  "success": true
}
```

### 错误响应

```json
{
  "success": false,
  "message": "用户不存在",
  "code": 404
}
```

### 设计说明

- **统一 `data` 字段**：单值和列表都使用 `data` 字段，通过 `ResponseData<T>` 枚举在类型层面区分
- **类型安全**：编译期保证单值和列表互斥，避免运行时错误
- **前端友好**：前端只需判断 `Array.isArray(data)` 即可区分类型
- **向后兼容**：JSON 格式保持简洁，无冗余字段

## 许可证

MIT