兼容旧版配置逻辑的关键是模拟旧行为而非统一类型：预处理Map补默认值、注册类型转换器、支持下划线转驼峰、递归处理嵌套、用LinkedHashMap保序、不忽略null值，并通过适配器封装渐进迁移。
旧版配置逻辑通常依赖 Object（如 Java Bean 或 JSON 对象） 的字段名直读、默认值回退、忽略大小写或驼峰/下划线自动映射等习惯，而 Map 更灵活但缺乏结构语义。要兼容旧逻辑，关键不是强行统一类型，而是让转换过程“模拟旧行为”，而非破坏原有调用链。
保留字段可读性与默认值逻辑
旧代码常假设：config.get("timeout") 返回 int，config.get("enableLog") 返回 boolean，且缺失时返回 null 或默认值。Map → Object 转换时若直接用 BeanUtils.populate()，它不会自动填充默认值，也不会做类型安全转换。
- 用
BeanUtils前先预处理 Map：补全缺失 key，按字段类型设默认值（如Integer.class → 0，Boolean.class → false） - 自定义
ConvertUtils.register()注册全局类型转换器，例如把字符串"1"自动转为Long，避免ConversionException - 不依赖字段名完全一致：用
PropertyUtils.setSimpleProperty(obj, "time_out", value)支持下划线转驼峰
兼容非字符串键与嵌套结构
旧配置可能含嵌套对象（如 {"db": {"host": "localhost", "port": 3306}}），或使用枚举/数字作 key（如 Map<integer string> statusMap = {...}</integer>）。直接用 Object.fromEntries() 或 BeanMap 会丢失类型或扁平化结构。
- Map → Object 时，对 value 是 Map 的字段，递归调用转换方法，保持嵌套 Bean 结构
- 若原始 Map 键是 Integer/Enum，先转为字符串再映射（如
String keyStr = String.valueOf(key)），并在目标类中提供对应 setter - 避免用
Object.fromEntries()处理含非字符串键的 Map；改用反射 +PropertyDescriptor，它只取 getter/setter 名称，不依赖 Map 的 key 类型
维持字段顺序与空值语义
部分旧逻辑依赖字段遍历顺序（如配置加载优先级）、或区分 null 与未设置（如 isSet("retry") 判断是否显式配置）。普通 HashMap 不保序，BeanMap 可能将 null 值过滤掉。
- 始终用
LinkedHashMap作为中间 Map，保证插入顺序与旧配置文件（如 properties/YAML）解析顺序一致 - Object → Map 时，不要跳过 null 值字段；用
Introspector+PropertyDescriptor获取所有属性，即使 getter 返回 null 也 put 进 map - 增加辅助方法
hasExplicitValue(obj, "fieldName")，通过反射读取字段原始值（非 getter），判断是否为初始 null（未赋值）还是业务 null
渐进式迁移不改调用方
最稳妥的方式不是重写所有配置读取代码，而是封装一层适配器：
- 定义接口
ConfigSource，旧实现返回UserConfig实例，新实现返回Map<string object></string>，但对外暴露相同 getXXX 方法 - 提供静态工厂
ConfigAdapters.fromMap(map).to(UserConfig.class)，内部自动处理类型转换、嵌套、默认值，返回强类型对象供旧代码继续使用 - 日志打点记录每次转换中字段类型不匹配、key 缺失等情况，便于发现潜在兼容问题
