DoraMate 这个项目做到第 12 期说实话最让我头疼的不是 UI 细节也不是 Agent 的推理效果而是数据模型。功能堆到一定程度之后设备信息、网络采样、Agent 分析结果、用户配置全部纠缠在一起每加一个字段都像在雷区里走路。这期我下定决心把整个数据模型和文件落盘方案重做了一遍过程非常值得记录。DoraMate 是一个用 Rust 全栈写的桌面端设备管理工具核心是采集本机和远端设备的硬件型号、MAC 地址、系统类型、系统版本、屏幕分辨率、网络状态生成设备清单并接入了 AI Agent 做健康度分析和维护建议。整个链路从桌面端采集、本地 SQLite 持久化到内置 HTTP API 和前端页面全部由 Rust 完成所以类型系统天然地可以贯穿全栈。这篇就来详解 DoraMate 的数据模型设计类型系统怎么分层、文件系统目录怎么规划、serde 序列化契约怎么守住以及这次踩过的几个真实坑。正在做 Rust 全栈、或者被前后端类型不同步折磨过的朋友这篇应该对你有用。1. 设备信息这种核心数据为什么值得一张类型表贯穿全栈1.1 DoraMate 的业务底色采集、存储、决策三件事在谈类型之前先把业务讲清楚。DoraMate 当初的目标很朴素运维一个实验室几十台设备的状态不能靠人工对着表格记录。每台设备的硬件型号、MAC 地址、系统类型、系统版本、分辨率、网络连接状态这些信息分散在系统命令、配置文件、在线服务等多个数据源。我需要一个统一的模型把杂乱的采集结果收拢成结构化数据。采集只是第一步。数据进了系统之后还要解决存储和决策两个问题。存储要求数据能稳定落盘、能按时间回溯、能跨版本迁移决策要求数据能让下游消费者包括人和 AI Agent快速理解。当我把这三个问题摆在一起看的时候结论很清晰数据模型不是存储层的附属品它是整个项目的地基地基不牢采集、存储、决策全都要跟着返工。Rust 全栈在这里的优势也体现出来了。同一门语言、同一套类型系统从采集源到数据库、从数据库到接口、从接口到桌面端渲染类型可以在整个链路里原样传递。每过一个边界都手工对齐一次的痛苦在这个项目里可以完全避免。1.2 主模型字段的选型决策枚举、字符串、还是独立表先看 DoraMate 的设备主模型#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] pub struct DeviceInfo { pub device_id: String, pub hardware_model: String, pub mac_address: String, pub os: OsType, pub os_version: String, pub resolution: Resolution, pub online: bool, pub last_seen_at: DateTimeUtc, } #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)] #[serde(rename_all snake_case)] pub enum OsType { Windows, Macos, Linux, Android, Ios, } #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] pub struct Resolution { pub width: u32, pub height: u32, }这几个字段看似简单每个背后都有选型理由。第一mac_address暂时用字符串而不是自定义新类型。虽然从建模洁癖角度讲为 MAC 写一个MacAddress新类型能带来静态保证但当前阶段的业务里MAC 地址在采集端已经完成归一化模型里只需要原样传递、原样展示。过早引入新类型意味着读取的每一处都要unwrap或者错误处理反而让代码可读性下降。等什么时候需要拿 MAC 做解析、拆分、合法性校验再升级不迟。这个决定后面在序列化章节还会引出一次事故当时就是因为升级方式不对。第二os用枚举而不是字符串。系统类型是强分类字段绝大多数逻辑都要根据系统分支走不同路径用枚举可以把非法值挡在编译期。但要注意枚举的前提是集合稳定这个前提在现实里并不总是成立所以我后来在枚举设计上做了一层兜底这个放在第 5 章专门讲。第三online和last_seen_at是设备当前状态的快照而更细粒度的network_state不放在主表里。网络状态这种高频变化的数据如果写进主模型每次采样都要更新整行不但锁竞争频繁历史趋势也没法保留。DoraMate 的做法是单独建一张network_samples表每小时采样一次DeviceInfo里的online只是对外接口的最近一次状态缓存。把高频数据和低频数据拆开是整个模型里性价比最高的一个决定。1.3 全栈 Rust 的穿透力从采集到 UI 只维护一份类型DoraMate 的桌面端是 Tauri 加 Rust 核心内置 HTTP 接口也由同一份类型定义驱动。这意味着DeviceInfo既是 SQLite 的行映射目标也是 JSON API 的响应体还是前端页面的状态类型。前期节省的是大量重复代码不需要手写一份 Java/Python 的 DTO再在 JS 里写一份 interface然后找个工具自动生成最后还要保证两边同步。在 Rust 全栈里前端拿到的类型和后台定义的类型在编译期就是同一个来源字段名一致性不用靠人肉维护。不过有一个前提得说清楚这套红利只在全栈都是 Rust的封闭环境里成立。DoraMate 后续如果接了非 Rust 的外部系统同一套类型的优势就会打折。所以我在下一章安排了传输模型层把对外契约和内部模型分开用三层拆分把全栈红利和未来解耦同时兼顾。2. 领域模型、持久化模型、传输模型三层拆分守住各自边界2.1 一个结构体打天下为什么走不远我见过很多 Rust 项目包括我自己早期的代码一个struct Device从头用到尾数据库查出来是它业务逻辑处理是它API 返回也是它前端接收的还是它。前期确实爽少写一行是一行。但只要你开始加字段就明白了三个角色对字段的需求根本不一样数据库表需要id、created_at、updated_at、schema_version业务逻辑大部分时候不关心这些业务逻辑需要agent_conclusions、owner_id这类关联字段前端展示不需要API 返回需要字段命名的稳定性、空值处理策略数据库列名的叫法跟前端展示的叫法经常是两回事。让一个结构体同时兼任三个角色本质上是把三组不同的变更压力集中到了一个地方。数据库要加列、业务要加状态、API 要加字段任何一个需求进来都要动同一个结构体风险被无限放大。2.2 三层的代码长什么样重构之后DoraMate 的模型分成三层领域模型Device业务逻辑的中心状态最完整包含设备归属、Agent 分析结论、最近一次采样时间等。持久化模型DeviceEntity和 SQLite 表一一对应字段名即列名包含id、created_at、updated_at、schema_version。传输模型DeviceDto对外 API 和前端页面消费的形态字段裁剪过、命名按接口规范、空值按前端需求填充。持久化模型大概是这样的#[derive(Debug, Clone, Serialize, Deserialize)] pub struct DeviceEntity { pub id: i64, pub device_id: String, pub hardware_model: String, pub mac_address: String, pub os: String, pub os_version: String, pub width: u32, pub height: u32, pub online: bool, pub last_seen_at: String, pub created_at: String, pub updated_at: String, pub schema_version: i32, }注意os在 Entity 里是字符串因为在数据库里它就是一个文本列。等它经过TryFrom转换进领域模型时才会被精确解析成OsType枚举。没有人手动修改数据库的话这个解析总能成功一旦出现脏数据解析会明确失败而不是悄悄吞掉。2.3 转换层的职责边界From 负责搬运TryFrom 负责校验三层模型自然需要转换代码。DoraMate 的原则是无逻辑的字段搬运写From有规则的转换写显式TryFrom。两者的分界线很清楚——纯赋值用From涉及解析、校验、失败可能性的用TryFrom。impl TryFromDeviceEntity for Device { type Error ModelError; fn try_from(entity: DeviceEntity) - ResultSelf, Self::Error { let os OsType::from_raw(entity.os).ok_or(ModelError::UnknownOs(entity.os))?; Ok(Self { id: entity.device_id, hardware_model: entity.hardware_model, mac_address: entity.mac_address, os, os_version: entity.os_version, resolution: Resolution { width: entity.width, height: entity.height, }, online: entity.online, last_seen_at: DateTime::parse_from_rfc3339(entity.last_seen_at) .map_err(ModelError::BadTimestamp)?, }) } } impl FromDevice for DeviceDto { fn from(device: Device) - Self { Self { device_id: device.id, os: device.os.as_str().to_string(), resolution: format!({}x{}, device.resolution.width, device.resolution.height), } } }TryFrom这个写法有一个关键收益数据库里一旦出现枚举值之外的字符串或者时间戳格式坏了转换会明确失败并带上错误原因。DoraMate 的策略是失败后把记录标记为parse_error放进修复队列而不是让脏数据混进业务流。这个处理方式保证业务层永远只面对合法的Device实例。2.4 三层拆分换来的是什么三层拆分的直接收益是三类变更可以各自独立演进数据库表要改只动 Entity 和迁移脚本API 要变只动 DTO 和接口文档业务规则要变只动领域模型。三者之间的转换层充当翻译官而不是让任何一方直接暴露到另外两方的世界里。代价当然也有。每多一层模型就多一层转换代码。但 Rust 的模式匹配和From实现让这层代码成本很低而且这些转换逻辑往往是项目里最容易写测试的部分。真正贵的是一个结构体打天下时改一个字段要同时担心数据库迁移、API 兼容、前端展示、Agent 解析四种连锁反应——那时候的调试成本才是真金白银。3. 文件系统架构数据目录、快照目录、索引目录的分工与扩容类型模型定了之后下一个核心问题是数据怎么落盘。Rust 桌面应用最容易犯的错是把所有文件丢在可执行文件旁边或者一股脑塞进一个data目录。DoraMate 这次按目录职责彻底分家。3.1 目录规划配置、数据、缓存必须分家路径用 dirs目录类别平台路径示例内容数据目录Linux:~/.local/share/doramate/SQLite 数据库、设备快照、索引元信息配置目录~/.config/doramate/config.toml、Agent 策略配置、采集任务定义缓存目录~/.cache/doramate/临时下载、缩略图、升级包选路径时不要手写std::env::home_dir()拼接那个 API 在跨平台场景下有历史遗留问题。我用的是dirscrate 来获取各平台的官方目录Windows 上落在 AppDatamacOS 上落在Application SupportLinux 上走 XDG 规范。路径统一由启动时的一个AppPaths结构体解析出来之后所有模块都通过它取路径而不是到处硬编码。3.2 版本化快照目录时间旅行的代价与收益DoraMate 的目录结构设计如下doramate/ db/ doramate.db doramate.db-wal doramate.db-shm schema/ migration_001.sql migration_002.sql migration_003.sql snapshots/ 2025-01-01T00-00-00Z/ devices.json network_samples.json 2025-01-08T00-00-00Z/ devices.json network_samples.json indexes/ devices.idx devices_fulltext.idx tmp/这个结构里最值得解释的是snapshots目录。设备采集是周期性动作每次采集结束后DoraMate 会把当前设备清单和网络采样序列化成一个完整 JSON 快照放到以 UTC 时间戳命名的子目录里。为什么快照独立于数据库因为 SQLite 只保存当前状态而快照解决的是过去某个时间点设备长什么样的问题。有了快照AI Agent 可以对比分析设备的历史健康度变化运维人员也可以回溯问题出现的时间点。快照目录的命名用YYYY-MM-DDTHH-MM-SSZ这种排序友好格式方便脚本按前缀做时间范围扫描。每次快照是完整全量不是增量。原因很直接设备数量级在几百台完整 JSON 也就几百 KB增量格式省下的空间远抵不上它带来的复杂度。schema目录对应 SQLite 的迁移脚本按序号排列。DoraMate 没用外部迁移工具桌面应用要离线可用迁移量又不大直接用PRAGMA user_version加内置脚本启动时按序号依次执行不需要渲染任何运行时文件。3.3 原子写入与崩溃恢复tmp 目录不是万能的快照是 JSON 文件如果直接fs::write遇到断电或者进程被杀会留下半截文件。DoraMate 的所有快照写入统一走原子写流程写临时文件、强制落盘、rename 替换、最后再 fsync 目录。fn atomic_write_json(path: Path, value: impl Serialize) - io::Result() { let tmp path.with_extension(tmp); let mut file OpenOptions::new() .write(true) .create(true) .mode(0o600) .open(tmp)?; let mut writer BufWriter::new(mut file); serde_json::to_writer_pretty(mut writer, value)?; writer.flush()?; writer.get_ref().sync_all()?; drop(writer); fs::rename(tmp, path)?; Ok(()) }几个细节必须强调。第一rename只有同一文件系统内才是原子操作。临时文件如果放在系统/tmp目录而数据目录在另一个分区rename 会返回跨设备错误。所以 DoraMate 的tmp目录固定在数据目录内部就是这个原因。第二File::create默认权限位不可控设备快照虽然没有密码但也属于隐私数据。用OpenOptions把权限限定为0o600避免同机其他用户读取。第三writer.flush()只是把数据从 BufWriter 推到内核页缓存真正保证落盘的是sync_all()。对快照这种不可再生数据多调一次 fsync 的耗时完全可以接受。提示如果你用Buffer写出后又立刻 rename一定要先 drop 掉 writer 再 rename否则文件句柄还握着数据rename 可能会因为 Windows 的文件锁机制失败。这段我实际踩过Windows 上尤其明显。3.4 能用数据库管理的就别让外部文件挡路DoraMate 早期把设备名称的全文索引写成了一个几 MB 的 JSON 文件后来发现性能和维护都是问题。这次重构把索引表挪进了 SQLite外部indexes目录只保留元信息真正的查询走数据库索引。经验是文件系统里躺着几十个 JSON是迟早要出事的事能用数据库管理的尽量进数据库文件只承载必须由文件承载的东西比如快照、配置、资源文件。4. serde 序列化契约Rust 类型是编译期约束也是线上数据格式类型定义了、文件架构也稳定了中间还有一个隐性杀手JSON 格式的稳定性。Rust 全栈项目里前后端同源最容易犯的错是反正都是同一个类型改就改了。改完之后旧数据、旧客户端、旧 Agent 可能全崩。这一章讲 serde 怎么把序列化格式变成一种可测试的契约。4.1 三个高频属性default、skip_serializing_if、transparent先看 DoraMate 的传输模型#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] #[serde(default)] pub struct DeviceDto { pub device_id: String, pub os: String, pub os_version: String, pub mac_address: String, pub resolution: String, #[serde(skip_serializing_if Option::is_none)] pub wireless_ssid: OptionString, pub online: bool, }#[serde(default)]保证新增字段之后老 JSON 反序列化不会因为缺字段直接失败。skip_serializing_if让空 Option 不输出 null客户端处理更舒服。这两个属性对前后端兼容是最基础的保险。这里要特别提醒字段默认值不能随便填。有人图省事给mac_address填default 结果老客户端把空串当真值去展示反而制造了隐性 bug。DoraMate 的习惯是新增字段的默认值必须是明确的空状态要么None要么Vec::new()要么语义上确实是零值的东西不要用空字符串糊弄过去。另一个高频属性是#[serde(transparent)]。它把新类型序列化成内部字段的原始形态。这个设计在自定义封装类型上极其好用我下面事故案例里会具体说到。4.2 契约测试把 JSON fixture 锁进测试套件类型系统再强也挡不住同一个类型字段语义变了这种兼容问题。DoraMate 这次专门加了一套契约测试在tests/fixtures/下保存了从 v1 到当前版本的所有 JSON 样例每个样例对应一个测试直接把 JSON 字符串反序列化成DeviceDto断言关键字段值。#[test] fn v1_device_dto_fixture_can_be_deserialized() { let raw include_str!(fixtures/v1/device_dto.json); let dto: DeviceDto serde_json::from_str(raw).expect(v1 fixture must still parse); assert_eq!(dto.device_id, dev-001); assert_eq!(dto.os, linux); assert_eq!(dto.mac_address, aa:bb:cc:dd:ee:ff); assert_eq!(dto.resolution, 2560x1600); assert!(dto.online); }这种测试成本极低但价值极高。只要有人改了字段名、改了枚举 tag、改了字段类型测试立刻红。尤其当你同时维护桌面端和 HTTP 接口时契约测试就是两种消费方之间的安全带。没有这套测试你根本不知道老版本客户端什么时候会静默失败。4.3 一次 MAC 地址字段重构引发的兼容事故这个坑我必须展开讲。早期 DoraMate 的mac_address是String序列化出来是mac_address: aa:bb:cc:dd:ee:ff。有一次我觉得该加合法性校验就给 MAC 地址包了一层MacAddress(String)新类型还实现了序列化但没做扁平化。结果输出变成了{ mac_address: { value: aa:bb:cc:dd:ee:ff } }旧版桌面端直接反序列化失败整机列表白屏。问题的根子不是加了新类型而是没有意识到序列化输出形态本身就是公开 API 的一部分它一变所有消费者全部遭殃。修复方案其实很简单给新类型加上#[serde(transparent)]让它序列化回原来的字符串形态兼容性立刻找回。但这个事故给我留下的教训很深在 Rust 里类型不只是编译期约束它的Serialize行为直接决定了线上数据格式。任何自定义类型进入公开模型之前都要先问一句它序列化出来的东西老版本能不能吃不能吃就补契约测试挡路而不是等线上炸了才追。5. 关键决策复盘手写 SQL、未知枚举兜底、AI Agent 的元数据接口最后一章聊聊这次重构里的三个方向性决策。它们不直接写进某个结构体但决定了整个数据模型未来能不能平稳扩展。5.1 为什么没上 ORM表少、查询固定、迁移量小DoraMate 的存储层一直用手写 SQL 加rusqlite这次重构之后依然没有引入sqlx或diesel。理由很现实这个项目的数据表不超过十张查询模式固定按设备 ID 查、按批次查、做聚合统计没有复杂的联表。引入 ORM 的收益在复杂业务里才兑现在当前这个规模下反而带来宏处理时间、迁移工具学习成本、动态查询的抽象摩擦。手写 SQL 的代价是字段映射要手动维护。我的应对方式是在 Entity 层写严格的映射测试把每张表的 SELECT 列和结构体字段绑死一次查询对应一个测试。这样既保留了手写 SQL 的直接性和可控性又不会因为改表结构漏改代码而出现静默错误。5.2 枚举不是越多越好未知值兜底设计回到第 1 章的OsType。第一版设计时我把当时见过的所有系统都列进枚举还放了FreeBsd、Solaris这种变体。后来采集端真的碰到一个没定义的系统时serde_json直接反序列化失败整条记录废弃。这是典型的枚举越界事故。现在的设计是两层#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] pub enum KnownOs { Windows, Macos, Linux, Android, Ios, } #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] #[serde(untagged)] pub enum OsType { Known(KnownOs), Unknown(String), }已知系统走正常枚举未知系统走字符串兜底。不认识的系统能存下来、能展示、能参与基本的统计只是不能参与需要精确分类的逻辑。这个模式的本质是别让类型系统成为数据流通的阻碍。类型系统应该帮助数据流动而不是用未知把数据挡在门外。5.3 给 AI Agent 的扩展点在类型之上加一层字段描述最后说一个 DoraMate 独有的设计。AI Agent 要读设备数据做分析如果 Agent 只认DeviceDto里写死的字段以后设备类型扩展比如增加 GPU 信息、硬盘 SMART 状态核心模型改了Agent 也得跟着改 prompt 和代码这显然不可持续。这次我在类型系统之上加了一层字段元数据描述用 JSON Schema 描述DeviceDto的每一个字段的语义、单位、取值范围。Agent 启动时读取这份描述而不是硬编码字段名。{ device_id: { type: string, description: 设备唯一标识 }, os: { type: string, description: 操作系统类型 }, resolution: { type: string, description: 屏幕分辨率格式 WxH }, last_seen_at: { type: string, description: 最近一次上线时间RFC3339 } }新增字段时只要同步更新描述文件Agent 就能动态理解新数据的含义。静态类型保证数据不出错元数据描述让下游消费者知道数据是什么。这是类型系统在 AI 时代的一次延伸也是 DoraMate 数据模型和传统 Rust 项目最不一样的地方。最后补一句最实在的体会。数据模型这件事拖延的代价是指数增长的。DoraMate 前八期功能开发得飞快第九期开始每次改字段都牵一发动全身到了第十二期我才痛下决心重做。如果你也在做 Rust 全栈项目设备信息、资产这类核心数据从第一版就把类型分层、目录分家、契约测试这三件事做了后面省下的时间绝对超过前期多花的功夫。踩过的坑都摆在这了能帮你少绕几周弯路这篇就值了。