# object-mapper

**Repository Path**: wx_1098/object-mapper

## Basic Information

- **Project Name**: object-mapper
- **Description**: 🚀 强大而优雅的对象映射工具库 | ⚡️ 极致的性能表现 | 🎯 类型安全 | 💡 简洁的API设计

主要特性:
✨ 支持复杂数据结构转换和嵌套属性映射
🛠 强大的转换管道系统,轻松处理数据格式化
🎮 灵活的条件映射和动态规则
🔌 可扩展的插件系统

适用场景:
📡 API响应数据格式化和规范化
💾 数据库模型与业务模型转换
🌉 跨系统数据迁移
📊 报表数据处理

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-10
- **Last Updated**: 2025-04-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Object Mapper 使用指南（优化版）

## 🎯 快速入门

### 1. 安装与基础概念

**对象映射**是将一个对象的属性按照规则转换到另一个对象的过程。适用于：

- **数据转换** ：当你需要将一种数据结构转换为另一种数据结构时，比如将后端返回的数据格式转换为前端组件需要的格式。
- **对象克隆** ：需要创建一个对象的副本，但又不想手动复制每个属性时。
- **数据整合** ：将多个对象的数据整合到一个新的对象中。
- **API 数据处理** ：处理不同 API 返回的数据格式，使其符合你的应用需求。

```bash
npm install @wx_1098/object-mapper
```

```typescript
// 初始化映射器
import { ObjectMapper, Transformers } from '@wx_1098/object-mapper';

const mapper = new ObjectMapper();
```

### 2. 最简示例

```typescript
const user = { name: '小明', age: 18 };

// 基础映射规则（字符串简写）
const result = mapper.map(user, [
  'username:name', // 将源.name映射到目标.username
  'age' // 同名属性直接映射
]);

/* 结果：
{ username: "小明", age: 18 } */
```

---

## 🧭 核心功能详解

### 3. 路径语法

支持**点分隔符**与**数组格式**两种路径写法：

```typescript
// 点分隔写法（自动拆分为数组）
mapper.map(data, ['a.b.c']);

// 数组写法（直接使用路径段）
mapper.map(data, [{ target: ['x', 'y', 'z'] }]);

// 混合写法（处理特殊字符）
const data = { 'user.id': 123 };
mapper.map(data, [{ target: 'userId', source: ['user.id'] }]);
```

### 4. 嵌套结构处理

```typescript
const order = {
  customer: {
    name: '小明',
    address: {
      city: '北京'
    }
  }
};

mapper.map(order, ['clientName:customer.name', 'location:customer.address.city']);

/* 结果：
{
  clientName: "小明",
  location: "北京"
} */
```

### 5. 自动创建嵌套结构

```typescript
mapper.map({ value: 100 }, ['a.b.c.value']);

/* 自动创建缺失结构：
{
  a: {
    b: {
      c: {
        value: 100
      }
    }
  }
} */
```

---

## 🛠️ 进阶功能

### 6. 值转换管道

使用内置转换器或自定义函数处理值：

```typescript
const product = { price: '199.99' };

mapper.map(product, [
  {
    target: 'price',
    transform: [
      Transformers.string.trim, // 去空格
      (val) => parseFloat(val), // 转数字
      Transformers.number.currency('¥') // 格式化为货币
    ]
  }
]);

/* 结果：{ price: "¥200.00" } */
```

### 7. 条件映射

```typescript
const data = { role: 'admin', score: 85 };

mapper.map(data, [
  {
    target: 'accessLevel',
    when: (ctx) => ctx.source.role === 'admin' // 仅当role为admin时映射
  },
  {
    target: 'grade',
    when: (ctx) => ctx.value >= 60, // 使用转换后的值判断
    transform: (score) => (score >= 90 ? 'A' : 'B')
  }
]);

/* 结果：{ accessLevel: "admin", grade: "B" } */
```

---

## ⚙️ 配置策略

### 8. 全局配置

```typescript
const customMapper = new ObjectMapper({
  strict: true, // 严格模式（路径不存在时报错）
  nullPolicy: 'ignore', // 忽略空值
  autoType: true // 自动类型转换
});
```

### 9. 局部配置覆盖

```typescript
mapper.map(data, [
  {
    target: 'specialField',
    config: {
      strict: false // 仅对本规则生效
    }
  }
]);
```

---

## 🧩 插件系统

### 10. 开发日志插件

```typescript
const loggerPlugin = {
  beforeMap: (ctx) => console.log('开始映射:', ctx.source),
  afterRule: (ctx) => console.log(`处理规则: ${ctx.rule.targetPath}`),
  onError: (err) => console.error('发生错误:', err)
};

mapper.use(loggerPlugin);
```

### 11. 错误处理插件

```typescript
const errorHandler = {
  onError: (error, ctx) => {
    alert(`映射错误: ${error.message}`);
    return false; // 阻止错误抛出
  }
};

mapper.use(errorHandler);
```

---

## 🏆 最佳实践

### 场景 1：API 响应处理

```typescript
// 原始API数据结构
const apiResponse = {
  user_info: {
    full_name: '王小明',
    contacts: [{ type: 'email', value: 'xm@example.com' }]
  }
};

// 转换规则
mapper.map(apiResponse, [
  'user.name:user_info.full_name',
  {
    target: 'user.email',
    source: 'user_info.contacts',
    transform: (contacts) => contacts.find((c) => c.type === 'email')?.value || ''
  }
]);

/* 结果：
{
  user: {
    name: "王小明",
    email: "xm@example.com"
  }
} */
```

### 场景 2：数据库模型转换

```typescript
// 数据库原始数据
const dbRow = {
  id: 1,
  created_at: '2023-05-20T08:00:00Z',
  price_cents: 2999
};

// 转换规则
mapper.map(dbRow, [
  'productId:id',
  {
    target: 'price',
    source: 'price_cents',
    transform: (cents) => (cents / 100).toFixed(2)
  },
  {
    target: 'createdAt',
    transform: [Transformers.date.toISO]
  }
]);

/* 结果：
{
  productId: 1,
  price: "29.99",
  createdAt: "2023-05-20T08:00:00.000Z"
} */
```

---

## ⚠️ 重要注意事项

1. **路径解析规则**

   - `items.0.name` → 解析为数组索引
   - `items[0].name` → 解析为对象属性
   - 空路径段会被自动忽略（`a..b` → `['a','b']`）

2. **性能优化**

   ```typescript
   // 启用路径缓存（默认关闭）
   new ObjectMapper({ cachePaths: true });

   // 预编译常用规则
   const commonRules = mapper.normalizeRules(myRules);
   ```

3. **调试技巧**

   ```typescript
   // 查看标准化后的规则
   console.log(mapper.normalizeRules(['a.b.c']));

   // 使用调试插件
   mapper.use({
     beforeRule: (ctx) => console.log('当前值:', ctx.value)
   });
   ```

---

## 📚 学习路径建议

1. **新手阶段**

   - 掌握基础属性映射
   - 理解路径解析规则
   - 尝试简单值转换

2. **进阶阶段**

   - 学习条件映射策略
   - 掌握嵌套结构处理
   - 配置全局/局部策略

3. **专家阶段**
   - 开发自定义插件
   - 实现复杂类型转换
   - 优化映射性能

---

**通过本指南，您将能：**

- ✅ 处理各种数据结构转换
- ✅ 实现智能条件映射
- ✅ 开发定制化插件
- ✅ 优化映射器性能
- ✅ 应对复杂业务场景