# anycms-core
支持多种 Rust Web 框架的统一 API 响应库。
## 特性
- **框架无关的核心**：`ApiResult<T>` 结构独立于任何 Web 框架工作
- **多框架支持**：内置 actix-web 和 axum 集成
- **Feature flags**：按需使用 - 零未使用的依赖
- **灵活的响应格式**：支持单值、列表、分页、错误码和额外元数据
- **字段级验证错误**：`FieldError` 支持表单验证场景
- **业务错误码**：`bizCode` 独立于 HTTP 状态码，支持自定义业务语义
- **响应时间戳**：内置 `timestamp` 字段，支持自动注入当前时间
- **请求追踪**：内置 `traceId` 字段，方便生产环境排查
- **序列化风格可配置**：支持 camelCase（默认）和 snake_case
- **tracing 集成**：自动按响应级别记录日志（4xx -> WARN, 5xx -> ERROR）
## 安装
在 `Cargo.toml` 中添加：
```toml
[dependencies]
anycms-core = "0.5"
```
### Feature Flags
- `actix` (默认)：启用 actix-web 集成
- `axum`：启用 axum 集成
- `validator`：启用 `validator` crate 集成，自动转换验证错误
- `tracing`：启用 `tracing` crate 集成，自动按级别记录错误日志
- `full`：启用所有集成（actix + axum + validator + tracing）
- `camel-case` (默认)：JSON 字段使用 camelCase
- `snake-case`：JSON 字段使用 snake_case
#### 示例
```toml
# 默认（actix-web + camelCase）
anycms-core = "0.5"
# 仅 axum
anycms-core = { version = "0.5", default-features = false, features = ["axum"] }
# snake_case 风格
anycms-core = { version = "0.5", features = ["snake-case"] }
# 启用 validator 集成
anycms-core = { version = "0.5", features = ["validator"] }
# 启用 tracing 集成
anycms-core = { version = "0.5", features = ["tracing"] }
# 启用全部
anycms-core = { version = "0.5", features = ["full"] }
```
## 项目结构
```
src/
├── lib.rs # 库入口，带 feature 条件导出
├── result.rs # 核心 ApiResult<T>、错误类型、FieldError
├── pagination.rs # 分页元数据结构
├── tracing.rs # tracing 集成 (feature = "tracing")
├── validator.rs # validator crate 集成 (feature = "validator")
└── 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 条件编译
- 相互隔离，避免冲突
3. **集成层** ([tracing.rs](src/tracing.rs), [validator.rs](src/validator.rs))
- 可选的第三方 crate 集成
- 通过 feature flags 按需启用
## 使用方法
### 成功响应
```rust
use anycms_core::{ApiResult, ResultPagination};
// 单值
let result = ApiResult::value(user);
// 列表 + 分页
let result = ApiResult::list(users)
.with_pagination(ResultPagination::new(100, 1, 10))
.with_extra("has_more", serde_json::json!(true));
// 空响应
let result = ApiResult::<()>::ok();
```
### 错误响应
```rust
use anycms_core::{ApiResult, ApiError};
// 使用 ApiError
let result: ApiResult<User> = ApiError::not_found("用户不存在").into();
// 使用快捷方法
let result = ApiResult::<User>::fail("操作失败").with_code(500);
```
### 业务错误码
`bizCode` 独立于 HTTP 状态码，用于前端业务逻辑判断：
```rust
use anycms_core::ApiResult;
// HTTP 404 + 业务码 10001
let result = ApiResult::<User>::fail("用户不存在")
.with_code(404)
.with_biz_code(10001);
```
### 时间戳
```rust
use anycms_core::ApiResult;
// 自动注入当前时间（Unix 毫秒）
let result = ApiResult::value(user).with_current_timestamp();
// 手动指定时间戳
let result = ApiResult::ok().with_timestamp(1700000000000);
```
### 验证错误
```rust
use anycms_core::{ApiResult, FieldError};
// 一次性传入所有字段错误
let result: ApiResult<User> = ApiResult::validation_errors(vec![
FieldError::new("email", "格式不正确"),
FieldError::new("name", "不能为空"),
]);
// 或链式添加
let result = ApiResult::<User>::fail("验证失败")
.with_code(422)
.with_error("email", "格式不正确")
.with_error("name", "不能为空");
```
### validator crate 集成
启用 `validator` feature 后，可以自动将 `validator::ValidationErrors` 转换为 `ApiResult` 响应：
```rust
use anycms_core::ApiResult;
use validator::Validate;
#[derive(Validate)]
struct CreateUser {
#[validate(email(message = "邮箱格式不正确"))]
email: String,
#[validate(length(min = 1, message = "用户名不能为空"))]
name: String,
}
async fn create_user(data: CreateUser) -> ApiResult<User> {
// validate() 返回 Err 时自动转换为 422 响应
if let Err(errors) = data.validate() {
return errors.into(); // From<ValidationErrors> for ApiResult<T>
}
// ... 业务逻辑
ApiResult::value(user)
}
```
嵌套结构体的字段名会自动加前缀（如 `address.city`），支持与自定义业务错误合并：
```rust
use anycms_core::{validation_errors_to_field_errors, ApiResult, FieldError};
fn handle(data: CreateUser) -> ApiResult<User> {
let mut errors: Vec<FieldError> = Vec::new();
// 收集 validator 错误
if let Err(ve) = data.validate() {
errors.extend(validation_errors_to_field_errors(&ve));
}
// 添加自定义业务校验
if data.name == "admin" {
errors.push(FieldError::new("name", "用户名 'admin' 已被保留"));
}
if !errors.is_empty() {
return ApiResult::validation_errors(errors);
}
// ...
}
```
### 请求追踪
```rust
use anycms_core::ApiResult;
let result = ApiResult::<User>::fail("用户不存在")
.with_code(404)
.with_trace_id("req-abc123");
```
### 分页
```rust
use anycms_core::ResultPagination;
let pagination = ResultPagination::new(95, 3, 10);
// 自动计算并输出：
// - total: 95
// - page: 3
// - pageSize: 10
// - totalPages: 10
// - hasNextPage: true
// - hasPrevPage: true
```
### 错误码
`ErrorCode` 覆盖常用 HTTP 状态码，每个变体都有对应的 `ApiError` 快捷方法：
```rust
use anycms_core::ApiError;
ApiError::bad_request("参数错误"); // 400
ApiError::unauthorized("未认证"); // 401
ApiError::forbidden("无权限"); // 403
ApiError::not_found("资源不存在"); // 404
ApiError::conflict("冲突"); // 409
ApiError::request_timeout("请求超时"); // 408
ApiError::payload_too_large("文件过大"); // 413
ApiError::too_many_requests("限流"); // 429
ApiError::validation("校验失败"); // 422
ApiError::internal("内部错误"); // 500
ApiError::gateway_timeout("网关超时"); // 504
```
### 框架集成
#### Actix-web
```rust
use actix_web::get;
use anycms_core::ApiResult;
#[get("/users/{id}")]
async fn get_user(path: web::Path<u32>) -> ApiResult<User> {
match find_user(path.into_inner()).await {
Some(user) => ApiResult::value(user),
None => ApiResult::<User>::fail("用户不存在").with_code(404),
}
}
```
#### Axum
```rust
use axum::extract::Path;
use anycms_core::ApiResult;
async fn get_user(Path(id): Path<u32>) -> ApiResult<User> {
match find_user(id).await {
Some(user) => ApiResult::value(user),
None => ApiResult::<User>::fail("用户不存在").with_code(404),
}
}
```
## Tracing 集成
启用 `tracing` feature 后，可以通过 `with_tracing()` 方法自动按响应级别记录日志：
```toml
[dependencies]
anycms-core = { version = "0.5", features = ["tracing"] }
```
### 使用方法
```rust
use anycms_core::{ApiResult, ApiResultTracing};
// 成功响应：不产生任何日志（避免噪音）
let result = ApiResult::value(user).with_tracing();
// 4xx 错误：WARN 级别
let result = ApiResult::<User>::fail("用户不存在")
.with_code(404)
.with_tracing(); // -> tracing::warn!
// 5xx 错误：ERROR 级别
let result = ApiResult::<User>::fail("内部错误")
.with_code(500)
.with_tracing(); // -> tracing::error!
```
### 日志级别规则
| 成功 (`success: true`) | - | 无日志 | 避免噪音 |
| 客户端错误 | 400-499 | `WARN` | 如参数错误、权限不足 |
| 服务端错误 | 500+ | `ERROR` | 如内部异常、网关超时 |
日志会自动包含 `code`、`trace_id`、`biz_code` 等结构化字段。
## 请求追踪中间件
`anycms-core` 为 actix-web 和 axum 提供了中间件，自动为响应注入 `traceId`。
### 工作原理
1. 从请求头中提取 trace ID（默认检查 `X-Request-ID` 和 `X-Trace-ID`）
2. 若请求头中不存在，则自动生成 UUID v4
3. 将 trace ID 注入到 `ApiResult` 响应的 `traceId` 字段
### Actix-web 使用
```rust
use actix_web::{web, App, HttpServer};
use anycms_core::actix::ApiResultLayer;
.wrap(ApiResultLayer::default()) // 自动注入 trace_id
.route("/users", web::get().to(list_users))
.route("/users/{id}", web::get().to(get_user))
})
```
### Axum 使用
```rust
use axum::{Router, routing::get, middleware};
use anycms_core::axum::api_result_middleware;
// 零配置（使用默认配置）
let app = Router::new()
.route("/users", get(list_users))
.layer(middleware::from_fn(api_result_middleware));
// 自定义配置
use anycms_core::axum::{ApiResultMiddlewareConfig, api_result_middleware_with_config};
let config = ApiResultMiddlewareConfig {
trace_id_headers: vec!["x-request-id".to_string()],
inject_timestamp: true, // 同时自动注入 timestamp
};
let app = Router::new()
.route("/users", get(list_users))
.layer(middleware::from_fn_with_state(config, api_result_middleware_with_config));
```
## ResultPagination 数据库查询辅助
`ResultPagination` 提供了数据库分页查询的辅助方法，可以直接用于 SQL `OFFSET` / `LIMIT` 子句：
```rust
use anycms_core::ResultPagination;
let pagination = ResultPagination::new(100, 3, 10);
// 用于 SQL OFFSET 子句: (page - 1) * page_size
let offset = pagination.offset(); // 20
// 用于 SQL LIMIT 子句: 等同于 page_size
let limit = pagination.limit(); // 10
// 页面判断
pagination.is_first_page(); // false (当前是第 3 页)
pagination.is_last_page(); // false (总共 10 页)
// 翻页
pagination.next_page(); // Some(4)
pagination.prev_page(); // Some(2)
```
### 典型数据库查询场景
```rust
use anycms_core::{ApiResult, ResultPagination};
async fn list_users(page: i64, page_size: i64) -> ApiResult<User> {
let total = count_users().await; // SELECT COUNT(*)
let pagination = ResultPagination::new(total, page, page_size);
let users = query_users(
pagination.offset(), // OFFSET
pagination.limit(), // LIMIT
).await;
ApiResult::list(users).with_pagination(pagination)
}
```
## API 响应格式
### 成功响应（单值）
```json
{
"success": true,
"data": { "id": 1, "name": "张三" }
}
```
### 成功响应（列表 + 分页）
```json
{
"success": true,
"data": [
{ "id": 1, "name": "张三" },
{ "id": 2, "name": "李四" }
],
"pagination": {
"total": 100,
"page": 1,
"pageSize": 10,
"totalPages": 10,
"hasNextPage": true,
"hasPrevPage": false
}
}
```
### 空成功响应
```json
{
"success": true
}
```
### 错误响应
```json
{
"success": false,
"message": "用户不存在",
"code": 404
}
```
### 业务错误码响应
```json
{
"success": false,
"message": "用户不存在",
"code": 404,
"bizCode": 10001,
"timestamp": 1780542642018
}
```
### 验证错误响应
```json
{
"success": false,
"message": "Validation failed",
"code": 422,
"errors": [
{ "field": "email", "message": "格式不正确" },
{ "field": "name", "message": "不能为空" }
]
}
```
### 带追踪的错误响应
```json
{
"success": false,
"message": "用户不存在",
"code": 404,
"traceId": "req-abc123"
}
```
## 示例
运行演示示例：
```bash
# Actix-web 演示
cargo run --example actix_demo --features actix
# Axum 演示
cargo run --example axum_demo --features axum
# 验证错误演示
cargo run --example validation_demo
# validator crate 集成演示
cargo run --example validator_demo --features validator
# 请求追踪演示
cargo run --example trace_id_demo --features actix
# 业务错误码 + 时间戳演示
cargo run --example biz_code_demo
# ResponseData From trait 演示
cargo run --example from_trait_demo
# 中间件演示 (Actix-web)
cargo run --example middleware_actix_demo --features actix
# 中间件演示 (Axum)
cargo run --example middleware_axum_demo --features axum
# tracing 集成演示
cargo run --example tracing_demo --features tracing
# 检查所有示例
cargo check --examples --all-features
```
## 许可证
MIT