如何在Jackson JSON序列化/反序列化中自定义处理含自定义键类型的Map属性？

看起来你遇到的问题很典型——明明给带复杂键的Map加了自定义序列化/反序列化注解，结果却没起作用，反序列化还是失败。结合你的描述，我整理几个大概率的原因和对应的排查/解决方法：

1. 注解的使用方式是否正确 #

首先要确认你用对了注解的参数：

• 如果你是要把整个Map转换成列表，而不是单独处理键或值，那么应该用@JsonSerialize(using = YourMapToListSerializer.class)和@JsonDeserialize(using = YourListToMapDeserializer.class)，而不是keyUsing或contentUsing。这两个参数是用来单独处理Map的键或者值的序列化，和你要整体转结构的需求不匹配。
• 另外，注解的位置也很关键：如果你的字段有对应的getter/setter方法，Jackson默认会优先处理方法上的注解，而不是字段本身。所以要么把注解加在getter（序列化）和setter（反序列化）上，要么在类上加上@JsonPropertyAccess(JsonPropertyAccess.READ_WRITE)强制Jackson读取字段上的注解。

2. 自定义转换器的实现是否符合要求 #

你提到转换后输出是列表，那要确保你的序列化器和反序列化器逻辑是正确的：

• 序列化器示例：

public class YourMapToListSerializer extends JsonSerializer<Map<ComplexKey, YourValue>> {
    @Override
    public void serialize(Map<ComplexKey, YourValue> map, JsonGenerator gen, SerializerProvider serializers) throws IOException {
        // 把Map转成包含键值对的列表，比如List<MapEntryDto>
        List<MapEntryDto> entries = map.entrySet().stream()
                .map(entry -> new MapEntryDto(entry.getKey(), entry.getValue()))
                .collect(Collectors.toList());
        gen.writeObject(entries);
    }
}

• 反序列化器示例：

public class YourListToMapDeserializer extends JsonDeserializer<Map<ComplexKey, YourValue>> {
    @Override
    public Map<ComplexKey, YourValue> deserialize(JsonParser p, DeserializationContext ctxt) throws IOException {
        List<MapEntryDto> entries = p.readValueAs(new TypeReference<List<MapEntryDto>>() {});
        return entries.stream()
                .collect(Collectors.toMap(MapEntryDto::getKey, MapEntryDto::getValue));
    }
}

要注意：这里的MapEntryDto是一个简单的DTO类，包含ComplexKey和YourValue的字段，用来在JSON中表示键值对。如果你的转换器没有生成这种明确的列表结构，Jackson可能还是会尝试默认的Map序列化逻辑，导致注解失效。

3. Jackson的配置是否覆盖了注解 #

如果你用的是Spring Boot这类框架，有时候全局的ObjectMapper配置可能会影响注解的生效：

• 检查有没有自定义的Jackson2ObjectMapperBuilder或者ObjectMapper Bean，是否设置了disable(MapperFeature.USE_ANNOTATIONS)这类会禁用注解的配置。
• 如果你的自定义序列化器没有通过注解生效，可以尝试手动注册到ObjectMapper里：

@Bean
public ObjectMapper objectMapper() {
    ObjectMapper mapper = new ObjectMapper();
    SimpleModule module = new SimpleModule();
    module.addSerializer(new YourMapToListSerializer());
    module.addDeserializer(new TypeReference<Map<ComplexKey, YourValue>>() {}, new YourListToMapDeserializer());
    mapper.registerModule(module);
    return mapper;
}

这种方式相当于全局注册，会覆盖注解的优先级，但可以确保序列化器被正确使用。

4. 复杂键的潜在干扰 #

虽然你认为不需要键序列化器，但如果你的ComplexKey类没有正确实现equals()和hashCode()方法，在反序列化转成Map的时候会出现键重复或者找不到的问题，表现出来像是反序列化失败。一定要确保ComplexKey的这两个方法是根据业务逻辑正确实现的，否则即使转换器把列表转成了Map，后续的操作也会出问题。

先从这几个方向排查，应该能找到注解不生效的原因。

内容的提问来源于stack exchange，提问作者Kalle Richter