# daoyi-cloud-common
daoyi-cloud-rs 项目的公共基础库，封装了 Web 服务开发中常用的基础设施能力，供所有业务模块复用。
## 模块概览
| `app` | 应用启动器，串联配置加载、日志初始化、数据库连接、HTTP 服务器启动 |
| `auth` | JWT 认证（编解码 + 中间件） |
| `conf` | 全局配置管理（YAML + 环境变量覆盖，OnceCell 单例） |
| `constants` | 常量定义（默认值、全局值、枚举） |
| `db` | 数据库连接池管理（SeaORM + PostgreSQL） |
| `error` | 统一错误类型 `ApiError`，自动映射 HTTP 状态码 |
| `extract` | Axum 参数提取器（ValidJson / ValidQuery / ValidPath，自动校验） |
| `logger` | 日志初始化（tracing + chrono 时间格式） |
| `openapi` | OpenAPI 文档配置（JWT Bearer 安全方案） |
| `pojo` | 通用 POJO（分页参数 PageParam / 分页结果 PageResult） |
| `response` | 统一 API 响应结构 ApiResponse + `success!` 宏 |
| `server` | HTTP 服务器（Axum + 中间件栈 + Swagger UI + Scalar） |
| `utils` | 工具类（ID 生成、密码加密、序列化） |
## 核心特性
### 统一错误处理
`ApiError` 枚举覆盖了 Web 开发中常见的错误场景，自动映射为合适的 HTTP 状态码：
| `NotFound` | 404 |
| `MethodNotAllowed` | 405 |
| `Unauthenticated` | 401 |
| `Validation` | 422 |
| `Biz` | 400 |
| `DbErr` / `Internal` | 500 |
### 参数校验提取器
提供 `ValidJson<T>`、`ValidQuery<T>`、`ValidPath<T>` 三个提取器，在提取参数的同时自动执行 `validator` 校验，校验失败直接返回
`ApiError::Validation`：
```rust
async fn create(ValidJson(params): ValidJson<UserParams>) -> CommonResult<User> {
// params 已通过校验，可直接使用
}
```
### JWT 认证
- HS256 算法签发/验证 Token
- 中间件自动从 `Authorization: Bearer <token>` 提取并校验
- 支持通过配置忽略指定 URL（Glob 模式匹配）
- 校验成功后将 `Principal` 注入请求扩展
### 统一响应
所有接口返回 `ApiResponse<T>` 结构：
```json
{
"code": 0,
"msg": "",
"data": {}
}
```
配合 `success!` 宏简化使用：
```rust
success!(result) // ApiResult<ApiResponse<T>>
success!() // 无数据返回
```
### 分页
`PageParam` 支持页码/每页条数校验，`PageResult<T>` 泛型分页结果：
```rust
let page = PageResult::from_pagination(params.pagination, total, list);
```
### API 文档
自动集成 Swagger UI 和 Scalar 两套 API 文档界面，共享同一份 OpenAPI 规范。
## 依赖关系
```
daoyi-cloud-common
├── axum (Web 框架)
├── sea-orm (ORM)
├── utoipa + utoipa-swagger-ui + utoipa-scalar (API 文档)
├── jsonwebtoken (JWT)
├── bcrypt (密码加密)
├── validator + axum-valid (参数校验)
├── tracing + tracing-subscriber (日志)
├── tower-http (中间件)
├── config (配置管理)
└── idgenerator + xid (ID 生成)
```