本文介绍如何在 php（无原生泛型支持）中兼顾 dry 原则与类型安全性：通过 psalm 等静态分析工具的 `@template` 注解模拟泛型行为，避免为每种类型重复编写容器类，同时保障 ide 智能提示与类型检查能力。
在 PHP 开发中，当我们需要为不同数据类型（如 Cookie、Candy）创建语义明确的容器类（如 CookieBag、CandyBag）时，很容易陷入两难：若直接继承抽象基类并重写方法签名，会违反 Liskov 替换原则（LSP），导致接口契约失效；若为每种类型单独实现全部逻辑，则严重违背 DRY（Don’t Repeat Yourself）原则。
幸运的是，虽然 PHP 目前（截至 8.3）不支持原生泛型语法（如 GenericBag
✅ 推荐方案：使用 @template 实现“伪泛型”容器
以下是一个可复用、类型感知的通用容器实现：
*/
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;
}
public function del(string $key): void
{
unset($this->bag[$key]);
}
/**
* @return array
*/
public function all(): array
{
return $this->bag;
}
/**
* @param callable(T, string): bool $callback
* @return array
*/
public function filter(callable $callback): array
{
return array_filter($this->bag, $callback, ARRAY_FILTER_USE_BOTH);
}
} ? 关键点说明：@template T 声明一个类型参数 T，作用域为整个类；@var array 和 @param T 等注解让 Psalm/PHPStan/IDE（如 PhpStorm）理解 $bag 存储的是 T 类型值；返回类型 static + @return static 配合链式调用，保持子类调用时的类型推导准确性；所有类型约束均在静态分析阶段生效，运行时完全零开销，100% 向后兼容。
? 使用示例：类型安全的业务调用
现在你可以安全地将 GenericBag 限定为特定类型使用：
立即学习“PHP免费学习笔记（深入）”；
$bag
*/
public function giveCookie(GenericBag $bag): void
{
$bag->set('chocolate', new Cookie()); // ✅ 正确：参数类型被校验
// $bag->set('error', 'string'); // ❌ Psalm 报错：Expected Cookie, got string
}
}
class CandyShop
{
/**
* @param GenericBag $bag
*/
public function stockCandy(GenericBag $bag): void
{
$candy = $bag->get('gummy'); // ✅ 返回类型自动推导为 ?Candy
if ($candy instanceof Candy) {
echo $candy->getName();
}
}
} ⚠️ 注意事项与最佳实践
- 必须启用静态分析工具：单独写 @template 注解不会产生任何运行时效果。请务必集成 Psalm（推荐）、PHPStan 或 Phan 到 CI/IDE 中，并开启模板检查（如 Psalm 的 --find-unused-psalm-suppress 和 --no-suggestions 可提升严格性）。
-
避免滥用继承：切勿再定义 CookieBag extends GenericBag —— 这不仅冗余，还会破坏模板类型推导。GenericBag
本身已是类型专用实例。 -
构造器与工厂模式：若需初始化逻辑（如从 HTTP 请求加载 Cookie），建议使用静态工厂方法：
/** * @return GenericBag
*/ public static function fromRequest(): self { $bag = new self(); foreach ($_COOKIE as $k => $v) { $bag->set($k, new Cookie($v)); } return $bag; } -
与接口协作：可为 GenericBag 定义泛型接口（如 @template T implements BagInterface
），进一步统一契约，但需注意 PHP 接口本身不支持 @template，应通过类注解+文档约定实现。
✅ 总结
在缺乏语言级泛型的 PHP 生态中，@template + 静态分析是目前最成熟、最实用的类型专用容器解决方案。它完美平衡了：
- DRY：一份容器逻辑服务所有类型；
- 类型安全：编译期捕获类型误用，提升重构信心与协作效率；
- 渐进采用：无需修改现有运行时逻辑，零风险落地。
与其等待遥远的 PHP 泛型（RFC 多次讨论但尚未进入实现阶段），不如立即用 @template 为你的领域模型注入强类型力量——干净、专业、且真正可行。
