PHP-CSS-Parser 项目中 Positionable 接口的设计演进

在 PHP-CSS-Parser 项目中，开发团队正在对代码中涉及行号处理的类进行重构。这个重构的核心目标是引入一个统一的接口和特性(trait)来规范那些需要记录行号的类。

背景与需求

项目中存在多个需要记录行号的类，如 Rule 等。这些类目前各自实现了行号相关的功能，但存在以下问题：

1. 方法命名不一致（如 getLineNo 和 getLineNumber）
2. 行号表示方式不统一（使用 0 表示无行号）
3. 部分类需要同时处理行号和列号

设计方案

团队经过讨论确定了以下设计方案：

接口定义

新接口命名为 Positionable，包含以下方法：

• getLineNumber(): 返回可为 null 的整型，表示行号
• getLineNo(): 保持向后兼容的方法，返回非空整型
• setPosition(): 统一设置位置信息的方法

特性实现

配套的特性(trait)将提供：

• 默认的属性存储
• getLineNo() 到 getLineNumber() 的转发
• 0 到 null 的自动转换

类型处理

• 使用 null 代替 0 表示无行号
• 行号范围限定为正整数
• 列号设计为可选参数

技术考量

1. 向后兼容性：通过保留 getLineNo() 方法并标记为废弃，确保现有代码继续工作
2. 类型安全：使用严格的类型约束，行号限定为正整数
3. 灵活性：通过 nullable 类型和可选列号参数，适应不同使用场景
4. 代码复用：特性机制减少了重复代码

实现细节

在具体实现中，开发团队采用了分阶段的重构策略：

1. 首先引入 Positionable 接口和配套特性
2. 逐步迁移现有类使用新接口
3. 后续考虑将位置设置从构造函数中分离

这种渐进式的重构方式可以降低风险，同时保持代码的稳定性。

总结

这次重构展示了良好的软件设计实践：

• 统一接口规范类似功能
• 通过特性减少代码重复
• 考虑向后兼容性
• 使用现代PHP的类型系统增强代码健壮性

这种设计不仅解决了当前的问题，还为项目未来的扩展奠定了良好的基础。