04.4.13.3 Workspace分层与架构选型
所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.4 Rust / 04.4.13 部署云原生与工程架构
04.4.13.3-001 中型 Rust 服务项目的虚拟 workspace 整体结构怎么组织?
一句话结论
在仓库根 Cargo.toml 声明 [workspace] 与成员列表,按架构层划分多个 crate:核心领域、应用编排、基础设施实现、对外接口各成 crate,二进制入口 crate 负责装配并启动服务。
概念解释
workspace 是 Cargo 对同一仓库内多个包的组织方式:共享锁文件、target 目录与依赖解析,成员 crate 之间可直接 path 依赖。按架构分层拆 crate 的目的是让依赖方向在编译期可检查:核心 crate 不依赖外层实现,外层 crate 依赖核心。
原理流程
- 根
Cargo.toml声明 workspace 成员目录。 - 各 crate 提供独立
Cargo.toml与src/lib.rs(或src/main.rs)。 - 成员间通过 path 依赖引用,依赖方向沿架构层单向流动。
- 入口二进制 crate 装配各层并启动运行时。
- 编译时按依赖图增量构建,核心层先于外层编译。
代码或图示
# 根 Cargo.toml
[workspace]
members = [
"crates/domain",
"crates/application",
"crates/infrastructure",
"crates/api",
]
常见误区
- 所有代码塞进单一 lib crate:模块边界只靠目录约定,编译期无法阻止逆向依赖。
- workspace 成员互相随意依赖:依赖图成环或核心层被外层污染,分层失去意义。
追问
- workspace 与多仓库发布有什么区别?答:单仓库 workspace 内用 path 依赖,改动一次提交可见;跨仓库才需要版本号与私有 registry 协调。
- 根目录
Cargo.lock作用?答:workspace 共享一份锁定解析结果,保证成员依赖版本一致。
04.4.13.3-002 [workspace.dependencies] 在架构层统一依赖版本解决什么问题?
一句话结论
它把公共依赖的版本与 feature 集中在根配置声明,成员 crate 用 workspace = true 继承;架构层面保证各层使用同一版本的基础库,避免传递依赖出现多版本重复。
概念解释
基础库(serde、tokio、thiserror 等)版本分散在各 crate 时,容易出现同一依赖被解析成多个版本,编译体积与运行时类型不兼容问题随之而来。集中声明后升级只改一处,成员继承同一约束。内部业务 crate 之间的版本对齐也通过 workspace 统一管理。
原理流程
- 根
[workspace.dependencies]声明公共依赖版本与 feature。 - 成员 crate 依赖项写
version = "..."加workspace = true。 - Cargo 解析时成员继承根配置的版本约束。
- 升级公共库只修改根配置一处。
cargo tree -d检查是否仍有重复版本。
代码或图示
# 根 Cargo.toml
[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
thiserror = "2"
# 成员 crate Cargo.toml
[dependencies]
serde = { workspace = true }
thiserror = { workspace = true }
常见误区
- 成员 crate 再写死不同版本号:绕过 workspace 继承,版本对齐失效。
- 把内部业务 crate 也放进
[workspace.dependencies]却不发布:跨 crate 引用仍需 path 或版本策略配合。
追问
- 继承后还能在成员里追加 feature 吗?答:可以在成员依赖项上补充 feature,基础版本约束仍来自根配置,具体合并规则以 Cargo 文档为准。
- 如何发现重复依赖?答:
cargo tree -d列出同一包的多版本条目,再回溯是哪些 crate 引入了冲突约束。
04.4.13.3-003 domain、application、infrastructure、api 四层各自职责是什么?
一句话结论
domain 放领域模型与业务规则,application 编排用例并调用端口,infrastructure 实现端口(数据库、消息、外部客户端),api 暴露 HTTP/gRPC 接口并装配依赖;依赖方向从外向内,核心不感知外层实现。
概念解释
四层对应 Clean Architecture 的同心圆:内层是业务核心,外层是技术实现与接口。domain 不依赖数据库框架与 Web 框架;application 定义用例编排与端口接口;infrastructure 提供具体技术实现;api 做协议适配与状态装配。换框架或换存储时,核心规则不动。
原理流程
- domain 定义实体、值对象、领域错误与仓储端口 trait。
- application 实现用例服务,通过端口 trait 操作领域对象。
- infrastructure 用 SQLx/SeaORM 等实现端口 trait,持有连接池。
- api 注册路由、把请求映射为用例入参,把结果映射为响应。
- 入口 crate 把 infrastructure 实现注入 application,再挂到 api 状态。
代码或图示
api(路由、DTO、装配)
→ application(用例编排、端口)
→ domain(模型、规则、端口定义)
infrastructure(端口实现:DB/MQ/外部 API)
→ 实现 application/domain 定义的 trait
常见误区
- 把 SQLx 类型直接写进 domain 模型:核心层绑定具体数据库框架,换存储要改核心规则。
- application 直接写 HTTP 响应类型:用例被协议层污染,无法被 CLI 或消息消费者复用。
追问
- 四层是否必须拆成四个 crate?答:小项目可在单 crate 内按模块分层;规模增大后再拆 crate,边界用编译依赖强制约束。
- 端口 trait 定义在哪一层?答:定义在使用它的内层(domain 或 application),实现在 infrastructure,这是依赖倒置的关键。
04.4.13.3-004 依赖方向规则如何落地,为什么核心层不能依赖外层?
一句话结论
规则是外层依赖内层、内层不反向依赖;domain/application 不引用 Web 框架、数据库驱动与外部 SDK,这些只出现在 infrastructure 与 api。反向依赖会让核心规则被技术实现绑架,测试与替换成本上升。
概念解释
依赖方向保证业务规则独立于技术选型:核心层可在无数据库、无网络的环境下单元测试;外层替换实现(换 ORM、换框架)不影响用例。Rust 的 crate 依赖是编译期强制的,把分层落到 crate 边界后,逆向依赖在编译期就暴露。
原理流程
- 绘制依赖图:api → application → domain,infrastructure → application/domain。
- 检查各 crate 的
[dependencies],核心层不出现外层技术栈。 - 外层通过实现内层 trait 完成对接。
- 评审与 CI 检查依赖方向是否被破坏。
- 出现逆向依赖时把接口下沉到内层,实现留在外层。
代码或图示
允许:
api → application, domain
application→ domain
infra → application, domain
禁止:
domain → sqlx / axum / 外部 SDK
application→ 具体数据库实现类型
常见误区
- 核心层为了方便直接引入序列化框架:domain 被协议格式绑定,换 DTO 表示要改模型。
- 认为「只是引用一个类型没关系」:类型依赖会沿调用链扩散,最终核心层与实现耦合。
追问
- 如何用工具检查依赖方向?答:审查各 crate 依赖清单,或用脚本/cargo-deny 规则约束核心层允许的依赖集合。
- 核心层需要日志怎么办?答:在核心层定义日志端口或使用抽象接口,具体日志实现由外层注入。
04.4.13.3-005 如何用 feature 开关隔离可选后端实现?
一句话结论
可选数据库后端、可选消息队列或可选客户端通过 Cargo feature 条件编译隔离:端口 trait 在核心层固定,不同实现 crate 或依赖由 feature 选择,编译产物只包含启用的实现。
概念解释
feature 是编译期依赖隔离手段:同一服务面向不同部署环境可能需要不同存储后端。核心层定义统一端口,实现按 feature 分组启用;未启用的后端不进入编译产物,减小体积与依赖面。运行时开关与编译期 feature 不要混用(详见部署配置专题)。
原理流程
- 核心层定义后端操作的端口 trait。
- 各后端实现作为独立依赖或独立模块。
[features]声明后端开关,默认启用常用组合。- 代码用
#[cfg(feature = "...")]条件编译实现注册。 - 构建时按目标环境选择 feature 组合。
代码或图示
[features]
postgres = ["dep:sqlx-postgres"]
sqlite = ["dep:sqlx-sqlite"]
default = ["postgres"]
#[cfg(feature = "postgres")]
mod postgres_impl;
常见误区
- 用运行时配置字符串选择编译期才存在的后端:未编译的实现无法运行时加载。
- 多个 feature 同时启用导致实现类型冲突:注册与装配逻辑要按 feature 互斥或兼容设计。
追问
- feature 与运行时开关如何分工?答:feature 决定编译进产物的实现集,运行时开关控制已编译功能的启停,二者层级不同。
- 如何测试未默认启用的后端?答:CI 按 feature 组合分别构建与测试,保证每个可选后端可独立编译通过。
04.4.13.3-006 拆分 crate 为什么能缩短编译时间,边界怎么划才有效?
一句话结论
单 crate 内任何改动都会触发整 crate 重编译;拆成边界稳定的 crate 后,只重编译受影响的 crate 及其下游,配合增量编译减少无效重建。拆分要按变更频率与依赖方向划界,为拆而拆反而增加构建编排成本。
概念解释
Cargo 的编译粒度是 crate:一个文件改动,同 crate 全部代码重新编译。核心模型、稳定端口与易变接口分开后,改 API 层不会重编领域核心。边界应匹配架构层与变更频率:高频改动的外层与稳定内层分离,共享类型单独成 crate。
原理流程
- 识别变更频率:稳定核心、共享契约、易变接口分层。
- 按架构方向拆 crate,明确各 crate 职责。
- 改动后观察
cargo build重编译范围是否收敛。 - 避免细粒度 crate 爆炸:过碎会增加依赖解析与链接开销。
- 结合 sccache 等缓存进一步复用编译结果。
代码或图示
单 crate:改一个 handler → 全 crate 重编译
拆分后:
改 api crate → 重编 api
domain/application 未变 → 不重编
常见误区
- 按文件目录机械拆 crate:彼此频繁互调的代码被切开,编译反而反复跨 crate。
- 拆完不检查依赖图:核心与实现混在同一 crate,重编译范围没有真正收敛。
追问
- 编译时间优化还有哪些手段?答:共享编译缓存(sccache)、更快链接器(mold/lld)、减小单 crate 体积、分层 profile 配置,具体工具链选择以当前 Rust 生态为准。
- 如何衡量拆分收益?答:对比典型改动场景下的重编译 crate 数量与 wall-clock 时间,而不是只看 crate 数量。
04.4.13.3-007 sccache 在 Rust 工程中起什么作用,如何接入?
一句话结论
sccache 是编译缓存服务,把编译产物按源码与参数哈希缓存下来,跨目录、跨机器复用;接入后干净构建或 CI 中未变化的 crate 直接命中缓存,减少重复编译。
概念解释
Rust 编译缓存按 crate 与编译参数键控:源码、依赖版本、cfg 与 feature 不变即命中。sccache 支持本地缓存与共享后端,适合多开发者与 CI 场景。它缓存的是编译器输出,不替代 Cargo 增量编译;缓存失效后仍需完整编译。
原理流程
- 安装 sccache 并设置 Rust 编译包装器环境变量。
- 编译时工具链调用 sccache 包装 rustc。
- sccache 计算输入哈希,命中则返回缓存产物。
- 未命中则调用 rustc 编译并回写缓存。
- CI 中持久化或共享缓存后端,提升二次构建命中率。
代码或图示
# 接入思路(环境变量名与后端配置以 sccache 文档为准)
RUSTC_WRAPPER=sccache
sccache --start-server
cargo build
常见误区
- 以为缓存能加速首次冷构建:缓存只复用历史编译结果,首次构建仍需全量编译。
- 缓存键不区分 cfg/feature:不同配置复用错误产物,出现难以复现的编译问题。
追问
- 缓存命中率如何观察?答:sccache 提供统计命令查看命中与未命中次数,CI 上按缓存大小与命中率调优。
- 缓存与增量编译冲突吗?答:二者层级不同,Cargo 增量编译在 crate 内复用中间产物,sccache 跨会话缓存编译输出,可配合使用。
04.4.13.3-008 mold 与 lld 链接器优化解决什么问题,适用场景如何?
一句话结论
链接阶段把各 crate 目标文件与标准库组合成二进制,mold 与 lld 是比系统默认链接器更快的替代实现,缩短链接耗时;它们属于构建工具链优化,不改变程序行为,按平台可用情况选择。
概念解释
大型 Rust 项目链接阶段占比可观,尤其 debug 与频繁重建场景。lld 是 LLVM 项目链接器,跨平台;mold 是面向高速链接的现代链接器,Linux 生态常见。通过 Cargo 配置或环境变量指定链接器,具体可用范围受目标平台与工具链版本约束。
原理流程
- 确认目标平台支持的替代链接器。
- 在 Cargo 配置或环境变量中指定链接器路径。
- 构建时 rustc 调用指定链接器完成目标文件合并。
- 对比链接耗时与产物大小变化。
- 发布构建仍按 profile 配置做 LTO 与 strip 等优化。
代码或图示
链接器选择思路(具体配置键以 Cargo/rustc 当前文档为准):
默认系统链接器 → lld(跨平台 LLVM)
→ mold(Linux 高速链接)
常见误区
- 把链接器加速当成编译加速:它只优化链接阶段,代码生成与类型检查时间不变。
- 不验证产物行为:切换链接器后需跑测试确认二进制正常运行。
追问
- debug 与 release 对链接器需求有何不同?答:debug 频繁重建更受益于快链接器;release 通常开启 LTO,链接策略以体积与最终性能权衡为准。
- Windows/macOS 可用哪些链接器?答:各平台链接器生态不同,lld 覆盖更广,mold 主要面向 Linux;以当前工具链支持矩阵为准。
04.4.13.3-009 内部 crate 的版本统一策略怎么定?
一句话结论
单仓库内内部 crate 用 workspace 继承版本或不发布的 path 依赖,不单独维护语义化版本;跨仓库或对外发布的内部库才按版本号演进,并在 workspace 依赖中统一约束。
概念解释
内部 crate 随主应用一起发布,版本号独立管理意义不大:改一处全仓对齐即可。强行给每个内部 crate 打语义版本,会产生版本兼容矩阵与无谓的发布流程。策略分两类:单仓库 path 依赖 + 版本继承;需要跨仓库复用时走私有 registry 与显式版本。
原理流程
- 判断 crate 是否需要独立于主应用发布。
- 单仓库成员:依赖写 path 或 workspace 继承,版本随仓库演进。
- 跨仓库复用:发布到私有 registry,遵循语义化版本。
- 根
[workspace.dependencies]统一内部依赖版本约束。 - 升级时批量对齐,记录破坏性变更。
代码或图示
# 单仓库内部 crate:path 引用
[dependencies]
app-domain = { path = "../domain" }
# 跨仓库复用:registry 版本引用
[dependencies]
shared-contracts = "1.2"
常见误区
- 给内部 crate 维护独立 changelog 与版本号:发布成本高,收益与耦合程度不匹配。
- 跨仓库引用仍用相对 path:脱离本仓库后路径失效。
追问
- 内部 crate 什么时候值得拆成独立仓库?答:被多个独立服务复用、发布节奏不同、需要独立权限与变更控制时。
- 版本继承怎么写?答:成员依赖项标注
workspace = true,版本号集中在根[workspace.dependencies]声明。
04.4.13.3-010 内部 crate 发布策略:path 依赖、私有 registry 与单仓库如何取舍?
一句话结论
同仓代码用 path 依赖,改动原子可见;多仓复用走私有 registry 并管理版本;共享契约类 crate 优先单仓库内聚,避免过早拆仓带来的发布与协调成本。
概念解释
三种方式对应不同耦合形态:path 依赖绑定仓库结构,编译解析直接走本地路径;私有 registry 提供版本化下载,适合跨团队跨服务;单仓库多 crate 是最常见的中间形态。取舍依据是复用范围、发布节奏与团队边界,而不是技术潮流。
原理流程
- 列出被引用的内部 crate 与引用方分布。
- 同仓引用:path 依赖,提交同时包含双方改动。
- 跨仓引用:发布私有 registry,按版本升级。
- 评估共享类型是否应随主仓演进,减少独立发布面。
- 定期清理不再被复用的内部 crate。
代码或图示
单仓库多 crate → path 依赖(改动一次提交)
跨仓库复用 → 私有 registry + 语义版本
共享契约 → 先单仓内聚,确认复用面后再拆
常见误区
- 刚抽出公共模块就发布独立仓库:复用方还没稳定,接口反复变更导致版本负担。
- 私有 registry 上保留大量旧版本:版本治理缺失,依赖解析难以收敛。
追问
- path 依赖能打进发布产物吗?答:path 引用在构建时解析为本地源码,产物二进制不携带路径信息;跨机器构建需仓库或 registry 可用。
- 私有 registry 需要哪些配套?答:认证凭证、版本检索、依赖审计与镜像同步,具体设施按团队 CI 选型。
04.4.13.3-011 多 crate workspace 中集成测试放在哪里,如何组织?
一句话结论
集成测试放在被测试 crate 的 tests/ 目录,每个文件是独立集成测试 crate,只能通过该 crate 的公开 API 访问;跨 crate 端到端流程测试可放在入口二进制 crate 的 tests 目录或独立测试成员。
概念解释
Cargo 测试分三类:单元测试在源码文件内,集成测试在 tests/,文档测试在 doc 注释。多 crate 下,application 层用例测试通过其公开接口驱动,mock 实现端口;跨层流程测试需要装配真实或替身实现。测试辅助代码放在共享测试辅助 crate,避免各 tests 目录重复。
原理流程
- 单元测试留在各模块源码旁,访问私有项。
- 集成测试写入对应 crate 的
tests/目录。 - 测试只调用公开 API,验证外部可观察行为。
- 跨 crate 流程测试在入口 crate 或独立 test member 组装多层。
- 共享 mock 与断言工具抽到测试辅助 crate。
代码或图示
crates/application/
src/... 单元测试内联
tests/use_case.rs 集成测试(公开 API 驱动)
crates/api/
tests/flow.rs 跨层流程测试
常见误区
- 在集成测试里访问私有模块:
tests/是外部 crate,私有项不可见,需要测试的行为应通过公开接口暴露。 - 跨层测试复制 mock 实现:各测试目录重复维护,应抽到共享测试辅助 crate。
追问
- 测试辅助代码能不能放主 lib crate?答:可以用
#[cfg(test)]隔离,但跨 crate 复用时需要独立测试辅助 crate 并声明 dev-dependencies。 cargo test如何按 crate 过滤?答:-p <crate-name>指定成员,配合测试名过滤运行,具体命令以 Cargo 文档为准。
04.4.13.3-012 公共 API 边界如何通过 lib.rs 重导出与可见性控制?
一句话结论
crate 的公开接口由 lib.rs 声明的 pub 模块与重导出类型决定;内部实现用 pub(crate) 或私有模块隐藏,对外只暴露稳定的类型与 trait,避免内部结构随版本外泄。
概念解释
Rust 可见性在编译期强制:pub 对外可见,pub(crate) 仅本 crate 内可见,默认私有。重导出(pub use)可以整理对外命名空间,把分散在子模块的类型聚合到顶层。良好的公共 API 让依赖方只看到必要类型,内部重构不破坏外部使用。
原理流程
- 在
lib.rs声明对外模块与重导出。 - 子模块内部类型保持私有或
pub(crate)。 - 对外类型实现所需 trait,暴露稳定方法签名。
- 依赖方通过顶层路径引用类型。
- 内部模块调整不影响公开路径,破坏变更走版本演进。
代码或图示
// lib.rs
pub mod domain;
pub mod ports;
pub use domain::User;
pub use ports::UserRepository;
mod internal {
// 仅本 crate 可见
}
常见误区
- 内部结构全标
pub:公开 API 面过大,后续重构处处受限。 - 重导出与子模块路径并存:依赖方引用路径混乱,稳定口径不统一。
追问
pub(crate)与pub区别?答:pub(crate)类型在本 crate 外不可见,适合内部实现共享;跨 crate 接口必须pub。- 如何审查公共 API 面?答:
cargo doc生成文档查看对外类型,结合cargo public-api类工具(按当前生态可用情况)核对变更。
04.4.13.3-013 二进制 crate 与库 crate 在 workspace 中如何分工?
一句话结论
库 crate 承载可复用的领域、用例与实现逻辑,对外暴露类型与 trait;二进制 crate 是入口,装配依赖、启动运行时并提供可执行产物。业务规则不写在 main.rs 中。
概念解释
分离的好处是核心逻辑可被测试与复用:库 crate 不绑定启动流程,测试直接调用;二进制 crate 只做组合根(composition root),读取配置、构造实现、挂接路由。一个 workspace 可以有多个二进制服务,共享同一组库 crate。
原理流程
- 各架构层 crate 输出 lib 目标。
- 入口 binary crate 依赖相关 lib crate。
- main 函数加载配置、构造基础设施实现。
- 把实现注入应用层,组装 api 路由。
- 启动运行时进入服务循环。
代码或图示
crates/domain/src/lib.rs → 库
crates/application/src/lib.rs → 库
crates/api/src/lib.rs → 库(路由组装)
crates/server/src/main.rs → 二进制入口
常见误区
- 在 main.rs 里写业务编排:逻辑脱离库 crate,无法被测试与其他入口复用。
- 库 crate 直接读环境变量或启动服务:库应纯逻辑,启动副作用留在 binary。
追问
- 一个服务需要多个二进制入口怎么办?答:共享库 crate,各 binary crate 独立装配,例如 HTTP 服务与后台任务消费者分开打包。
- 库 crate 能否包含 main 函数?答:lib 目标不提供可执行入口,需要可执行产物另建 bin crate。
04.4.13.3-014 共享契约 crate(proto/DTO/contracts)应该放在什么位置?
一句话结论
跨服务或跨端共享的请求/响应结构、协议消息与错误码独立成契约 crate,被 api 层与上游消费者共同依赖;契约只含数据结构与序列化,不含业务规则与实现逻辑。
概念解释
契约 crate 解决类型共享问题:HTTP 接口 DTO、gRPC 生成消息、共享错误枚举在一处定义,服务端与客户端使用同一类型,避免手写两份结构漂移。契约层不依赖数据库与框架实现,保持轻量;演进时注意向后兼容。
原理流程
- 识别跨服务/跨端复用的结构与枚举。
- 建立契约 crate,派生序列化 trait。
- api 层用契约类型映射请求响应,消费者依赖同一 crate。
- 契约变更评审兼容性:新增可选字段优先,不破坏既有字段。
- 版本演进记录在契约 crate 发布说明。
代码或图示
// contracts/src/lib.rs
use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize, Clone)]
pub struct UserDto {
pub id: String,
pub name: String,
}
常见误区
- 契约 crate 引入数据库模型或业务方法:共享层变重,消费者被迫传递不必要依赖。
- 服务端私有响应结构直接发给客户端:缺少共享契约,客户端只能手写对应结构。
追问
- gRPC 生成代码放哪?答:生成消息类型可纳入契约 crate 或独立 proto crate,按工具链生成方式组织;具体生成流程以 tonic/protobuf 工具当前版本为准。
- 契约 DTO 与领域模型什么关系?答:契约是对外数据形态,领域模型是内部规则载体,二者之间在 api/application 层转换,不直接互相暴露。
04.4.13.3-015 Rust crate 间出现循环依赖会怎样,如何检测与拆分?
一句话结论
Cargo 不允许 crate 级循环依赖,解析或编译阶段直接报错;模块级循环在单 crate 内允许但增加理解成本。发现成环后按职责下沉接口、拆分共享类型来打破循环。
概念解释
cargo 依赖图必须是有向无环图:A 依赖 B、B 又依赖 A 无法解析。循环通常源于职责边界不清:两个模块互相引用对方类型。拆分思路是把共享部分抽到第三个 crate,或把接口下沉到被依赖方,让依赖方向重新单向。
原理流程
- 编译/解析报错提示循环依赖。
- 用
cargo tree查看依赖链与成环节点。 - 识别双方互相引用的类型与方法。
- 共享类型抽独立 crate,或 trait 定义下沉到内层。
- 重构后依赖图恢复无环。
代码或图示
成环:A → B → A
拆分:
共享类型 → C(A、B 都依赖 C)
或接口下沉:B 依赖 A 定义的 trait,A 不再反向依赖 B
常见误区
- 用间接包装类型绕开循环:类型链条拉长,循环实质仍在。
- 单 crate 内模块随意互引:编译不报错,但模块边界已经模糊。
追问
- 单 crate 内模块循环引用合法吗?答:Rust 模块级相互引用在 crate 内允许,但会提高理解与测试成本,应在设计上保持单向依赖。
- 如何提前发现成环?答:评审依赖清单与
cargo tree输出,核心层依赖集合纳入 CI 检查。
04.4.13.3-016 什么时候该把单 crate 模块拆成独立 crate,判断标准是什么?
一句话结论
当模块变更频率稳定、依赖方向清晰、需要独立编译测试或被多个入口复用时,拆成独立 crate;边界频繁互调、共享类型少的代码保留在单 crate 内模块划分。
概念解释
拆 crate 的收益是编译隔离、边界强制与复用,成本是依赖编排与导航复杂度。判断看四个维度:变更是否独立、依赖是否单向、是否需要复用、测试是否独立。过早拆分把小项目切成一堆细 crate,维护成本高于收益。
原理流程
- 盘点模块职责、调用方向与变更频率。
- 核心稳定、外层易变的模块优先分离。
- 被多入口复用的共享类型独立成 crate。
- 拆分后验证依赖图无环、方向正确。
- 观察编译与测试收益,过细则合并回模块。
代码或图示
倾向拆 crate:
稳定核心 / 共享契约 / 独立可测的用例层
倾向留模块:
高频互调 / 边界模糊 / 仅单入口使用
常见误区
- 按目录数量机械拆 crate:没有依赖隔离收益,只增加 workspace 噪音。
- 拆完发现双方频繁跨 crate 调用:说明边界划错,应合并或重新划分。
追问
- 先模块后 crate 的演进路径是什么?答:单 crate 内按模块分层,边界稳定后再提取 crate;避免一开始就设计过细的包结构。
- 拆 crate 对发布有影响吗?答:单仓库内影响小;若计划对外复用,拆分时就要考虑公共 API 面与版本策略。
04.4.13.3-017 端口与适配器(六边形架构)在 Rust 中怎么落地?
一句话结论
端口是内层定义的 trait(输入用例端口、输出仓储/外部服务端口),适配器是外层实现该 trait 的具体结构;核心只依赖 trait,数据库、消息、HTTP 客户端都是可替换的适配器。
概念解释
六边形架构把应用核心放在中间,左右两侧分别是驱动适配器(HTTP、消息消费者)与被驱动适配器(数据库、外部 API)。Rust 用 trait 表达端口:核心层声明方法签名,外层 struct 实现 trait。替换实现时核心代码与测试不变,只换注入的适配器。
原理流程
- 在 domain/application 层定义输出端口 trait。
- 用例服务通过 trait 调用外部能力,不引用具体实现类型。
- infrastructure 层 struct 实现该 trait,封装 SQL/HTTP/MQ。
- 入口装配时把适配器实例传给应用层。
- 测试时注入 trait 替身,验证用例行为。
代码或图示
// 核心层端口定义
trait UserRepository {
fn find_by_id(&self, id: &str) -> Option<User>;
}
// 外层适配器实现
struct PgUserRepository { pool: sqlx::PgPool }
impl UserRepository for PgUserRepository {
fn find_by_id(&self, id: &str) -> Option<User> {
// SQLx 查询实现
todo!()
}
}
常见误区
- 把 trait 定义在 infrastructure 层:核心反向依赖实现层,端口倒置失效。
- 端口方法直接暴露数据库行类型:适配器类型泄漏进核心,换存储要改核心。
追问
- 输入端口怎么抽象?答:用例服务自身实现输入端口 trait,驱动适配器调用该 trait;命令/查询对象作为方法入参。
- 端口 trait 放 domain 还是 application?答:依赖基础设施的输出端口通常在 application,纯领域规则相关端口可在 domain,按职责归属判断。
04.4.13.3-018 适配器实现 trait 的落地方式有哪些要点?
一句话结论
适配器 struct 持有外部资源(连接池、客户端实例),在 impl 块中实现端口 trait;方法内完成外部调用与类型映射,把外部数据转成核心模型,错误转成领域或应用错误。
概念解释
适配器是隔离层:外部技术细节不越过端口边界。struct 字段保存连接池或客户端,trait 方法内执行查询/调用,结果映射为核心类型;外部错误经过转换包装,不把驱动错误类型直接暴露给核心。多个适配器可实现同一端口,按环境替换。
原理流程
- 定义适配器 struct,持有资源句柄。
- 构造函数接收连接池/客户端,完成初始化校验。
impl端口 trait,方法内执行外部操作。- 外部响应映射为领域模型,错误转为应用层错误。
- 装配层选择具体适配器注入用例。
代码或图示
struct RedisCacheAdapter { client: redis::Client }
impl CachePort for RedisCacheAdapter {
fn get(&self, key: &str) -> Result<Option<String>, AppError> {
// 调用客户端并映射结果
todo!()
}
}
常见误区
- 适配器方法返回原始驱动错误:核心层耦合具体错误类型,换实现即破坏编译。
- 在适配器里写业务规则:规则应在 domain/application,适配器只做技术操作与映射。
追问
- 适配器需要保存状态吗?答:保存外部资源句柄(池、客户端),业务状态应归领域模型;无状态方法可直接实现。
- 多个适配器如何切换?答:装配层按配置选择实现,以 trait object 或泛型注入用例。
04.4.13.3-019 依赖注入在 Rust 中如何通过构造装配与 AppState 落地?
一句话结论
在组合根处构造适配器实例,以 trait 或泛型形式注入应用服务,再随 Web 框架的状态(如 axum 的 State<AppState>)传递到路由处理器;核心不自己构造外部依赖。
概念解释
依赖注入把「创建依赖」与「使用依赖」分开:用例服务接收端口实现而非自己 new 仓储。Rust 没有运行时 DI 容器,装配在 main/组合根显式完成。框架状态结构体持有已装配的服务或适配器,handler 提取状态并调用用例。
原理流程
- 组合根加载配置,创建连接池与客户端。
- 构造适配器 struct 并实现端口 trait。
- 装配应用服务,注入适配器依赖。
- 服务实例装入框架状态结构体。
- 路由 handler 提取 State,调用用例方法。
代码或图示
struct AppState {
user_service: UserService<PgUserRepository>,
}
let state = AppState {
user_service: UserService::new(pg_repository),
};
let app = axum::Router::new()
.route("/users/{id}", get(get_user))
.with_state(state);
常见误区
- 用例服务内部直接创建仓储:依赖硬编码,测试无法替换替身。
- AppState 里塞满原始连接池:状态越过应用层直接暴露给 handler,分层被绕过。
追问
- DI 需要框架级容器吗?答:Rust 项目通常显式构造注入,类型在编译期确定;复杂装配再评估是否引入辅助封装。
- 状态在多线程下如何共享?答:装入
Arc或框架状态克隆机制内部处理,依赖类型需满足Send + Sync。
04.4.13.3-020 静态分发泛型与动态分发 Box<dyn> 在 DI 中如何取舍?
一句话结论
泛型静态分发在编译期单态化,性能好、类型确定;Box<dyn> 动态分发允许运行时替换不同实现,装配灵活但有虚表调用开销。应用层端口按是否需要运行时切换选择。
概念解释
Rust 两种分发方式:泛型为每个具体类型生成代码,无运行时分派;trait object 通过 vtable 调用,实现类型在运行时确定。服务端单一生成环境常用泛型;需要多实现并存、插件式装配或集合持有不同实现时用 trait object。异步 trait object 有额外约束(见后续题)。
原理流程
- 判断依赖实现是否在运行时变化。
- 固定实现:用泛型参数,编译期单态化。
- 多实现并存:包装
Box<dyn Port>或Arc<dyn Port>。 - 状态与服务按所选方式持有依赖。
- 测试注入替身时保持分发方式一致。
代码或图示
// 静态分发
struct UserService<R: UserRepository> { repo: R }
// 动态分发
struct UserServiceDyn { repo: Box<dyn UserRepository> }
常见误区
- 所有端口都用
Box<dyn>:不必要的动态分派掩盖类型边界,异步场景还受限。 - 泛型参数泄漏到框架状态:路由层需要携带泛型,状态类型变复杂,可在组合根收敛为具体类型。
追问
- trait object 要求 trait 满足什么?答:对象安全(object safety),方法签名不违反 dyn 兼容规则;不满足的 trait 只能泛型使用。
- 异步端口适合哪种分发?答:
async fn in trait与 trait object 的兼容情况随工具链版本演进,具体支持形式以当前 Rust 版本与 trait 定义为准。
04.4.13.3-021 领域模型与 DTO 的边界如何划分?
一句话结论
领域模型承载业务规则与不变量,DTO 是对外传输的数据形态;两者在 api/application 层显式转换,不把数据库模型或领域结构直接暴露成 HTTP 响应。
概念解释
领域模型围绕业务行为组织(状态变更、校验、聚合一致性),DTO 围绕接口契约组织(字段扁平、序列化格式、版本兼容)。混用会导致:领域规则被接口格式绑架,或响应泄漏内部结构。转换层负责字段映射、裁剪与格式适配,双向都要显式编写。
原理流程
- domain 定义实体/值对象,方法封装状态变更与不变量校验。
- api 层定义请求/响应 DTO,派生序列化 trait。
- 用例返回领域对象或结果类型。
- 映射层把领域模型转成 DTO,按接口需要裁剪字段。
- 反向把请求 DTO 校验后转成用例命令。
代码或图示
// 领域模型
struct Order { id: OrderId, status: OrderStatus }
// 对外 DTO
#[derive(Serialize)]
struct OrderResponse {
id: String,
status: String,
}
impl From<Order> for OrderResponse {
fn from(order: Order) -> Self { /* 字段映射 */ todo!() }
}
常见误区
- 数据库行结构直接作为响应 DTO:内部字段、关联表与敏感信息随接口外泄。
- 领域模型派生对外序列化:接口字段调整被迫改动核心规则代码。
追问
- DTO 校验放在哪一层?答:入参格式与范围在 api 层校验,业务不变量在 domain 层校验,两层职责不同。
- 模型转换会丢信息吗?答:显式映射列出保留字段,未映射字段不进入响应;需要扩展字段时先改契约。
04.4.13.3-022 错误类型如何按架构层分层?
一句话结论
domain 定义领域错误(违反不变量),application 定义用例错误(用例前置条件不满足),infrastructure 把外部错误转换为应用错误,api 层把错误映射为 HTTP 状态码与响应体;底层错误不直接泄漏到外层。
概念解释
分层错误让每一层只理解自己语义内的失败:核心错误不携带数据库驱动类型,HTTP 状态码只出现在接口层。Rust 中库边界常用 thiserror 定义枚举错误,应用顶层可用 anyhow 聚合;错误链通过 source 保留因果,外层按需匹配转换。
原理流程
- domain 错误枚举表达规则违反(如状态非法、余额不足)。
- application 错误包装领域错误与用例失败场景。
- infrastructure 捕获驱动/客户端错误,转成应用错误并保留原因。
- api 层匹配错误类型,映射状态码与响应体。
- 日志记录错误链,响应只暴露必要信息。
代码或图示
#[derive(thiserror::Error, Debug)]
enum DomainError {
#[error("订单状态不允许该操作")]
InvalidStatus,
}
#[derive(thiserror::Error, Debug)]
enum AppError {
#[error(transparent)]
Domain(#[from] DomainError),
#[error("依赖不可用")]
DependencyUnavailable,
}
常见误区
- 核心层直接返回 SQLx 错误类型:换数据库实现即破坏核心编译与错误口径。
- 所有错误都用
anyhow包装:上层无法按类型匹配分支,错误语义丢失。
追问
thiserror与anyhow分工?答:thiserror用于定义可枚举、可匹配的库错误类型;anyhow用于应用顶层聚合任意错误,边界处再转成结构化错误。- 错误如何映射 HTTP 状态码?答:在 api 层实现错误到状态码的转换,领域错误不感知 HTTP 语义。
04.4.13.3-023 事务边界应该放在哪一层?
一句话结论
事务边界属于应用用例层:一个用例方法内的多个仓储操作在同一事务中提交或回滚;仓储端口提供事务能力,infrastructure 实现具体事务,domain 不直接管理数据库事务。
概念解释
事务保证用例级一致性:跨聚合或跨表的写入要么全部成功,要么全部回滚。把事务放在 application 层可以让用例编排决定边界;仓储接口暴露事务开始/提交或传入事务句柄。核心 domain 不依赖数据库事务概念,避免被存储机制绑定。
原理流程
- 用例服务开始一个业务用例。
- 通过端口开启事务(仓储端口或事务管理器)。
- 用例内多次操作参与同一事务。
- 全部成功提交,任一失败回滚。
- infrastructure 实现事务与连接绑定,错误转应用错误。
代码或图示
async fn place_order(&self, cmd: PlaceOrder) -> Result<OrderId, AppError> {
let mut tx = self.repo.begin_tx().await?;
let order = Order::create(cmd)?;
tx.save(&order).await?;
tx.commit().await?;
Ok(order.id())
}
常见误区
- 把事务拆到单个仓储方法:跨仓储操作无法纳入同一事务,一致性破裂。
- domain 模型方法内开数据库事务:核心层绑定存储机制,无法脱离数据库测试。
追问
- 跨聚合事务如何处理?答:单库内由用例层事务覆盖;跨服务/跨库一致性走最终一致与补偿,不在本地事务内强行包裹。
- 事务句柄要不要进 domain?答:事务是基础设施概念,端口抽象后由 application 持有,domain 只表达业务操作。
04.4.13.3-024 pub(crate) 如何用来限制内部实现可见性?
一句话结论
pub(crate) 让类型或方法在本 crate 内共享、对外不可见;跨 crate 接口才用 pub。用它隐藏适配器内部结构、辅助类型与实现细节,收紧公共 API 面。
概念解释
Rust 可见性层级:私有(默认)、pub(crate)、pub。同一 crate 内多个模块需要互访但不希望外部依赖时,用 pub(crate);对外稳定接口放 pub。可见性在编译期强制,误用会直接报错,便于在评审前收紧边界。
原理流程
- 识别类型是对外接口还是内部实现。
- 内部共享类型标
pub(crate),模块内私有保持默认。 - 对外类型与方法标
pub,写入 lib.rs 重导出。 - 编译检查跨 crate 引用是否越界。
- 重构时内部类型调整不影响外部路径。
代码或图示
pub struct OrderService { /* 对外 */ }
pub(crate) struct OrderMapper { /* 同 crate 内部 */ }
mod helpers {
pub(crate) fn normalize() -> String { /* ... */ }
}
常见误区
- 内部 struct 全标
pub:公共 API 面失控,后续无法自由重构。 - 该跨 crate 共享的类型标
pub(crate):外层实现无法引用,编译报错后再调整。
追问
pub(super)与pub(crate)区别?答:pub(super)只对父模块可见,范围更窄;pub(crate)覆盖整个 crate,按共享范围选择。- 可见性与文档什么关系?答:
pub类型应写文档注释,pub(crate)内部实现可按模块内约定注释。
04.4.13.3-025 领域服务与应用服务的职责如何区分?
一句话结论
领域服务承载跨实体的纯业务规则,不依赖外部技术;应用服务编排用例流程,调用领域对象与端口,协调事务、持久化与外部调用。一个是业务规则,一个是流程编排。
概念解释
当业务逻辑无法自然归入单个实体时,抽领域服务(如转账涉及两个账户的规则校验);应用服务是用例入口,接收命令、加载聚合、调用领域规则、保存结果。领域服务可被多个用例复用,不感知 HTTP 与数据库细节。
原理流程
- 识别规则归属:单实体行为放实体,跨实体规则放领域服务。
- 应用服务接收用例命令,通过端口加载聚合。
- 调用领域实体/领域服务执行规则变更。
- 应用服务控制事务与持久化顺序。
- 返回结果或错误给接口层。
代码或图示
// 领域服务:纯业务规则
struct TransferPolicy;
impl TransferPolicy {
fn check(from: &Account, to: &Account, amount: Money) -> Result<(), DomainError> {
todo!()
}
}
// 应用服务:编排
struct TransferService<R: AccountRepository> { repo: R }
常见误区
- 应用服务里堆业务规则:用例层变成大泥球,规则无法被其他用例复用。
- 领域服务直接调用仓储或发消息:规则层混入副作用,脱离业务规则职责。
追问
- 领域服务需要状态吗?答:通常无状态,方法操作传入的实体与值对象;状态归属聚合与实体。
- 应用服务之间能互相调用吗?答:可以编排,但应避免深层嵌套;跨用例复用的规则下沉到领域层。
04.4.13.3-026 值对象与聚合根在 Rust struct 中如何落地?
一句话结论
值对象用不可变 struct 表达,按值相等比较(如 Money、Address);聚合根是实体,持有内部实体集合并保证聚合不变量,对外只暴露根的操作方法。
概念解释
DDD 战术建模在 Rust 中对应类型设计:值对象无标识,字段私有并通过构造函数校验;聚合根有标识(ID 类型),管理内部实体生命周期,外部不能绕过根修改内部状态。Rust 的所有权与私有字段天然支持封装不变量。
原理流程
- 值对象:私有字段 + 构造函数校验 + 实现相等比较。
- 聚合根:ID 类型标识,持有子实体/值对象集合。
- 根方法封装状态变更,先校验不变量再修改。
- 外部通过根方法操作聚合,不直接改内部字段。
- 仓储按根粒度保存与加载聚合。
代码或图示
struct Money { amount: i64, currency: String }
struct Order {
id: OrderId,
status: OrderStatus,
lines: Vec<OrderLine>,
}
impl Order {
fn add_line(&mut self, line: OrderLine) -> Result<(), DomainError> {
// 不变量校验后修改
todo!()
}
}
常见误区
- 把所有字段公开:外部可绕过校验构造非法值,聚合不变量失效。
- 聚合根直接暴露内部集合
Vec:外部可增删元素,根失去一致性控制。
追问
- 值对象需要 ID 吗?答:不需要,相等由字段值决定;有唯一标识的是实体。
- 聚合边界怎么划?答:按一致性与变更边界划分,频繁一起变更、需要强一致的对象归入同一聚合。
04.4.13.3-027 仓储接口定义在 domain/application,实现在 infrastructure,具体怎么对应?
一句话结论
仓储端口 trait 声明在使用它的内层 crate,方法入参出参用领域类型;infrastructure crate 用具体数据库实现该 trait,持有连接池并完成行模型到领域模型的映射。
概念解释
仓储模式把持久化抽象成集合式接口:用例只知道「保存/查找聚合」,不关心 SQL 与驱动。接口在内层定义保证依赖倒置;实现在外层可替换。行数据结构只存在于 infrastructure,不泄漏到 domain。
原理流程
- 内层定义仓储 trait,方法使用聚合根与 ID 类型。
- infrastructure 定义数据库行结构(私有)。
- 实现 trait:查询行数据,映射为领域聚合。
- 保存时把聚合拆成行数据写入。
- 装配层把实现注入应用服务。
代码或图示
// 内层端口
trait OrderRepository {
fn save(&mut self, order: Order) -> Result<(), AppError>;
fn find(&self, id: &OrderId) -> Result<Option<Order>, AppError>;
}
// 外层实现
struct PgOrderRepository { pool: sqlx::PgPool }
impl OrderRepository for PgOrderRepository { /* 映射与查询 */ }
常见误区
- 仓储方法返回数据库行类型:领域层耦合驱动模型。
- 接口定义在 infrastructure:核心反向依赖实现,端口倒置失效。
追问
- 仓储返回聚合还是单个实体?答:按聚合边界加载,外部通过根访问内部实体;跨聚合引用用 ID。
- 分页查询接口放仓储吗?答:查询参数与结果可在端口表达,具体 SQL 实现留在 infrastructure。
04.4.13.3-028 核心层如何做到不依赖 Web 框架与异步运行时?
一句话结论
domain/application 只定义类型、trait 与纯逻辑,不引用 axum/actix/tokio 等框架 crate;需要异步能力时通过端口 trait 抽象,具体运行时由外层装配。核心层可在普通单元测试环境运行。
概念解释
核心层独立于技术栈是可测试性与可替换性的基础:不依赖框架就可以在无网络、无运行时的测试里验证规则。Rust 依赖在 crate 清单中可见,核心 crate 的 [dependencies] 不应出现 Web 框架与驱动。异步抽象需要注意 trait object 兼容性,按工具链版本选择表达形式。
原理流程
- 审查核心 crate 依赖清单,移除框架与驱动。
- 外部能力通过端口 trait 声明,方法签名用核心类型。
- 异步需求在 trait 内表达,外层实现对接运行时。
- 核心单元测试不启动运行时即可运行纯逻辑。
- 框架类型只出现在 api 与 infrastructure crate。
代码或图示
domain/application 允许依赖:
serde(按需)、thiserror、核心类型库
禁止直接依赖:
axum / actix-web / sqlx / redis / tokio 运行时宏
常见误区
- 核心层为了方便引入序列化框架:模型被协议格式绑定,换表示要改核心。
- 端口方法直接返回框架响应类型:用例被协议层污染,无法复用。
追问
- 核心层需要日志怎么办?答:定义日志端口或接收外部记录器抽象,具体 tracing 实现在外层注入。
- 异步核心如何测试?答:纯规则同步测试;涉及端口的用例用替身实现,在测试运行时中验证。
04.4.13.3-029 副作用(发邮件、发消息、调外部 API)为什么要隔离到适配器层?
一句话结论
副作用属于技术实现与外部交互,通过端口抽象后由适配器执行;核心层只声明「需要发生什么」,不直接调用邮件客户端、MQ 生产者或外部 HTTP SDK,保证规则可独立测试与替换。
概念解释
副作用包括写外部系统、发通知、调用第三方服务。直接在领域/用例代码里调用 SDK 会绑定具体厂商、增加测试依赖、污染核心规则。端口把副作用抽象成领域语义操作(如「通知用户」),适配器对接具体实现。
原理流程
- 核心层定义副作用端口 trait(通知、发布事件、调用外部服务)。
- 用例调用端口方法表达业务意图。
- infrastructure 适配器实现端口,封装 SDK 调用。
- 错误转换为应用错误,失败策略在用例或端口层定义。
- 测试注入替身验证调用意图,不触发真实外部交互。
代码或图示
trait NotificationPort {
fn notify(&self, user: &UserId, message: &str) -> Result<(), AppError>;
}
struct EmailAdapter { client: EmailClient }
impl NotificationPort for EmailAdapter { /* 发送邮件实现 */ }
常见误区
- 用例方法里直接
reqwest::post(...):核心绑定外部 HTTP 客户端,测试必须 mock 网络。 - 适配器里写业务判断:通知内容与触发条件应来自用例/领域规则。
追问
- 副作用失败是否回滚业务?答:按业务策略区分:关键通知可纳入用例失败,异步通知走最终一致与重试,端口层记录失败语义。
- 事件发布算副作用吗?答:核心层定义领域事件,事件到 MQ 的投递在适配器完成,属于副作用隔离。
04.4.13.3-030 如何在工程中守护架构依赖方向不被破坏?
一句话结论
把分层落到 crate 边界后,通过依赖清单审查、cargo tree 检查与 CI 规则约束核心层允许的依赖集合;评审时核对 trait 定义位置与类型流向,发现逆向依赖及时重构。
概念解释
架构守护防止分层随演进腐化:早期边界清晰,后来新功能随手引入框架类型到核心层。手段分编译期与流程期:crate 依赖清单天然暴露逆向引用,脚本或 deny 规则可固化允许列表;代码评审把依赖方向作为检查项。
原理流程
- 列出各 crate 允许的外部依赖与内部依赖方向。
- 审查
[dependencies],核心层不得出现禁用 crate。 - 用
cargo tree回溯类型来源,确认无逆向引用。 - CI 脚本校验依赖允许列表,破坏则阻断合并。
- 评审记录架构例外,定期清理技术债。
代码或图示
守护清单:
domain 依赖:无 Web 框架、无数据库驱动
application 依赖:domain + 端口抽象
infra 依赖:application/domain + 具体技术库
api 依赖:application + 框架
常见误区
- 只靠口头约定分层:新成员或赶工时容易绕过,边界逐渐模糊。
- 规则过严不允许例外:合理的共享基础库未纳入白名单,规则被整体绕过。
追问
- 工具能自动检查 crate 依赖方向吗?答:可读取各 crate 清单脚本化校验允许列表;cargo-deny 可做依赖来源与 bans 检查,架构方向规则按团队脚本落地。
- 发现核心层引入外部类型怎么办?答:把接口下沉到核心、实现移到外层,类型映射在边界完成,不保留逆向依赖。
04.4.13.3-031 贫血模型与充血模型在 Rust 项目中各是什么形态?
一句话结论
贫血模型是只含字段的数据结构,行为集中在服务层;充血模型把状态变更与不变量校验封装在实体/值对象方法中。Rust 项目常见混合形态:核心聚合充血,外围数据结构偏贫血。
概念解释
贫血模型:struct 暴露字段,服务层操作数据,规则集中但实体不封装自身一致性;充血模型:实体方法负责校验与变更,外部不能绕过规则。Rust 的私有字段与方法可落地充血模型;复杂业务规则优先收敛到聚合根与值对象。
原理流程
- 识别数据结构是否携带业务规则。
- 有不变量与状态迁移的对象封装为充血实体。
- 仅作数据传输的结构保持贫血 DTO。
- 服务层编排充血实体的方法调用。
- 评审时检查规则是否散落在服务层。
代码或图示
// 充血:方法内校验并变更状态
impl Order {
fn cancel(&mut self) -> Result<(), DomainError> {
if self.status == OrderStatus::Shipped {
return Err(DomainError::InvalidStatus);
}
self.status = OrderStatus::Cancelled;
Ok(())
}
}
常见误区
- 聚合根字段全公开:外部随意改状态,充血封装名存实亡。
- 纯数据 DTO 上挂业务方法:传输结构被规则污染,复用边界混乱。
追问
- Rust 所有权对充血模型有什么影响?答:变更方法接收
&mut self,状态修改通过所有权检查保证唯一可写引用,与封装规则配合。 - 哪种模型更适合小项目?答:简单 CRUD 可用贫血结构加快开发;有明确业务规则的聚合应收敛为充血,避免规则散落。
04.4.13.3-032 领域事件在 Rust 架构中如何定义与分发?
一句话结论
核心层定义领域事件结构(聚合状态变更的事实记录),用例收集事件;外层适配器把事件发布到消息队列或调用订阅者。核心不直接投递 MQ,事件分发属于副作用。
概念解释
领域事件表达「已经发生的业务事实」(如 OrderCreated、PaymentCompleted)。聚合在状态变更后记录事件,应用用例在提交后取出并交给事件端口。订阅方按事件解耦处理后续动作;事件命名用过去时态,携带必要数据而非实体引用。
原理流程
- 聚合根变更时生成事件并挂在内部列表。
- 用例提交事务后取出未发布事件。
- 调用事件端口发布事件(适配器对接 MQ)。
- 订阅服务消费事件,执行后续处理。
- 失败与重试由消息链路与消费端策略处理。
代码或图示
struct OrderCreated { order_id: OrderId, amount: Money }
trait EventPort {
fn publish(&self, event: DomainEvent) -> Result<(), AppError>;
}
enum DomainEvent {
OrderCreated(OrderCreated),
}
常见误区
- 核心层直接发 MQ 消息:副作用泄漏进规则层,测试与替换困难。
- 事件携带可变实体引用:序列化与后续处理耦合聚合内部状态。
追问
- 事件与事务如何保证一致?答:本地事务内保存聚合与事件记录,提交后再发布;跨系统走最终一致与重试,必要时用 outbox 模式。
- 事件订阅在同进程内怎么做?答:可在装配层注册处理器,经端口调用;跨进程则走消息队列,二者边界在适配器区分。
04.4.13.3-033 同步与异步框架/运行时如何选型?
一句话结论
IO 密集、高并发连接的 Web 服务选异步运行时(Tokio 生态);CPU 密集、计算型任务或简单脚本可用同步模型。选型看负载类型、团队异步熟练度、依赖库异步支持,而不是默认追新。
概念解释
异步模型在等待网络/磁盘时让出任务线程,适合大量并发连接;代价是 async/await 类型复杂度、Send/Sync 约束与调试成本。同步模型(线程阻塞)实现直观,但高并发下线程开销受限。Rust 生态 Web 框架多基于 Tokio 异步,部分库提供同步阻塞接口。
原理流程
- 区分负载:IO 等待为主还是 CPU 计算为主。
- 评估并发连接规模与延迟要求。
- 核对所选数据库/消息/客户端库的异步支持成熟度。
- 评估团队对异步类型与并发约束的掌握程度。
- 原型压测对比吞吐、延迟与复杂度后定型。
代码或图示
倾向异步:
大量并发连接、IO 等待多、长连接服务(HTTP/gRPC/SSE)
倾向同步:
批处理计算、简单工具、阻塞调用为主且并发不高
常见误区
- CPU 密集任务塞进异步 worker:阻塞调用卡住调度,应放阻塞线程池。
- 所有新服务默认异步:团队异步经验不足时,类型错误与并发问题成本被低估。
追问
- 异步生态库不全怎么办?答:核对关键依赖是否有异步实现;缺失部分可隔离到阻塞线程池,不要在异步任务里直接阻塞。
- 同步与异步能混用吗?答:可以分层隔离,阻塞操作放专门线程池,异步运行时不被长时间占用;混用边界要在架构文档说明。
04.4.13.3-034 ORM 与查询构建器在 Rust 生态如何取舍?
一句话结论
ORM(如 SeaORM、Diesel)提供模型映射与关系抽象,开发快但受框架能力约束;查询构建器/运行时查询(如 SQLx 宏与查询 API)贴近 SQL,控制力强、映射显式。选型看团队 SQL 水平、模型复杂度与性能要求。
概念解释
ORM 把表映射为模型,提供关联、迁移与查询抽象;查询构建器或原生 SQL 让开发者直接写查询语句,结果手动或按宏校验映射。Rust 生态中 SQLx 偏运行时/编译期校验的查询层,Diesel 是类型安全查询 DSL,SeaORM 是异步 ORM。具体能力边界以各库当前版本为准。
原理流程
- 评估领域模型与表结构的映射复杂度。
- 评估团队对 SQL 与查询性能的把控能力。
- 核对库的异步支持、迁移工具与类型安全程度。
- 原型实现典型查询,对比开发效率与生成 SQL 质量。
- 把选型理由与限制记录到 ADR。
代码或图示
ORM 取向:
模型关系清晰、CRUD 为主、希望减少手写映射
查询层取向:
复杂查询/性能敏感、希望直接控制 SQL 与执行计划
常见误区
- 按流行度选 ORM:未核对异步支持与复杂查询能力,后期被框架限制卡住。
- 为减少映射手写全部裸 SQL:缺少类型校验与结构约束,查询错误推迟到运行时。
追问
- SQLx 的编译期校验依赖什么?答:查询宏可在编译期对照数据库连接或离线校验文件检查 SQL,具体模式以 SQLx 当前版本文档为准。
- 混合使用可行吗?答:核心仓储端口不变,不同底层实现可替换;但同一服务内不宜随意切换多套数据访问风格。
04.4.13.3-035 单体与微服务的拆分时机如何判断?
一句话结论
团队规模、模块边界清晰度、独立部署与伸缩需求、故障隔离要求达到阈值再拆微服务;早期单体按模块分层组织,避免过早分布式带来的复杂度。拆分先从仓库内 crate/模块边界开始验证。
概念解释
单体开发快、调试简单、事务本地;微服务独立部署伸缩、团队自治,但引入网络开销、分布式事务、服务发现与运维成本。Rust 服务内存占用小、启动快,单体可承载更大规模;拆分信号是模块间耦合下降、部署节奏冲突、资源需求差异显著。
原理流程
- 评估团队人数与沟通成本。
- 检查模块边界是否清晰、是否可独立演进。
- 看部署频率、伸缩需求与故障隔离要求是否分化。
- 先在单体内按 crate/模块划清边界,验证依赖方向。
- 边界稳定后再按业务域拆分服务,逐步迁移。
代码或图示
倾向保持单体:
团队小、业务早期、模块耦合高、事务一致性要求强
倾向拆分:
模块边界稳定、独立伸缩/部署、团队自治、故障域隔离
常见误区
- 为「架构先进」过早拆微服务:分布式问题先于业务复杂度出现,运维负担压垮团队。
- 单体内部不做分层:拆分时才发现模块耦合,无法干净切出服务。
追问
- 拆分第一步做什么?答:在单体内抽出边界清晰的模块/crate,明确端口与数据归属,再考虑独立部署。
- 微服务拆分按什么边界?答:按业务域与一致性边界,避免按技术层拆;数据归属随服务一起切分。
04.4.13.3-036 事件驱动与请求驱动的架构如何取舍?
一句话结论
请求驱动同步调用链路清晰、一致性直观;事件驱动解耦生产者消费者、支持削峰与异步扩展,但增加最终一致、重试与可观测复杂度。取舍看耦合需求、实时性与异步容忍度。
概念解释
请求驱动:调用方同步等待响应,链路短、排障直接。事件驱动:生产者发布事实事件,消费者按需订阅,双方不直接依赖。Rust 项目中事件常经 MQ(Kafka/RabbitMQ/NATS)投递;后台任务与通知类场景适合事件化,核心交易链路可保持请求驱动。
原理流程
- 梳理交互场景:强同步返回还是异步后续处理。
- 评估解耦收益:多个下游是否需要订阅同一事实。
- 检查对最终一致、重试幂等的接受程度。
- 事件链路补充幂等、重试、死信与追踪上下文。
- 混合架构:核心链路请求驱动,扩展动作事件驱动。
代码或图示
请求驱动:
即时返回结果、链路简单、强一致事务
事件驱动:
下游解耦、削峰填谷、异步通知/归档/衍生计算
常见误区
- 所有交互都走事件:同步场景被异步化,响应延迟与一致性问题上升。
- 事件消费不做幂等:重试导致重复处理,状态重复变更。
追问
- 事件驱动如何保证不丢消息?答:发布确认、持久化、消费重试与死信队列配合;关键链路用 outbox 保证本地事务与事件一致。
- 如何追踪跨事件链路?答:事件携带追踪上下文,日志与指标按事件类型与消费者维度关联。
04.4.13.3-037 团队规模与可维护性如何影响模块边界设计?
一句话结论
小团队可接受较粗模块与简单分层;团队增大、并行开发增多后,需要清晰 crate 边界、明确所有权与接口约定,减少合并冲突与跨模块沟通。边界成本随规模变化,设计应匹配当前团队而非假想规模。
概念解释
模块边界同时是代码边界与协作边界:多人并行修改同一 crate 容易冲突,按业务域拆分可减少耦合。可维护性指标包括定位改动范围、理解依赖方向、新人上手成本。团队扩张时先补文档与接口约定,再细化物理边界。
原理流程
- 统计团队人数与并行开发模块。
- 识别高频冲突的目录与 crate。
- 按业务域划分所有权与接口边界。
- 接口变更走评审,内部实现可自由重构。
- 定期复盘模块边界是否阻碍或帮助协作。
代码或图示
小团队:单 crate 内模块分层,约定清楚即可
大团队:按域拆 crate,明确公开 API、评审流程与测试归属
常见误区
- 团队还小就设计细粒度边界:编排成本超过协作收益。
- 团队扩大后仍共享大 crate:并行改动互相阻塞,合并冲突频繁。
追问
- 模块所有权怎么落实?答:目录/crate 归属明确团队,接口变更需所属方评审,文档记录负责人。
- 边界过多如何发现?答:改动需要跨多个 crate 同步修改、编译链路长,说明边界划细或方向错误。
04.4.13.3-038 老模块迁移到新架构时如何做并存策略?
一句话结论
迁移按模块逐步替换:先在新架构内实现对应能力,通过端口适配旧调用,灰度切换流量,验证稳定后下线旧代码;不做一次性重写,新旧在过渡期并存且边界清晰。
概念解释
大爆炸式重写风险高:周期长、期间两边都要维护。增量迁移保留旧系统可用,新模块按边界切入。Rust 项目可先用 crate/模块包裹旧逻辑,逐步把实现替换为新架构;数据与接口兼容期内双写或适配。
原理流程
- 划定迁移边界与优先级,选低风险模块先行。
- 新架构实现端口,适配层对接旧调用方。
- 流量按灰度切换到新实现,对比行为与指标。
- 稳定后移除旧实现与适配代码。
- 记录迁移顺序与回退路径。
代码或图示
并存阶段:
旧模块 → 适配端口 → 新实现
灰度流量 → 新实现;其余 → 旧模块
验证通过 → 移除旧模块与适配层
常见误区
- 一次性重写:交付周期内旧功能继续演进,重写完成时已落后。
- 新旧边界不清:调用关系混杂,无法判断哪段代码可下线。
追问
- 数据层如何并存?答:读旧库、写新库或双写过渡,按一致性要求选择迁移策略;数据回填与校验纳入计划。
- 迁移期间如何防止旧代码继续扩大?答:新功能落在新架构,旧模块只修必要缺陷,评审控制增量。
04.4.13.3-039 微服务间通信选 gRPC 还是 HTTP JSON?
一句话结论
内部服务间高性能、强契约通信选 gRPC(基于 HTTP/2、Protobuf、代码生成);对外开放接口、浏览器直连或简单集成场景用 HTTP JSON。选型看调用方类型、性能要求与契约治理成熟度。
概念解释
gRPC 用 Protobuf 定义契约,双向流与压缩二进制,适合内部低延迟调用;HTTP JSON 可读性好、无生成链、跨语言门槛低。Rust 生态 gRPC 常用 tonic,HTTP 框架按服务选型。契约演进、错误模型与消息大小都影响选择。
原理流程
- 区分调用方:内部服务还是外部/浏览器。
- 评估性能、消息体积与流式需求。
- 核对团队 Protobuf/代码生成维护能力。
- 设计契约与错误模型,确认版本兼容策略。
- 原型对比序列化体积、延迟与开发体验。
代码或图示
gRPC:
内部服务、高性能、强契约、流式调用、Protobuf schema
HTTP JSON:
开放接口、简单集成、可读性优先、无生成链
常见误区
- 内部调用也用 HTTP JSON 大报文:序列化与传输开销累积,接口契约靠文档约定易漂移。
- 对外浏览器接口强推 gRPC:浏览器与网关支持成本高,除非有专门适配层。
追问
- gRPC 契约如何演进?答:Protobuf 字段编号与规则保持兼容,新增字段可选,不修改既有字段语义;具体规则以 Protobuf 兼容性规范为准。
- Rust gRPC 库现状?答:tonic 是常见选择,配套 Protobuf 代码生成;版本与能力以当前文档为准。
04.4.13.3-040 数据库共享与服务独立库如何取舍?
一句话结论
单体或紧耦合模块可共享数据库;微服务按业务域独立数据库,数据归属随服务边界。共享库降低初期成本但形成耦合,独立库保障自治与演进,但跨库查询与一致性需要额外方案。
概念解释
数据库共享时表结构被多服务依赖,schema 变更互相牵制;独立库让服务自治,存储选型按负载决定。跨服务数据通过 API 或事件获取,不直接读他库。拆分初期可先共享库、按域划分表,边界稳定后再切分独立实例。
原理流程
- 按业务域梳理数据归属与使用关系。
- 紧耦合、同事务边界内的数据共享库。
- 服务自治边界明确后,独立数据库实例。
- 跨服务数据走接口/事件,避免直连他库表。
- 迁移期安排 schema 分离与数据校验。
代码或图示
共享数据库:
单体、模块紧耦合、本地事务一致、团队小
独立数据库:
服务自治、独立伸缩/备份、存储选型自由
跨服务数据:API / 事件 / 只读投影
常见误区
- 拆了服务仍共享表:服务名义独立,数据库耦合依旧,schema 变更互相阻塞。
- 独立库后跨服务 join 复制数据:未设计投影与缓存,查询链路混乱。
追问
- 跨服务一致性怎么处理?答:最终一致 + 事件/补偿,关键业务设计幂等与对账;不追求跨库本地事务。
- 独立库初期成本是什么?答:数据访问层重复、迁移与备份复杂度上升,需要明确服务边界再切分。
04.4.13.3-041 缓存应该放在架构的哪一层?
一句话结论
缓存作为 infrastructure 适配器实现端口,位于应用层之下:用例通过缓存端口读写,具体 Redis/本地缓存实现可替换;缓存策略(失效、一致性)在架构层定义,不散落于 handler。
概念解释
缓存是技术实现,应挂在端口之后:核心层定义缓存语义(取/存/失效),外层对接 Redis 或本地内存缓存。分层缓存(本地 + 分布式)与穿透/击穿/雪崩策略在适配器与配置层处理。缓存不改变业务规则,只优化读取性能。
原理流程
- 内层定义缓存端口 trait(get/set/invalidate)。
- 用例按业务需要调用缓存端口。
- infrastructure 实现 Redis 或本地缓存适配器。
- 失效策略随领域事件或写操作触发。
- 监控命中率与一致性问题,调优策略。
代码或图示
application → CachePort trait
infrastructure → RedisCache / LocalCache 适配器
策略:失效时机、TTL、空值缓存、击穿保护
常见误区
- handler 里直接操作 Redis 客户端:缓存实现泄漏到接口层,无法替换与测试。
- 缓存与数据库一致性无策略:更新后脏数据长期驻留,读到过期结果。
追问
- 本地缓存与分布式缓存怎么配合?答:热点数据本地缓存降延迟,共享数据放分布式缓存;两层 TTL 与失效事件协调,具体方案按一致性要求设计。
- 缓存端口放 domain 还是 application?答:属于应用编排使用的技术端口,通常在 application 定义,domain 纯规则不依赖缓存概念。
04.4.13.3-042 后台任务与主服务应该同进程部署还是独立服务?
一句话结论
轻量定时任务与短队列消费者可同进程隔离线程/任务运行;重负载、需要独立伸缩或故障隔离的后台工作拆成独立部署单元。Rust 单进程资源占用低,但任务堆积与故障会影响主服务时应分离。
概念解释
同进程部署省运维、共享配置与连接池,但后台任务占用运行时资源,异常可能拖垮主服务;独立服务可按任务负载单独伸缩、独立发布与故障隔离。划分依据是资源消耗、延迟敏感度、故障隔离要求与团队运维能力。
原理流程
- 梳理后台任务类型:定时、队列消费、批处理。
- 评估资源占用与对请求路径的影响。
- 低负载任务纳入主服务隔离任务池。
- 高负载/敏感任务拆独立二进制与部署单元。
- 共享逻辑抽库 crate,装配各自独立。
代码或图示
同进程:
定时刷新缓存、轻量通知、低频批处理
→ 独立任务线程池,不阻塞异步 worker
独立部署:
高吞吐消费者、重批处理、需要独立伸缩/故障隔离
→ 独立二进制 + 独立副本与资源配额
常见误区
- 重队列消费者与 Web 服务同进程:任务堆积占满线程,接口延迟恶化。
- 所有后台逻辑都拆独立服务:部署单元增多,配置与监控成本超过收益。
追问
- 同进程后台任务如何隔离?答:阻塞任务放专门线程池,异步任务限并发;连接池与主服务按需分配,避免互相抢占。
- 独立服务共享什么?答:共享领域与应用库 crate、契约 crate,配置与连接池各自装配。
04.4.13.3-043 技术选型时除功能外,非功能因素如何评估?
一句话结论
内存占用、启动速度、静态部署能力、二进制体积、依赖安全与可观测性都是选型维度;Rust 在内存与启动速度上有优势,但要核对工具链成熟度、生态库覆盖与团队学习成本。
概念解释
功能满足只是门槛,生产环境还要看:常驻内存、冷启动延迟、镜像与产物体积、依赖漏洞面、日志指标追踪接入、跨平台构建。非功能因素按部署形态加权:Serverless 看重启动速度与体积,长驻服务看重内存稳定性与运维成熟度。
原理流程
- 列出部署形态与运行约束(资源配额、启动时限)。
- 评估候选方案的内存、CPU、体积与启动表现。
- 核对依赖安全、许可证与维护活跃度。
- 检查观测、测试与调试工具链是否齐备。
- 原型实测关键指标,记录取舍到选型文档。
代码或图示
非功能清单:
内存占用 / 启动速度 / 二进制体积
依赖漏洞面 / 许可证 / 维护活跃度
日志指标追踪 / 测试工具 / 跨平台构建
常见误区
- 只对比 API 功能:上线后才发现内存或启动不满足部署约束。
- 忽视团队学习成本:选型先进但落地慢,问题排查依赖外部经验。
追问
- Rust 静态部署优势体现在哪?答:静态链接减少运行时系统库依赖,镜像精简、环境一致性好;具体链接方式按目标平台选择。
- 如何量化非功能指标?答:压测常驻 RSS、冷启动耗时、产物大小与依赖数量,形成基线对比候选方案。
04.4.13.3-044 技术债如何识别与安排重构节奏?
一句话结论
技术债来自绕过分层、重复代码、类型模糊与缺失测试;识别靠评审、复杂度信号与故障复盘,重构按风险与收益排期,穿插在功能迭代中进行,不积累成一次性大重写。
概念解释
技术债有利息:耦合越高改动越慢、故障越多。识别信号包括:改动一处要碰多个 crate、错误类型不匹配、测试难以编写、评审反复指出同类问题。重构节奏应小步可控:先补测试与边界,再抽模块/拆 crate,每步可验证可回退。
原理流程
- 评审与复盘记录债务类型与影响面。
- 用依赖图、重复代码、测试覆盖等信号量化优先级。
- 高风险高收益项排入迭代,先补回归测试。
- 小步重构:抽类型、定端口、拆 crate,逐步推进。
- 定期复盘债务清单,避免新债叠加。
代码或图示
债务信号:
跨层依赖、重复逻辑、错误类型松散、测试难写
改动范围随需求持续扩大
节奏:
补测试 → 定边界 → 抽模块 → 拆 crate → 验证回归
常见误区
- 债务堆积后安排大重写:周期内业务继续演进,重写易失败。
- 为重构打断所有功能交付:重构与需求按比例穿插,保持可发布状态。
追问
- 如何区分合理抽象与过度设计?答:有明确复用或边界隔离需求才抽象;小项目保留直接实现,债务在边界模糊出现时再还。
- 重构前必须有什么?答:覆盖现有行为的回归测试或可观察的行为基线,否则重构无法验证正确性。
04.4.13.3-045 模块与 crate 命名有哪些约定?
一句话结论
目录与 crate 用小写连字符,按业务域或架构层命名;模块名表达职责而非实现细节,内部模块用层级前缀区分。命名与依赖方向一致,避免同义多名导致查找困难。
概念解释
Rust crate 名用 kebab-case,模块名用 snake_case。架构分层 crate 可带层前缀(domain/application/infrastructure/api),业务域 crate 按域命名。命名稳定后作为导航入口,避免出现 utils、common 这类职责模糊的模块。
原理流程
- crate 名按架构层或业务域确定,小写连字符。
- 模块名蛇形小写,表达对外职责。
- 内部实现模块加层级前缀,与公开模块区分。
- 跨 crate 引用路径与命名保持一致。
- 评审检查命名是否职责清晰、无重复同义。
代码或图示
crates/
order-domain/ 领域模型与规则
order-application/ 用例编排
order-infra/ 数据库与外部适配
order-api/ 路由与 DTO
常见误区
- 模块命名
common/helpers:职责不清,什么都往里塞。 - 同一概念多个命名(user/account/member):类型与路径混乱,检索困难。
追问
- crate 名能与二进制名不同吗?答:可以,lib crate 与 bin crate 名称独立;入口二进制按服务可执行名命名。
- 模块名需要带业务前缀吗?答:跨域共享模块可带域前缀,单域内模块保持简洁,避免前缀冗余。
04.4.13.3-046 工程中错误类型约定如何统一?
一句话结论
库与核心边界用 thiserror 定义可枚举匹配的错误类型;应用顶层用 anyhow 聚合任意错误,进入边界后转成结构化错误。错误链保留原因,HTTP 映射只在接口层完成。
概念解释
统一错误约定让团队知道在哪定义错误、用什么类型包装:thiserror 生成 Error trait 实现与显示信息,适合对外可匹配的枚举;anyhow::Error 携带任意错误上下文,适合 main 与顶层流程。边界处转换避免松散错误穿透到核心。
原理流程
- 各层定义本层错误枚举,派生
thiserror::Error。 - 跨层错误用
#[from]聚合,保留来源。 - 应用顶层用
anyhow收尾,日志记录错误链。 - api 层匹配结构化错误,映射状态码。
- 评审检查错误类型是否越界泄漏。
代码或图示
#[derive(thiserror::Error, Debug)]
enum ServiceError {
#[error("not found: {0}")]
NotFound(String),
#[error(transparent)]
Infra(#[from] InfraError),
}
fn main() -> Result<(), anyhow::Error> {
Ok(app::run()?)
}
常见误区
- 全链路
anyhow:上层无法按类型分支处理,错误语义丢失。 - 核心层错误携带 HTTP 状态码:规则层绑定协议,违反分层。
追问
- 错误上下文怎么附加?答:在边界用
context类方法补充可读信息,底层错误作为 source 保留;具体方法名以 anyhow/thiserror 当前版本为准。 - 自定义错误需要实现哪些 trait?答:
thiserror派生Error、Debug、Display;按需实现Send + Sync以满足跨线程传递。
04.4.13.3-047 日志在分层架构中有哪些约定?
一句话结论
日志输出统一走观测层抽象,结构化字段携带请求/用户/资源标识;domain 与 application 不直接绑定日志库实现,日志级别按职责区分,敏感信息不进日志。
概念解释
日志约定包括:级别使用(debug/info/warn/error)、结构化键名、上下文传递与脱敏。核心层通过端口或记录器抽象输出日志,具体 tracing 实现在外层装配。业务规则层不打印框架细节,接口与适配器层记录外部调用结果。
原理流程
- 定义日志字段规范:请求 ID、用户标识、资源类型与 ID。
- 核心层依赖日志抽象,外层注入 tracing 实现。
- 关键用例节点记 info,异常路径记 warn/error。
- 结构化字段便于检索,敏感值按脱敏规则处理。
- 评审检查日志级别与字段一致性。
代码或图示
trait LoggerPort {
fn info(&self, msg: &str, fields: &[(&str, &str)]);
}
// 外层适配器对接 tracing-subscriber
常见误区
- 核心层直接
println!或引入 tracing crate:规则层绑定观测实现。 - 日志只打自由文本:缺少结构化字段,无法按请求关联链路。
追问
- 日志级别如何选择?答:正常流程 info,可恢复异常 warn,失败路径 error;debug 用于开发排障,生产默认关闭。
- 跨层日志上下文怎么传递?答:请求标识随用例参数或上下文结构传递,适配器记录时带上同一标识。
04.4.13.3-048 文档注释与公开 API 文档有什么约定?
一句话结论
对外公开类型与方法必须写 doc 注释,说明职责、参数、错误与使用约束;内部实现按模块约定注释。cargo doc 生成文档作为 API 参考,公开接口变更同步更新文档。
概念解释
Rust 文档注释 /// 同时是文档与可执行示例。公共 API 文档回答「做什么、怎么用、何时失败」;内部代码注释解释「为什么这样做」,不复述代码。文档与代码同仓库维护,评审把文档更新作为公开变更的一部分。
原理流程
pub类型/方法补///注释与必要示例。- 说明入参约束、返回结果与错误场景。
- 内部复杂逻辑注释设计意图与边界。
cargo doc构建检查文档可生成。- 公开 API 变更时同步更新文档与示例。
代码或图示
/// 按 ID 查找订单;不存在时返回 [`AppError::NotFound`]。
///
/// # 错误
/// - 仓储不可用返回 `Infra` 错误
fn find_order(id: &OrderId) -> Result<Order, AppError> {
todo!()
}
常见误区
- 公开 API 无文档:调用方只能读源码理解行为,重构失去契约保护。
- 文档复述方法名:注释应补充约束与失败场景,而非重复签名。
追问
- 文档示例会被执行吗?答:Rust doc 注释中的代码块默认作为文档测试参与
cargo test,示例需可编译运行。 - 内部模块要写多少文档?答:私有实现解释非显然的设计决策,不必逐行注释;公开接口必须完整。
04.4.13.3-049 ADR(架构决策记录)解决什么问题,怎么写?
一句话结论
ADR 记录重要架构决策的背景、备选方案、结论与后果,让后续成员理解决策原因而非只看到结果;每个选型或边界决策一篇,放在仓库文档目录随代码演进。
概念解释
架构决策容易随人员流动丢失:后人只推翻结论却不知道约束。ADR 固定上下文:面临的问题、评估过的选项、选择理由、放弃的代价与后续影响。格式保持轻量:背景、备选、决策、后果、状态,编号可追溯。
原理流程
- 识别影响分层、技术选型、通信方式的决策。
- 记录问题背景与约束条件。
- 列出备选方案与取舍依据。
- 写明最终决策与预期/实际后果。
- 决策被推翻时更新状态与新 ADR,不删除历史记录。
代码或图示
ADR 结构:
标题 / 状态(提议、接受、废弃、替代)
背景与约束
备选方案对比
决策结论
后果与后续行动
常见误区
- 只写结论不记理由:后人无法判断结论是否仍适用。
- ADR 写完不维护:决策条件变化后记录与现状脱节。
追问
- 哪些决策需要 ADR?答:技术栈选型、分层边界、服务拆分、通信协议、存储方案等长期影响项;琐碎实现选择不必记录。
- ADR 放哪里?答:仓库文档目录编号存放,与代码同版本演进;索引链接到各篇决策。
04.4.13.3-050 配置项与常量在代码中放在什么位置?
一句话结论
环境相关、可调整的值放配置结构体由启动注入;编译期固定、业务不变量用常量或静态值放在对应模块。配置从外层装配传入,核心层不读取环境变量。
概念解释
配置与常量边界:随环境/部署变化的是配置(地址、阈值、开关),不随环境变化的业务规则值是常量(上限、状态名、单位)。配置按架构层分组挂载,常量归属使用它的领域模块。核心层不直接 std::env::var 读取。
原理流程
- 判断值是否随环境变化:变化走配置,固定走常量。
- 配置结构体按层分组,组合根注入。
- 常量定义在使用它的模块,命名大写蛇形。
- 业务不变量常量归 domain,技术默认值归 infrastructure。
- 评审检查核心层无环境变量直读。
代码或图示
// 领域常量
const MAX_ITEMS_PER_ORDER: usize = 50;
// 配置(外层注入)
struct OrderConfig { max_items: usize }
impl OrderConfig {
fn max_items(&self) -> usize { self.max_items }
}
常见误区
- 业务上限写成环境配置:规则值被部署随意改动,绕过不变量。
- 连接地址等环境值硬编码常量:换环境要改代码重新发布。
追问
- 配置默认值放哪?答:启动配置结构体或模板提供安全默认;业务不变量默认值归领域常量。
- 跨模块共享常量放哪?答:被多域复用的基础常量放共享类型 crate,私有常量留在本模块。
04.4.13.3-051 测试金字塔在 Rust 工程中如何落地?
一句话结论
底层大量单元测试覆盖领域规则,中层集成测试通过公开 API 验证用例与适配器对接,少量端到端测试覆盖关键链路;Rust 中单元测试内联在源码,集成测试在 tests/ 目录。
概念解释
测试金字塔对应 Rust 测试类型:单元测试贴近代码、运行快、覆盖分支;集成测试验证公开接口与协作;端到端验证真实部署链路。领域规则靠单元测试,端口替身测试用例,适配器测试对接真实或替身依赖。
原理流程
- 领域模型与规则写内联单元测试。
- 用例层用 mock 端口验证编排与错误分支。
tests/目录集成测试走公开 API。- 关键链路补充端到端或容器化集成测试。
- CI 按单元 → 集成 → 端到端顺序执行。
代码或图示
单元测试:src 内 #[test],纯规则、最快
集成测试:tests/ 目录,公开 API 驱动
端到端: 启动服务与依赖,验证关键链路
常见误区
- 只写端到端测试:反馈慢、定位困难,规则分支覆盖不足。
- 集成测试访问私有实现:应通过公开接口验证外部行为。
追问
- mock 端口怎么实现?答:为端口 trait 写测试替身 struct,按用例返回固定结果或记录调用,放测试辅助 crate。
- 测试速度如何保障?答:单元测试不碰网络;外部依赖用替身,集成/端到端测试单独分组按需要运行。
04.4.13.3-052 CI 中如何加入架构约束检查?
一句话结论
CI 脚本读取各 crate 依赖清单,校验核心层禁止依赖的技术栈与内部依赖方向;配合 fmt/clippy/test 门禁,破坏分层的合并被阻断。规则随架构演进更新并记录例外。
概念解释
架构守护自动化防止分层腐化:核心 crate 清单出现 Web 框架或数据库驱动即失败;内部依赖只允许外层指向内层。脚本可解析 Cargo.toml 检查允许列表,cargo-deny 辅助依赖来源与许可证检查。CI 门禁与评审互补。
原理流程
- 定义各 crate 允许的外部依赖与内部方向。
- 编写脚本解析清单,核对允许列表。
- CI 流水线在测试前运行架构检查。
- 破坏规则返回非零退出,阻断合并。
- 合理例外登记文档,定期收紧规则。
代码或图示
CI 门禁顺序:
fmt → clippy → 架构依赖检查 → test → deny/审计
常见误区
- 架构规则只在评审口头把关:演进后边界模糊,难以回溯检查。
- 规则不维护:新基础库未纳入白名单,检查误报后被整体关闭。
追问
- 脚本检查什么粒度?答:crate 级依赖存在性与方向;类型级逆向引用可在评审与
cargo tree输出中复核。 - cargo-deny 能做架构方向检查吗?答:deny 规则覆盖来源、许可证、bans 等;分层方向通常需要项目自定义脚本配合。
04.4.13.3-053 代码评审在 Rust 架构层面关注什么?
一句话结论
评审关注依赖方向是否越界、错误类型是否分层、并发类型是否满足 Send/Sync、所有权边界是否清晰,以及公共 API 面是否失控;功能正确之外核对架构约定。
概念解释
Rust 评审除业务逻辑外,重点看类型与并发约束:跨层类型泄漏、松散错误穿透、不必要的克隆与引用、共享状态同步安全性。架构类问题在编译期部分可发现,评审补充设计层面的边界判断。
原理流程
- 核对改动 crate 的依赖方向与类型流向。
- 检查错误是否在边界转换,未泄漏驱动类型。
- 审查并发状态:共享类型
Send + Sync,锁粒度合理。 - 检查公开可见性与文档是否匹配预期。
- 记录架构债务项,排入后续重构。
代码或图示
评审清单:
依赖方向 / 类型边界 / 错误分层
Send + Sync / 锁与克隆 / 可见性与文档
常见误区
- 只看业务功能是否跑通:架构越界在后续迭代累积成大泥球。
- 评审纠结风格细节:格式由 rustfmt 统一,评审聚焦设计与边界。
追问
- 所有权问题在评审怎么判断?答:看借用范围、克隆必要性、可变引用唯一性;
&mut self方法是否暴露了不该有的写权限。 - 评审发现分层问题怎么处理?答:当前 PR 最小修复或登记债务项;严重逆向依赖优先在本 PR 纠正,避免带病合并。
04.4.13.3-054 公开 API 版本兼容如何演进?
一句话结论
公开类型与方法签名保持向后兼容:新增可选字段与方法优先,不删除既有签名,破坏变更按版本标记并提供迁移路径;Rust 语义化版本与弃用属性辅助演进。
概念解释
被其他 crate 或服务依赖的接口是契约:字段删除、类型改签名、语义反转都会破坏调用方。演进规则:新增能力用可选成员,旧实现保留;废弃方法先标记弃用并给过渡期;破坏性变更提升主版本并在文档说明迁移步骤。
原理流程
- 识别被外部依赖的公开 API 面。
- 新增需求以可选字段/新方法扩展,不改既有签名。
- 旧接口标记弃用,文档指向替代项。
- 过渡期后随主版本移除旧接口。
- 变更记录在发布说明与 ADR。
代码或图示
#[deprecated(note = "使用 find_order_v2 替代,将在下一主版本移除")]
fn find_order(&self, id: &str) -> Result<Order, AppError> {
todo!()
}
常见误区
- 直接改公开字段类型:调用方编译失败,无迁移窗口。
- 废弃接口长期不清理:API 面膨胀,调用方困惑。
追问
- Serde 字段如何保持兼容?答:新增字段加默认值,不重命名既有字段;移除字段需要先过渡期,具体规则以 Serde 兼容性实践为准。
- 内部 crate 也需要版本兼容吗?答:单仓库内可同步演进;对外或跨仓库复用的 crate 按语义化版本管理兼容窗口。
04.4.13.3-055 依赖治理在架构层如何落地?
一句话结论
核心层依赖最小化,只保留类型与规则所需基础库;技术依赖集中在 infrastructure/api。定期审计重复版本、漏洞与许可证,新增依赖评审必要性。
概念解释
依赖直接影响编译体积、攻击面与稳定性。架构分层天然限制依赖扩散:domain 清单保持精简,数据库/消息/HTTP 客户端只出现在外层。治理手段包括版本对齐、重复版本检查、漏洞扫描与许可证审查,在 CI 门禁执行。
原理流程
- 列出各层允许引入的依赖类别。
- 核心层新增依赖需评审必要性。
- 根 workspace 统一公共依赖版本。
- 定期检查重复版本、漏洞公告与许可证。
- 移除未使用依赖,收敛依赖面。
代码或图示
domain: 最小依赖(类型、错误、基础工具)
application:domain + 端口抽象
infra/api: 数据库、消息、框架、客户端库
常见误区
- 核心图方便引入重依赖:规则层被技术库绑架,编译与测试变重。
- 依赖只增不减:传递依赖累积,漏洞与许可证风险扩大。
追问
- 如何发现未使用依赖?答:结合 cargo 依赖分析工具与编译影响评估;具体工具链以当前 Rust 生态可用情况为准。
- 许可证审查关注什么?答:避免与项目分发方式冲突的许可证,记录依赖许可证清单。
04.4.13.3-056 跨 crate 共享的错误与类型应该放在哪里?
一句话结论
被多层复用的基础类型、共享错误枚举放独立契约/共享 crate;仅单层使用的类型留在本层。共享 crate 保持轻量,不反向依赖业务实现。
概念解释
类型放置原则按复用范围:domain 模型归 domain,接口 DTO 归契约,跨层通用错误与值对象放共享 crate。避免类型在多个 crate 重复定义导致不兼容;共享 crate 被依赖时不能再依赖业务外层,防止成环。
原理流程
- 统计类型被哪些 crate 引用。
- 单层使用:留在所属层 crate。
- 多层复用:提取到共享/契约 crate。
- 检查共享 crate 依赖方向,不引入业务实现。
- 公开类型补文档与测试。
代码或图示
shared/contracts crate:
共享错误码、ID 类型、基础值对象、对外 DTO
不放入共享:
某层私有映射、适配器内部结构、业务编排类型
常见误区
- 共享类型散落在各层重复定义:同名不同结构,跨层传递出错。
- 共享 crate 引入框架依赖:所有依赖方被迫传递引入该框架。
追问
- 共享错误枚举与层错误什么关系?答:共享错误码表达通用语义,各层错误可包装它;层特定错误留在本层枚举。
- ID 类型为什么要共享?答:跨层传递需要同一类型,避免
String到处混用导致格式错误。
04.4.13.3-057 运行时特性开关如何与代码分层配合?
一句话结论
开关配置从外层注入应用层,用例按开关分支控制功能路径;核心规则不读取环境变量,开关判断集中在编排层。编译期 feature 与运行时开关分层使用,互不替代。
概念解释
功能开关服务于灰度与实验:新功能路径在代码中已编译存在,配置决定是否启用。分层上配置进入 application 用例,domain 规则不感知开关;开关组合要有测试覆盖,避免分支不可验证。开关下线后清理对应代码。
原理流程
- 配置结构体定义功能开关字段。
- 组合根注入配置到应用服务。
- 用例按开关选择新/旧路径。
- 测试覆盖开关开与关两种分支。
- 功能稳定后移除开关与旧路径。
代码或图示
struct FeatureFlags { new_checkout: bool }
impl CheckoutService {
fn pay(&self, cart: &Cart) -> Result<(), AppError> {
if self.flags.new_checkout {
self.new_flow(cart)?;
} else {
self.legacy_flow(cart)?;
}
Ok(())
}
}
常见误区
- domain 方法内读环境变量判断开关:规则层混入部署配置。
- 开关长期保留:两套路径并存,测试与理解成本累积。
追问
- 开关与 Cargo feature 区别?答:feature 编译期裁剪实现,开关运行期切换已编译路径;前者改产物,后者改行为。
- 灰度开关需要记录什么?答:生效范围、切换时间与指标对比,回滚路径在发布说明登记。
04.4.13.3-058 配置结构如何与架构层对应?
一句话结论
配置按架构域分组:http 接口配置、数据库/缓存/消息基础设施配置、观测配置;应用层只接收本层需要的子配置,核心规则不持有部署配置。
概念解释
配置树与模块树对应有助于定位:哪个模块用哪组配置一目了然。分组结构体在组合根装配,分发给对应服务;避免一个全局配置对象到处传递。敏感配置单独分组并脱敏处理。
原理流程
- 按架构域识别配置分组。
- 定义子配置结构体并派生反序列化。
- 根配置组合各组,启动期校验。
- 装配时子配置注入对应模块。
- 配置分组随模块边界同步调整。
代码或图示
#[derive(Deserialize)]
struct AppConfig {
http: HttpConfig,
infra: InfraConfig,
observability: ObservabilityConfig,
features: FeatureFlags,
}
常见误区
- 所有配置字段扁平堆在根结构体:模块分不清哪些配置归属自己。
- 核心服务持有整份根配置:感知不需要的部署参数,边界松散。
追问
- 配置分组变化如何同步?答:新增模块时建立对应子配置组,架构评审核对配置树与模块树一致。
- 跨模块共享配置放哪?答:观测、通用开关等共享项放公共子组,私有配置留在各自分组。
04.4.13.3-059 组合根(composition root)放在什么位置?
一句话结论
组合根是组装依赖的入口代码:读取配置、构造适配器、注入用例、挂载路由,放在二进制 crate 的启动模块;库 crate 不自行装配外部依赖。
概念解释
依赖注入的装配集中在组合根,避免每个服务自己创建依赖。Rust 项目中 main 或启动模块承担组合根职责:这里才出现具体数据库驱动、客户端与框架路由。库 crate 只定义类型与 trait,装配可替换。
原理流程
- 二进制入口加载配置并校验。
- 创建连接池、外部客户端等基础设施。
- 构造适配器并实现端口 trait。
- 装配应用服务,注册路由与后台任务。
- 启动运行时进入服务循环。
代码或图示
// server/src/main.rs(组合根)
#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
let config = load_config()?;
let repo = PgOrderRepository::new(&config.database).await?;
let service = OrderService::new(repo);
let app = api::router(service, config.http);
serve(app).await
}
常见误区
- 库 crate 内直接 new 数据库连接:装配逻辑下沉核心,无法测试替换。
- 装配逻辑散落在 handler:依赖构造与业务处理混在一起。
追问
- 组合根之外能创建依赖吗?答:用例通过端口接收已注入实现,不自行构造外部依赖;例外是纯值对象构造。
- 多个二进制入口如何共享装配?答:抽公共装配函数在库 crate,各入口传入配置调用,避免重复组装代码。
04.4.13.3-060 环境差异如何通过 trait 隔离,而不在业务代码里写环境判断?
一句话结论
环境差异(实现选择、外部地址、开关)通过配置注入与 trait 实现差异隔离;业务代码面向端口编程,不出现 if env == "prod" 之类分支。环境只影响组合根装配。
概念解释
业务代码判断环境名会导致测试覆盖困难、分支散落。正确做法:环境专属值走配置,环境专属实现走不同适配器,业务用例调用统一端口。测试注入替身实现,生产装配真实实现,同一套业务逻辑服务多环境。
原理流程
- 识别环境相关差异:地址、凭证、实现、开关。
- 差异值由配置注入,差异实现由适配器承担。
- 业务代码只依赖端口与配置字段。
- 组合根按环境选择适配器实现。
- 评审搜索业务代码中的环境名判断并移除。
代码或图示
禁止:
if env == "prod" { ... } else { ... }
允许:
trait 端口 → 生产适配器 / 测试替身
配置字段 → 不同环境取值
常见误区
- 用环境名分支替代配置与抽象:环境组合增多后分支爆炸。
- 测试依赖特定环境:业务逻辑被部署环境绑定,本地无法独立运行。
追问
- 日志级别等环境差异怎么处理?答:作为配置字段注入观测层,业务代码不判断环境。
- 如何检查环境分支残留?答:评审与代码搜索环境名常量在业务 crate 的出现,环境判断只允许出现在组合根与配置层。
04.4.13.3-061 一个典型 axum 服务的四层目录树长什么样?
一句话结论
入口二进制 crate 装配路由,api crate 提供路由与 DTO,application crate 定义用例与端口,domain crate 放模型规则,infrastructure crate 实现数据库与外部适配器;各 crate 通过依赖方向单向连接。
概念解释
目录树是分层的物理体现:api 对接 axum 框架,application 编排用例,domain 纯规则,infra 对接技术实现。入口 crate 组合根组装全部依赖。实际项目可按规模合并 crate,但模块层级保持一致。
原理流程
- 根 workspace 声明成员 crate。
- domain 定义实体、值对象、领域错误。
- application 定义用例服务与端口 trait。
- infra 实现仓储与外部服务适配器。
- api 注册路由映射 DTO,入口 crate 装配启动。
代码或图示
crates/
domain/src/lib.rs 模型、规则、领域错误
application/src/lib.rs 用例服务、端口 trait
infrastructure/src/ Pg 仓储、Redis、外部客户端
api/src/lib.rs axum 路由、请求响应 DTO
server/src/main.rs 组合根、启动运行时
常见误区
- 目录分层但 crate 依赖互通:物理边界未强制,分层只是注释。
- 把 axum 路由代码放进 application:用例层绑定 Web 框架。
追问
- 小项目这个树怎么简化?答:合并为单 crate 内四个模块,保持依赖方向;规模增长后再提取 crate。
- 契约 DTO 放哪?答:跨服务共享放独立 contracts crate;仅本服务接口使用可放 api crate。
04.4.13.3-062 domain crate 是否应该依赖 serde?
一句话结论
domain 模型原则上不依赖序列化框架,保持纯规则;需要对外序列化时在 api/契约层做 DTO 映射。若领域结构需要持久化序列化或内部工具便利,可在评估后引入,但要记录边界理由。
概念解释
依赖 serde 意味着模型被序列化格式约束:字段 rename、可选性、派生属性渗入核心。严格分层下 domain 不感知 JSON/二进制格式;映射在边界完成。例外场景:领域结构本身就是数据契约、或内部共享配置模型,此时引入 serde 是有意识的权衡。
原理流程
- 判断模型是否需要对外或跨层序列化。
- 严格分层:domain 不派生序列化属性,DTO 单独定义。
- 映射层完成领域模型与 DTO 互转。
- 确有必要时在 domain 引入 serde 并在 ADR 记录理由。
- 评审检查派生属性是否污染核心规则。
代码或图示
// 严格分层:domain 无 serde 依赖
struct Order { id: OrderId, status: OrderStatus }
// api/契约层
#[derive(Serialize)]
struct OrderDto { id: String, status: String }
常见误区
- 所有领域结构派生 Serialize/Deserialize:核心层绑定协议格式,换表示要改模型。
- 持久化行结构直接复用领域模型:存储格式进入核心边界。
追问
- 哪些核心类型适合带 serde?答:跨层共享的值对象或配置模型,且序列化是其职责一部分;纯行为聚合不建议。
- serde 依赖会影响编译吗?答:属于基础序列化库,体积有限;核心依赖最小化原则下权衡引入必要性。
04.4.13.3-063 应用服务如何编排多个仓储端口?
一句话结论
应用服务持有多个端口 trait 引用,按用例流程依次调用仓储与领域服务,控制事务边界与调用顺序;编排只做流程协调,业务规则下沉到领域层,不直接操作数据库细节。
概念解释
复杂用例跨多个聚合:加载订单、校验库存、写支付记录。应用服务通过端口访问各聚合,顺序与一致性边界在用例层定义。多个仓储注入服务构造函数,测试时替换为替身。编排逻辑应可被独立测试,不依赖框架与网络。
原理流程
- 用例接收命令对象,参数校验在边界完成。
- 通过仓储端口加载所需聚合。
- 调用领域规则完成状态变更。
- 依次保存变更,纳入同一事务边界。
- 返回结果或结构化错误给接口层。
代码或图示
struct CheckoutService<O: OrderRepo, I: InventoryRepo, P: PaymentRepo> {
orders: O,
inventory: I,
payments: P,
}
impl<O, I, P> CheckoutService<O, I, P> {
fn checkout(&self, cmd: Checkout) -> Result<Receipt, AppError> {
let mut order = self.orders.find(&cmd.order_id)?;
order.reserve(&cmd.items)?;
self.inventory.reserve(&cmd.items)?;
let receipt = self.payments.charge(&order)?;
self.orders.save(order)?;
Ok(receipt)
}
}
常见误区
- 编排服务里写 SQL 或驱动调用:技术细节渗入用例层。
- 规则判断散在编排流程中:领域行为无法被其他用例复用。
追问
- 多仓储事务怎么保证?答:事务边界在用例层开启,端口实现参与同一事务;跨库一致性走最终一致。
- 服务构造函数参数太多怎么办?答:按聚合分组端口,或用配置结构收集依赖;超过合理数量时检查职责是否过载。
04.4.13.3-064 infrastructure 层如何持有连接池并实现仓储端口?
一句话结论
适配器 struct 持有连接池或客户端实例,构造时完成初始化;trait 方法内从池取连接、执行查询、把行数据映射为领域聚合,外部错误转换为应用错误。连接池生命周期由组合根管理。
概念解释
连接池是基础设施资源,不属于领域模型。仓储适配器负责池获取、SQL 执行与类型映射:私有行结构不泄漏到外层;方法签名只使用核心类型。池大小、超时等配置从组合根传入,适配器不自行读取环境变量。
原理流程
- 构造函数接收连接池配置或现成池实例。
- 实现端口 trait 方法,从池获取连接。
- 执行查询,把行映射为领域模型。
- 驱动错误包装为应用错误,保留来源。
- 组合根在停机时随池关闭释放资源。
代码或图示
struct PgOrderRepository { pool: sqlx::PgPool }
impl PgOrderRepository {
fn new(pool: sqlx::PgPool) -> Self { Self { pool } }
}
impl OrderRepository for PgOrderRepository {
fn find(&self, id: &OrderId) -> Result<Option<Order>, AppError> {
let row = sqlx::query!("SELECT ... WHERE id = $1", id.as_str())
.fetch_optional(&self.pool)
.map_err(InfraError::from)?;
Ok(row.map(Order::from_row))
}
}
常见误区
- 适配器方法返回驱动错误类型:核心层耦合数据库实现。
- 每个方法新建连接池:资源浪费,池应在组合根创建一次。
追问
- 行映射放适配器还是领域模型?答:行结构属于基础设施,映射在适配器完成;领域模型提供重建方法或由适配器组装,避免模型认识数据库行。
- 连接池配置在哪?答:配置结构体传入构造函数,池大小与超时按部署基线设置。
04.4.13.3-065 端口 trait 方法异步化有哪些现状与限制?
一句话结论
Rust 异步 trait 方法可直接在 trait 内声明 async fn;若需要 dyn trait object 承载异步方法,兼容性与返回类型包装受工具链版本约束,需要按当前版本确认实现方式。
概念解释
异步端口让适配器对接异步数据库与 HTTP 客户端。普通泛型使用下,trait 内 async fn 直接可用;trait object(dyn)对异步方法的支持历史上受限,常需要返回 impl Future 或包装为 boxed future。具体支持程度随 Rust 版本演进,不确定处以编译器与 docs.rs 文档为准。
原理流程
- 确定端口使用泛型静态分发还是 trait object。
- 泛型场景:trait 方法直接声明
async fn。 - 动态分发场景:核对当前工具链对异步
dyn的支持。 - 受限时用返回 Future 类型或 boxed future 表达。
- 测试替身按同一 trait 签名实现异步方法。
代码或图示
// 泛型静态分发下的异步端口
trait OrderRepository {
async fn find(&self, id: &OrderId) -> Result<Option<Order>, AppError>;
}
常见误区
- 假设所有异步 trait 都能直接
Box<dyn Trait>:dyn 兼容性受版本限制,编译报错后再改结构成本高。 - 在端口方法里阻塞等待异步操作:异步上下文被阻塞,运行时调度受损。
追问
- 待确认点怎么标注?答:记录「待确认:当前工具链版本下异步方法是否支持 dyn 直接派生,验证方式为编译最小 trait object 示例并查阅 Rust 版本文档」。
- 同步端口与异步端口能共存吗?答:同一抽象内保持一致风格;需要兼容同步实现时在适配器边界做阻塞隔离。
04.4.13.3-066 如何用 trait 替身测试 application 层用例?
一句话结论
为端口 trait 编写测试替身 struct,按用例返回固定聚合或记录调用;应用服务测试只注入替身,验证编排顺序、规则调用与错误分支,不连接真实数据库或网络。
概念解释
端口倒置让应用层可脱离技术设施测试:替身实现 trait,模拟仓储返回、缺失、失败等场景。测试断言用例在给定输入下调用了哪些端口、产出什么结果。真实适配器另写集成测试对接外部依赖。
原理流程
- 定义测试替身 struct,实现端口 trait。
- 替身内部保存期望返回值与调用记录。
- 装配应用服务时注入替身。
- 调用用例方法,断言结果与错误分支。
- 校验调用顺序与参数,覆盖成功/失败/边界场景。
代码或图示
struct FakeRepo { saved: Vec<Order> }
impl OrderRepository for FakeRepo {
async fn save(&mut self, order: Order) -> Result<(), AppError> {
self.saved.push(order);
Ok(())
}
async fn find(&self, _id: &OrderId) -> Result<Option<Order>, AppError> {
Ok(None)
}
}
#[tokio::test]
async fn checkout_persists_order() {
let repo = FakeRepo { saved: vec![] };
let service = CheckoutService::new(repo);
// 调用与断言
}
常见误区
- 应用层测试连真实数据库:测试慢且依赖环境,失败原因难以定位。
- 替身只返回成功值:未覆盖失败与缺失分支,错误路径无测试保护。
追问
- 替身放哪个 crate?答:跨多个测试复用放测试辅助 crate;单 crate 使用可放在 tests 目录或源码测试模块。
- 如何验证调用顺序?答:替身记录调用列表,断言顺序与参数;复杂交互用调用日志比对。
04.4.13.3-067 跨层数据映射(domain → DTO → response)放在哪一层?
一句话结论
领域模型到对外 DTO 的映射在 api 层完成,用例返回领域结果或应用结果类型;请求 DTO 到命令对象的转换也在 api 边界。领域模型不认识 DTO,DTO 不反向引用内部实现。
概念解释
映射是边界职责:内部表示与外部契约解耦。api 层负责双向转换:请求入参校验后转用例命令,用例结果转响应 DTO。映射代码集中在转换模块,避免散落在 handler 中。跨服务共享结构走契约 crate。
原理流程
- 请求到达 api 层,反序列化为请求 DTO。
- 边界校验后转换为用例命令对象。
- 应用服务返回领域聚合或结果类型。
- api 层映射为响应 DTO,裁剪敏感字段。
- 序列化为响应返回。
代码或图示
// api 层转换
impl From<Order> for OrderResponse {
fn from(order: Order) -> Self {
Self {
id: order.id().to_string(),
status: order.status().to_string(),
}
}
}
常见误区
- 领域模型直接序列化进响应:内部字段与结构外泄,契约被模型绑定。
- 映射逻辑写进领域方法:模型认识对外格式,分层被穿透。
追问
- 多层嵌套对象怎么映射?答:逐层定义 From 转换,聚合根映射组合子结构 DTO;复杂映射抽独立转换模块。
- 命令对象与 DTO 区别?答:DTO 是传输形态,命令是用例入参语义对象;命令可被多个接口复用,不绑定协议格式。
04.4.13.3-068 入参 DTO 校验与领域不变量校验如何分层?
一句话结论
api 层做格式与范围校验(类型、长度、枚举、必填),domain 层做业务不变量校验(状态迁移、余额规则、聚合一致性);两层互补,边界校验不替代规则校验。
概念解释
格式校验回答「输入是否合法可解析」,不变量校验回答「业务上是否允许」。例如邮箱格式在边界校验,账户是否允许扣款在领域校验。领域不变量封装在实体方法内,绕过边界也不能构造非法状态。
原理流程
- 请求 DTO 反序列化,类型与必填由 Serde 检查。
- api 层校验长度、格式、取值范围。
- 命令进入领域,实体/值对象构造与变更方法校验不变量。
- 违反规则返回领域错误,映射为响应状态码。
- 测试覆盖两层校验分支。
代码或图示
// 边界:格式与范围
struct CreateUserRequest { name: String }
// 领域:不变量
impl User {
fn rename(&mut self, name: String) -> Result<(), DomainError> {
if name.trim().is_empty() {
return Err(DomainError::EmptyName);
}
self.name = name;
Ok(())
}
}
常见误区
- 只在 DTO 层校验业务规则:领域对象可被其他用例非法构造。
- 领域层重复做格式解析:字符串格式检查属于边界职责,领域接收已解析的值对象。
追问
- 值对象构造校验放哪?答:值对象构造函数内校验自身不变量,非法值无法构造,边界解析后传入。
- 跨聚合一致性校验在哪?答:聚合内不变量在实体,跨聚合规则在领域服务或应用用例协调。
04.4.13.3-069 架构边界被破坏有哪些典型信号?
一句话结论
信号包括 domain 清单出现框架/驱动依赖、核心方法返回外部类型、handler 直接操作仓储、错误类型穿透到接口、模块间逆向引用;出现这些说明分层已被绕过,需要重构纠正。
概念解释
边界腐化是渐进的:新功能图方便引入一个外部类型,随后调用链扩散。典型信号可在依赖清单、类型签名与调用关系中观察。早期发现成本低,积累后核心层与实现层深度耦合,测试与替换困难。
原理流程
- 审查核心 crate 依赖清单是否出现禁用技术栈。
- 检查核心方法签名是否返回驱动/框架类型。
- 追踪 handler 是否跳过用例直接访问基础设施。
- 核对错误类型是否在边界完成转换。
- 发现信号后按依赖倒置重构:接口下沉,实现外移。
代码或图示
破坏信号:
domain 依赖 sqlx/axum/tokio
核心返回 PgRow / Json 响应类型
handler 直接取连接池执行查询
驱动错误穿透到 HTTP 层
crate 依赖图出现逆向边
常见误区
- 认为「只引用一个类型没关系」:类型依赖沿调用链扩散,边界逐步失效。
- 破坏后继续在旧结构上堆功能:重构成本随时间上升。
追问
- 如何批量排查类型泄漏?答:
cargo tree看依赖,搜索核心 crate 源码中的外部类型名;CI 依赖允许列表自动拦截新增禁用依赖。 - 发现破坏后第一步做什么?答:划清接口边界,把外部类型映射隔离到适配器,核心只保留端口与核心类型。
04.4.13.3-070 跨端共享契约(proto/OpenAPI)在仓库中如何放置?
一句话结论
跨服务、跨端复用的契约定义(Protobuf schema、OpenAPI 规范、共享 DTO)放独立契约 crate 或契约目录,被 api 层与消费者共同依赖;契约只含结构与枚举,不含业务逻辑。
概念解释
契约集中管理避免服务端与客户端手写两份结构漂移。Protobuf 经代码生成接入 Rust,OpenAPI 可生成类型或作为文档规范。契约演进保持向后兼容,变更经过评审;服务内部使用的 DTO 留在 api crate。
原理流程
- 识别跨服务/跨端复用的数据结构。
- 建立契约 crate 或 schema 目录。
- 定义消息、字段编号、枚举与错误码。
- 生成 Rust 类型或由 api 层引用。
- 消费者依赖同一契约包,版本随演进管理。
代码或图示
crates/
contracts-proto/ Protobuf schema 与生成代码
contracts-dto/ 共享 JSON DTO 与错误枚举
常见误区
- 契约 crate 引入业务规则或数据库依赖:共享层变重,消费者被迫传递依赖。
- 服务端响应结构直接发给客户端却无共享定义:客户端手写结构,字段漂移难发现。
追问
- 生成代码纳入版本管理吗?答:按工具链与 CI 策略决定;生成产物可在构建时产出,schema 必须纳入版本管理。
- 契约版本不兼容怎么处理?答:新增可选字段保持兼容,破坏变更独立版本或新服务接口,迁移期并存。
04.4.13.3-071 大单体拆分的第一步应该做什么?
一句话结论
先在单体内按业务域抽出边界清晰的模块/crate,明确端口、数据归属与依赖方向,验证可独立演进后再拆成独立服务;不第一步就切部署与数据库。
概念解释
单体拆分失败多源于边界未清就拆部署。物理拆分前先做逻辑拆分:领域模型、用例、仓储端口按域分离,找出耦合点。逻辑边界稳定后,独立部署与数据库切分才有依据,风险可控。
原理流程
- 梳理业务域与现有模块耦合关系。
- 单体内按域提取模块/crate,定义端口。
- 明确各域数据归属与跨域调用方式。
- 验证边界内测试独立可运行。
- 边界稳定后再拆分服务、切分数据库与通信链路。
代码或图示
第一步:逻辑拆分
域模块/crate + 端口 + 数据归属
第二步:部署拆分
独立服务 + 接口/事件通信
第三步:数据拆分
独立数据库 + 投影/对账
常见误区
- 先拆服务再补边界:跨服务调用纠缠,分布式事务与耦合问题叠加。
- 按技术层拆服务:表现层、数据层各自独立,业务链路被切断。
追问
- 单体里哪些信号说明边界可拆?答:模块间只通过端口交互、数据归属明确、变更很少跨模块同步。
- 拆分过程中旧单体怎么办?答:并行运行,新模块按灰度切入,旧逻辑逐步下线,不做一次性切换。
04.4.13.3-072 共享内核与重复代码之间如何权衡?
一句话结论
被多个域稳定复用的通用概念抽共享内核;仅表面相似、规则不同的代码保留重复,避免过早抽象把异质业务捆在一起。抽象以真实复用为前提。
概念解释
DRY 原则不等于所有相似代码合并:共享内核要求各域对概念理解一致。重复代码耦合低、独立演进;错误抽象会把差异掩盖在通用层,改动影响面扩大。判断依据是复用次数、规则一致性与变更节奏。
原理流程
- 识别重复出现的结构与逻辑。
- 判断规则是否真的一致,还是仅形式相似。
- 一致且多次复用:抽取共享内核/crate。
- 规则不同:保留各自实现,记录差异原因。
- 共享内核演进时评估对各域的影响。
代码或图示
倾向共享:
同语义值对象、通用错误类型、基础工具
多域复用、规则一致、变更同步
保留重复:
表面相似但业务规则不同
演进节奏不同、耦合代价高于重复
常见误区
- 见到第二处相似就抽象:抽象点过早,第三处出现时规则已分化。
- 共享内核不断膨胀:通用层混入特定业务,反向污染各域。
追问
- 共享内核放哪?答:独立基础 crate 或共享类型包,依赖方向被各域单向引用,不依赖业务外层。
- 发现错误抽象怎么拆回?答:按域复制回独立实现,再清理共享层对应部分,每步可回归验证。
04.4.13.3-073 事件总线在端口层如何抽象?
一句话结论
核心层定义事件发布端口 trait,方法接收领域事件;事件总线、MQ 生产者是 infrastructure 适配器。核心不感知总线实现,订阅处理器通过端口或外层装配注册。
概念解释
事件端口把「发布事实」与「投递机制」分离:用例只调用发布端口,具体投递到 Kafka/RabbitMQ/NATS 或内存总线由适配器决定。事件结构在核心定义,携带业务数据;失败语义与重试在适配器与消费端处理。
原理流程
- 核心定义领域事件枚举与事件端口 trait。
- 用例在状态变更后调用端口发布事件。
- infrastructure 适配器对接消息总线,序列化事件并投递。
- 同进程订阅在装配层注册处理器;跨进程由消费者订阅。
- 失败重试、死信与追踪在消息链路处理。
代码或图示
trait EventPublisher {
async fn publish(&self, event: DomainEvent) -> Result<(), AppError>;
}
enum DomainEvent {
OrderCreated(OrderCreated),
PaymentCompleted(PaymentCompleted),
}
常见误区
- 核心层直接持有 MQ 生产者类型:投递机制泄漏进规则层。
- 事件内部携带可变聚合引用:序列化与后续处理耦合内部状态。
追问
- 事件与事务一致性怎么保证?答:本地事务保存聚合与事件记录,提交后发布;跨系统用 outbox 模式与重试保障最终一致。
- 总线适配器如何测试?答:替身端口记录发布事件;适配器集成测试对接测试 MQ 验证投递格式。
04.4.13.3-074 外部 API 客户端如何作为适配器落地?
一句话结论
外部 HTTP/第三方 SDK 客户端封装在 infrastructure 适配器,实现内层定义的外部服务端口;适配器负责请求构造、响应映射、错误转换与超时控制,核心只描述业务意图。
概念解释
外部依赖属于被驱动适配器:支付网关、短信服务、第三方数据接口。端口定义业务操作(如「发起支付」「发送通知」),适配器对接具体 SDK/HTTP API。凭证与地址由组合根注入,适配器不在代码中硬编码。
原理流程
- 内层定义外部服务端口 trait,方法用核心类型。
- infrastructure 封装客户端 struct,持有 SDK 实例或 HTTP 客户端。
- 实现端口:构造请求、调用外部接口、映射响应。
- 外部错误转应用错误,超时与重试策略在适配器配置。
- 测试用替身端口验证用例,适配器另做集成测试。
代码或图示
trait PaymentGateway {
async fn charge(&self, order: &Order, amount: Money) -> Result<ChargeRef, AppError>;
}
struct HttpPaymentGateway { client: reqwest::Client, endpoint: String }
impl PaymentGateway for HttpPaymentGateway { /* 调用与映射 */ }
常见误区
- 用例代码直接 reqwest 调用第三方:核心绑定 HTTP 客户端与具体接口。
- 适配器把第三方响应结构透传给核心:外部 schema 变化冲击业务层。
追问
- 客户端超时与重试放哪?答:适配器配置与实现,端口语义保持业务化;重试策略按外部服务特性评估。
- 凭证怎么传入?答:配置经组合根注入适配器构造函数,不写进源码或镜像。
04.4.13.3-075 模块级集成测试与跨 crate 测试如何组织?
一句话结论
单 crate 内集成测试放 tests/ 目录,跨 crate 流程测试放入口 crate 或独立测试成员;共享 mock 与断言抽测试辅助 crate,测试只能通过公开 API 驱动被测单元。
概念解释
多 crate 工程的测试分层:单元测试内联在源码,crate 集成测试验证公开接口,端到端流程测试组装多层。测试辅助代码独立成 dev-dependency crate,避免各测试目录重复实现替身。测试组织与 workspace 成员结构对应。
原理流程
- 单元测试留在各模块源码旁。
- crate 集成测试写入
tests/,调用公开 API。 - 跨层流程测试在入口 binary crate 或 test member 装配。
- 共享替身、断言工具抽到测试辅助 crate。
- CI 按 crate 与测试类型分组执行。
代码或图示
crates/application/tests/use_case.rs 用例集成测试
crates/server/tests/flow.rs 跨层流程测试
crates/test-support/ mock 与断言辅助
常见误区
- 集成测试访问私有模块:
tests/是外部 crate,私有项不可见。 - 各测试目录复制 mock 实现:替身逻辑分叉,测试行为不一致。
追问
- 测试辅助 crate 能否包含生产代码?答:只放测试替身与工具,声明 dev-dependencies;生产逻辑不进入辅助 crate。
- 跨 crate 测试需要真实依赖吗?答:用例测试用替身;适配器与端到端测试按需对接测试容器或测试环境。
04.4.13.3-076 workspace 成员的 feature 统一启用策略如何定?
一句话结论
公共依赖的 feature 在根 [workspace.dependencies] 统一声明,成员按需追加;可选后端等内部 feature 按成员职责分组,默认组合明确,CI 覆盖各 feature 组合编译。
概念解释
feature 策略避免依赖特性分散:基础库版本与常用 feature 集中管理,成员只补充特有开关。内部 crate 的可选实现 feature 明确默认启用集,构建目标按环境选择。feature 组合在 CI 验证,防止未默认路径编译失败。
原理流程
- 根配置声明公共依赖版本与基础 feature。
- 成员依赖继承 workspace 配置,追加特有 feature。
- 内部可选后端定义 feature 开关与默认集。
- CI 矩阵构建默认组合与关键可选组合。
- 新增 feature 记录用途与启用条件。
代码或图示
[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
[members.infra.dependencies]
serde = { workspace = true, features = ["rc"] }
常见误区
- 成员各自声明不一致的 feature:同一依赖解析出重复特性组合,类型兼容问题。
- 可选 feature 长期不测试:非默认路径编译失败直到发布前才暴露。
追问
- feature 与配置开关如何对应?答:feature 决定编译进产物的实现,配置开关控制已编译功能启停;文档写明二者关系。
- 如何查看某成员启用了哪些 feature?答:
cargo tree -e features查看依赖特性启用情况,具体命令以 Cargo 文档为准。
04.4.13.3-077 编译产物分层如何让核心层编译更快?
一句话结论
稳定核心与共享契约先编译为独立 crate,易变外层改动只重编外层;核心层依赖精简减少重编译面,配合缓存与快链接器缩短构建时间。分层同时服务于架构边界与编译效率。
概念解释
Cargo 按 crate 增量编译:核心不变时改动 API 层不触发核心重编。依赖精简让核心编译输入稳定;外层重依赖(框架、驱动)隔离在 infrastructure/api。编译产物分层与架构分层重合,稳定在内、易变在外。
原理流程
- 核心 crate 依赖最小化,类型稳定。
- 重依赖隔离到外层 crate。
- 改动外层时编译范围收敛到外层及下游。
- 接入编译缓存复用未变化产物。
- 观察典型改动的重编译 crate 数量与耗时。
代码或图示
编译顺序:
contracts/domain(稳定,先编译)
→ application(端口与用例)
→ infrastructure / api(重依赖,易变)
常见误区
- 核心 crate 引入重框架依赖:每次框架关联改动都重编核心,收益消失。
- 拆 crate 过细:依赖解析与链接开销上升,编译速度反降。
追问
- 如何衡量编译分层收益?答:对比典型需求改动下重编译 crate 数与 wall-clock 时间,而非 crate 总数。
- release 编译优化另算吗?答:LTO、strip 等 profile 优化影响最终产物,与 crate 分层缩短增量编译是两个层面。
04.4.13.3-078 架构文档如何与代码保持同步?
一句话结论
架构文档记录分层、边界、端口与关键决策,随代码变更评审更新;目录树、依赖方向与 ADR 是代码外的补充视图,代码与文档在同一次变更中修改,不事后补写。
概念解释
文档过期比没有文档更误导。同步机制:代码评审检查架构相关变更是否更新文档;ADR 记录决策原因,README/索引说明模块职责。文档描述稳定边界与决策,不复述可变实现细节,减少同步成本。
原理流程
- 仓库维护架构概览:分层图、模块职责、依赖方向。
- 关键决策写入 ADR,编号可追溯。
- 变更涉及边界调整时,同 PR 更新文档。
- 定期复核文档与代码结构是否一致。
- 过期文档及时修正或归档。
代码或图示
文档组成:
架构概览(分层、目录树、依赖方向)
ADR(决策背景、备选、结论)
模块 README(职责、端口、测试归属)
常见误区
- 架构文档上线后不再维护:代码演进后文档描述旧结构,误导新人。
- 文档复述每行代码:细节易过期,文档应保留边界与决策层信息。
追问
- 文档更新纳入评审了吗?答:涉及分层、端口、依赖的 PR 必须核对对应文档;纯内部实现调整不必改概览。
- 新人先看什么?答:架构概览与 ADR 理解边界和决策原因,再读 lib.rs 与模块入口。
04.4.13.3-079 选型评审记录与回退方案如何准备?
一句话结论
技术选型在评审中记录候选方案、取舍依据、风险与回退路径;接受方案后写入 ADR,预留替代实现端口,避免选型锁定后无法退回。
概念解释
选型不是一锤定音:关键技术(框架、数据库、通信协议)都应评估退出成本。评审记录备选与放弃理由,架构层用端口隔离具体实现,使替换成为换适配器而非改核心。回退方案包括数据迁移、灰度切回与兼容窗口。
原理流程
- 列出候选技术与非功能要求。
- 对比功能、性能、生态、团队成本与风险。
- 记录决策与未选方案的放弃原因。
- 设计抽象端口,隔离所选技术实现。
- 准备回退步骤:切换方案、数据处理、灰度与验证。
代码或图示
选型记录:
背景约束 / 候选方案 / 对比结论
决策 / 风险 / 回退路径
抽象端口(实现可替换)
常见误区
- 只记录「选了什么」,不记为什么:后续无法判断决策是否仍适用。
- 选型实现直接渗入核心:发现不适合时替换成本极高。
追问
- 回退方案什么时候演练?答:高风险选型在预发环境验证切换流程;数据类回退需要备份与回填方案。
- 端口抽象成本高吗?答:初期增加接口设计,换取后续可替换性;核心业务领域尤其值得隔离。
04.4.13.3-080 新人理解这套 Rust 架构从哪里入手?
一句话结论
先读架构概览与 ADR 掌握分层与决策,再从入口 crate 的组合根看装配链路,沿 api → application → domain → infrastructure 追踪一次请求,最后读端口 trait 与适配器实现。
概念解释
理解顺序应从全局边界到局部实现:先知道各层职责与依赖方向,再看代码如何组装。组合根展示依赖如何注入,请求链路展示各层协作;端口定义是理解可替换性的关键入口。避免一上来钻适配器细节。
原理流程
- 阅读架构概览:分层、目录树、模块职责。
- 读相关 ADR:关键决策背景与约束。
- 从 main/组合根追踪装配:配置、适配器、服务、路由。
- 沿一次请求经过 api → application → domain → infra。
- 回到端口 trait 理解抽象边界与测试替身。
代码或图示
上手路径:
架构概览 → ADR → 组合根 main
→ 请求链路(api→app→domain→infra)
→ 端口 trait 与适配器实现
常见误区
- 直接从数据库适配器读起:陷入技术细节,看不到分层意图。
- 跳过文档读源码:不清楚边界约束,容易在修改时越界。
追问
- 仓库里哪些文件是入口?答:根 workspace 清单、入口 binary 的 main、各 lib crate 的 lib.rs 重导出。
- 如何验证理解是否到位?答:能画出依赖方向图、说出端口与适配器对应关系、指出某类变更应改在哪一层。
04.4.13.3-081 小项目强行套用四层架构有什么过度设计风险?
一句话结论
小项目业务简单、团队少时,强行拆四个 crate 与端口适配器会增加样板代码、编译编排与导航成本,收益低于维护代价;应先用单 crate 模块分层,边界清晰后再提取 crate。
概念解释
分层架构服务于复杂度增长:领域规则多、复用要求高、团队并行多时价值显现。早期过度设计表现为:大量 trait 与适配器包装薄逻辑、 crate 间频繁互调、配置与测试成本上升。判断标准是当前复杂度,而不是预设未来规模。
原理流程
- 评估项目规模:功能数量、团队人数、复用需求。
- 简单项目:单 crate 内模块分层,保持直接实现。
- 识别稳定边界后再逐步提取 crate。
- 避免为尚不存在的复用设计抽象。
- 复杂度上升时按 ADR 记录架构演进。
代码或图示
小项目形态:
单 crate + 模块目录
直接实现,少 trait 包装
触发拆分信号:
模块边界稳定、多入口复用、并行开发冲突、规则复杂
常见误区
- 照搬大型项目结构:样板代码多于业务代码,新人上手慢。
- 抽象点过早锁定:后续业务分化时错误抽象难以回退。
追问
- 怎么判断分层是否过重?答:改动一个小功能要碰多个 crate 与 trait,测试与编译成本明显高于直接实现。
- 简化后还能演进吗?答:模块分层保留边界意图,规模增长时提取 crate 有清晰路径。
04.4.13.3-082 发现逆向依赖后如何重构:从 domain 移除外层依赖?
一句话结论
先在核心层定义需要的端口 trait 与核心类型,把外层类型映射隔离到适配器;移除 domain 对框架/驱动的依赖,再让 infrastructure 实现端口。每步保持编译通过与测试回归。
概念解释
逆向依赖重构按依赖倒置方向反转:外部概念下沉为核心抽象,实现留在外层。步骤是识别泄漏类型 → 定义端口与核心模型 → 边界映射转换 → 移除核心依赖 → 验证编译与测试。不宜一次性大改,分小步提交。
原理流程
- 扫描 domain 清单与源码,列出禁用外部类型。
- 在核心定义端口 trait,方法签名用核心类型。
- 在 infrastructure 实现适配器,完成外部类型到核心类型映射。
- 移除 domain 中的外部依赖与类型引用。
- 跑测试与编译检查,确认边界恢复单向。
代码或图示
重构前:domain → sqlx 行类型
重构后:
domain 定义 OrderRepository trait
infra PgOrderRepository 实现 trait
行映射留在 infra,domain 只持有 Order 模型
常见误区
- 直接删除核心依赖不提供替代抽象:编译断裂,业务逻辑无处安放。
- 重构同时改业务行为:边界修复与功能变更混杂,回归风险高。
追问
- 重构期间新功能怎么安排?答:新功能按新边界开发,旧逆向依赖逐步清理,不在旧结构上增量扩大。
- 如何确认重构彻底?答:核心 crate 清单无禁用依赖,源码无外部类型名,CI 依赖规则通过。
04.4.13.3-083 架构演进过程中 crate 何时合并、何时拆分?
一句话结论
职责频繁互调、边界松散的 crate 合并回模块;业务域独立、变更节奏分离、需要复用或独立伸缩的 crate 拆分。合并与拆分都以依赖方向和变更频率为依据,随规模演进调整。
概念解释
架构边界不是一次定死:早期过细拆分应合并,规模增长后按域拆分。合并信号是跨 crate 调用频繁、共享类型多、编译反复联动;拆分信号是模块稳定独立、多入口复用、并行开发与部署需求分化。调整时先逻辑边界后物理 crate。
原理流程
- 观察各 crate 调用频率、共享类型与变更节奏。
- 过细边界:合并为单 crate 内模块,保留分层目录。
- 独立域:提取 crate,定义端口与数据归属。
- 每次调整更新依赖图、文档与测试组织。
- 复盘调整后编译、协作与替换成本是否改善。
代码或图示
倾向合并:
高频互调 / 共享类型多 / 编译联动 / 边界模糊
倾向拆分:
域独立 / 变更分离 / 多入口复用 / 独立伸缩
常见误区
- crate 结构一旦定下不再调整:规模变化后边界与实际协作脱节。
- 凭直觉频繁拆并:每次调整成本高,应基于调用与变更数据判断。
追问
- 合并拆分先动物理还是逻辑?答:先在模块层面梳理职责与依赖,稳定后再调整 crate 边界,避免来回折腾。
- 调整后如何验证收益?答:看改动范围、编译耗时、测试独立性与协作冲突是否改善,记录到架构复盘。