Data Mapper (數據映射器) 是企業級應用架構模式,核心目標:領域對象(實體)與數據庫結構完全解耦。不同於 Active Record(實體自帶持久化方法),Mapper 將 SQL 構建、映射、事務管理集中在獨立類中,實現:
Domain Layer Infrastructure Layer
┌─────────────┐ ┌──────────────────┐
│ User │ │ UserMapper │
│ - id │◄─────►│ - insert() │
│ - name │ │ - findById() │
│ - email │ │ - update() │
└─────────────┘ └────────┬─────────┘
│
┌──────────▼──────────┐
│ Db (PDO Wrapper) │
│ - query() │
│ - execute() │
└─────────────────────┘
<?php
class Db {
private static ?self $instance = null;
private PDO $pdo;
private function __construct(string $host, string $user, string $pass, string $dbname, string $charset = 'utf8mb4') {
$dsn = "mysql:host={$host};dbname={$dbname};charset={$charset}";
$this->pdo = new PDO($dsn, $user, $pass, [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
PDO::ATTR_EMULATE_PREPARES => false, // 真正預處理
]);
}
public static function getInstance(string $host, string $user, string $pass, string $dbname): self {
if (self::$instance === null) {
self::$instance = new self($host, $user, $pass, $dbname);
}
return self::$instance;
}
public function fetchOne(string $sql, array $params = []): array|false {
$stmt = $this->pdo->prepare($sql);
$stmt->execute($params);
return $stmt->fetch();
}
public function fetchAll(string $sql, array $params = []): array {
$stmt = $this->pdo->prepare($sql);
$stmt->execute($params);
return $stmt->fetchAll();
}
public function execute(string $sql, array $params = []): int {
$stmt = $this->pdo->prepare($sql);
$stmt->execute($params);
return $stmt->rowCount();
}
public function lastInsertId(): string {
return $this->pdo->lastInsertId();
}
public function beginTransaction(): void { $this->pdo->beginTransaction(); }
public function commit(): void { $this->pdo->commit(); }
public function rollBack(): void { $this->pdo->rollBack(); }
}
abstract class DataMapper {
protected Db $db;
protected string $tableName;
protected string $entityClass;
public function __construct() {
// 實際項目從容器獲取 Db 實例
$this->db = Db::getInstance('localhost', 'root', '', 'test');
}
/** 將數據庫行映射為實體對象 */
abstract protected function mapRow(array $row): object;
/** 將實體對象映射為數據庫字段陣列 */
abstract protected function mapEntity(object $entity): array;
public function findById(int|string $id): ?object {
$row = $this->db->fetchOne("SELECT * FROM {$this->tableName} WHERE id = ?", [$id]);
return $row ? $this->mapRow($row) : null;
}
public function findAll(array $criteria = [], string $orderBy = '', int $limit = 0, int $offset = 0): array {
$sql = "SELECT * FROM {$this->tableName}";
$params = [];
if ($criteria) {
$where = [];
foreach ($criteria as $k => $v) {
$where[] = "`{$k}` = ?";
$params[] = $v;
}
$sql .= " WHERE " . implode(' AND ', $where);
}
if ($orderBy) $sql .= " ORDER BY {$orderBy}";
if ($limit) $sql .= " LIMIT {$limit}" . ($offset ? " OFFSET {$offset}" : '');
$rows = $this->db->fetchAll($sql, $params);
return array_map([$this, 'mapRow'], $rows);
}
public function insert(object $entity): int|false {
$data = $this->mapEntity($entity);
$fields = implode(', ', array_map(fn($k) => "`{$k}`", array_keys($data)));
$placeholders = implode(', ', array_fill(0, count($data), '?'));
$sql = "INSERT INTO {$this->tableName} ({$fields}) VALUES ({$placeholders})";
if ($this->db->execute($sql, array_values($data))) {
return (int)$this->db->lastInsertId();
}
return false;
}
public function update(object $entity): bool {
$data = $this->mapEntity($entity);
$id = $data['id'] ?? null;
if (!$id) return false;
unset($data['id']);
$set = implode(', ', array_map(fn($k) => "`{$k}` = ?", array_keys($data)));
$sql = "UPDATE {$this->tableName} SET {$set} WHERE `id` = ?";
$params = [...array_values($data), $id];
return $this->db->execute($sql, $params) > 0;
}
public function delete(int|string $id): bool {
return $this->db->execute("DELETE FROM {$this->tableName} WHERE `id` = ?", [$id]) > 0;
}
}
// 純淨實體類(無任何持久化邏輯)
class User {
public ?int $id = null;
public string $username = '';
public string $email = '';
public string $mobile = '';
public DateTime $createdAt;
public function __construct() {
$this->createdAt = new DateTime();
}
}
// 映射器實現
class UserMapper extends DataMapper {
protected string $tableName = 'users';
protected string $entityClass = User::class;
protected function mapRow(array $row): User {
$user = new User();
$user->id = (int)$row['id'];
$user->username = $row['username'];
$user->email = $row['email'];
$user->mobile = $row['mobile'];
$user->createdAt = new DateTime($row['created_at']);
return $user;
}
protected function mapEntity(object $entity): array {
/** @var User $entity */
return [
'id' => $entity->id,
'username' => $entity->username,
'email' => $entity->email,
'mobile' => $entity->mobile,
'created_at' => $entity->createdAt->format('Y-m-d H:i:s'),
];
}
// 業務專用查詢
public function findByEmail(string $email): ?User {
$row = $this->db->fetchOne("SELECT * FROM {$this->tableName} WHERE email = ?", [$email]);
return $row ? $this->mapRow($row) : null;
}
}
<?php
require 'Db.php';
require 'DataMapper.php';
require 'User.php';
require 'UserMapper.php';
// 1. 創建用戶
$mapper = new UserMapper();
$user = new User();
$user->username = 'Anrai';
$user->email = 'huanglei.web@gmail.com';
$user->mobile = '123456789';
$userId = $mapper->insert($user);
echo "新用戶 ID: {$userId}\n";
// 2. 查詢用戶
$found = $mapper->findById($userId);
echo "查詢到: {$found->username} ({$found->email})\n";
// 3. 更新
$found->mobile = '987654321';
$mapper->update($found);
// 4. 列表查詢
$users = $mapper->findAll(['email' => 'huanglei.web@gmail.com'], 'id DESC', 10);
foreach ($users as $u) {
echo "{$u->id}: {$u->username}\n";
}
| 維度 | Data Mapper | Active Record |
|---|---|---|
| 實體純度 | 純 POPO,零依賴 | 繼承基類,耦合 DB |
| 複雜映射 | 支援繼承、組合、值對象 | 困難,通常 1:1 表映射 |
| 測試性 | 極佳(實體無依賴) | 需 Mock DB 或用 SQLite |
| 代碼量 | 較大(需寫 Mapper) | 極少(框架自動生成) |
| 性能 | 可精細控制 SQL | 可能產生 N+1、過度查詢 |
| 框架代表 | Doctrine ORM、Hibernate、Entity Framework | Laravel Eloquent、ThinkPHP Model、Rails ActiveRecord |
$user->orders 首次訪問才查詢)。Criteria/QueryBuilder 替代陣列條件,類型安全。數據映射器模式是 領域驅動設計 (DDD) 的基石,通過 獨立 Mapper 類封裝所有 SQL 與映射邏輯,實現領域模型與持久化機制的完全隔離。雖然初期代碼量大於 Active Record,但在中大型項目中,其帶來的 可維護性、可測試性、擴展性 收益遠超成本。現代 PHP 專案建議直接使用 Doctrine ORM** 成熟實現,而非手寫。