# DataForge 设计文档
## 架构设计
```mermaid
graph TD
A[API Layer] --> B[Core Engine]
B --> C[Data Generators]
B --> D[Schema Parser]
B --> E[Rule Engine]
C --> F[Basic Types]
C --> G[Complex Types]
C --> H[Localized Data]
E --> I[Regex Engine]
E --> J[Pattern Engine]
E --> K[Custom Rules]
```
## 核心模块
### 1. 生成引擎 CoreEngine
- 基于Rayon的并行流水线
- 内存池管理（零拷贝实现）
- 生成策略控制（顺序/随机/混合）
### 2. 数据库适配层 `DatabaseAdapter`
```rust
pub trait DatabaseAdapter {
/// 自动推断表结构
fn infer_schema(&self) -> Result<TableSchema>;
/// 批量数据插入（支持事务回滚）
fn bulk_insert(&self, data: Vec<Value>) -> Result<usize>;
/// 类型转换系统
fn type_mapping(&self, rust_type: &str) -> String;
}
```
### 3. 规则引擎 RuleEngine
- 多层级规则继承系统
- 正则表达式编译优化
- 自定义函数hook机制
#### 核心数据结构
```rust
// 数据生成配置
struct GenConfig {
batch_size: usize, // 每批次生成数量
locale: Locale, // 区域设置
null_probability: f32, // 空值概率
string_pool: Arc<Pool>, // 字符串资源池
}
// 数据库连接配置
struct DBConfig {
max_retries: u32, // 最大重试次数
batch_insert_size: usize,
transaction_mode: TransactionMode,
}
```
## 错误处理设计
### 错误分级策略
```rust
#[derive(Debug, thiserror::Error)]
pub enum DataForgeError {
#[error("配置错误: {0}")]
ConfigError(String), // <mcsymbol name="ConfigError" filename="src/error.rs" path="src/error.rs" startline="34" type="enum"></mcsymbol>
#[error("数据库操作失败: {0}")]
DatabaseError(#[from] sqlx::Error),
#[error("并发任务超时")]
TimeoutError,
#[error("数据验证失败: {0}")]
ValidationError(String),
}
```
### 重试机制
```rust
impl DBConfig {
/// 带指数退避的重试逻辑
pub fn execute_with_retry<F, T>(&self, op: F) -> Result<T>
where
F: Fn() -> Result<T> + Send
{
let mut retries = 0;
while retries < self.max_retries {
match op() {
Ok(result) => return Ok(result),
Err(e) => {
let delay = 2u64.pow(retries) * 100; // 指数退避
thread::sleep(Duration::from_millis(delay));
retries += 1;
}
}
}
Err(DataForgeError::TimeoutError)
}
}
```
## 性能优化
### 1. 内存管理
- 使用Arena分配器管理临时对象
- 字符串资源池复用
```rust
impl StringPool {
pub fn get(&self, pattern: &str) -> Arc<str> {
// 使用LRU缓存最近使用的1000个模式
}
}
```
### 2. 并发处理
- Rayon并行迭代器
- 无锁队列进行任务分发
- 基于CPU核心数的动态分片策略
## 日志与监控
### 性能指标采集
```rust
/// 生成器指标统计
#[derive(Default)]
struct GeneratorMetrics {
generated_count: AtomicUsize,
error_count: AtomicUsize,
latency_histogram: Histogram,
}
impl GeneratorMetrics {
/// Prometheus格式指标暴露
pub fn expose_metrics(&self) -> String {
format!(r#"
dataforge_generated_total {}
dataforge_errors_total {}
dataforge_latency_seconds_bucket{{le="0.1"}} {}
"#,
self.generated_count.load(Ordering::Relaxed),
self.error_count.load(Ordering::Relaxed),
self.latency_histogram.percentile(0.1)
)
}
}
```
### 安全设计
1. 敏感数据处理
- 数据库密码使用 secrecy crate进行内存加密
- 连接字符串在日志中自动脱敏
2. 注入防护
```rust
fn sanitize_sql(input: &str) -> String {
input.replace('\'', "''").replace(';', "")
}
```
## 扩展接口
```rust
/// 自定义生成器实现示例
impl CustomGenerator for ChineseAddress {
fn generate(&self, ctx: &Context) -> Value {
format!("{}省{}市{}",
regions::province(),
random_chinese(2..4),
random_chinese(5..8)
)
}
}
```
## 依赖管理
核心依赖清单
| rayon | 1.9 | 并行 |
| sqlx | 0.7 | 多数据库支持 |
| tracing | 0.1 | 分布式性能追踪 |
| ahash | 0.8 | 高性能哈希算法 |
## 部署方案
### Docker多阶段构建
```dockerfile
FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release
FROM debian:bullseye-slim
COPY --from=builder /app/target/release/dataforge /usr/local/bin
CMD ["dataforge", "run"]
```
## 测试策略
- 模糊测试：使用proptest进行属性测试
- 并发安全测试：Loom测试框架
- 数据库兼容性测试矩阵：
| MySQL | 5.7/8.0 | 100% |
| PostgreSQL | 12-15 | 后续计划 |
| SQLite | 3.30+ | 后续计划 |
## 未来路线图
- 支持NoSQL数据库（MongoDB/Cassandra）
- 分布式生成模式（基于Rayon+Redis）
- WebAssembly运行时支持
- 可视化规则编辑器