概述

代理模式（Proxy Pattern）是一种结构型设计模式，其核心思想是为目标对象提供一个代理对象，通过代理对象控制对目标对象的访问。代理模式在不改变目标对象接口和核心逻辑的前提下，可在访问前后添加额外操作（如权限校验、日志记录、缓存处理、延迟加载），实现对目标对象的增强和控制。

该模式遵循“单一职责原则”，将目标对象的核心业务逻辑与附加功能（如监控、控制）分离，代理对象专注于访问控制，目标对象专注于业务实现，同时支持动态切换代理类型，提升系统的灵活性和可维护性。

核心价值

适用场景

注意事项

完整代码

以“商品数据查询”为业务场景，目标对象为数据库查询服务，通过代理实现“缓存代理”（查询结果缓存）和“日志代理”（操作日志记录），控制对目标对象的访问并增强功能。

<?php
declare(strict_types = 1);

/**
 * 目标接口：定义商品查询的统一规范
 */
interface ProductServiceInterface
{
    /**
     * 根据商品ID查询商品信息
     * @param int $productId 商品ID
     * @return array 商品信息
     */
    public function getProductById(int $productId): array;

    /**
     * 根据商品分类查询商品列表
     * @param string $category 商品分类
     * @return array 商品列表
     */
    public function getProductsByCategory(string $category): array;
}

/**
 * 目标对象：商品数据库查询服务（核心业务逻辑）
 */
class ProductDatabaseService implements ProductServiceInterface
{
    /**
     * 模拟数据库查询，创建成本高（如建立数据库连接、复杂查询）
     */
    public function getProductById(int $productId): array
    {
        // 模拟数据库查询耗时操作
        sleep(1);
        echo "【数据库查询】查询商品ID：{$productId}的信息" . PHP_EOL;
        return [
            'id' => $productId,
            'name' => "商品{$productId}（数据库查询）",
            'price' => rand(100, 1000),
            'category' => '电子设备'
        ];
    }

    public function getProductsByCategory(string $category): array
    {
        // 模拟数据库查询耗时操作
        sleep(1);
        echo "【数据库查询】查询分类：{$category}的商品列表" . PHP_EOL;
        return [
            ['id' => 101, 'name' => "商品101（{$category}）", 'price' => 599],
            ['id' => 102, 'name' => "商品102（{$category}）", 'price' => 799],
            ['id' => 103, 'name' => "商品103（{$category}）", 'price' => 999]
        ];
    }
}

/**
 * 代理类1：缓存代理（附加缓存功能，减少数据库查询）
 */
class ProductCacheProxy implements ProductServiceInterface
{
    /**
     * 持有目标对象引用
     * @var ProductServiceInterface
     */
    private ProductServiceInterface $target;

    /**
     * 缓存存储（内存缓存，实际可使用Redis等）
     * @var array
     */
    private array $cache = [];

    /**
     * 缓存过期时间（秒）
     * @var int
     */
    private int $cacheExpire = 300;

    public function __construct(ProductServiceInterface $target)
    {
        $this->target = $target;
    }

    public function getProductById(int $productId): array
    {
        $cacheKey = "product:id:{$productId}";
        // 1. 先查询缓存
        if (isset($this->cache[$cacheKey]) && time() - $this->cache[$cacheKey]['time'] < $this->cacheExpire) {
            echo "【缓存命中】从缓存中获取商品ID：{$productId}的信息" . PHP_EOL;
            return $this->cache[$cacheKey]['data'];
        }

        // 2. 缓存未命中，调用目标对象查询
        $data = $this->target->getProductById($productId);

        // 3. 存入缓存
        $this->cache[$cacheKey] = [
            'data' => $data,
            'time' => time()
        ];
        echo "【缓存存储】将商品ID：{$productId}的信息存入缓存" . PHP_EOL;
        return $data;
    }

    public function getProductsByCategory(string $category): array
    {
        $cacheKey = "product:category:{$category}";
        // 1. 先查询缓存
        if (isset($this->cache[$cacheKey]) && time() - $this->cache[$cacheKey]['time'] < $this->cacheExpire) {
            echo "【缓存命中】从缓存中获取分类：{$category}的商品列表" . PHP_EOL;
            return $this->cache[$cacheKey]['data'];
        }

        // 2. 缓存未命中，调用目标对象查询
        $data = $this->target->getProductsByCategory($category);

        // 3. 存入缓存
        $this->cache[$cacheKey] = [
            'data' => $data,
            'time' => time()
        ];
        echo "【缓存存储】将分类：{$category}的商品列表存入缓存" . PHP_EOL;
        return $data;
    }
}

/**
 * 代理类2：日志代理（附加日志记录功能，监控操作）
 */
class ProductLogProxy implements ProductServiceInterface
{
    /**
     * 持有目标对象引用（可嵌套其他代理）
     * @var ProductServiceInterface
     */
    private ProductServiceInterface $target;

    public function __construct(ProductServiceInterface $target)
    {
        $this->target = $target;
    }

    public function getProductById(int $productId): array
    {
        // 1. 调用前记录日志（请求信息）
        $this->log("开始查询商品ID：{$productId}的信息", 'info');

        try {
            // 2. 调用目标对象（或嵌套的其他代理）
            $data = $this->target->getProductById($productId);

            // 3. 调用后记录日志（响应信息）
            $this->log("商品ID：{$productId}查询成功，结果：" . json_encode($data, JSON_UNESCAPED_UNICODE), 'info');
            return $data;
        } catch (\Exception $e) {
            // 4. 异常时记录错误日志
            $this->log("商品ID：{$productId}查询失败，错误：" . $e->getMessage(), 'error');
            throw $e;
        }
    }

    public function getProductsByCategory(string $category): array
    {
        // 1. 调用前记录日志
        $this->log("开始查询分类：{$category}的商品列表", 'info');

        try {
            // 2. 调用目标对象
            $data = $this->target->getProductsByCategory($category);

            // 3. 调用后记录日志
            $this->log("分类：{$category}查询成功，商品数量：" . count($data), 'info');
            return $data;
        } catch (\Exception $e) {
            // 4. 异常日志
            $this->log("分类：{$category}查询失败，错误：" . $e->getMessage(), 'error');
            throw $e;
        }
    }

    /**
     * 模拟日志记录（实际可写入文件、数据库或日志系统）
     * @param string $message 日志内容
     * @param string $level 日志级别
     */
    private function log(string $message, string $level = 'info'): void
    {
        $time = date('Y-m-d H:i:s');
        echo "【{$time}】【{$level}】{$message}" . PHP_EOL;
    }
}

// 测试代码
try {
    echo "=== 测试1：直接调用目标对象（无代理） ===" . PHP_EOL;
    $productService = new ProductDatabaseService();
    $productService->getProductById(1001); // 耗时1秒，无缓存和日志
    echo PHP_EOL;

    echo "=== 测试2：缓存代理 + 日志代理（嵌套代理） ===" . PHP_EOL;
    // 嵌套代理：日志代理包裹缓存代理，缓存代理包裹目标对象
    $target = new ProductDatabaseService();
    $cacheProxy = new ProductCacheProxy($target);
    $logProxy = new ProductLogProxy($cacheProxy);

    // 第一次查询：缓存未命中，走数据库查询，记录日志并缓存
    $logProxy->getProductById(1001);
    echo PHP_EOL;

    // 第二次查询：缓存命中，直接从缓存获取，记录日志
    $logProxy->getProductById(1001);
    echo PHP_EOL;

    // 测试分类查询
    $logProxy->getProductsByCategory('电子设备');
} catch (\Exception $e) {
    echo "错误：" . $e->getMessage();
}

核心结构拆解

代理模式的核心由“目标接口”“目标对象”和“代理对象”三部分组成，结构清晰且职责明确：

关键优化点

常见错误规避

扩展场景示例（新增代理无需修改原有代码）

若业务新增“权限代理”（验证用户是否有权限查询商品），仅需新增代理类，无需修改目标对象、已有代理和客户端代码：

// 新增代理类：权限代理（验证用户权限）
class ProductAuthProxy implements ProductServiceInterface
{
    private ProductServiceInterface $target;
    private array $allowedRoles = ['admin', 'editor', 'viewer']; // 允许访问的角色

    public function __construct(ProductServiceInterface $target)
    {
        $this->target = $target;
    }

    public function getProductById(int $productId): array
    {
        // 1. 权限校验（模拟当前用户角色）
        $currentRole = $this->getCurrentUserRole();
        if (!in_array($currentRole, $this->allowedRoles, true)) {
            throw new \RuntimeException("用户角色【{$currentRole}】无权限查询商品ID：{$productId}");
        }

        // 2. 权限通过，转发调用
        echo "【权限校验通过】用户角色：{$currentRole} 允许查询商品ID：{$productId}" . PHP_EOL;
        return $this->target->getProductById($productId);
    }

    public function getProductsByCategory(string $category): array
    {
        // 1. 权限校验
        $currentRole = $this->getCurrentUserRole();
        if (!in_array($currentRole, $this->allowedRoles, true)) {
            throw new \RuntimeException("用户角色【{$currentRole}】无权限查询分类：{$category}的商品");
        }

        // 2. 转发调用
        echo "【权限校验通过】用户角色：{$currentRole} 允许查询分类：{$category}" . PHP_EOL;
        return $this->target->getProductsByCategory($category);
    }

    /**
     * 模拟获取当前用户角色（实际可从会话、Token中获取）
     * @return string
     */
    private function getCurrentUserRole(): string
    {
        // 模拟不同用户角色，可切换测试
        return 'editor'; // 可选：'admin'/'editor'/'viewer'/'guest'
    }
}

// 测试新增权限代理（嵌套多层代理）
echo "=== 测试3：权限代理 + 日志代理 + 缓存代理 ===" . PHP_EOL;
$target = new ProductDatabaseService();
$cacheProxy = new ProductCacheProxy($target);
$logProxy = new ProductLogProxy($cacheProxy);
$authProxy = new ProductAuthProxy($logProxy);

$authProxy->getProductById(1001); // 权限校验→日志→缓存→数据库（缓存命中）
echo PHP_EOL;

// 测试无权限场景（修改getCurrentUserRole返回'guest'）
// $authProxy->getProductsByCategory('电子设备'); // 抛出无权限异常

实际应用场景

代理模式与其他模式对比