罗罗编程学习记录
本页内容 展开查看

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 依赖核心。

原理流程

  1. 根 Cargo.toml 声明 workspace 成员目录。
  2. 各 crate 提供独立 Cargo.toml 与 src/lib.rs(或 src/main.rs)。
  3. 成员间通过 path 依赖引用,依赖方向沿架构层单向流动。
  4. 入口二进制 crate 装配各层并启动运行时。
  5. 编译时按依赖图增量构建,核心层先于外层编译。

代码或图示

# 根 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 统一管理。

原理流程

  1. 根 [workspace.dependencies] 声明公共依赖版本与 feature。
  2. 成员 crate 依赖项写 version = "..." 加 workspace = true。
  3. Cargo 解析时成员继承根配置的版本约束。
  4. 升级公共库只修改根配置一处。
  5. 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 做协议适配与状态装配。换框架或换存储时,核心规则不动。

原理流程

  1. domain 定义实体、值对象、领域错误与仓储端口 trait。
  2. application 实现用例服务,通过端口 trait 操作领域对象。
  3. infrastructure 用 SQLx/SeaORM 等实现端口 trait,持有连接池。
  4. api 注册路由、把请求映射为用例入参,把结果映射为响应。
  5. 入口 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 边界后,逆向依赖在编译期就暴露。

原理流程

  1. 绘制依赖图:api → application → domain,infrastructure → application/domain。
  2. 检查各 crate 的 [dependencies],核心层不出现外层技术栈。
  3. 外层通过实现内层 trait 完成对接。
  4. 评审与 CI 检查依赖方向是否被破坏。
  5. 出现逆向依赖时把接口下沉到内层,实现留在外层。

代码或图示

允许:
  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 不要混用(详见部署配置专题)。

原理流程

  1. 核心层定义后端操作的端口 trait。
  2. 各后端实现作为独立依赖或独立模块。
  3. [features] 声明后端开关,默认启用常用组合。
  4. 代码用 #[cfg(feature = "...")] 条件编译实现注册。
  5. 构建时按目标环境选择 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。

原理流程

  1. 识别变更频率:稳定核心、共享契约、易变接口分层。
  2. 按架构方向拆 crate,明确各 crate 职责。
  3. 改动后观察 cargo build 重编译范围是否收敛。
  4. 避免细粒度 crate 爆炸:过碎会增加依赖解析与链接开销。
  5. 结合 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 增量编译;缓存失效后仍需完整编译。

原理流程

  1. 安装 sccache 并设置 Rust 编译包装器环境变量。
  2. 编译时工具链调用 sccache 包装 rustc。
  3. sccache 计算输入哈希,命中则返回缓存产物。
  4. 未命中则调用 rustc 编译并回写缓存。
  5. 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 配置或环境变量指定链接器,具体可用范围受目标平台与工具链版本约束。

原理流程

  1. 确认目标平台支持的替代链接器。
  2. 在 Cargo 配置或环境变量中指定链接器路径。
  3. 构建时 rustc 调用指定链接器完成目标文件合并。
  4. 对比链接耗时与产物大小变化。
  5. 发布构建仍按 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 与显式版本。

原理流程

  1. 判断 crate 是否需要独立于主应用发布。
  2. 单仓库成员:依赖写 path 或 workspace 继承,版本随仓库演进。
  3. 跨仓库复用:发布到私有 registry,遵循语义化版本。
  4. 根 [workspace.dependencies] 统一内部依赖版本约束。
  5. 升级时批量对齐,记录破坏性变更。

代码或图示

# 单仓库内部 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 是最常见的中间形态。取舍依据是复用范围、发布节奏与团队边界,而不是技术潮流。

原理流程

  1. 列出被引用的内部 crate 与引用方分布。
  2. 同仓引用:path 依赖,提交同时包含双方改动。
  3. 跨仓引用:发布私有 registry,按版本升级。
  4. 评估共享类型是否应随主仓演进,减少独立发布面。
  5. 定期清理不再被复用的内部 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 目录重复。

原理流程

  1. 单元测试留在各模块源码旁,访问私有项。
  2. 集成测试写入对应 crate 的 tests/ 目录。
  3. 测试只调用公开 API,验证外部可观察行为。
  4. 跨 crate 流程测试在入口 crate 或独立 test member 组装多层。
  5. 共享 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 让依赖方只看到必要类型,内部重构不破坏外部使用。

原理流程

  1. 在 lib.rs 声明对外模块与重导出。
  2. 子模块内部类型保持私有或 pub(crate)。
  3. 对外类型实现所需 trait,暴露稳定方法签名。
  4. 依赖方通过顶层路径引用类型。
  5. 内部模块调整不影响公开路径,破坏变更走版本演进。

代码或图示

// 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。

原理流程

  1. 各架构层 crate 输出 lib 目标。
  2. 入口 binary crate 依赖相关 lib crate。
  3. main 函数加载配置、构造基础设施实现。
  4. 把实现注入应用层,组装 api 路由。
  5. 启动运行时进入服务循环。

代码或图示

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 生成消息、共享错误枚举在一处定义,服务端与客户端使用同一类型,避免手写两份结构漂移。契约层不依赖数据库与框架实现,保持轻量;演进时注意向后兼容。

原理流程

  1. 识别跨服务/跨端复用的结构与枚举。
  2. 建立契约 crate,派生序列化 trait。
  3. api 层用契约类型映射请求响应,消费者依赖同一 crate。
  4. 契约变更评审兼容性:新增可选字段优先,不破坏既有字段。
  5. 版本演进记录在契约 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,或把接口下沉到被依赖方,让依赖方向重新单向。

原理流程

  1. 编译/解析报错提示循环依赖。
  2. 用 cargo tree 查看依赖链与成环节点。
  3. 识别双方互相引用的类型与方法。
  4. 共享类型抽独立 crate,或 trait 定义下沉到内层。
  5. 重构后依赖图恢复无环。

代码或图示

成环: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,维护成本高于收益。

原理流程

  1. 盘点模块职责、调用方向与变更频率。
  2. 核心稳定、外层易变的模块优先分离。
  3. 被多入口复用的共享类型独立成 crate。
  4. 拆分后验证依赖图无环、方向正确。
  5. 观察编译与测试收益,过细则合并回模块。

代码或图示

倾向拆 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。替换实现时核心代码与测试不变,只换注入的适配器。

原理流程

  1. 在 domain/application 层定义输出端口 trait。
  2. 用例服务通过 trait 调用外部能力,不引用具体实现类型。
  3. infrastructure 层 struct 实现该 trait,封装 SQL/HTTP/MQ。
  4. 入口装配时把适配器实例传给应用层。
  5. 测试时注入 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 方法内执行查询/调用,结果映射为核心类型;外部错误经过转换包装,不把驱动错误类型直接暴露给核心。多个适配器可实现同一端口,按环境替换。

原理流程

  1. 定义适配器 struct,持有资源句柄。
  2. 构造函数接收连接池/客户端,完成初始化校验。
  3. impl 端口 trait,方法内执行外部操作。
  4. 外部响应映射为领域模型,错误转为应用层错误。
  5. 装配层选择具体适配器注入用例。

代码或图示

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 提取状态并调用用例。

原理流程

  1. 组合根加载配置,创建连接池与客户端。
  2. 构造适配器 struct 并实现端口 trait。
  3. 装配应用服务,注入适配器依赖。
  4. 服务实例装入框架状态结构体。
  5. 路由 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 有额外约束(见后续题)。

原理流程

  1. 判断依赖实现是否在运行时变化。
  2. 固定实现:用泛型参数,编译期单态化。
  3. 多实现并存:包装 Box<dyn Port> 或 Arc<dyn Port>。
  4. 状态与服务按所选方式持有依赖。
  5. 测试注入替身时保持分发方式一致。

代码或图示

// 静态分发
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 围绕接口契约组织(字段扁平、序列化格式、版本兼容)。混用会导致:领域规则被接口格式绑架,或响应泄漏内部结构。转换层负责字段映射、裁剪与格式适配,双向都要显式编写。

原理流程

  1. domain 定义实体/值对象,方法封装状态变更与不变量校验。
  2. api 层定义请求/响应 DTO,派生序列化 trait。
  3. 用例返回领域对象或结果类型。
  4. 映射层把领域模型转成 DTO,按接口需要裁剪字段。
  5. 反向把请求 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 保留因果,外层按需匹配转换。

原理流程

  1. domain 错误枚举表达规则违反(如状态非法、余额不足)。
  2. application 错误包装领域错误与用例失败场景。
  3. infrastructure 捕获驱动/客户端错误,转成应用错误并保留原因。
  4. api 层匹配错误类型,映射状态码与响应体。
  5. 日志记录错误链,响应只暴露必要信息。

代码或图示

#[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 不依赖数据库事务概念,避免被存储机制绑定。

原理流程

  1. 用例服务开始一个业务用例。
  2. 通过端口开启事务(仓储端口或事务管理器)。
  3. 用例内多次操作参与同一事务。
  4. 全部成功提交,任一失败回滚。
  5. 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。可见性在编译期强制,误用会直接报错,便于在评审前收紧边界。

原理流程

  1. 识别类型是对外接口还是内部实现。
  2. 内部共享类型标 pub(crate),模块内私有保持默认。
  3. 对外类型与方法标 pub,写入 lib.rs 重导出。
  4. 编译检查跨 crate 引用是否越界。
  5. 重构时内部类型调整不影响外部路径。

代码或图示

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 与数据库细节。

原理流程

  1. 识别规则归属:单实体行为放实体,跨实体规则放领域服务。
  2. 应用服务接收用例命令,通过端口加载聚合。
  3. 调用领域实体/领域服务执行规则变更。
  4. 应用服务控制事务与持久化顺序。
  5. 返回结果或错误给接口层。

代码或图示

// 领域服务:纯业务规则
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 的所有权与私有字段天然支持封装不变量。

原理流程

  1. 值对象:私有字段 + 构造函数校验 + 实现相等比较。
  2. 聚合根:ID 类型标识,持有子实体/值对象集合。
  3. 根方法封装状态变更,先校验不变量再修改。
  4. 外部通过根方法操作聚合,不直接改内部字段。
  5. 仓储按根粒度保存与加载聚合。

代码或图示

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。

原理流程

  1. 内层定义仓储 trait,方法使用聚合根与 ID 类型。
  2. infrastructure 定义数据库行结构(私有)。
  3. 实现 trait:查询行数据,映射为领域聚合。
  4. 保存时把聚合拆成行数据写入。
  5. 装配层把实现注入应用服务。

代码或图示

// 内层端口
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 兼容性,按工具链版本选择表达形式。

原理流程

  1. 审查核心 crate 依赖清单,移除框架与驱动。
  2. 外部能力通过端口 trait 声明,方法签名用核心类型。
  3. 异步需求在 trait 内表达,外层实现对接运行时。
  4. 核心单元测试不启动运行时即可运行纯逻辑。
  5. 框架类型只出现在 api 与 infrastructure crate。

代码或图示

domain/application 允许依赖:
  serde(按需)、thiserror、核心类型库

禁止直接依赖:
  axum / actix-web / sqlx / redis / tokio 运行时宏

常见误区

  • 核心层为了方便引入序列化框架:模型被协议格式绑定,换表示要改核心。
  • 端口方法直接返回框架响应类型:用例被协议层污染,无法复用。

追问

  • 核心层需要日志怎么办?答:定义日志端口或接收外部记录器抽象,具体 tracing 实现在外层注入。
  • 异步核心如何测试?答:纯规则同步测试;涉及端口的用例用替身实现,在测试运行时中验证。

04.4.13.3-029 副作用(发邮件、发消息、调外部 API)为什么要隔离到适配器层?

一句话结论

副作用属于技术实现与外部交互,通过端口抽象后由适配器执行;核心层只声明「需要发生什么」,不直接调用邮件客户端、MQ 生产者或外部 HTTP SDK,保证规则可独立测试与替换。

概念解释

副作用包括写外部系统、发通知、调用第三方服务。直接在领域/用例代码里调用 SDK 会绑定具体厂商、增加测试依赖、污染核心规则。端口把副作用抽象成领域语义操作(如「通知用户」),适配器对接具体实现。

原理流程

  1. 核心层定义副作用端口 trait(通知、发布事件、调用外部服务)。
  2. 用例调用端口方法表达业务意图。
  3. infrastructure 适配器实现端口,封装 SDK 调用。
  4. 错误转换为应用错误,失败策略在用例或端口层定义。
  5. 测试注入替身验证调用意图,不触发真实外部交互。

代码或图示

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 规则可固化允许列表;代码评审把依赖方向作为检查项。

原理流程

  1. 列出各 crate 允许的外部依赖与内部依赖方向。
  2. 审查 [dependencies],核心层不得出现禁用 crate。
  3. 用 cargo tree 回溯类型来源,确认无逆向引用。
  4. CI 脚本校验依赖允许列表,破坏则阻断合并。
  5. 评审记录架构例外,定期清理技术债。

代码或图示

守护清单:
  domain 依赖:无 Web 框架、无数据库驱动
  application 依赖:domain + 端口抽象
  infra 依赖:application/domain + 具体技术库
  api 依赖:application + 框架

常见误区

  • 只靠口头约定分层:新成员或赶工时容易绕过,边界逐渐模糊。
  • 规则过严不允许例外:合理的共享基础库未纳入白名单,规则被整体绕过。

追问

  • 工具能自动检查 crate 依赖方向吗?答:可读取各 crate 清单脚本化校验允许列表;cargo-deny 可做依赖来源与 bans 检查,架构方向规则按团队脚本落地。
  • 发现核心层引入外部类型怎么办?答:把接口下沉到核心、实现移到外层,类型映射在边界完成,不保留逆向依赖。

04.4.13.3-031 贫血模型与充血模型在 Rust 项目中各是什么形态?

一句话结论

贫血模型是只含字段的数据结构,行为集中在服务层;充血模型把状态变更与不变量校验封装在实体/值对象方法中。Rust 项目常见混合形态:核心聚合充血,外围数据结构偏贫血。

概念解释

贫血模型:struct 暴露字段,服务层操作数据,规则集中但实体不封装自身一致性;充血模型:实体方法负责校验与变更,外部不能绕过规则。Rust 的私有字段与方法可落地充血模型;复杂业务规则优先收敛到聚合根与值对象。

原理流程

  1. 识别数据结构是否携带业务规则。
  2. 有不变量与状态迁移的对象封装为充血实体。
  3. 仅作数据传输的结构保持贫血 DTO。
  4. 服务层编排充血实体的方法调用。
  5. 评审时检查规则是否散落在服务层。

代码或图示

// 充血:方法内校验并变更状态
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)。聚合在状态变更后记录事件,应用用例在提交后取出并交给事件端口。订阅方按事件解耦处理后续动作;事件命名用过去时态,携带必要数据而非实体引用。

原理流程

  1. 聚合根变更时生成事件并挂在内部列表。
  2. 用例提交事务后取出未发布事件。
  3. 调用事件端口发布事件(适配器对接 MQ)。
  4. 订阅服务消费事件,执行后续处理。
  5. 失败与重试由消息链路与消费端策略处理。

代码或图示

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 异步,部分库提供同步阻塞接口。

原理流程

  1. 区分负载:IO 等待为主还是 CPU 计算为主。
  2. 评估并发连接规模与延迟要求。
  3. 核对所选数据库/消息/客户端库的异步支持成熟度。
  4. 评估团队对异步类型与并发约束的掌握程度。
  5. 原型压测对比吞吐、延迟与复杂度后定型。

代码或图示

倾向异步:
  大量并发连接、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。具体能力边界以各库当前版本为准。

原理流程

  1. 评估领域模型与表结构的映射复杂度。
  2. 评估团队对 SQL 与查询性能的把控能力。
  3. 核对库的异步支持、迁移工具与类型安全程度。
  4. 原型实现典型查询,对比开发效率与生成 SQL 质量。
  5. 把选型理由与限制记录到 ADR。

代码或图示

ORM 取向:
  模型关系清晰、CRUD 为主、希望减少手写映射

查询层取向:
  复杂查询/性能敏感、希望直接控制 SQL 与执行计划

常见误区

  • 按流行度选 ORM:未核对异步支持与复杂查询能力,后期被框架限制卡住。
  • 为减少映射手写全部裸 SQL:缺少类型校验与结构约束,查询错误推迟到运行时。

追问

  • SQLx 的编译期校验依赖什么?答:查询宏可在编译期对照数据库连接或离线校验文件检查 SQL,具体模式以 SQLx 当前版本文档为准。
  • 混合使用可行吗?答:核心仓储端口不变,不同底层实现可替换;但同一服务内不宜随意切换多套数据访问风格。

04.4.13.3-035 单体与微服务的拆分时机如何判断?

一句话结论

团队规模、模块边界清晰度、独立部署与伸缩需求、故障隔离要求达到阈值再拆微服务;早期单体按模块分层组织,避免过早分布式带来的复杂度。拆分先从仓库内 crate/模块边界开始验证。

概念解释

单体开发快、调试简单、事务本地;微服务独立部署伸缩、团队自治,但引入网络开销、分布式事务、服务发现与运维成本。Rust 服务内存占用小、启动快,单体可承载更大规模;拆分信号是模块间耦合下降、部署节奏冲突、资源需求差异显著。

原理流程

  1. 评估团队人数与沟通成本。
  2. 检查模块边界是否清晰、是否可独立演进。
  3. 看部署频率、伸缩需求与故障隔离要求是否分化。
  4. 先在单体内按 crate/模块划清边界,验证依赖方向。
  5. 边界稳定后再按业务域拆分服务,逐步迁移。

代码或图示

倾向保持单体:
  团队小、业务早期、模块耦合高、事务一致性要求强

倾向拆分:
  模块边界稳定、独立伸缩/部署、团队自治、故障域隔离

常见误区

  • 为「架构先进」过早拆微服务:分布式问题先于业务复杂度出现,运维负担压垮团队。
  • 单体内部不做分层:拆分时才发现模块耦合,无法干净切出服务。

追问

  • 拆分第一步做什么?答:在单体内抽出边界清晰的模块/crate,明确端口与数据归属,再考虑独立部署。
  • 微服务拆分按什么边界?答:按业务域与一致性边界,避免按技术层拆;数据归属随服务一起切分。

04.4.13.3-036 事件驱动与请求驱动的架构如何取舍?

一句话结论

请求驱动同步调用链路清晰、一致性直观;事件驱动解耦生产者消费者、支持削峰与异步扩展,但增加最终一致、重试与可观测复杂度。取舍看耦合需求、实时性与异步容忍度。

概念解释

请求驱动:调用方同步等待响应,链路短、排障直接。事件驱动:生产者发布事实事件,消费者按需订阅,双方不直接依赖。Rust 项目中事件常经 MQ(Kafka/RabbitMQ/NATS)投递;后台任务与通知类场景适合事件化,核心交易链路可保持请求驱动。

原理流程

  1. 梳理交互场景:强同步返回还是异步后续处理。
  2. 评估解耦收益:多个下游是否需要订阅同一事实。
  3. 检查对最终一致、重试幂等的接受程度。
  4. 事件链路补充幂等、重试、死信与追踪上下文。
  5. 混合架构:核心链路请求驱动,扩展动作事件驱动。

代码或图示

请求驱动:
  即时返回结果、链路简单、强一致事务

事件驱动:
  下游解耦、削峰填谷、异步通知/归档/衍生计算

常见误区

  • 所有交互都走事件:同步场景被异步化,响应延迟与一致性问题上升。
  • 事件消费不做幂等:重试导致重复处理,状态重复变更。

追问

  • 事件驱动如何保证不丢消息?答:发布确认、持久化、消费重试与死信队列配合;关键链路用 outbox 保证本地事务与事件一致。
  • 如何追踪跨事件链路?答:事件携带追踪上下文,日志与指标按事件类型与消费者维度关联。

04.4.13.3-037 团队规模与可维护性如何影响模块边界设计?

一句话结论

小团队可接受较粗模块与简单分层;团队增大、并行开发增多后,需要清晰 crate 边界、明确所有权与接口约定,减少合并冲突与跨模块沟通。边界成本随规模变化,设计应匹配当前团队而非假想规模。

概念解释

模块边界同时是代码边界与协作边界:多人并行修改同一 crate 容易冲突,按业务域拆分可减少耦合。可维护性指标包括定位改动范围、理解依赖方向、新人上手成本。团队扩张时先补文档与接口约定,再细化物理边界。

原理流程

  1. 统计团队人数与并行开发模块。
  2. 识别高频冲突的目录与 crate。
  3. 按业务域划分所有权与接口边界。
  4. 接口变更走评审,内部实现可自由重构。
  5. 定期复盘模块边界是否阻碍或帮助协作。

代码或图示

小团队:单 crate 内模块分层,约定清楚即可
大团队:按域拆 crate,明确公开 API、评审流程与测试归属

常见误区

  • 团队还小就设计细粒度边界:编排成本超过协作收益。
  • 团队扩大后仍共享大 crate:并行改动互相阻塞,合并冲突频繁。

追问

  • 模块所有权怎么落实?答:目录/crate 归属明确团队,接口变更需所属方评审,文档记录负责人。
  • 边界过多如何发现?答:改动需要跨多个 crate 同步修改、编译链路长,说明边界划细或方向错误。

04.4.13.3-038 老模块迁移到新架构时如何做并存策略?

一句话结论

迁移按模块逐步替换:先在新架构内实现对应能力,通过端口适配旧调用,灰度切换流量,验证稳定后下线旧代码;不做一次性重写,新旧在过渡期并存且边界清晰。

概念解释

大爆炸式重写风险高:周期长、期间两边都要维护。增量迁移保留旧系统可用,新模块按边界切入。Rust 项目可先用 crate/模块包裹旧逻辑,逐步把实现替换为新架构;数据与接口兼容期内双写或适配。

原理流程

  1. 划定迁移边界与优先级,选低风险模块先行。
  2. 新架构实现端口,适配层对接旧调用方。
  3. 流量按灰度切换到新实现,对比行为与指标。
  4. 稳定后移除旧实现与适配代码。
  5. 记录迁移顺序与回退路径。

代码或图示

并存阶段:
  旧模块 → 适配端口 → 新实现
  灰度流量 → 新实现;其余 → 旧模块
  验证通过 → 移除旧模块与适配层

常见误区

  • 一次性重写:交付周期内旧功能继续演进,重写完成时已落后。
  • 新旧边界不清:调用关系混杂,无法判断哪段代码可下线。

追问

  • 数据层如何并存?答:读旧库、写新库或双写过渡,按一致性要求选择迁移策略;数据回填与校验纳入计划。
  • 迁移期间如何防止旧代码继续扩大?答:新功能落在新架构,旧模块只修必要缺陷,评审控制增量。

04.4.13.3-039 微服务间通信选 gRPC 还是 HTTP JSON?

一句话结论

内部服务间高性能、强契约通信选 gRPC(基于 HTTP/2、Protobuf、代码生成);对外开放接口、浏览器直连或简单集成场景用 HTTP JSON。选型看调用方类型、性能要求与契约治理成熟度。

概念解释

gRPC 用 Protobuf 定义契约,双向流与压缩二进制,适合内部低延迟调用;HTTP JSON 可读性好、无生成链、跨语言门槛低。Rust 生态 gRPC 常用 tonic,HTTP 框架按服务选型。契约演进、错误模型与消息大小都影响选择。

原理流程

  1. 区分调用方:内部服务还是外部/浏览器。
  2. 评估性能、消息体积与流式需求。
  3. 核对团队 Protobuf/代码生成维护能力。
  4. 设计契约与错误模型,确认版本兼容策略。
  5. 原型对比序列化体积、延迟与开发体验。

代码或图示

gRPC:
  内部服务、高性能、强契约、流式调用、Protobuf  schema

HTTP JSON:
  开放接口、简单集成、可读性优先、无生成链

常见误区

  • 内部调用也用 HTTP JSON 大报文:序列化与传输开销累积,接口契约靠文档约定易漂移。
  • 对外浏览器接口强推 gRPC:浏览器与网关支持成本高,除非有专门适配层。

追问

  • gRPC 契约如何演进?答:Protobuf 字段编号与规则保持兼容,新增字段可选,不修改既有字段语义;具体规则以 Protobuf 兼容性规范为准。
  • Rust gRPC 库现状?答:tonic 是常见选择,配套 Protobuf 代码生成;版本与能力以当前文档为准。

04.4.13.3-040 数据库共享与服务独立库如何取舍?

一句话结论

单体或紧耦合模块可共享数据库;微服务按业务域独立数据库,数据归属随服务边界。共享库降低初期成本但形成耦合,独立库保障自治与演进,但跨库查询与一致性需要额外方案。

概念解释

数据库共享时表结构被多服务依赖,schema 变更互相牵制;独立库让服务自治,存储选型按负载决定。跨服务数据通过 API 或事件获取,不直接读他库。拆分初期可先共享库、按域划分表,边界稳定后再切分独立实例。

原理流程

  1. 按业务域梳理数据归属与使用关系。
  2. 紧耦合、同事务边界内的数据共享库。
  3. 服务自治边界明确后,独立数据库实例。
  4. 跨服务数据走接口/事件,避免直连他库表。
  5. 迁移期安排 schema 分离与数据校验。

代码或图示

共享数据库:
  单体、模块紧耦合、本地事务一致、团队小

独立数据库:
  服务自治、独立伸缩/备份、存储选型自由
  跨服务数据:API / 事件 / 只读投影

常见误区

  • 拆了服务仍共享表:服务名义独立,数据库耦合依旧,schema 变更互相阻塞。
  • 独立库后跨服务 join 复制数据:未设计投影与缓存,查询链路混乱。

追问

  • 跨服务一致性怎么处理?答:最终一致 + 事件/补偿,关键业务设计幂等与对账;不追求跨库本地事务。
  • 独立库初期成本是什么?答:数据访问层重复、迁移与备份复杂度上升,需要明确服务边界再切分。

04.4.13.3-041 缓存应该放在架构的哪一层?

一句话结论

缓存作为 infrastructure 适配器实现端口,位于应用层之下:用例通过缓存端口读写,具体 Redis/本地缓存实现可替换;缓存策略(失效、一致性)在架构层定义,不散落于 handler。

概念解释

缓存是技术实现,应挂在端口之后:核心层定义缓存语义(取/存/失效),外层对接 Redis 或本地内存缓存。分层缓存(本地 + 分布式)与穿透/击穿/雪崩策略在适配器与配置层处理。缓存不改变业务规则,只优化读取性能。

原理流程

  1. 内层定义缓存端口 trait(get/set/invalidate)。
  2. 用例按业务需要调用缓存端口。
  3. infrastructure 实现 Redis 或本地缓存适配器。
  4. 失效策略随领域事件或写操作触发。
  5. 监控命中率与一致性问题,调优策略。

代码或图示

application → CachePort trait
infrastructure → RedisCache / LocalCache 适配器
策略:失效时机、TTL、空值缓存、击穿保护

常见误区

  • handler 里直接操作 Redis 客户端:缓存实现泄漏到接口层,无法替换与测试。
  • 缓存与数据库一致性无策略:更新后脏数据长期驻留,读到过期结果。

追问

  • 本地缓存与分布式缓存怎么配合?答:热点数据本地缓存降延迟,共享数据放分布式缓存;两层 TTL 与失效事件协调,具体方案按一致性要求设计。
  • 缓存端口放 domain 还是 application?答:属于应用编排使用的技术端口,通常在 application 定义,domain 纯规则不依赖缓存概念。

04.4.13.3-042 后台任务与主服务应该同进程部署还是独立服务?

一句话结论

轻量定时任务与短队列消费者可同进程隔离线程/任务运行;重负载、需要独立伸缩或故障隔离的后台工作拆成独立部署单元。Rust 单进程资源占用低,但任务堆积与故障会影响主服务时应分离。

概念解释

同进程部署省运维、共享配置与连接池,但后台任务占用运行时资源,异常可能拖垮主服务;独立服务可按任务负载单独伸缩、独立发布与故障隔离。划分依据是资源消耗、延迟敏感度、故障隔离要求与团队运维能力。

原理流程

  1. 梳理后台任务类型:定时、队列消费、批处理。
  2. 评估资源占用与对请求路径的影响。
  3. 低负载任务纳入主服务隔离任务池。
  4. 高负载/敏感任务拆独立二进制与部署单元。
  5. 共享逻辑抽库 crate,装配各自独立。

代码或图示

同进程:
  定时刷新缓存、轻量通知、低频批处理
  → 独立任务线程池,不阻塞异步 worker

独立部署:
  高吞吐消费者、重批处理、需要独立伸缩/故障隔离
  → 独立二进制 + 独立副本与资源配额

常见误区

  • 重队列消费者与 Web 服务同进程:任务堆积占满线程,接口延迟恶化。
  • 所有后台逻辑都拆独立服务:部署单元增多,配置与监控成本超过收益。

追问

  • 同进程后台任务如何隔离?答:阻塞任务放专门线程池,异步任务限并发;连接池与主服务按需分配,避免互相抢占。
  • 独立服务共享什么?答:共享领域与应用库 crate、契约 crate,配置与连接池各自装配。

04.4.13.3-043 技术选型时除功能外,非功能因素如何评估?

一句话结论

内存占用、启动速度、静态部署能力、二进制体积、依赖安全与可观测性都是选型维度;Rust 在内存与启动速度上有优势,但要核对工具链成熟度、生态库覆盖与团队学习成本。

概念解释

功能满足只是门槛,生产环境还要看:常驻内存、冷启动延迟、镜像与产物体积、依赖漏洞面、日志指标追踪接入、跨平台构建。非功能因素按部署形态加权:Serverless 看重启动速度与体积,长驻服务看重内存稳定性与运维成熟度。

原理流程

  1. 列出部署形态与运行约束(资源配额、启动时限)。
  2. 评估候选方案的内存、CPU、体积与启动表现。
  3. 核对依赖安全、许可证与维护活跃度。
  4. 检查观测、测试与调试工具链是否齐备。
  5. 原型实测关键指标,记录取舍到选型文档。

代码或图示

非功能清单:
  内存占用 / 启动速度 / 二进制体积
  依赖漏洞面 / 许可证 / 维护活跃度
  日志指标追踪 / 测试工具 / 跨平台构建

常见误区

  • 只对比 API 功能:上线后才发现内存或启动不满足部署约束。
  • 忽视团队学习成本:选型先进但落地慢,问题排查依赖外部经验。

追问

  • Rust 静态部署优势体现在哪?答:静态链接减少运行时系统库依赖,镜像精简、环境一致性好;具体链接方式按目标平台选择。
  • 如何量化非功能指标?答:压测常驻 RSS、冷启动耗时、产物大小与依赖数量,形成基线对比候选方案。

04.4.13.3-044 技术债如何识别与安排重构节奏?

一句话结论

技术债来自绕过分层、重复代码、类型模糊与缺失测试;识别靠评审、复杂度信号与故障复盘,重构按风险与收益排期,穿插在功能迭代中进行,不积累成一次性大重写。

概念解释

技术债有利息:耦合越高改动越慢、故障越多。识别信号包括:改动一处要碰多个 crate、错误类型不匹配、测试难以编写、评审反复指出同类问题。重构节奏应小步可控:先补测试与边界,再抽模块/拆 crate,每步可验证可回退。

原理流程

  1. 评审与复盘记录债务类型与影响面。
  2. 用依赖图、重复代码、测试覆盖等信号量化优先级。
  3. 高风险高收益项排入迭代,先补回归测试。
  4. 小步重构:抽类型、定端口、拆 crate,逐步推进。
  5. 定期复盘债务清单,避免新债叠加。

代码或图示

债务信号:
  跨层依赖、重复逻辑、错误类型松散、测试难写
  改动范围随需求持续扩大

节奏:
  补测试 → 定边界 → 抽模块 → 拆 crate → 验证回归

常见误区

  • 债务堆积后安排大重写:周期内业务继续演进,重写易失败。
  • 为重构打断所有功能交付:重构与需求按比例穿插,保持可发布状态。

追问

  • 如何区分合理抽象与过度设计?答:有明确复用或边界隔离需求才抽象;小项目保留直接实现,债务在边界模糊出现时再还。
  • 重构前必须有什么?答:覆盖现有行为的回归测试或可观察的行为基线,否则重构无法验证正确性。

04.4.13.3-045 模块与 crate 命名有哪些约定?

一句话结论

目录与 crate 用小写连字符,按业务域或架构层命名;模块名表达职责而非实现细节,内部模块用层级前缀区分。命名与依赖方向一致,避免同义多名导致查找困难。

概念解释

Rust crate 名用 kebab-case,模块名用 snake_case。架构分层 crate 可带层前缀(domain/application/infrastructure/api),业务域 crate 按域命名。命名稳定后作为导航入口,避免出现 utils、common 这类职责模糊的模块。

原理流程

  1. crate 名按架构层或业务域确定,小写连字符。
  2. 模块名蛇形小写,表达对外职责。
  3. 内部实现模块加层级前缀,与公开模块区分。
  4. 跨 crate 引用路径与命名保持一致。
  5. 评审检查命名是否职责清晰、无重复同义。

代码或图示

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 与顶层流程。边界处转换避免松散错误穿透到核心。

原理流程

  1. 各层定义本层错误枚举,派生 thiserror::Error。
  2. 跨层错误用 #[from] 聚合,保留来源。
  3. 应用顶层用 anyhow 收尾,日志记录错误链。
  4. api 层匹配结构化错误,映射状态码。
  5. 评审检查错误类型是否越界泄漏。

代码或图示

#[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 实现在外层装配。业务规则层不打印框架细节,接口与适配器层记录外部调用结果。

原理流程

  1. 定义日志字段规范:请求 ID、用户标识、资源类型与 ID。
  2. 核心层依赖日志抽象,外层注入 tracing 实现。
  3. 关键用例节点记 info,异常路径记 warn/error。
  4. 结构化字段便于检索,敏感值按脱敏规则处理。
  5. 评审检查日志级别与字段一致性。

代码或图示

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 文档回答「做什么、怎么用、何时失败」;内部代码注释解释「为什么这样做」,不复述代码。文档与代码同仓库维护,评审把文档更新作为公开变更的一部分。

原理流程

  1. pub 类型/方法补 /// 注释与必要示例。
  2. 说明入参约束、返回结果与错误场景。
  3. 内部复杂逻辑注释设计意图与边界。
  4. cargo doc 构建检查文档可生成。
  5. 公开 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 固定上下文:面临的问题、评估过的选项、选择理由、放弃的代价与后续影响。格式保持轻量:背景、备选、决策、后果、状态,编号可追溯。

原理流程

  1. 识别影响分层、技术选型、通信方式的决策。
  2. 记录问题背景与约束条件。
  3. 列出备选方案与取舍依据。
  4. 写明最终决策与预期/实际后果。
  5. 决策被推翻时更新状态与新 ADR,不删除历史记录。

代码或图示

ADR 结构:
  标题 / 状态(提议、接受、废弃、替代)
  背景与约束
  备选方案对比
  决策结论
  后果与后续行动

常见误区

  • 只写结论不记理由:后人无法判断结论是否仍适用。
  • ADR 写完不维护:决策条件变化后记录与现状脱节。

追问

  • 哪些决策需要 ADR?答:技术栈选型、分层边界、服务拆分、通信协议、存储方案等长期影响项;琐碎实现选择不必记录。
  • ADR 放哪里?答:仓库文档目录编号存放,与代码同版本演进;索引链接到各篇决策。

04.4.13.3-050 配置项与常量在代码中放在什么位置?

一句话结论

环境相关、可调整的值放配置结构体由启动注入;编译期固定、业务不变量用常量或静态值放在对应模块。配置从外层装配传入,核心层不读取环境变量。

概念解释

配置与常量边界:随环境/部署变化的是配置(地址、阈值、开关),不随环境变化的业务规则值是常量(上限、状态名、单位)。配置按架构层分组挂载,常量归属使用它的领域模块。核心层不直接 std::env::var 读取。

原理流程

  1. 判断值是否随环境变化:变化走配置,固定走常量。
  2. 配置结构体按层分组,组合根注入。
  3. 常量定义在使用它的模块,命名大写蛇形。
  4. 业务不变量常量归 domain,技术默认值归 infrastructure。
  5. 评审检查核心层无环境变量直读。

代码或图示

// 领域常量
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 测试类型:单元测试贴近代码、运行快、覆盖分支;集成测试验证公开接口与协作;端到端验证真实部署链路。领域规则靠单元测试,端口替身测试用例,适配器测试对接真实或替身依赖。

原理流程

  1. 领域模型与规则写内联单元测试。
  2. 用例层用 mock 端口验证编排与错误分支。
  3. tests/ 目录集成测试走公开 API。
  4. 关键链路补充端到端或容器化集成测试。
  5. 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 门禁与评审互补。

原理流程

  1. 定义各 crate 允许的外部依赖与内部方向。
  2. 编写脚本解析清单,核对允许列表。
  3. CI 流水线在测试前运行架构检查。
  4. 破坏规则返回非零退出,阻断合并。
  5. 合理例外登记文档,定期收紧规则。

代码或图示

CI 门禁顺序:
  fmt → clippy → 架构依赖检查 → test → deny/审计

常见误区

  • 架构规则只在评审口头把关:演进后边界模糊,难以回溯检查。
  • 规则不维护:新基础库未纳入白名单,检查误报后被整体关闭。

追问

  • 脚本检查什么粒度?答:crate 级依赖存在性与方向;类型级逆向引用可在评审与 cargo tree 输出中复核。
  • cargo-deny 能做架构方向检查吗?答:deny 规则覆盖来源、许可证、bans 等;分层方向通常需要项目自定义脚本配合。

04.4.13.3-053 代码评审在 Rust 架构层面关注什么?

一句话结论

评审关注依赖方向是否越界、错误类型是否分层、并发类型是否满足 Send/Sync、所有权边界是否清晰,以及公共 API 面是否失控;功能正确之外核对架构约定。

概念解释

Rust 评审除业务逻辑外,重点看类型与并发约束:跨层类型泄漏、松散错误穿透、不必要的克隆与引用、共享状态同步安全性。架构类问题在编译期部分可发现,评审补充设计层面的边界判断。

原理流程

  1. 核对改动 crate 的依赖方向与类型流向。
  2. 检查错误是否在边界转换,未泄漏驱动类型。
  3. 审查并发状态:共享类型 Send + Sync,锁粒度合理。
  4. 检查公开可见性与文档是否匹配预期。
  5. 记录架构债务项,排入后续重构。

代码或图示

评审清单:
  依赖方向 / 类型边界 / 错误分层
  Send + Sync / 锁与克隆 / 可见性与文档

常见误区

  • 只看业务功能是否跑通:架构越界在后续迭代累积成大泥球。
  • 评审纠结风格细节:格式由 rustfmt 统一,评审聚焦设计与边界。

追问

  • 所有权问题在评审怎么判断?答:看借用范围、克隆必要性、可变引用唯一性;&mut self 方法是否暴露了不该有的写权限。
  • 评审发现分层问题怎么处理?答:当前 PR 最小修复或登记债务项;严重逆向依赖优先在本 PR 纠正,避免带病合并。

04.4.13.3-054 公开 API 版本兼容如何演进?

一句话结论

公开类型与方法签名保持向后兼容:新增可选字段与方法优先,不删除既有签名,破坏变更按版本标记并提供迁移路径;Rust 语义化版本与弃用属性辅助演进。

概念解释

被其他 crate 或服务依赖的接口是契约:字段删除、类型改签名、语义反转都会破坏调用方。演进规则:新增能力用可选成员,旧实现保留;废弃方法先标记弃用并给过渡期;破坏性变更提升主版本并在文档说明迁移步骤。

原理流程

  1. 识别被外部依赖的公开 API 面。
  2. 新增需求以可选字段/新方法扩展,不改既有签名。
  3. 旧接口标记弃用,文档指向替代项。
  4. 过渡期后随主版本移除旧接口。
  5. 变更记录在发布说明与 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 门禁执行。

原理流程

  1. 列出各层允许引入的依赖类别。
  2. 核心层新增依赖需评审必要性。
  3. 根 workspace 统一公共依赖版本。
  4. 定期检查重复版本、漏洞公告与许可证。
  5. 移除未使用依赖,收敛依赖面。

代码或图示

domain:    最小依赖(类型、错误、基础工具)
application:domain + 端口抽象
infra/api: 数据库、消息、框架、客户端库

常见误区

  • 核心图方便引入重依赖:规则层被技术库绑架,编译与测试变重。
  • 依赖只增不减:传递依赖累积,漏洞与许可证风险扩大。

追问

  • 如何发现未使用依赖?答:结合 cargo 依赖分析工具与编译影响评估;具体工具链以当前 Rust 生态可用情况为准。
  • 许可证审查关注什么?答:避免与项目分发方式冲突的许可证,记录依赖许可证清单。

04.4.13.3-056 跨 crate 共享的错误与类型应该放在哪里?

一句话结论

被多层复用的基础类型、共享错误枚举放独立契约/共享 crate;仅单层使用的类型留在本层。共享 crate 保持轻量,不反向依赖业务实现。

概念解释

类型放置原则按复用范围:domain 模型归 domain,接口 DTO 归契约,跨层通用错误与值对象放共享 crate。避免类型在多个 crate 重复定义导致不兼容;共享 crate 被依赖时不能再依赖业务外层,防止成环。

原理流程

  1. 统计类型被哪些 crate 引用。
  2. 单层使用:留在所属层 crate。
  3. 多层复用:提取到共享/契约 crate。
  4. 检查共享 crate 依赖方向,不引入业务实现。
  5. 公开类型补文档与测试。

代码或图示

shared/contracts crate:
  共享错误码、ID 类型、基础值对象、对外 DTO

不放入共享:
  某层私有映射、适配器内部结构、业务编排类型

常见误区

  • 共享类型散落在各层重复定义:同名不同结构,跨层传递出错。
  • 共享 crate 引入框架依赖:所有依赖方被迫传递引入该框架。

追问

  • 共享错误枚举与层错误什么关系?答:共享错误码表达通用语义,各层错误可包装它;层特定错误留在本层枚举。
  • ID 类型为什么要共享?答:跨层传递需要同一类型,避免 String 到处混用导致格式错误。

04.4.13.3-057 运行时特性开关如何与代码分层配合?

一句话结论

开关配置从外层注入应用层,用例按开关分支控制功能路径;核心规则不读取环境变量,开关判断集中在编排层。编译期 feature 与运行时开关分层使用,互不替代。

概念解释

功能开关服务于灰度与实验:新功能路径在代码中已编译存在,配置决定是否启用。分层上配置进入 application 用例,domain 规则不感知开关;开关组合要有测试覆盖,避免分支不可验证。开关下线后清理对应代码。

原理流程

  1. 配置结构体定义功能开关字段。
  2. 组合根注入配置到应用服务。
  3. 用例按开关选择新/旧路径。
  4. 测试覆盖开关开与关两种分支。
  5. 功能稳定后移除开关与旧路径。

代码或图示

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 接口配置、数据库/缓存/消息基础设施配置、观测配置;应用层只接收本层需要的子配置,核心规则不持有部署配置。

概念解释

配置树与模块树对应有助于定位:哪个模块用哪组配置一目了然。分组结构体在组合根装配,分发给对应服务;避免一个全局配置对象到处传递。敏感配置单独分组并脱敏处理。

原理流程

  1. 按架构域识别配置分组。
  2. 定义子配置结构体并派生反序列化。
  3. 根配置组合各组,启动期校验。
  4. 装配时子配置注入对应模块。
  5. 配置分组随模块边界同步调整。

代码或图示

#[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,装配可替换。

原理流程

  1. 二进制入口加载配置并校验。
  2. 创建连接池、外部客户端等基础设施。
  3. 构造适配器并实现端口 trait。
  4. 装配应用服务,注册路由与后台任务。
  5. 启动运行时进入服务循环。

代码或图示

// 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" 之类分支。环境只影响组合根装配。

概念解释

业务代码判断环境名会导致测试覆盖困难、分支散落。正确做法:环境专属值走配置,环境专属实现走不同适配器,业务用例调用统一端口。测试注入替身实现,生产装配真实实现,同一套业务逻辑服务多环境。

原理流程

  1. 识别环境相关差异:地址、凭证、实现、开关。
  2. 差异值由配置注入,差异实现由适配器承担。
  3. 业务代码只依赖端口与配置字段。
  4. 组合根按环境选择适配器实现。
  5. 评审搜索业务代码中的环境名判断并移除。

代码或图示

禁止:
  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,但模块层级保持一致。

原理流程

  1. 根 workspace 声明成员 crate。
  2. domain 定义实体、值对象、领域错误。
  3. application 定义用例服务与端口 trait。
  4. infra 实现仓储与外部服务适配器。
  5. 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 是有意识的权衡。

原理流程

  1. 判断模型是否需要对外或跨层序列化。
  2. 严格分层:domain 不派生序列化属性,DTO 单独定义。
  3. 映射层完成领域模型与 DTO 互转。
  4. 确有必要时在 domain 引入 serde 并在 ADR 记录理由。
  5. 评审检查派生属性是否污染核心规则。

代码或图示

// 严格分层: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 引用,按用例流程依次调用仓储与领域服务,控制事务边界与调用顺序;编排只做流程协调,业务规则下沉到领域层,不直接操作数据库细节。

概念解释

复杂用例跨多个聚合:加载订单、校验库存、写支付记录。应用服务通过端口访问各聚合,顺序与一致性边界在用例层定义。多个仓储注入服务构造函数,测试时替换为替身。编排逻辑应可被独立测试,不依赖框架与网络。

原理流程

  1. 用例接收命令对象,参数校验在边界完成。
  2. 通过仓储端口加载所需聚合。
  3. 调用领域规则完成状态变更。
  4. 依次保存变更,纳入同一事务边界。
  5. 返回结果或结构化错误给接口层。

代码或图示

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 执行与类型映射:私有行结构不泄漏到外层;方法签名只使用核心类型。池大小、超时等配置从组合根传入,适配器不自行读取环境变量。

原理流程

  1. 构造函数接收连接池配置或现成池实例。
  2. 实现端口 trait 方法,从池获取连接。
  3. 执行查询,把行映射为领域模型。
  4. 驱动错误包装为应用错误,保留来源。
  5. 组合根在停机时随池关闭释放资源。

代码或图示

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 文档为准。

原理流程

  1. 确定端口使用泛型静态分发还是 trait object。
  2. 泛型场景:trait 方法直接声明 async fn。
  3. 动态分发场景:核对当前工具链对异步 dyn 的支持。
  4. 受限时用返回 Future 类型或 boxed future 表达。
  5. 测试替身按同一 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,模拟仓储返回、缺失、失败等场景。测试断言用例在给定输入下调用了哪些端口、产出什么结果。真实适配器另写集成测试对接外部依赖。

原理流程

  1. 定义测试替身 struct,实现端口 trait。
  2. 替身内部保存期望返回值与调用记录。
  3. 装配应用服务时注入替身。
  4. 调用用例方法,断言结果与错误分支。
  5. 校验调用顺序与参数,覆盖成功/失败/边界场景。

代码或图示

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。

原理流程

  1. 请求到达 api 层,反序列化为请求 DTO。
  2. 边界校验后转换为用例命令对象。
  3. 应用服务返回领域聚合或结果类型。
  4. api 层映射为响应 DTO,裁剪敏感字段。
  5. 序列化为响应返回。

代码或图示

// 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 层做业务不变量校验(状态迁移、余额规则、聚合一致性);两层互补,边界校验不替代规则校验。

概念解释

格式校验回答「输入是否合法可解析」,不变量校验回答「业务上是否允许」。例如邮箱格式在边界校验,账户是否允许扣款在领域校验。领域不变量封装在实体方法内,绕过边界也不能构造非法状态。

原理流程

  1. 请求 DTO 反序列化,类型与必填由 Serde 检查。
  2. api 层校验长度、格式、取值范围。
  3. 命令进入领域,实体/值对象构造与变更方法校验不变量。
  4. 违反规则返回领域错误,映射为响应状态码。
  5. 测试覆盖两层校验分支。

代码或图示

// 边界:格式与范围
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 直接操作仓储、错误类型穿透到接口、模块间逆向引用;出现这些说明分层已被绕过,需要重构纠正。

概念解释

边界腐化是渐进的:新功能图方便引入一个外部类型,随后调用链扩散。典型信号可在依赖清单、类型签名与调用关系中观察。早期发现成本低,积累后核心层与实现层深度耦合,测试与替换困难。

原理流程

  1. 审查核心 crate 依赖清单是否出现禁用技术栈。
  2. 检查核心方法签名是否返回驱动/框架类型。
  3. 追踪 handler 是否跳过用例直接访问基础设施。
  4. 核对错误类型是否在边界完成转换。
  5. 发现信号后按依赖倒置重构:接口下沉,实现外移。

代码或图示

破坏信号:
  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。

原理流程

  1. 识别跨服务/跨端复用的数据结构。
  2. 建立契约 crate 或 schema 目录。
  3. 定义消息、字段编号、枚举与错误码。
  4. 生成 Rust 类型或由 api 层引用。
  5. 消费者依赖同一契约包,版本随演进管理。

代码或图示

crates/
  contracts-proto/   Protobuf schema 与生成代码
  contracts-dto/     共享 JSON DTO 与错误枚举

常见误区

  • 契约 crate 引入业务规则或数据库依赖:共享层变重,消费者被迫传递依赖。
  • 服务端响应结构直接发给客户端却无共享定义:客户端手写结构,字段漂移难发现。

追问

  • 生成代码纳入版本管理吗?答:按工具链与 CI 策略决定;生成产物可在构建时产出,schema 必须纳入版本管理。
  • 契约版本不兼容怎么处理?答:新增可选字段保持兼容,破坏变更独立版本或新服务接口,迁移期并存。

04.4.13.3-071 大单体拆分的第一步应该做什么?

一句话结论

先在单体内按业务域抽出边界清晰的模块/crate,明确端口、数据归属与依赖方向,验证可独立演进后再拆成独立服务;不第一步就切部署与数据库。

概念解释

单体拆分失败多源于边界未清就拆部署。物理拆分前先做逻辑拆分:领域模型、用例、仓储端口按域分离,找出耦合点。逻辑边界稳定后,独立部署与数据库切分才有依据,风险可控。

原理流程

  1. 梳理业务域与现有模块耦合关系。
  2. 单体内按域提取模块/crate,定义端口。
  3. 明确各域数据归属与跨域调用方式。
  4. 验证边界内测试独立可运行。
  5. 边界稳定后再拆分服务、切分数据库与通信链路。

代码或图示

第一步:逻辑拆分
  域模块/crate + 端口 + 数据归属
第二步:部署拆分
  独立服务 + 接口/事件通信
第三步:数据拆分
  独立数据库 + 投影/对账

常见误区

  • 先拆服务再补边界:跨服务调用纠缠,分布式事务与耦合问题叠加。
  • 按技术层拆服务:表现层、数据层各自独立,业务链路被切断。

追问

  • 单体里哪些信号说明边界可拆?答:模块间只通过端口交互、数据归属明确、变更很少跨模块同步。
  • 拆分过程中旧单体怎么办?答:并行运行,新模块按灰度切入,旧逻辑逐步下线,不做一次性切换。

04.4.13.3-072 共享内核与重复代码之间如何权衡?

一句话结论

被多个域稳定复用的通用概念抽共享内核;仅表面相似、规则不同的代码保留重复,避免过早抽象把异质业务捆在一起。抽象以真实复用为前提。

概念解释

DRY 原则不等于所有相似代码合并:共享内核要求各域对概念理解一致。重复代码耦合低、独立演进;错误抽象会把差异掩盖在通用层,改动影响面扩大。判断依据是复用次数、规则一致性与变更节奏。

原理流程

  1. 识别重复出现的结构与逻辑。
  2. 判断规则是否真的一致,还是仅形式相似。
  3. 一致且多次复用:抽取共享内核/crate。
  4. 规则不同:保留各自实现,记录差异原因。
  5. 共享内核演进时评估对各域的影响。

代码或图示

倾向共享:
  同语义值对象、通用错误类型、基础工具
  多域复用、规则一致、变更同步

保留重复:
  表面相似但业务规则不同
  演进节奏不同、耦合代价高于重复

常见误区

  • 见到第二处相似就抽象:抽象点过早,第三处出现时规则已分化。
  • 共享内核不断膨胀:通用层混入特定业务,反向污染各域。

追问

  • 共享内核放哪?答:独立基础 crate 或共享类型包,依赖方向被各域单向引用,不依赖业务外层。
  • 发现错误抽象怎么拆回?答:按域复制回独立实现,再清理共享层对应部分,每步可回归验证。

04.4.13.3-073 事件总线在端口层如何抽象?

一句话结论

核心层定义事件发布端口 trait,方法接收领域事件;事件总线、MQ 生产者是 infrastructure 适配器。核心不感知总线实现,订阅处理器通过端口或外层装配注册。

概念解释

事件端口把「发布事实」与「投递机制」分离:用例只调用发布端口,具体投递到 Kafka/RabbitMQ/NATS 或内存总线由适配器决定。事件结构在核心定义,携带业务数据;失败语义与重试在适配器与消费端处理。

原理流程

  1. 核心定义领域事件枚举与事件端口 trait。
  2. 用例在状态变更后调用端口发布事件。
  3. infrastructure 适配器对接消息总线,序列化事件并投递。
  4. 同进程订阅在装配层注册处理器;跨进程由消费者订阅。
  5. 失败重试、死信与追踪在消息链路处理。

代码或图示

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。凭证与地址由组合根注入,适配器不在代码中硬编码。

原理流程

  1. 内层定义外部服务端口 trait,方法用核心类型。
  2. infrastructure 封装客户端 struct,持有 SDK 实例或 HTTP 客户端。
  3. 实现端口:构造请求、调用外部接口、映射响应。
  4. 外部错误转应用错误,超时与重试策略在适配器配置。
  5. 测试用替身端口验证用例,适配器另做集成测试。

代码或图示

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 成员结构对应。

原理流程

  1. 单元测试留在各模块源码旁。
  2. crate 集成测试写入 tests/,调用公开 API。
  3. 跨层流程测试在入口 binary crate 或 test member 装配。
  4. 共享替身、断言工具抽到测试辅助 crate。
  5. 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 验证,防止未默认路径编译失败。

原理流程

  1. 根配置声明公共依赖版本与基础 feature。
  2. 成员依赖继承 workspace 配置,追加特有 feature。
  3. 内部可选后端定义 feature 开关与默认集。
  4. CI 矩阵构建默认组合与关键可选组合。
  5. 新增 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。编译产物分层与架构分层重合,稳定在内、易变在外。

原理流程

  1. 核心 crate 依赖最小化,类型稳定。
  2. 重依赖隔离到外层 crate。
  3. 改动外层时编译范围收敛到外层及下游。
  4. 接入编译缓存复用未变化产物。
  5. 观察典型改动的重编译 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/索引说明模块职责。文档描述稳定边界与决策,不复述可变实现细节,减少同步成本。

原理流程

  1. 仓库维护架构概览:分层图、模块职责、依赖方向。
  2. 关键决策写入 ADR,编号可追溯。
  3. 变更涉及边界调整时,同 PR 更新文档。
  4. 定期复核文档与代码结构是否一致。
  5. 过期文档及时修正或归档。

代码或图示

文档组成:
  架构概览(分层、目录树、依赖方向)
  ADR(决策背景、备选、结论)
  模块 README(职责、端口、测试归属)

常见误区

  • 架构文档上线后不再维护:代码演进后文档描述旧结构,误导新人。
  • 文档复述每行代码:细节易过期,文档应保留边界与决策层信息。

追问

  • 文档更新纳入评审了吗?答:涉及分层、端口、依赖的 PR 必须核对对应文档;纯内部实现调整不必改概览。
  • 新人先看什么?答:架构概览与 ADR 理解边界和决策原因,再读 lib.rs 与模块入口。

04.4.13.3-079 选型评审记录与回退方案如何准备?

一句话结论

技术选型在评审中记录候选方案、取舍依据、风险与回退路径;接受方案后写入 ADR,预留替代实现端口,避免选型锁定后无法退回。

概念解释

选型不是一锤定音:关键技术(框架、数据库、通信协议)都应评估退出成本。评审记录备选与放弃理由,架构层用端口隔离具体实现,使替换成为换适配器而非改核心。回退方案包括数据迁移、灰度切回与兼容窗口。

原理流程

  1. 列出候选技术与非功能要求。
  2. 对比功能、性能、生态、团队成本与风险。
  3. 记录决策与未选方案的放弃原因。
  4. 设计抽象端口,隔离所选技术实现。
  5. 准备回退步骤:切换方案、数据处理、灰度与验证。

代码或图示

选型记录:
  背景约束 / 候选方案 / 对比结论
  决策 / 风险 / 回退路径
  抽象端口(实现可替换)

常见误区

  • 只记录「选了什么」,不记为什么:后续无法判断决策是否仍适用。
  • 选型实现直接渗入核心:发现不适合时替换成本极高。

追问

  • 回退方案什么时候演练?答:高风险选型在预发环境验证切换流程;数据类回退需要备份与回填方案。
  • 端口抽象成本高吗?答:初期增加接口设计,换取后续可替换性;核心业务领域尤其值得隔离。

04.4.13.3-080 新人理解这套 Rust 架构从哪里入手?

一句话结论

先读架构概览与 ADR 掌握分层与决策,再从入口 crate 的组合根看装配链路,沿 api → application → domain → infrastructure 追踪一次请求,最后读端口 trait 与适配器实现。

概念解释

理解顺序应从全局边界到局部实现:先知道各层职责与依赖方向,再看代码如何组装。组合根展示依赖如何注入,请求链路展示各层协作;端口定义是理解可替换性的关键入口。避免一上来钻适配器细节。

原理流程

  1. 阅读架构概览:分层、目录树、模块职责。
  2. 读相关 ADR:关键决策背景与约束。
  3. 从 main/组合根追踪装配:配置、适配器、服务、路由。
  4. 沿一次请求经过 api → application → domain → infra。
  5. 回到端口 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 间频繁互调、配置与测试成本上升。判断标准是当前复杂度,而不是预设未来规模。

原理流程

  1. 评估项目规模:功能数量、团队人数、复用需求。
  2. 简单项目:单 crate 内模块分层,保持直接实现。
  3. 识别稳定边界后再逐步提取 crate。
  4. 避免为尚不存在的复用设计抽象。
  5. 复杂度上升时按 ADR 记录架构演进。

代码或图示

小项目形态:
  单 crate + 模块目录
  直接实现,少 trait 包装

触发拆分信号:
  模块边界稳定、多入口复用、并行开发冲突、规则复杂

常见误区

  • 照搬大型项目结构:样板代码多于业务代码,新人上手慢。
  • 抽象点过早锁定:后续业务分化时错误抽象难以回退。

追问

  • 怎么判断分层是否过重?答:改动一个小功能要碰多个 crate 与 trait,测试与编译成本明显高于直接实现。
  • 简化后还能演进吗?答:模块分层保留边界意图,规模增长时提取 crate 有清晰路径。

04.4.13.3-082 发现逆向依赖后如何重构:从 domain 移除外层依赖?

一句话结论

先在核心层定义需要的端口 trait 与核心类型,把外层类型映射隔离到适配器;移除 domain 对框架/驱动的依赖,再让 infrastructure 实现端口。每步保持编译通过与测试回归。

概念解释

逆向依赖重构按依赖倒置方向反转:外部概念下沉为核心抽象,实现留在外层。步骤是识别泄漏类型 → 定义端口与核心模型 → 边界映射转换 → 移除核心依赖 → 验证编译与测试。不宜一次性大改,分小步提交。

原理流程

  1. 扫描 domain 清单与源码,列出禁用外部类型。
  2. 在核心定义端口 trait,方法签名用核心类型。
  3. 在 infrastructure 实现适配器,完成外部类型到核心类型映射。
  4. 移除 domain 中的外部依赖与类型引用。
  5. 跑测试与编译检查,确认边界恢复单向。

代码或图示

重构前:domain → sqlx 行类型
重构后:
  domain 定义 OrderRepository trait
  infra PgOrderRepository 实现 trait
  行映射留在 infra,domain 只持有 Order 模型

常见误区

  • 直接删除核心依赖不提供替代抽象:编译断裂,业务逻辑无处安放。
  • 重构同时改业务行为:边界修复与功能变更混杂,回归风险高。

追问

  • 重构期间新功能怎么安排?答:新功能按新边界开发,旧逆向依赖逐步清理,不在旧结构上增量扩大。
  • 如何确认重构彻底?答:核心 crate 清单无禁用依赖,源码无外部类型名,CI 依赖规则通过。

04.4.13.3-083 架构演进过程中 crate 何时合并、何时拆分?

一句话结论

职责频繁互调、边界松散的 crate 合并回模块;业务域独立、变更节奏分离、需要复用或独立伸缩的 crate 拆分。合并与拆分都以依赖方向和变更频率为依据,随规模演进调整。

概念解释

架构边界不是一次定死:早期过细拆分应合并,规模增长后按域拆分。合并信号是跨 crate 调用频繁、共享类型多、编译反复联动;拆分信号是模块稳定独立、多入口复用、并行开发与部署需求分化。调整时先逻辑边界后物理 crate。

原理流程

  1. 观察各 crate 调用频率、共享类型与变更节奏。
  2. 过细边界:合并为单 crate 内模块,保留分层目录。
  3. 独立域:提取 crate,定义端口与数据归属。
  4. 每次调整更新依赖图、文档与测试组织。
  5. 复盘调整后编译、协作与替换成本是否改善。

代码或图示

倾向合并:
  高频互调 / 共享类型多 / 编译联动 / 边界模糊

倾向拆分:
  域独立 / 变更分离 / 多入口复用 / 独立伸缩

常见误区

  • crate 结构一旦定下不再调整:规模变化后边界与实际协作脱节。
  • 凭直觉频繁拆并:每次调整成本高,应基于调用与变更数据判断。

追问

  • 合并拆分先动物理还是逻辑?答:先在模块层面梳理职责与依赖,稳定后再调整 crate 边界,避免来回折腾。
  • 调整后如何验证收益?答:看改动范围、编译耗时、测试独立性与协作冲突是否改善,记录到架构复盘。