Gson字段命名策略不生效于Map键 如何实现Map键横杠转下划线适配

问题根因 #

Gson 内置的setFieldNamingStrategy设计作用范围仅为Java类的声明成员字段名，执行流程完全不会介入Map类型的序列化/反序列化环节。对于所有Map结构（包括HashMap、MultivaluedMap以及各类Map衍生实现类），Gson默认的处理逻辑是直接将Map的原生键值对与JSON结构做一一映射，不会对Map的键名执行任何自定义命名规则的转换。

最优实现路径 #

不需要从零编写全量的Map序列化逻辑，仅需自定义一个拦截Map类型的TypeAdapterFactory，在Map键的读写切入点注入短横线转下划线的转换规则，即可同时兼容已有的普通字段命名策略，完全不侵入原有业务逻辑。
实现步骤：

1. 抽取统一的Map键转换规则，和现有命名策略的替换逻辑保持一致

   public class MapKeyNameConverter {
       /**
        * 统一键名转换：将短横线替换为下划线
        */
       public static String convertKey(String originalKey) {
           if (originalKey == null) {
               return null;
           }
           return originalKey.replace('-', '_');
       }
   }
   

   注意：Map键的转换不需要套用原字段策略里的UPPER_CAMEL_CASE规则。该规则是针对Java类的驼峰成员字段做大小写转换的，Map键本身就是JSON层面的原始键值，仅需执行短横线替换逻辑即可，避免出现非预期的键名变形。

2. 编写Map类型专用的TypeAdapterFactory，完全复用Gson原生的Map值处理能力，仅在键名读写环节做转换

   public class KeyTransformMapAdapterFactory implements TypeAdapterFactory {
       @Override
       public <T> TypeAdapter<T> create(Gson gson, TypeToken<T> typeToken) {
           // 仅拦截Map及其子类的处理流程，其他类型直接走Gson原生逻辑
           if (!Map.class.isAssignableFrom(typeToken.getRawType())) {
               return null;
           }
           // 获取Gson原生的Map处理Adapter作为代理，不重写值的序列化逻辑
           TypeAdapter<Map> delegate = (TypeAdapter<Map>) gson.getDelegateAdapter(this, typeToken);
           
           return (TypeAdapter<T>) new TypeAdapter<Map>() {
               // 序列化写JSON阶段：将Map原始键转换后再输出
               @Override
               public void write(JsonWriter out, Map value) throws IOException {
                   if (value == null) {
                       out.nullValue();
                       return;
                   }
                   out.beginObject();
                   for (Map.Entry entry : (Set<Map.Entry>) value.entrySet()) {
                       String rawKey = String.valueOf(entry.getKey());
                       String transformedKey = MapKeyNameConverter.convertKey(rawKey);
                       out.name(transformedKey);
                       // 值的序列化完全复用Gson原生能力，无侵入
                       gson.toJson(entry.getValue(), entry.getValue().getClass(), out);
                   }
                   out.endObject();
               }
   
               // 反序列化读JSON阶段：将JSON中读到的键转换后再存入Map
               @Override
               public Map read(JsonReader in) throws IOException {
                   if (in.peek() == JsonToken.NULL) {
                       in.nextNull();
                       return null;
                   }
                   // 根据业务需要替换为对应的Map实现类，比如MultiValuedTreeMap
                   Map result = new HashMap();
                   in.beginObject();
                   while (in.hasNext()) {
                       String rawJsonKey = in.nextName();
                       String transformedKey = MapKeyNameConverter.convertKey(rawJsonKey);
                       // 值的反序列化完全复用Gson原生能力，无侵入
                       Object value = gson.fromJson(in, Object.class);
                       result.put(transformedKey, value);
                   }
                   in.endObject();
                   return result;
               }
           };
       }
   }
   

   • 适配特殊Map实现的调整：如果业务要求反序列化后保留特定的Map类型（比如MultiValuedTreeMap、MultivaluedHashMap），仅需在read方法初始化结果集时，根据传入的TypeToken判断目标类型，替换为对应的Map实现类即可，不需要编写单独的Adapter。

3. 将自定义Factory注册到Gson实例中，注册顺序需放在默认适配器之前，保证拦截生效

   private static Gson gson = new GsonBuilder()
       .setFieldNamingStrategy(new ApiEventNamingStrategy())
       // 注册Map键转换的适配器工厂
       .registerTypeAdapterFactory(new KeyTransformMapAdapterFactory())
       .create();
   

方案优势 #

• 对原有逻辑零侵入：普通Java类的字段序列化、值的格式兼容、JSON流的边界校验等逻辑全部复用Gson原生实现，不会出现序列化精度丢失、特殊值处理异常的问题。
• 全局统一生效：不管是ApiGatewayAuthorizerContext中嵌套的contextProperties Map，还是AwsProxyRequest里的MultiValuedTreeMap Header结构，所有Map类型的键都会自动执行短横线到下划线的转换，不需要在业务代码里手动做键名重写。
• 不需要修改上游配置：因为转换逻辑完全在Gson的序列化边界完成，不需要调整AWS API Gateway、Lambda的运行逻辑，也不需要修改下游对接组件的解析规则，对业务代码完全透明。

内容的提问来源于stack exchange，提问作者Jimson James