anycms-core

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

特性

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

安装

在 Cargo.toml 中添加：

[dependencies]
anycms-core = "0.3"

Feature Flags

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

示例

# 默认（仅 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, pagination.rs)

   • 包含数据结构和构建器方法
   • 零框架依赖
   • 无论启用哪个 feature 都会编译

2. 框架层 (frameworks/)

   • 实现框架特定的 trait
   • 基于 feature flags 条件编译
   • 相互隔离，避免冲突

使用方法

Actix-web

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

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))
}

示例

运行演示示例：

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

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

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

API 响应格式

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

成功响应（单值）

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

成功响应（列表）

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

空成功响应

{
  "success": true
}

错误响应

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

设计说明

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

许可证

MIT