rust-database

Rust 数据库层交付

交付一个兼容迁移、支持回滚且可观测的数据访问层，并以数据库的实际方言、架构和事务语义为依据。不要将 HTTP 处理程序当作仓储；不要使用模拟来验证真实数据库行为。

确认数据库契约

修改之前：

• 收集数据库产品、确切版本、扩展、部署拓扑以及读写节点的信息；
• 收集当前架构约束、索引、触发器、视图和迁移历史；
• 确认 SQLx、Diesel、SeaORM（或其他数据访问栈）的锁定版本及其功能；
• 确定 Rust 工具链/MSRV、同步或异步执行模型；
• 明确连接数限制、实例数量、超时、事务隔离级别和一致性要求；
• 定义数据量特征、热点查询模式、分页策略、保留策略和归档需求；
• 记录凭证来源、TLS 配置、租户边界、行级权限和审计要求；
• 确认部署是否允许停机、双写、回填或破坏性 DDL 操作。

无法访问真实数据库时，应区分“代码/离线元数据验证”和“真实方言验证”。报告时不要混淆这两种方法。

工作流

1. 建立当前基线

rustc --version --verbose
cargo metadata --format-version 1
cargo tree -e features
cargo test --all-targets

定位连接初始化、连接池配置、仓储实现、查询、迁移、测试夹具和 CI 数据库连接。执行现有的迁移状态/检查命令；未经明确授权，不要运行会修改共享数据库的操作。

2. 保留现有数据访问栈

不要仅因偏好 SQLx、Diesel 或 SeaORM 而重写。根据当前代码库和任务需求选择合适的数据访问栈：

• SQLx：需要直接访问 SQL、异步查询和可选的编译期查询验证；
• Diesel：使用类型化 DSL 查询、同步连接或现有 Diesel 架构；
• SeaORM：使用异步 ORM/实体模型及相应的迁移系统；
• 原生数据库驱动：仅用于协议或功能不支持通用数据访问层的情况，但这会扩大维护和安全审查范围。

具体选择标准和类型边界记录在 数据访问栈与类型 中。所有 API 都必须与 Cargo.lock 中版本对应的文档保持一致，避免将最新示例直接用于旧版项目。

3. 让架构约束保证事实

• 将主键、唯一性约束、外键、非空检查和检查约束定义为由数据库保证的不可变不变量；
• Rust 类型表达领域语义，但无法取代数据库提供的跨进程并发保障；
• 明确指定整数宽度、小数精度、时区、UUID、JSON 格式和可空性映射；
• 所有查询都使用绑定参数。动态标识符或排序字段只能通过允许列表和类型映射来指定，不能将其当作普通绑定值并误以为安全；
• 只选择必要的列，避免依赖不稳定的 SELECT * 布局；
• 数据量较大时，优先采用稳定排序策略和基于键集的分页，而不是不受限制的偏移量操作。

4. 在更改代码前设计迁移

对于每项架构变更，请记录：

1. 前向 DDL 语句；
2. 应用的新旧版本之间的兼容窗口；
3. 数据回填方法、批次大小和回滚点；
4. 索引构建风险和锁竞争影响；
5. 回滚或前向恢复策略；
6. 验证查询、监控指标和终止条件。

采用以下顺序：扩展 → 回填 → 切换 → 收缩。破坏性操作——删除列、更改类型、重建大型表、清除数据、不可逆回填——需要在 迁移与架构演进 中明确指定目标解析和授权详情。

5. 在完整用例中使用事务

• 通过应用服务或仓储工作单元发起事务；不要不加区分地跨 HTTP 处理程序提交事务；
• 确保同一共享事务和连接集中的写入原子性成功；
• 避免在事务范围之外进行无界的用户交互，包括避免在事务中进行不必要的外部 HTTP 等待；
• 根据数据库文档选择隔离级别，以识别丢失更新、写偏斜、幻读等风险；
• 仅重试数据库明确标识的瞬时错误。设置重试次数、退避策略和幂等边界；
• 提交失败是可能发生的；不要将“最后一条 SQL 语句成功”视为事务已完成；
• 丢弃／回滚可作为安全网，但不能替代明确的控制流设计或测试实践。

连接池、隔离级别和重试机制详见事务与连接池。

6. 设计稳定的数据访问接口

application use case
  -> repository / unit of work port
  -> SQL/ORM adapter
  -> database

• 仓储方法应接受领域参数并返回领域结果，不应泄露 Web DTO；
• 将错误分类为以下类别：未找到、唯一性冲突、外键违规、序列化失败、超时、不可用；
• 保留完整的错误链，以用于日志记录和诊断，同时避免在用户响应中暴露敏感 SQL 参数；
• 批处理接口必须定义排序语义、部分失败处理方式、幂等性保证，并返回行数；
• 避免 N+1 查询。在需要预取联接或批处理时，使用符合实际的数据规模验证性能。

7. 配置有限的连接预算

使用以下公式验证总连接预算：(每个实例的连接池上限 × 最大实例数) + 运维连接。设置获取、连接、语句和事务超时；定义空闲／最大生命周期、健康检查和优雅关闭流程。不要为每个请求实例化新的连接池，也不要让无限期等待掩盖资源耗尽问题。

8. 使用真实引擎进行验证

至少执行以下验证：

1. 从空数据库执行所有迁移；
2. 升级现有数据库支持的架构版本；
3. 验证仓储操作成功、记录缺失、约束冲突和类型边界；
4. 测试事务提交、回滚、提交失败和可重试的并发问题；
5. 确保并发写入时不变量仍然成立；
6. 确认查询计划、索引命中情况和代表性数据量；
7. 评估连接池耗尽场景、数据库重启／断连以及优雅关闭行为；
8. 验证日志、指标和追踪不会泄露绑定值或凭据。

测试执行和运维清单详见测试与运维。

常见门禁（网关）

cargo fmt --all -- --check
cargo check --all-targets
cargo test --all-targets
cargo clippy --all-targets -- -D warnings

运行仓储专属的迁移验证、SQLx 离线元数据检查、Diesel 架构审计或真实数据库集成测试。命令和功能可能因版本而异；请先查看项目配置。

完成标准

• 明确界定数据库版本、模式、访问栈和一致性假设；
• 所有查询都使用参数化，动态标识符通过允许列表进行筛选；
• 记录迁移兼容窗口、回填策略、恢复流程和破坏性操作边界；
• 事务覆盖完整用例，并说明连接预算和超时设置的理由；
• 通过真实数据库测试验证迁移、约束、回滚和并发风险；
• fmt、check、test、Clippy 均通过；未经验证的真实数据库测试必须明确标注。

交接边界

主要职责	分配给
HTTP 路由、处理程序、状态码、中间件	rust-web
凭据、租户授权、审计日志、敏感字段暴露	rust-web-security
异步取消、锁、任务、阻塞隔离	rust-concurrency
测试分层、覆盖率指标、性能基线	rust-testing
功能、构建脚本、离线元数据、发布流水线	rust-cargo-build
类型、所有权语义、错误 trait、标准库行为	rust-stable

按需资源

• 访问栈和类型：选择或调整 SQLx、Diesel、SeaORM 或类型映射时查阅。
• 迁移和模式演进：查看 DDL 设计、兼容性回填和恢复策略。
• 事务和连接池：参考原子性保证、隔离级别、重试逻辑和容量管理。
• 测试和运维：查看真实数据库测试设置、查询计划和可观测性实践。
• 场景示例：需要端到端任务分解时，使用此模板。
• examples/golden-transaction/：此处提供事务边界示例的离线编译和验证。

参考资料

• std::error（Rust 标准库）
• SQLx 文档
• Diesel 指南
• SeaORM 文档