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

花韻仙語

发布时间：2026-01-26 18:38:02

550人浏览过

来源于php中文网

原创

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

本文介绍如何在 php 缺乏原生泛型支持的前提下，通过 psalm 等静态分析工具的模板注解（`@template`）模拟类型专用容器，兼顾代码复用性（dry）与方法签名的类型准确性，避免 lsp 违反风险。

在 PHP 开发中，我们常需构建多种语义明确、类型受限的“容器”类（如 CookieBag、CandyBag），以提升领域建模清晰度与 IDE 支持体验。但若采用继承方式强行覆盖 get()/set() 的参数与返回类型（如将 mixed 替换为 ?Cookie），虽看似直观，实则违反里氏替换原则（LSP）：子类无法完全替代父类使用场景，导致依赖 BagInterface 的通用逻辑（如 GrandMa::giveCookie()）在传入 CookieBag 时因类型契约不兼容而失效。

PHP 目前不支持原生泛型（如 GenericBag<T>），因此不能像 C++ 模板或 TypeScript 泛型那样在编译期生成类型特化版本。但可通过静态分析友好型文档注解实现近似效果——核心是使用 @template 声明类型参数，并配合 @param T、@return T 等标注约束泛型行为。

以下是一个可落地的实践方案：

<?php

/**
 * @template T
 */
class GenericBag
{
    /** @var array<string, T> */
    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<string, T>
     */
    public function all(): array
    {
        return $this->bag;
    }

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

✅ 关键要点说明：

立即学习“PHP免费学习笔记（深入）”；

AI Web Designer

AI网页设计师，快速生成个性化的网站设计

下载

@template T 声明该类支持一个泛型类型参数；
@var array<string, T> 明确内部存储结构的键值类型关系；
所有涉及值操作的方法均通过 @param T / @return T 绑定类型，确保 get() 返回值与 set() 输入值类型一致；
使用 static 作为返回类型（而非 self）更准确表达“返回当前特化实例”，利于链式调用推导；
注解语法兼容 Psalm、PHPStan 及主流 IDE（如 PHPStorm），可在编码阶段获得类型检查与自动补全。

使用时，无需创建子类，直接实例化并借助类型注解声明语义：

<?php

class Cookie { /* ... */ }
class Candy { /* ... */ }

// 类型安全的专用实例（仅靠注解驱动）
/** @var GenericBag<Cookie> */
$cookieBag = new GenericBag();

/** @var GenericBag<Candy> */
$candyBag = new GenericBag();

// ✅ 正确：类型匹配
$cookieBag->set('session', new Cookie());
$cookie = $cookieBag->get('session');

// ❌ Psalm/PHPStan 将报错：Expected Cookie, got Candy
// $cookieBag->set('bad', new Candy());

class GrandMa
{
    /**
     * @param GenericBag<Cookie> $bag
     */
    public function giveCookie(GenericBag $bag): void
    {
        $bag->set('gift', new Cookie()); // ✅ 类型安全调用
    }
}

⚠️ 注意事项：