## `rubase` 目录解析
`rubase` 是项目的**基础层（Base Layer）**，是整个框架最底层、最通用的模块集合。它提供了实体抽象、工具函数、配置 DTO、加密工具、统一返回结果等基础设施能力。
### 目录结构总览
```
rubase/
├── mod.rs # 入口导出
├── ruentity/ # 实体抽象层（核心）
│ ├── baseentity.rs # 多实例实体 trait + GetSelf
│ ├── baseentitysingle.rs # 单实例实体 trait
│ └── basenum.rs # 实体类型枚举
├── rutils/ # 通用工具函数
│ ├── jsonutils.rs # JSON 序列化/反序列化
│ ├── strutils.rs # 字符串处理 + 环境变量解析 + 加密变量解密
│ ├── fileutils.rs # 文件系统操作（遍历、查找、平台检测）
│ ├── dateutils.rs # 日期时间工具
│ ├── web_utils.rs # Web 工具（IP 获取、User-Agent）
│ ├── idseq.rs # 雪花算法分布式 ID 生成器
│ ├── error.rs # 统一错误类型
│ ├── rufile.rs # 文件路径查找（配置目录定位）
│ └── daterange.rs # 时间范围结构体
├── rudto/ # 数据传输对象（DTO）
│ ├── cfgdto/ # 配置相关 DTO
│ │ ├── cfgdto.rs # 顶层配置聚合结构 CfgDto
│ │ ├── dbdto.rs # Gorm + DataSource（数据库连接配置）
│ │ ├── redisdto.rs # Redis 连接配置
│ │ ├── softdto.rs # 软件信息配置
│ │ ├── webdto.rs # Web 服务配置
│ │ └── etcdto.rs # Etcd 配置
│ └── filedto.rs # 文件 DTO（日志目录、文件大小等）
├── ruconst/ # 常量定义
│ └── ruconst.rs # 路径常量、Token Header 等
├── ruenc/ # 加密解密工具
│ └── ruenc.rs # AES-256-GCM 加解密 + Base64
├── ruresult/ # 统一返回结果
│ └── ruresult.rs # RuResult（对应 Go 的 IchubResult）
└── rucargo/ # Cargo 工具
├── cargohome/ # Cargo 目录定位
└── cargometa/ # Cargo 元数据解析
```
---
### 逐模块详解
#### 1. `ruentity` — 实体抽象层（核心设计）
这是整个框架最核心的设计，定义了两个基础 trait：
| [BaseEntity](file:///E:/soft/gitee.com/ruwebframe/src/rubase/ruentity/baseentity.rs) | 多实例实体 | `if_single()` 返回 `false` |
| [BaseEntitySingle](file:///E:/soft/gitee.com/ruwebframe/src/rubase/ruentity/baseentitysingle.rs) | 单实例实体 | `if_single()` 返回 `true` |
两者都提供：
- `to_json()` / `from_json()` — JSON 序列化/反序列化的默认实现
- `init()` / `shutdown()` — 生命周期钩子
- `auto_init()` — 是否自动初始化
同时提供两个便捷宏：
```rust
impl_base_entity!(Person); // 为 Person 实现 BaseEntity
impl_base_entity_single!(Database); // 为 Database 实现 BaseEntitySingle
```
还有 `GetSelf` trait（blanket implementation）为所有 `Clone` 类型提供 `GetSelf()` 方法，前面已讨论过。
[BaseEnum](file:///E:/soft/gitee.com/ruwebframe/src/rubase/ruentity/basenum.rs) 定义了实体类型枚举：`None` / `BaseEntity` / `BaseEntitySingle`。
---
#### 2. `rutils` — 通用工具函数
| [jsonutils.rs](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rutils/jsonutils.rs) | `struct2json` / `json2struct` / `struct_to_json`，封装 serde_json |
| [strutils.rs](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rutils/strutils.rs) | 字符串处理核心：环境变量解析 `${VAR:default}`、加密变量解密 `enc(...)`、蛇形/驼峰命名转换、`IsEmptyString` trait |
| [fileutils.rs](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rutils/fileutils.rs) | 平台检测（`if_windows/linux/macos`）、目录查找（`find_dir`）、文件遍历（`list_all_files`、`list_rs_files`） |
| [dateutils.rs](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rutils/dateutils.rs) | 基于 chrono 的本地/UTC 时间获取及格式化 |
| [web_utils.rs](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rutils/web_utils.rs) | HTTP 请求工具：获取客户端真实 IP（支持多层代理头）、User-Agent 解析 |
| [idseq.rs](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rutils/idseq.rs) | **雪花算法**分布式唯一 ID 生成器（32bit时间戳 + 3bit机器ID + 14bit序列），支持时钟回拨容错 |
| [error.rs](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rutils/error.rs) | 统一错误类型 `Error::E(String)`，兼容 `io::Error`、`redis::RedisError`、`&str`、`String` 等转换 |
| [rufile.rs](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rutils/rufile.rs) | 自动定位项目 `config/` 目录路径，支持环境变量 `IchubBasePath` 覆盖 |
| [daterange.rs](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rutils/daterange.rs) | 时间范围结构体 `DateRange { start, end }`，内嵌常用时间工具方法 |
**关键设计：环境变量解析链**（[strutils.rs](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rutils/strutils.rs)）
```
"${DB_HOST:localhost}" → parse_env_var() → 先查环境变量，无则用默认值
"enc(abc123)" → dec_var_enc() → 调用 RuEnc 解密
```
两者组合：`parse_env_var()` = `parse_env_var_only()` + `dec_var_enc()`
---
#### 3. `rudto` — 数据传输对象（DTO）
**配置聚合根** [CfgDto](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rudto/cfgdto/cfgdto.rs)：
```rust
pub struct CfgDto {
pub software: SoftDto, // 软件信息
pub web: WebDto, // Web 服务配置
pub gorm: Gorm, // ORM 配置
pub datasource: DataSource, // 数据源配置
pub redis: RedisDto, // Redis 配置
etcd: EtcdDto, // Etcd 配置
}
```
| [Gorm](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rudto/cfgdto/dbdto.rs) | `debug`, `dbType`, `maxOpenConns`, `maxIdleConns` 等连接池参数 |
| [DataSource](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rudto/cfgdto/dbdto.rs) | `host`, `port`, `dbname`, `username`, `password`（支持 `enc()` 加密），`buildUrl()` |
| [RedisDto](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rudto/cfgdto/redisdto.rs) | `addr`, `password`, `db`, `build_url()` → `redis://:password@host/db` |
| [FileDto](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rudto/filedto.rs) | `home_dir`, `suffix`, `size`（根据平台/主从自动调整） |
每个 DTO 都实现了 `parse_env_var()` 方法，支持环境变量占位符自动替换。
---
#### 4. `ruenc` — 加密解密
[RuEnc](file:///E:/soft/gitee.com/ruwebframe/src/rubase/ruenc/ruenc.rs) 是全局单例的加密工具：
- **算法**：AES-256-GCM（认证加密）
- **编码**：Base64（nonce + ciphertext 打包）
- **方法**：`enc(plaintext)` → 密文 / `dec(encoded)` → 明文
- 配置文件中的密码字段可通过 `enc(xxx)` 格式存储，由 `strutils::dec_var_enc()` 自动解密
---
#### 5. `ruresult` — 统一返回结果
[RuResult](file:///E:/soft/gitee.com/ruwebframe/src/rubase/ruresult/ruresult.rs) 对应 Go 的 `IchubResult`，提供统一的 API 返回格式：
```rust
pub struct RuResult {
pub code: i32, // 200=成功, 500=失败
pub msg: String, // 提示信息
pub data: Option<Value>, // 业务数据
pub exist: bool, // 是否存在数据
}
```
便捷构造器：`success()` / `success_data()` / `fail()` / `from_error()`
---
#### 6. `ruconst` — 常量
[ruconst.rs](file:///E:/soft/gitee.com/ruwebframe/src/rubase/ruconst/ruconst.rs) 定义全局常量：
- `IchubBasePath` / `IchubBasePathPkg` — 基础路径环境变量名
- `FILE_MODE_RS` — Rust 模块文件标准名 `mod.rs`
- `FILE_PATH_ENV` / `FILE_PATH_DB_POSTGRES` / `FILE_PATH_DB_MYSQL` — 配置文件路径
- `TOKEN_HEADER` — HTTP 认证头 `Authorization`
---
#### 7. `rucargo` — Cargo 工具
- [cargohome](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rucargo/cargohome/cargohome.rs) — 定位 Cargo 注册表目录（跨平台兼容 Windows/Linux）
- [cargometa](file:///E:/soft/gitee.com/ruwebframe/src/rubase/rucargo/cargometa/cargometa.rs) — 解析 `Cargo.toml` 元数据（工作区、包、依赖信息）
---
### 架构层次关系
```
┌─────────────────────────────────────────────────┐
│ rubase (基础层) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ ruentity │ │ ruresult │ │ ruconst │ │
│ │ 实体抽象 │ │ 统一返回 │ │ 全局常量 │ │
│ └────┬─────┘ └──────────┘ └───────────────┘ │
│ │ │
│ ┌────┴──────────────────────────────────────┐ │
│ │ rutils (工具层) │ │
│ │ jsonutils │ strutils │ fileutils │ ... │ │
│ │ dateutils │ idseq │ web_utils │ error │ │
│ └────────────────┬──────────────────────────┘ │
│ │ │
│ ┌────────────────┴──────────────────────────┐ │
│ │ rudto (数据对象) │ │
│ │ CfgDto ← Gorm/DataSource/RedisDto/... │ │
│ └───────────────────────────────────────────┘ │
│ │
│ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ ruenc │ │ rucargo │ │ (DI 注入) │ │
│ │ 加解密 │ │ Cargo工具 │ │ *_init.rs │ │
│ └──────────┘ └──────────┘ └───────────────┘ │
└─────────────────────────────────────────────────┘
↑ 被依赖
┌────────┴────────┐ ┌──────────┐ ┌──────────┐
│ rudomain │ │ database │ │ rudi │
│ (领域层) │ │ (数据层) │ │ (DI层) │
└─────────────────┘ └──────────┘ └──────────┘
```
**总结**：`rubase` 是整个项目的地基，提供实体抽象范式、跨平台工具函数、配置 DTO 体系、加密解密、统一返回格式等基础能力，所有上层模块（`database`、`rudomain`、`rudi`、`rucfg` 等）都依赖于它。