前言

在把 Dioxus Demo 转化为完整项目时我深刻体会到两点痛点：

• 功能层面虽然已完成。但代码结构却像“拼图”，缺少清晰边界。其实，
• 随手写的 # 与 UI 代码混用。导致后期维护成本飙升，

这篇文章聚焦于如何在保持 Demo 能跑的同时建立可维护、可 的工程化结构。

一、Dioxus 一到项目阶段，最容易乱的不是 UI，而是边界

从结论先说来看。Dioxus 工程化最关键不是拆层数，而是先立住四个边界：

• components只负责复用 UI。
• pages只负责页面编排与页面级状态。
• server只处理服务端逻辑与外部资源。
• models只定义输入输出的数据形状。

如果这些边界模糊，你会遇到：

• 组件里不小心 import 数据库模型。
• 页面直接写 SQL 查询语句。
• # 同时做校验、落库、拼文案。其实，
• 用作表单、数据库行、接口返回等多种角色。

为什么要先立住边界？

Dioxus 的全栈特性代表着客户端和服务端共享同一套 Rust 代码。如果你习惯把所有东西塞进“前端目录”，就会出现角色不清晰导致后期难以拆分和维护的问题。通过把不同网站的建立隔离开，并让 Server Functions 保持 Axum‑compatible 的入口形态。你可以在不牺牲全栈体验的前提下把代码责任划分得更明确。

二、目录先别花。先让人一眼看懂谁该改哪里

建议的起步结构

src/
├── main.rs
├── lib.rs
├── app.rs
├── components/
│ ├── mod.rs
│ ├── layout.rs
│ ├── note_form.rs
│ └── note_list.rs
├── pages/
│ ├── mod.rs
│ ├── home.rs
│ ├── new_note.rs
│ ├── edit_note.rs
│ └── not_found.rs
├── models/
│ ├── mod.rs
│ ├── note.rs
│ └── form.rs
└── server/
├── mod.rs
├── db.rs
├── errors.rs
├── note_repo.rs
└── note_service.rs

痛点：

• A 项目中添加新需求时如果需要改动多个文件，很可能说明边界已经混合。比如同时修改表单 UI、页面流程与数据库查询，往往代表着各层职责交叉过度。其实，再看方法，保持上述四个模块清晰，可快速定位改动位置。话说回来，

一个能跑的最小骨架示例

fn main {
dioxus的观点是。:launch，}

pub mod app;pub mod components;pub mod pages;pub mod models;pub mod server;

// App component with routing and ErrorBoundary.
use dioxus::prelude::*;use crate::pages::{edit_note::EditNotePage,home::HomePage。new_note::NewNotePage,not_found::NotFoundPage};话说回来，#
pub fn App -> Element {
rsx!{
ErrorBoundary {
handle_error: |error| {
rsx!{
div { class:"app-error",h1 { "页面出错了" }
p { "{error}" }
}
}
},Router::::default
}
}
}
#
enum Route {
# HomePage {},# NewNotePage {},# EditNotePage { id: i64 },# NotFoundPage { route: Vec }。}

另一个直接跑起来的最小片段示例

use dioxus::prelude::*;use tracing_subscriber;

struct NoteFormData { 再看title，String,content: String。}

fn validatenoteform -> Result<, &'static str>{ if input.title.trim.isempty{ return Err;} if input.content.trim.isempty{ return Err;} Ok) }

fn App -> Element{ let mut title= usesignal;let mut content= usesignal;let mut message= usesignal;rsx，{ div{ h1{ "Dioxus Project Shape Demo"} input{ value:"{title}",placeholder:"标题",oninput:move|evt|title.set),} textarea{ value:"{content}"。placeholder:"正文",oninput:move|evt|content.set),} button{ onclick:move ||{ let form= NoteFormData{ title的观点是，title,content:content,};match validatenoteform{ Ok => { tracing::info!，message.set);},Err=>message.set),}}。"提交"} p{ "{message}"} } } }

fn main{ tracing_subscriber::fmt.init;说起来，dioxus::launch;说起来，}

mod tests{ use super::*;# fn rejectemptytitle{ let result=validatenoteform,content:"hello".into});assert_eq，); } }

使用者痛点 在这个示例里我们已经将数据形状分离；而组件仅关注 UI 与状态管理。这样做可以减少后期需求变更导致的大范围重构。

---

二、models 不要偷懒只放一个万能 Note 对象

A 常见错误是将一个 “万能” Note struct 用作列表项、详情页还有表单输入等多种用途，从而造成后期修改列表展示时无意中破坏表单逻辑。下面给出更稳健的拆分方式：

建议的数据结构拆分方案
作用域	字段	备注
显示层	id。i64 title,String excerpt,String	仅用于列表展示，避免包含过多业务字段导致冗余更新。
detail,String content。String	用于详情页展示。
form_data,String title,String content。String	专门对应编辑/创建表单，只包含必填字段。
为什么这样做？	切换职责后不会产生跨层副作用；按理说，例如更新列表标题不影响编辑表单逻辑。 每个结构体仅承担其职责，提高类型安全性与可读性。 未来需要新增字段。只需在对应结构体中 即可，无须遍历整个项目进行修正。说起来，

---

再看页面级错误。ErrorBoundary 放置技巧

Dioxus 支持通过 ErrorBoundary 捕获组件渲染过程中的错误，并在更高层统一处理，这样可以避免大量重复兜底代码。下面演示如何在页面级别使用它：

rust

// 页面组件

fn ArticleView -> Element{ let res:anyhow::Result<,&'static str>=Ok);// 模拟可能抛出的错误 match res{Ok=>rsx!{article{dangerousinnerhtml:"{html}"}},Err=>return Err)}

}

// 全局兜底 rsx!{ ErrorBoundary{ handle_error : |err|{ rsx!{ section{class:"error-panel" h2{"这块内容没渲染出来"} p{"{err}"}}}}。Router::::default }

使用者痛点 * 在大规模项目中，每个组件都需要手动判断错误并返回兜底 UI，会造成代码膨胀且易忽略。说起来，* 错误信息被吞掉后仅留下白屏或浏览器报错日志。对开发者定位十分困难，

---

Server Function 边界薄而强：仅做协议收口

// 真正业务逻辑所在 pub async fn savenote->Result{ if input.title.trim.isempty{bail!，} Ok }

// Server Function 封装

noteservice::savenote.await.map_err(|e| ServerFnError::new))}

使用者痛点

• 当业务逻辑写在 Server Function 内部时一旦出现数据库异常或参数校验失误，就需要手动拆解日志与错误信息。
• 因为需求增多。Server Function 层会演变成 “大魔王”，难以测试和复用。

---

全链路错误信息细粒度化处理

// 错误类型枚举 enum AppError { UserError,SystemError,DbError。... }

impl From' for ServerFnError {' // 转换为 Dioxus 可识别错误类型

• 如果直接返回字符串 “删除失败”，前端只能得到一句话，却无法判断具体原因。话说回来，
• 程序内部异常泄露给使用者不仅安全风险。还会让日志记录失去意义，

---

客户端日志的观点是，让 UI 操作留下痕迹

// 点击事件记录 button{ onclick : move |_| tracing::info!,"{title}" }

• 单纯使用 console.log 或 println 无法区分来源，也不支持结构化查询。
• 需要能够快速定位事件来源。

---

服务端统一初始化 & 日志字段规范化

fn main{ tracingsubscriber ::fmt .withmax_level.init;怎么说呢，dioxus ::launch;}

async fn savenote-> Result<>{ tracing ::info!，if input.title.trim .isempty {{ tracing ::warn!，anyhow :: bail!，}} // …db 操作，老实说，tracing ::info!，Ok) }

• println! 的输出缺乏上下文信息。如请求 ID 或使用者 ID，使得排查堆栈困难。
• 跨网站应用会产生多种日志源，一个统一框架能保证一致性与可视化效果。话说回来，

---

不要把日志与提示混成一件事

// 前端提示文本 notification;说起来，

// 日志记录 logging.info!，

• 如果两者使用相同文本，不利于从日志中快速定位问题原因。老实说，
• 提示应当人性化。而日志应当机器可读，

---

---

---

---

。

---