PHP 中实现类型安全的泛型容器：DRY 原则与静态类型模拟指南

2026-01-26

PHP 中实现类型安全的泛型容器：DRY 原则与静态类型模拟指南

本文讲解如何在 php（无原生泛型支持）中通过 psalm 模板注解（`@template`）模拟泛型容器，兼顾 dry 原则与类型专用性，避免继承导致的 lsp 违反，并提升 ide 提示与静态分析准确性。

在 PHP 开发中，我们常需构建多种语义明确的“专用容器”——如 CookieBag、CandyBag 或 ConfigBag——它们共享相同的基础操作（增、删、查、过滤），但又要求对存储值进行严格的类型约束。若采用传统继承方式（如让 CookieBag extends AbstractBag 并重写 get()/set() 的参数与返回类型），虽看似直观，实则违反里氏替换原则（LSP）：父类 AbstractBag 声明接受任意 mixed 类型，子类却强制限定为 Cookie，导致依赖 BagInterface 的通用代码（如 GrandMa::giveCookie()）在传入非 CookieBag 实例时发生运行时错误，且无法被类型系统提前捕获。

根本出路：放弃“继承特化”，转向“模板化泛化”
PHP 虽不支持原生泛型（如 GenericBag），但可通过行业标准的 PHPDoc 模板注解（@template）配合静态分析工具（如 Psalm、PHPStan）实现等效效果。这种方式不改变运行时行为，却能为开发者提供强类型提示、方法签名一致性保障和编译期错误预警。

以下是一个生产就绪的实现范例：

 */
    private array $bag = [];

    public function has(string $key): bool
    {
        return array_key_exists($key, $this->bag);
    }

    /**
     * @param string $key
     * @param T|null $fallback
     * @return T
     */
    public function get(string $key, $fallback = null)
    {
        return $this->has($key) ? $this->bag[$key] : $fallback;
    }

    /**
     * @param string $key
     * @param T $value
     * @return static
     */
    public function set(string $key, $value): self
    {
        $this->bag[$key] = $value;
        return $this;
    }

    /**
     * @param string $key
     * @return void
     */
    public function del(string $key): void
    {
        unset($this->bag[$key]);
    }

    /**
     * @return array
     */
    public function all(): array
    {
        return $this->bag;
    }

    /**
     * @param callable(mixed, string): bool $callback
     * @return array
     */
    public function filter(callable $callback): array
    {
        return array_filter($this->bag, $callback, ARRAY_FILTER_USE_BOTH);
    }
}

使用时，无需创建子类，而是直接实例化并用 PHPDoc 明确类型参数：

 $cookieBag */
$cookieBag = new GenericBag();

// 此处 IDE 和 Psalm 将校验：只能存 Cookie 对象，返回值为 ?Cookie
$cookieBag->set('session', new Cookie('PHPSESSID', 'abc123'));
$cookie = $cookieBag->get('session'); // $cookie: ?Cookie

// 同理，CandyBag 复用同一类，零重复逻辑
/** @var GenericBag $candyBag */
$candyBag = new GenericBag();
$candyBag->set('choco', new Candy('Dark Chocolate'));

// 在依赖注入场景中精准声明类型
class GrandMa
{
    /**
     * @param GenericBag $bag
     * @return void
     */
    public function giveCookie(GenericBag $bag): void
    {
        $bag->set('gift', new Cookie('grandma-cookie', 'yum')); // ✅ 类型安全
        // $bag->set('oops', new DateTime()); // ❌ Psalm 报错：Expected Cookie, got DateTime
    }
}

✅ 优势总结