如何用PSALM/PHPStan标注含枚举键的API响应数组？

针对你遇到的API返回数组（固定totalCount键+单个VehicleType枚举值作为键的数组结构），目前在PSALM中最优的标注方式是使用交集类型，结合固定数组形状和泛型数组来覆盖所有要求：

/**
 * @return array{totalCount: numeric-string} & array<value-of<VehicleType>, array>
 */
function fetchVehicleApiResponse(): array {
    // 你的API调用逻辑
}

方案说明： #

• 交集类型&同时满足两个约束：数组必须包含totalCount（类型为numeric-string），且额外的键只能是VehicleType枚举的有效值，对应的值为数组类型。
• 对比你之前尝试的四种方法，这个方案：
  • 避开了数组形状仅支持固定字符串键的限制
  • 不会把泛型键识别为字面量字符串
  • 强制包含totalCount键，同时限制额外键的范围
  • 不会生成嵌套数组结构

注意点： #

这个标注允许存在多个VehicleType枚举键（符合泛型数组的特性），如果你的API明确只会返回单个枚举键，目前PSALM没有原生语法能严格限制这一点，但这个标注已经是最接近业务逻辑的精确类型了，比降级为array或冗余的对象封装更合理。

内容的提问来源于stack exchange，提问作者ionov-e