核心思路是用数据结构承载不同规格数据形态，再通过方法重载统一调用入口：①简单值类型用原始/包装类重载；②结构化数据定义独立参数类型；③可选配置封装为Builder或配置对象；④重载分基础层、标准层、扩展层，最终归一至核心逻辑；⑤规避Object判断、基本/包装类混用、可变参数混乱等陷阱；⑥保留废弃方法保障兼容性；⑦工具类演进靠新增重载、精准Javadoc与结构化测试。
核心思路是：用数据结构承载不同规格的数据形态，再靠方法重载把调用入口统一收口，让使用者按需传参，内部自动路由到对应处理逻辑。
选合适的数据结构封装差异
不同规格的数据，本质是结构或语义不同。不能硬塞进一个参数类型里，得分类建模：
- 简单值类型差异（如 int / long / String 表示时间）→ 用各自原始类型或包装类作为重载参数，不强转
- 结构化数据差异（如旧版 Map<String,Object> vs 新版 JsonObject）→ 分别定义为独立参数类型，避免用 Object 做万能兜底
- 可选配置组合（如带时区、带格式、带语言）→ 封装成 Builder 类或配置对象（如 DateFormatConfig），作为单个重载参数，比堆叠七八个 boolean 参数清晰得多
重载方法按数据结构分层设计
每个重载版本对应一种明确的数据输入结构，不模糊、不交叉：
- 基础层：接收最通用、最轻量的输入，比如 String 或 long，适配遗留系统和脚本调用
- 标准层：接收 Java 8+ 时间类（LocalDateTime、Instant）、JSON 对象等主流结构，是主推接口
- 扩展层：接收带上下文的封装结构，比如 FormatRequest（含 time、pattern、zone、locale），用于复杂业务场景
所有重载最终都导向同一套核心处理逻辑，只是前置解析路径不同。例如 format(...) 方法内部，各版本都转成 Instant + ZoneId + pattern 后再统一格式化。
避免常见陷阱
不是参数越多越灵活，关键在“可区分、可维护”：
- 别用 Object + instanceof 判断做伪重载——破坏编译期检查，Javadoc 难写，IDE 提示弱
- 别让基本类型和包装类同时出现在重载组里（如 int 和 Integer），容易因自动拆箱引发歧义调用
- 可变参数（...）必须放在重载组末尾，且最好只设一个，否则和数组参数、泛型擦除叠加后匹配规则易失控
- 旧重载方法即使废弃，也保留空实现或委托转发，加 @Deprecated 注释，不删——保障二进制兼容性
配合工具类定位与演进
工具类本身无状态，重载就是它的演进主线：
- 新增规格时，加新重载，不改旧方法签名
- Javadoc 明确标注每个重载适用的 JDK 版本、数据源类型、典型调用场景
- 测试用例按数据结构维度组织，比如 testWithMapInput()、testWithZonedDateTimeInput()，确保每种规格真实走通
这样一套下来，工具类既保持了静态工具的简洁性，又具备了面向多规格数据的伸缩能力。
