Spring Boot中Lombok与Jackson序列化异常解决方案

前言

本文记录了在Spring Boot应用开发过程中遇到的与Lombok和Jackson序列化相关的两个常见异常，并提供了详细的解决方案。这些异常表现为：

com.fasterxml.jackson.databind.exc.InvalidDefinitionException: No serializer found for class com.example.entity.Dept and no properties discovered to create BeanSerializer

以及：

org.springframework.web.HttpMediaTypeNotAcceptableException: No acceptable representation

这两个异常虽然表现形式不同，但根源相同，都与Lombok注解处理器的配置有关。本文将分析异常产生的原因，并提供基于Maven配置的解决方案，帮助开发者在项目中正确配置Lombok与Spring Boot的集成。

问题场景

本案例基于以下技术栈：一个标准的Spring Boot REST应用，使用Lombok简化代码，使用MyBatis访问数据库，通过REST接口返回JSON数据。

实体类定义：

@Data
public class Dept {
    private Long id;
    private String name;
    // 其他字段...
}

控制器实现：

@RestController
@RequestMapping("/api")
public class DeptController {
    @Autowired
    private DeptService deptService;
    
    @GetMapping("/depts")
    public List<Dept> getDepts() {
        return deptService.list();  // 异常发生位置
    }
}

这种标准配置下，项目可以正常编译，但在运行时会抛出以下异常：

Closing non transactional SqlSession [org.apache.ibatis.session.defaults.DefaultSqlSession@79fdcea4]
ERROR o.a.c.c.C.[.[.[/].[dispatcherServlet] : Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed: org.springframework.http.converter.HttpMessageConversionException: Type definition error: [simple type, class com.exmaple.entity.Dept]] with root cause
com.fasterxml.jackson.databind.exc.InvalidDefinitionException: No serializer found for class com.exmaple.entity.Dept and no properties discovered to create BeanSerializer

这个异常表明，尽管使用了Lombok的@Data注解，但Jackson在尝试序列化对象时无法找到必要的getter方法。

问题分析

通过深入分析，可以确定问题的根本原因：

1. Jackson序列化机制：Jackson在序列化Java对象为JSON时，默认通过getter方法访问属性值
2. Lombok注解处理机制：Lombok通过注解处理器在编译期生成代码，而非运行时
3. 构建配置缺陷：Maven项目中Lombok的注解处理器未被正确配置，导致编译后的字节码中缺少必要的getter方法

通过检查项目的pom.xml配置，发现以下问题：

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>  <!-- 配置不当的位置 -->
</dependency>

关键缺陷在于：

1. 使用了<optional>true</optional>而非<scope>provided</scope>
2. 未配置Maven编译插件的注解处理器路径
3. 未显式指定Lombok版本号

常见的临时解决方案

在确定根本原因前，可能尝试过以下解决方案：

1. 修改Jackson配置，禁用空Bean检查

   @Bean
   public ObjectMapper objectMapper() {
       ObjectMapper mapper = new ObjectMapper();
       mapper.disable(SerializationFeature.FAIL_ON_EMPTY_BEANS);
       return mapper;
   }

   结果：导致第二个异常 No acceptable representation

2. 放弃Lombok，手动添加getter/setter方法
   这种方案违背了使用Lombok的初衷，不推荐

3. 使用Jackson注解强制字段访问

   @JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.ANY)
   @Data
   public class Dept { ... }

   结果：无法彻底解决问题

根本解决方案

经过分析和验证，确定了彻底解决这一问题的方法是正确配置Maven构建过程中的Lombok注解处理器。具体方案包括两个关键步骤：

1. 修改Lombok依赖配置：将<optional>true</optional>替换为<scope>provided</scope>
2. 添加Maven编译插件的注解处理器路径配置

标准配置示例如下：

<!-- Lombok依赖的正确配置 -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.36</version>  <!-- 明确指定版本号 -->
    <scope>provided</scope>     <!-- 使用 <scope>provided</scope> 而非 <optional>true</optional> -->
</dependency>

<!-- Maven编译插件配置 -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.10.1</version>
    <configuration>
        <source>${java.version}</source>
        <target>${java.version}</target>
        <annotationProcessorPaths>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>1.18.36</version>  <!-- 版本号必须明确指定,并和上面配置的依赖版本一致 -->
            </path>
            <!-- 其他注解处理器可在此处添加 -->
        </annotationProcessorPaths>
        <compilerArgs>
            <arg>-parameters</arg>  <!-- 保留参数名信息，有助于Spring功能 -->
        </compilerArgs>
    </configuration>
</plugin>

• 或者如下：(简化版，只需要配置Lombok版本号，即可)

<!-- Lombok依赖的正确配置 -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>1.18.36</version>  <!-- 明确指定版本号 -->
    <scope>provided</scope>     <!-- 使用 <scope>provided</scope> 而非 <optional>true</optional> -->
</dependency>

<!-- Maven编译插件配置 -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>1.18.36</version>  <!-- 版本号必须明确指定,并和上面配置的依赖版本一致 -->
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

完成配置修改后，执行mvn clean compile重新编译项目，然后重启应用。此时，Jackson序列化正常工作，REST接口可以正确返回JSON数据。

分析

1. Maven依赖作用域的区别

• <scope>provided</scope>：

  • 表示依赖在编译和测试阶段可用
  • 运行时期望由JDK或容器提供（对Lombok这类编译时工具尤其适合）
  • 确保注解处理器能够在编译期正确激活

• <optional>true</optional>：

  • 表示该依赖对于其他项目是可选的，主要用于传递依赖控制
  • 不影响当前项目的注解处理机制
  • 不适合标记编译时注解处理器

2. Maven注解处理器机制

• annotationProcessorPaths的作用：

  • 显式告知编译器哪些依赖是注解处理器
  • 将注解处理器添加到编译类路径中
  • 确保注解处理器按正确顺序执行

• 版本一致性：

  • 依赖声明和注解处理器路径中的版本必须一致
  • 避免使用继承的版本变量，减少潜在错误

3. 问题诊断难点

• 编译与运行时差异：

  • IDE插件模拟了Lombok功能，使开发阶段未发现问题
  • 编译可以通过是因为代码中未直接调用getter/setter
  • 问题只在运行时Jackson尝试序列化时才显现

最佳实践建议

基于对此问题的分析，总结以下在Spring Boot项目中使用Lombok的最佳实践：

1. 依赖配置规范

• 使用<scope>provided</scope>标记Lombok依赖
• 明确指定版本号，避免使用变量或继承版本
• 不要对Lombok使用<optional>true</optional>标记

2. 编译插件配置

• 配置Maven编译插件的annotationProcessorPaths节点
• 在注解处理器路径中也明确指定版本号
• 考虑添加-parameters编译参数，增强Spring反射功能

3. 版本管理策略

• 确保Lombok依赖版本与注解处理器路径中的版本完全一致
• 定期更新Lombok版本，使用稳定发布版
• 在整个项目组中统一Lombok版本

4. IDE配置同步

• 安装相应IDE的Lombok插件（IntelliJ IDEA或Eclipse等）
• 项目配置变更后重新导入或刷新项目结构
• 定期清理IDE缓存，确保与实际构建结果一致

总结

本文详细分析了Spring Boot项目中Lombok与Jackson序列化相关的常见异常问题，从技术原理角度阐述了问题产生的根本原因，并提供了系统的解决方案。通过正确配置Maven中的Lombok依赖和注解处理器路径，可以彻底解决这类序列化异常。

关键配置要点：

1. 将Lombok依赖标记为provided而非optional
2. 配置Maven编译插件的注解处理器路径
3. 明确指定一致的版本号

此解决方案不仅适用于文中描述的特定异常，也可以预防其他由Lombok注解处理不当导致的问题，对提升Java项目构建质量具有实际意义。

参考资料

1. Lombok官方文档：Maven配置
2. Spring Boot与Lombok集成指南
3. Maven编译插件文档
4. Jackson序列化文档
5. Maven依赖作用域说明
6. 注解处理API文档