Java: fill the gaps

Fluent API: что такое и зачем нужен



Fluent API набирает популярность последние лет 5 и часто вызывает вопросы:

🤔 В чём его польза?

🤔 Чем он отличается от билдера?

🤔 Когда нужен, а когда нет?



В этом и следующем посте постараюсь ответить на эти вопросы.



Основная задача Fluent API — улучшить читаемость кода. Для этого:



🔸 Несколько методов объединяются в цепочку и вызываются друг за другом. Получается логический блок, который воспринимается как единое целое

🔸 Названия методов не ограничиваются глаголом



Пример:

CompletableFuture.runAsync(…).thenRun(…).exceptionally(…);

Fluent API не всегда уместен и не всегда реализован удачно. Список формальных условий определить сложно, на практике такой формат часто выбирается интуитивно. Поэтому рассмотрим побольше примеров!



✅ Хороший пример из AssertJ:

assertThat(str).startsWith(…).contains(…);

За раз пишем несколько проверок для строки str. Без Fluent API кода будет больше



✅ Хороший пример из Мокито:

when(mock.method()).thenReturn(…).thenReturn(…).thenThrow(…);

Читается как одно предложение. Мне даже сложно представить, как это написать в “традиционном” стиле:)



✅ Прекрасный пример из Spring JDBC:

List<User > users = jdbcClient.sql(…)

.param("rating", 5, Types.INTEGER)

.query(mapper)

.list();

Почему пример прекрасен? Потому что Fluent API скрывает работу с объектом PreparedStatement. Код получается не только короче, но и проще🔥



😐 Так себе пример из Spring Data:

ExampleMatcher matcher = ExampleMatcher.matching()

.withIgnorePaths(…)

.withStringMatcher(StringMatcher.ENDING);

Приставка with у методов лишняя, название последнего метода неудачное



❌ Плохой пример из SLF4J:

logger.atInfo().log(…);

Классический logger.info(…) короче и удобнее



❌ Плохой пример из популярного джава канала:

Person person = new Person().setName(…).setAge(…);

Тоже никакой пользы от Fluent API, ни по читаемости, ни по удобству использования.



Итого



Fluent API подойдёт, когда работа с объектом проходит в несколько шагов, но единым логическим блоком. Основная цель — улучшить читаемость. Высший пилотаж — повысить с помощью Fluent API уровень инкапсуляции.



Чтобы сделать удобно и красиво, нужен опыт, насмотренность и немножко вдохновения:)



Отдельный случай — Fluent API при создании объектов. Здесь часто возникает путаница с билдером, и непонятно, что когда использовать. Этот вопрос я разберу отдельно в следующем посте🔥