ruwebframe应用之一：`domain` 目录深度讲解

leijmdas

91人浏览 · 2026-10-01 20:31:38
leijmdas · 2026-10-01 20:31:38 发布
## `domain` 目录深度讲解

`domain` 是项目的领域层（Domain Layer），遵循 **DDD（Domain-Driven Design）** 分层架构，承载所有业务实体、数据访问对象、业务服务、外观整合与 Web 控制器，是项目的核心业务逻辑层。

---

### 📦 目录结构总览（与实际代码一致）

```
src/domain/
├── mod.rs               # 入口:导出子模块 + serde 序列化辅助(i64→字符串)
├── rudb/                # 核心数据库域
│   ├── dbentity/        #   领域实体(SeaORM 表结构映射)
│   │   ├── plat_menu.rs / user_credits.rs       SeaORM 自动生成实体
│   │   ├── t_sys_user.rs / sys_dept.rs          数据库表实体
│   │   ├── person.rs                            手写示例实体(BaseEntity)
│   │   ├── db_multi.rs                          多实例模式示例
│   │   ├── *_init.rs                            实体 Bean 自动注册(DI)
│   │   └── *_test.rs                            #[cfg(test)] 单元测试
│   ├── dbdao/           #   数据访问对象(DAO)
│   │   ├── plat_menu_dao.rs / t_sys_user_dao.rs DAO(基于 GeneralDb)
│   │   ├── *_dao_init.rs                        DAO 自动注册(DI)
│   │   └── *_dao_test.rs                        #[cfg(test)]
│   ├── dbpage/          #   分页查询处理器
│   │   ├── user_credits_page.rs / t_sys_user_page.rs / plat_menu_page.rs
│   │   ├── config_page.rs                       HTTP 配置展示页
│   │   ├── *_page_init.rs                       分页 Bean 自动注册(DI)
│   │   └── *_page_test.rs                       #[cfg(test)]
│   ├── dbfacade/        #   外观整合层(Facade)
│   │   ├── db_facade.rs                         组合多个 DAO/实体
│   │   ├── db_facade_init.rs                    外观 Bean 自动注册
│   │   └── db_facade_test.rs                    #[cfg(test)]
│   └── dbweb/           #   Web 控制器(Ctl)
│       ├── user_credits_ctl.rs                  对外暴露 REST 接口
│       └── mod.rs
└── ruservice/           # 业务服务层(扩展)
    ├── ru_config_ext.rs + run_config_ext_init.rs  配置扩展
    ├── ru_cache_ext.rs + ru_cache_ext_init.rs     缓存扩展
    ├── web_client_ext.rs + web_client_ext_init.rs Web 客户端扩展
    └── 各 *_test.rs                               #[cfg(test)]
```

---

### 1️⃣ `mod.rs` — 入口与序列化辅助

[mod.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/mod.rs) 除了声明 `rudb`、`ruservice` 子模块并 `pub use rudb::dbfacade::*` 外，定义了**两个关键的 serde 序列化辅助模块**：

- `serde_i64_string`：将 `i64` 以**字符串形式**序列化/反序列化
- `serde_option_i64_string`：同上，但支持 `Option<i64>`

> **为什么？** JS 端 `Number` 无法精确表示超过 `2^53` 的整数，直接下发 i64 会丢失精度。转成字符串可保证数据库大 id 安全传向前端。

```rust
use serde::{self, Deserialize, Deserializer, Serializer};

pub mod serde_i64_string {
    pub fn serialize<S>(value: &i64, serializer: S) -> Result<S::Ok, S::Error>
    where S: Serializer {
        serializer.serialize_str(&value.to_string())
    }
    pub fn deserialize<'de, D>(deserializer: D) -> Result<i64, D::Error>
    where D: Deserializer<'de> {
        let s = String::deserialize(deserializer)?;
        s.parse().map_err(serde::de::Error::custom)
    }
}
```

---

### 2️⃣ `rudb` — 核心数据库域

[rudb/mod.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/rudb/mod.rs) 聚合 5 个子模块：`dbentity`、`dbdao`、`dbpage`、`dbfacade`、`dbweb`。

#### ① `dbentity` — 领域实体

分两类：

**A. SeaORM 自动生成实体**（配 `*_init.rs` 自动注册）

[plat_menu.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/rudb/dbentity/plat_menu.rs)：

```rust
#[derive(Clone, Debug, PartialEq, Eq, DeriveEntityModel, Serialize, Deserialize)]
#[sea_orm(table_name = "plat_menu")]
#[serde(rename_all = "camelCase")]          // 对外使用 camelCase
pub struct Model {
    #[sea_orm(primary_key)]
    #[serde(with = "serde_i64_string")]     // 大 id → 字符串
    pub id: i64,
    pub menu_code: Option<String>,
    pub menu_name: Option<String>,
    pub created_at: Option<DateTimeWithTimeZone>,
    ...
}
```

[user_credits.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/rudb/dbentity/user_credits.rs) 是另一个典型大表实体，包含大量 `Decimal/Option` 字段和唯一键 `idx_user_credits_user_currency_id`。

> **关键**：一个 `Model` 既是 SeaORM 数据库映射，又（因 `Serialize/Deserialize`）直接充当 API 的 DTO，配 `serde_i64_string` 解决前端精度问题，从而让实体即 DTO、无需额外转换层。

**B. 手写示例实体**

[person.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/rudb/dbentity/person.rs)（`BaseEntity` 多实例）与 [db_multi.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/rudb/dbentity/db_multi.rs)：

```rust
// person.rs
impl BaseEntity for Person {}      // 多实例:每次 DI 获取新实例
impl GetSelf for Person {}

// db_multi.rs
impl BaseEntity for DbMulti {}     // same
impl DbMulti {
    pub fn execute(&self) -> String { ru_log::info2("RuMulti execute 123 {}", self.id); ... }
}
```

#### ② `dbdao` — 数据访问对象（DAO）

[plat_menu_dao.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/rudb/dbdao/plat_menu_dao.rs)：

```rust
pub struct PlatMenuDao {
    #[serde(skip)]
    pub general_db: GeneralDb<plat_menu::Entity>,   // 泛型数据库操作器
}
impl BaseEntity for PlatMenuDao {}
impl PlatMenuDao {
    pub fn new() -> Self { Self { general_db: GeneralDb::<plat_menu::Entity>::new() } }
}

// ⭐ Deref 委托:DAO 自动获得 GeneralDb 的全部 CRUD 能力
impl Deref for PlatMenuDao {
    type Target = GeneralDb<plat_menu::Entity>;
    fn deref(&self) -> &Self::Target { &self.general_db }
}
impl DerefMut for PlatMenuDao { ... }
```

> **Deref 委托模式**：DAO 无需逐个转发 `find_by_id / insert / update / delete / query_model` 等方法，通过 `Deref/DerefMut` 自动透明继承 `GeneralDb<T>` 的能力。

**DI 自动注入**（[plat_menu_dao_init.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/rudb/dbdao/plat_menu_dao_init.rs)）：

```rust
#[ctor(unsafe)]                    // 程序启动时自动执行,无需手动调用
pub fn init() { PlatMenuDao::register_bean(); }

impl BeanSimple for PlatMenuDao {
    fn new_bean() -> Self { let mut bean = PlatMenuDao::new(); bean.init(); bean }
}

pub fn find_bean_plat_menu_dao() -> Option<Arc<Mutex<PlatMenuDao>>> { PlatMenuDao::find_bean() }  // 线程安全
pub fn find_bean_plat_menu_dao_simple() -> PlatMenuDao { PlatMenuDao::new_bean() }                 // 便捷获取
```

#### ③ `dbpage` — 分页查询处理器

[user_credits_page.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/rudb/dbpage/user_credits_page.rs) 通过 `Deref` 委托 `SimplePage`，并提供业务化的分页查询编排：

```rust
pub type SimplePageUserCredits = SimplePage<UserCreditsRequest, user_credits::Entity, user_credits::Model>;

pub struct UserCreditsPage { pub simple_page: SimplePageUserCredits }
impl Deref for UserCreditsPage { ... target = simple_page ... }

impl UserCreditsPage {
    pub async fn list(&mut self) -> PageResult {
        self.build_query();
        self.init_query();       // 业务查询条件(如 id>0 时过滤)
        self.general_db.query_model().await
    }
    pub async fn ui_list(&mut self) -> PageResult { self.list().await }
}
```

[config_page.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/rudb/dbpage/config_page.rs) 是 `BaseEntitySingle`（单例），直接作为 HTTP Responder 暴露 `/conf` 配置接口，展示"领域层直接绑定 HTTP 路由"的用法。

#### ④ `dbfacade` — 外观整合层

[db_facade.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/rudb/dbfacade/db_facade.rs) 组合多个组件，对外提供统一入口：

```rust
#[derive(Debug)]
pub struct DbFacade {
    pub multi: DbMulti,       // 业务实体
    pub dao: PlatMenuDao,     // DAO
}
impl BaseEntitySingle for DbFacade {}        // 单例
impl DbFacade {
    pub fn new() -> Self {
        Self {
            dao: find_bean_plat_menu_dao_simple(),   // 从 DI 拉取
            multi: find_bean_db_multi_simple(),
        }
    }
    pub fn execute(&self) -> String { ... }
}
```

[db_facade_init.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/rudb/dbfacade/db_facade_init.rs) 使用 `register_bean_singleton()` 注册**单例**：

```rust
#[ctor(unsafe)] pub fn init() { DbFacade::register_bean_singleton(); }
impl BeanSingle for DbFacade {
    fn new_bean() -> Self { let mut bean = DbFacade::new(); bean.init(); bean }
}
```

> **对比**：`BeanSimple`/`register_bean` = 多实例；`BeanSingle`/`register_bean_singleton` = 全局单例。`DbFacade` 是无状态整合对象，故用单例。

#### ⑤ `dbweb` — Web 控制器

[user_credits_ctl.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/rudb/dbweb/user_credits_ctl.rs) 是领域层对外暴露的 REST 层，覆盖标准 CRUD：

| 方法 | 路由 | 作用 |
|------|------|------|
| `uilist`   | `POST /api/v1/user_credits/uilist`   | 分页列表 |
| `uifind`   | `GET  /api/v1/user_credits/uifind/{id}` | 按 id 查询 |
| `uidel`    | `GET  /api/v1/user_credits/uidel/{id}`  | 删除 |
| `uisave`   | `POST /api/v1/user_credits/uisave`   | 新增(id=0 → NotSet) |
| `uiupdate` | `POST /api/v1/user_credits/uiupdate` | 更新 |

```rust
pub async fn uilist(req: web::Json<SimpleRequest<UserCreditsRequest>>) -> impl Responder {
    let mut page = find_bean_user_credits_page_simple();   // DI 获取分页处理器
    page.set_uireq(req.into_inner());
    let ret = page.ui_list().await;
    res_ok(ret)                                             // 统一响应包裹
}

pub fn register() {
    reg_route!(api_v1_user_credits_uilist, "/api/v1/user_credits/uilist", post, UserCreditsCtl::uilist);
    // ... 其余路由
}
```

---

### 3️⃣ `ruservice` — 业务服务层（扩展）

[ruservice/mod.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/ruservice/mod.rs) 提供三个扩展服务，均以"实现文件 + 独立 `_init` 自动注册"组织。

- [ru_config_ext.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/ruservice/ru_config_ext.rs) `RunConfigExt`：包装 `RuConfig`，通过 `Deref` 透明委托，提供 `read_nats()` 等按 DTO 读取配置的方法；`BaseEntitySingle` 单例。
- [web_client_ext.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/ruservice/web_client_ext.rs) `WebClientExt`：包装 `WebClient` + 内置 `RuCache`（超时 900s），`Deref` 委托 `WebClient`。
- [ru_cache_ext.rs](file:///E:/soft/gitee.com/ruwebframe/src/domain/ruservice/ru_cache_ext.rs) `RuCacheExt`：缓存扩展。

```rust
// ru_config_ext.rs —— "Go 式组合/嵌入"的 Rust 表达
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct RunConfigExt { pub conf: RuConfig }

impl BaseEntitySingle for RunConfigExt {}
impl Deref  for RunConfigExt { type Target = RuConfig; fn deref(&self) -> &RuConfig { &self.conf } }
impl DerefMut for RunConfigExt { ... }

impl RunConfigExt {
    pub fn new() -> Self { let mut c = RunConfigExt { conf: RuConfig::new() }; c.init(); c }
    pub fn read_nats(&self) -> NatsDto { self.parse_object::<NatsDto>("nats") }
}
```

每个扩展都有对应的 `*_init.rs`，用 `#[ctor(unsafe)]` 在启动时注册 Bean，业务代码通过 `find_bean_*()` 获取。

---

### 🧩 数据流：一次请求的完整旅程

```
浏览器
  → POST /api/v1/user_credits/uilist            [dbweb/user_credits_ctl.rs]
  → find_bean_user_credits_page_simple()         [dbpage/ 经 DI 获取 Page]
  → page.ui_list() → list()                       [dbpage/ 业务编排 + 构建查询]
  → general_db.query_model()                      [dbdao/ 经 Deref 委托的 CRUD]
  → user_credits / plat_menu 实体                  [dbentity/ SeaORM 映射]
  → PostgreSQL 数据库
```

### 🧩 三大核心设计模式总结

| 模式 | 位置 | 作用 |
|------|------|------|
| **serde 辅助序列化** | `mod.rs` 的 `serde_i64_string` | i64 转字符串,解决前端精度丢失 |
| **Deref/DerefMut 委托** | DAO、Page、各类 Ext | 组合内嵌对象并透明继承其能力,零胶水代码 |
| **#[ctor] 自动注入(DI)** | 各 `*_init.rs` | 启动时自动注册 Bean,业务通过 `find_bean_*()` 获取 |

模块组织遵循统一的**四件套生成式骨架**：`xx.rs`（实现）+ `xx_init.rs`（DI 注册）+ `xx_test.rs`（`#[cfg(test)]`）+ `mod.rs`（导出），从而让"数据库表 → 实体 → DAO → Page → Ctl(HTTP)"的全链路低代码化。