Larastan 中 HasManyThrough 关系的泛型类型丢失问题解析

问题背景

在使用 Larastan（Laravel 的 PHPStan 静态分析扩展）时，开发者遇到了一个关于 Eloquent 关系查询中泛型类型丢失的问题。具体表现为：当通过 HasManyThrough 关系获取查询构建器时，模型特定的泛型类型信息会丢失，导致静态分析无法正确推断返回类型。

问题现象

开发者观察到以下类型推断行为：

1. 直接访问关系方法时，类型推断正确：

   $organization->site_checks(); 
   // 正确推断为: Illuminate\Database\Eloquent\Relations\HasManyThrough<App\Models\SiteCheck>
   

2. 调用 getQuery() 方法后，泛型类型丢失：

   $organization->site_checks()->getQuery();
   // 错误推断为: Illuminate\Database\Eloquent\Builder<Illuminate\Database\Eloquent\Model>
   // 应为: Illuminate\Database\Eloquent\Builder<App\Models\SiteCheck>
   

问题根源

经过深入分析，发现问题实际上与 HasManyThrough 关系类型有关，而非最初怀疑的模型泛型问题。以下是关键发现：

1. 关系类型差异：普通关系（如 belongsToMany）能正确保留泛型信息，而 HasManyThrough 关系存在类型推断问题

2. 泛型传播中断：在关系链中，类型信息在 HasManyThrough 到 Builder 的转换过程中丢失

3. 静态分析限制：PHPStan 在处理复杂泛型嵌套时存在局限性，特别是当模型本身也是泛型时

解决方案与修复

Larastan 团队在 2.x 分支中修复了此问题。修复后：

1. HasManyThrough 关系现在能正确携带完整的泛型信息：

   $organization->site_checks();
   // 修复后推断为: Relations\HasManyThrough<SiteCheck, Site, Organization>
   

2. getQuery() 方法现在能正确保留模型类型：

   $organization->site_checks()->getQuery();
   // 修复后推断为: EloquentBuilder<SiteCheck>
   

相关技术要点

1. Eloquent 关系泛型：

   • Laravel 的 Eloquent 关系使用 PHP 泛型来标注相关模型类型
   • 正确的类型标注对静态分析至关重要

2. 静态方法返回类型：

   • 模型中的静态方法应使用 @return Builder<static> 而非 @return Builder<self>
   • 这是因为 Eloquent 的 query() 方法内部使用 new static 创建实例

3. 泛型通配符：

   • 当不确定或不关心内部类型时，可使用 <*> 通配符
   • 例如：@return Relations\HasManyThrough<SiteCheck<*>>

最佳实践建议

1. 始终明确定义关系返回类型：

   /** @return Relations\HasManyThrough<SiteCheck> */
   public function site_checks(): Relations\HasManyThrough
   

2. 处理泛型模型关系时：

   • 使用通配符表示未知的嵌套泛型
   • 保持类型层级的一致性

3. 升级到最新 Larastan 版本：

   • 确保使用包含此修复的版本
   • 注意新版本可能引入更严格的类型检查

总结

这个问题展示了静态分析工具在复杂 ORM 关系中的挑战。通过 Larastan 团队的及时修复，开发者现在可以更可靠地使用 HasManyThrough 关系进行类型安全开发。理解 Eloquent 的泛型系统并正确标注类型，是保证 Laravel 应用类型安全的关键。