The Hidden Pitfalls of Lombok’s @UtilityClass Annotation

Yesterday, I encountered a perplexing issue — all static imports in one of my modules seemed to be broken from the builder’s perspective, yet IntelliJ didn’t highlight anything amiss. After reviewing the code, I was unable to find anything that could have caused this issue.

Here’s a bit of context: I moved some methods from a regular class to a utility one. To simplify this process, I used the @UtilityClass annotation from Lombok, which would automatically mark the methods as static and add a private constructor, instead of me having to do these steps manually.

So I started the short research about the annotation usage. And lombok dev has already provided an answer in 2017:

The root of the problem lies in the intricacies of the Java compiler (javac). While Java allows the import of static methods, javac does not recognize the static methods generated by Lombok at compile time. This is because Lombok generates them during the annotation processing phase, which occurs after javac’s parsing phase. Therefore, the static methods are not available when javac checks for their existence during parsing.

The @UtilityClass annotation is found in the package lombok.experimental, and now I understand why it's deemed "experimental". Given this unexpected behavior and potential for compiler confusion, it's something to use with caution.