PHP 中实现类型专用容器的 DRY 原则与静态类型模拟方案

心靈之曲

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

1072人浏览过

来源于php中文网

原创

PHP 中实现类型专用容器的 DRY 原则与静态类型模拟方案

本文介绍如何在 php（无原生泛型支持）中兼顾 dry 原则与类型安全性：通过 psalm 等静态分析工具的 `@template` 注解模拟泛型行为，避免为每种类型重复编写容器类，同时保障 ide 智能提示与类型检查能力。

在 PHP 开发中，当我们需要为不同数据类型（如 Cookie、Candy）创建语义明确的容器类（如 CookieBag、CandyBag）时，很容易陷入两难：若直接继承抽象基类并重写方法签名，会违反 Liskov 替换原则（LSP），导致接口契约失效；若为每种类型单独实现全部逻辑，则严重违背 DRY（Don’t Repeat Yourself）原则。

幸运的是，虽然 PHP 目前（截至 8.3）不支持原生泛型语法（如 GenericBag<Cookie>），但我们可以通过 PHPDoc 模板注解（@template）配合静态分析工具，在不牺牲运行时兼容性的前提下，获得接近泛型的开发体验与类型安全保障。

✅ 推荐方案：使用 @template 实现“伪泛型”容器

以下是一个可复用、类型感知的通用容器实现：

<?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;
    }

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

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

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

? 关键点说明：@template T 声明一个类型参数 T，作用域为整个类；@var array<string, T> 和 @param T 等注解让 Psalm/PHPStan/IDE（如 PhpStorm）理解 $bag 存储的是 T 类型值；返回类型 static + @return static 配合链式调用，保持子类调用时的类型推导准确性；所有类型约束均在静态分析阶段生效，运行时完全零开销，100% 向后兼容。

? 使用示例：类型安全的业务调用

现在你可以安全地将 GenericBag 限定为特定类型使用：

Khroma

AI调色盘生成工具

下载

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

<?php

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

class GrandMa
{
    /**
     * @param GenericBag<Cookie> $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<Candy> $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<Cookie> 本身已是类型专用实例。

构造器与工厂模式：若需初始化逻辑（如从 HTTP 请求加载 Cookie），建议使用静态工厂方法：

/**
 * @return GenericBag<Cookie>
 */
public static function fromRequest(): self
{
    $bag = new self();
    foreach ($_COOKIE as $k => $v) {
        $bag->set($k, new Cookie($v));
    }
    return $bag;
}