在Psalm中优雅地处理对象属性与数组形状的映射

在实际开发中，我们经常遇到需要将对象属性转换为特定数组形状的需求。传统做法是通过手动维护@psalm-type注释来定义数组结构，这种方式不仅繁琐而且容易出错。Psalm提供了更优雅的解决方案。

传统方式的痛点

开发者通常需要为每个类单独定义类型别名，例如：

/**
 * @psalm-type FieldValueFileItemShape = array{
 *     filePath: string,
 *     fileName: string,
 *     mimeType: string,
 *     fileSize: int,
 *     originalFileName: string,
 *     checksum: string,
 *     isPostTmp?: bool,
 *     delete?: bool,
 *     isSymlink?: bool
 * }
 */
class FieldValueFileItem {
    // 类属性定义...
}

这种方式存在两个主要问题：

1. 需要手动维护类型定义，当类属性变更时容易忘记更新
2. 类型定义与类定义分离，增加了代码维护成本

Psalm的解决方案：properties-of

Psalm提供了properties-of泛型类型，可以自动将类属性映射为数组形状：

class C {
    private int $i = 1;
    private string $s = "aaa";
}

/** @param properties-of<C> $_a */
function f(array $_a): void {}

使用properties-of的优势：

1. 自动同步：当类属性变更时，相关类型会自动更新
2. 减少重复代码：无需手动维护类型定义
3. 类型安全：Psalm会严格检查数组形状是否匹配类属性

实际应用场景

这种技术特别适用于：

• DTO(数据传输对象)与数组的转换
• API响应数据的类型定义
• 数据库记录与领域对象的映射
• 序列化/反序列化操作

注意事项

1. properties-of会包含所有属性，包括私有属性
2. 对于可选属性，需要使用?标记
3. 继承关系中的属性也会被包含
4. 静态属性不会被包含在结果中

通过使用properties-of，开发者可以大幅减少类型定义的工作量，同时提高代码的可维护性和类型安全性。这是Psalm类型系统中一个非常实用的特性，值得在项目中广泛应用。