17370845950

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

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

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

✅ 关键要点说明：

• @template T 声明该类支持一个泛型类型参数；
• @var array 明确内部存储结构的键值类型关系；
• 所有涉及值操作的方法均通过 @param T / @return T 绑定

  

  类型，确保 get() 返回值与 set() 输入值类型一致；
• 使用 static 作为返回类型（而非 self）更准确表达“返回当前特化实例”，利于链式调用推导；
• 注解语法兼容 Psalm、PHPStan 及主流 IDE（如 PHPStorm），可在编码阶段获得类型检查与自动补全。

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

 */
$cookieBag = new GenericBag();

/** @var GenericBag */
$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 $bag
     */
    public function giveCookie(GenericBag $bag): void
    {
        $bag->set('gift', new Cookie()); // ✅ 类型安全调用
    }
}

⚠️ 注意事项：

• 此方案不提供运行时类型强制，所有检查依赖静态分析工具。务必集成 Psalm 或 PHPStan 到 CI 流程中；
• 避免在 GenericBag 内部对 T 做运行时类型判断（如 is_a($value, T::class)），因 T 仅为注解，PHP 解析器不可见；
• 若需运行时类型保障（如防止非法写入），可结合构造器参数或工厂方法注入类型约束逻辑，但会牺牲部分简洁性；
• 不推荐为每种类型创建继承子类（如 CookieBag extends GenericBag），这既破坏 DRY，又重蹈 LSP 覆辙。

总结而言，在 PHP 当前生态下，@template + 工具链支持是最务实的泛型模拟方案：它让抽象容器真正“一次编写、多处强类型复用”，在不增加运行时开销的前提下，显著提升大型项目的可维护性与协作效率。