rust-domain-boundaries

Rust 领域边界

使用此技能，避免无效状态进入 Rust 服务内部。在边界处一次性解析原始输入，将已验证的值存储为范围明确的领域类型，并让未经校验的构造难以实现。

核心工作流

1. 找出原始输入边界：HTTP 负载、路径／查询参数、配置文件、环境变量、数据库行、队列和 CLI 标志。
2. 将传输 DTO 与领域类型分开。让 serde 反序列化传入的数据结构，然后将 DTO 字段转换为经过验证的领域值。
3. 对受规则约束的值，用小型类型替代基本字符串类型：电子邮件地址、用户名、密码、订阅者姓名、slug、租户 ID、幂等键，以及类似货币或时长的值。
4. 为领域类型设置私有字段和智能构造函数。避免使用未经校验的 pub 字段，或用于可失败转换的 impl From<String>。
5. 返回有类型的验证错误，将其映射为实用的 HTTP 响应，同时不泄露内部细节。
6. 明确处理数据库和外部 API 的映射。在最终持久化或序列化边界处再转换为原始字符串。
7. 直接测试不变量。覆盖有效示例、格式错误的输入、长度边界、规范化规则和往返转换。

类型设计规则

• 对可失败的解析，优先使用 TryFrom<String>、TryFrom<&str> 或 FromStr。
• 除非性能分析证明必须借用，否则应存储自有值。
• 实现 AsRef<str> 或具名访问器，以便只读访问。
• 仅当格式化后的值可安全用于日志、错误消息和 UI 时，才实现 Display。
• 除非调试输出经过脱敏，否则避免为包含机密的值派生 Debug。
• 在测试中明确呈现规范化行为：去除空格、转换为小写、Unicode 处理和规范化。

请求边界模式

反序列化为请求结构，然后构造命令：

#[derive(serde::Deserialize)]
pub struct SubscribeRequest {
    email: String,
    name: String,
}

pub struct SubscribeCommand {
    pub email: EmailAddress,
    pub name: SubscriberName,
}

impl TryFrom<SubscribeRequest> for SubscribeCommand {
    type Error = SubscribeValidationError;

    fn try_from(value: SubscribeRequest) -> Result<Self, Self::Error> {
        Ok(Self {
            email: EmailAddress::parse(value.email)?,
            name: SubscriberName::parse(value.name)?,
        })
    }
}

处理程序应在业务逻辑或数据库代码运行前拒绝无效输入。如果验证需要数据库状态，应将纯解析与唯一性或授权检查分开。

测试

当不变量有许多边缘情况，或者 AI Agent 可能通过仅测试示例而漏掉无效输入时，请阅读 references/property-testing.md。

新领域类型的最低测试要求：

• 接受符合实际情况的有效值。
• 拒绝空输入和仅包含空白字符的输入。
• 当存储或产品规则设有限制时，拒绝过长的输入。
• 拒绝格式不符合要求的输入。
• 按测试文档所述，准确保留或规范化值。
• 当类型跨越 serde 或 SQL 映射边界时，测试往返转换。

参考文件

• references/newtype-patterns.md：Rust newtype 的构造函数、trait、serde 和持久化模式。
• references/property-testing.md：解析器和领域构造函数的属性测试策略。