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

本文介绍如何在 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 等标注约束泛型行为。

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

class GenericBag {     /** @var Array */     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);     } }

✅ 关键要点说明：

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

• @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 + 工具链支持是最务实的泛型模拟方案：它让抽象容器真正“一次编写、多处强类型复用”，在不增加运行时开销的前提下，显著提升大型项目的可维护性与协作效率。