我們知道，在軟件項目中，沒有什么能取代好的文檔。但是，也需要注意寫出的代碼有多直觀。畢竟，代碼越簡單自然，用戶體驗就越好。
在簡單的“編程規(guī)則”中，我們將忘記我們必須記住的一切，“強制”你記住的 API 是失敗的關(guān)鍵證明。
這就是為什么在本文中，我們將介紹該主題并向你展示如何從 Fluent-API 概念創(chuàng)建流體 API。
什么是 Fluent-API？
當(dāng)我們在軟件工程的上下文中談?wù)摃r，fluent-API 是一種面向?qū)ο蟮?API，其設(shè)計主要基于方法鏈。
這個概念由?Eric Evans?和?Martin Fowler?于 2005 年創(chuàng)建，旨在通過創(chuàng)建特定領(lǐng)域語言 ( DSL )來提高代碼可讀性。
在實踐中，創(chuàng)建一個流暢的 API 意味著開發(fā)一個 API，其中不需要記住接下來的步驟或方法，允許一個自然連續(xù)的序列，就好像它是一個選項菜單。
這種自然的節(jié)奏與餐廳甚至快餐連鎖店的工作方式類似，因為當(dāng)您將一道菜放在一起時，選項會根據(jù)你所做的選擇而有所不同。例如，如果你選擇雞肉三明治，則會根據(jù)所選菜肴等建議配菜。
Java 上下文中的 Fluent API
在 Java 世界中，我們可以想到此類實現(xiàn)的兩個著名示例。
第一個是?JOOQ?框架，這是一個由Lukas Eder領(lǐng)導(dǎo)的項目，它促進了 Java 和關(guān)系數(shù)據(jù)庫之間的通信。JOOQ 最顯著的區(qū)別在于它是面向數(shù)據(jù)的，這有助于避免和/或減少與關(guān)系和面向?qū)ο笙嚓P(guān)的阻抗問題或損失。
Query query = create.select(BOOK.TITLE, AUTHOR.FIRST_NAME, AUTHOR.LAST_NAME)
.from(BOOK)
.join(AUTHOR)
.on(BOOK.AUTHOR_ID.eq(AUTHOR.ID))
.where(BOOK.PUBLISHED_IN.eq(1948));
String sql = query.getSQL();
List<Object> bindValues = query.getBindValues();另一個例子是在企業(yè) Java 世界規(guī)范內(nèi)的非關(guān)系數(shù)據(jù)庫，即 NoSQL。其中包括Jakarta EE，它是同類中的第一個規(guī)范，并成為Eclipse Foundation旗下的Jakarta NoSQL。
本規(guī)范的目的是確保 Java 和 NoSQL 數(shù)據(jù)庫之間的順暢通信。
DocumentQuery query = select().from("Person").where(eq(Document.of("_id", id))).build();
Optional<Person> person = documentTemplate.singleResult(query);
System.out.println("Entity found: " + person);一般來說，一個 fluent API 分為三個部分：
- 最終的對象或結(jié)果：總的來說，fluent-API 類似于構(gòu)建器模式，但最強大的動態(tài)與 DSL 相結(jié)合。在這兩種情況下，結(jié)果往往是代表流程或新實體結(jié)果的實例。
- 選項：在這種情況下，是將用作“我們的交互式菜單”的接口或類的集合。從一個動作來看，這個想法是按照直觀的順序只顯示下一步可用的選項。
- 結(jié)果：在所有這個過程之后，答案可能會或可能不會導(dǎo)致實體、策略等的實例。關(guān)鍵點是結(jié)果必須是有效的。
流體 API 實踐
為了演示這一概念，我們將創(chuàng)建一個三明治訂單，其中包含具有相應(yīng)購買價格的訂單的預(yù)期結(jié)果。流程如下所示。
當(dāng)然，有多種方法可以實現(xiàn)這種流暢的 API 功能，但我們選擇了一個簡短的版本。
正如我們已經(jīng)提到的 API 的三個部分——對象、選項和結(jié)果——我們將從“訂單”接口將表示的順序開始。一個亮點是這個界面有一些界面，它們將負責(zé)展示我們的選項。
public interface Order {
interface SizeOrder {
StyleOrder size(Size size);
}
interface StyleOrder {
StyleQuantityOrder vegan();
StyleQuantityOrder meat();
}
interface StyleQuantityOrder extends DrinksOrder {
DrinksOrder quantity(int quantity);
}
interface DrinksOrder {
Checkout softDrink(int quantity);
Checkout cocktail(int quantity);
Checkout softDrink();
Checkout cocktail();
Checkout noBeveragesThanks();
}
static SizeOrder bread(Bread bread) {
Objects.requireNonNull(bread, "Bread is required o the order");
return new OrderFluent(bread);
}這個 API 的結(jié)果將是我們的訂單類。它將包含三明治、飲料及其各自的數(shù)量。
在我們返回教程之前的快速附加組件
我們不會在本文中關(guān)注但值得一提的一點與貨幣的表示有關(guān)。
當(dāng)涉及到數(shù)值運算時，最好使用 BigDecimal。那是因為，根據(jù)Java Effective書籍和博客When Make a Type 之類的參考資料，我們了解到復(fù)雜類型需要唯一的類型。這種推理，再加上“不要重復(fù)自己”的實用主義，結(jié)果就是使用了 Java 貨幣規(guī)范：?The Money API?。
import javax.money.MonetaryAmount;
import java.util.Optional;
public class Checkout {
private final Sandwich sandwich;
private final int quantity;
private final Drink drink;
private final int drinkQuantity;
private final MonetaryAmount total;
//...
}旅程的最后一步是 API 實現(xiàn)。它將負責(zé)代碼的“丑陋”部分，使 API 看起來很漂亮。
由于我們不使用數(shù)據(jù)庫或其他數(shù)據(jù)引用，因此價格表將直接放置在代碼中，并且我們打算使示例盡可能簡單。但值得強調(diào)的是，在自然環(huán)境中，這些信息會存在于數(shù)據(jù)庫或服務(wù)中。
import javax.money.MonetaryAmount;
import java.util.Objects;
class OrderFluent implements Order.SizeOrder, Order.StyleOrder, Order.StyleQuantityOrder, Order.DrinksOrder {
private final PricingTables pricingTables = PricingTables.INSTANCE;
private final Bread bread;
private Size size;
private Sandwich sandwich;
private int quantity;
private Drink drink;
private int drinkQuantity;
OrderFluent(Bread bread) {
this.bread = bread;
}
@Override
public Order.StyleOrder size(Size size) {
Objects.requireNonNull(size, "Size is required");
this.size = size;
return this;
}
@Override
public Order.StyleQuantityOrder vegan() {
createSandwich(SandwichStyle.VEGAN);
return this;
}
@Override
public Order.StyleQuantityOrder meat() {
createSandwich(SandwichStyle.MEAT);
return this;
}
@Override
public Order.DrinksOrder quantity(int quantity) {
if (quantity <= 0) {
throw new IllegalArgumentException("You must request at least one sandwich");
}
this.quantity = quantity;
return this;
}
@Override
public Checkout softDrink(int quantity) {
if (quantity <= 0) {
throw new IllegalArgumentException("You must request at least one sandwich");
}
this.drinkQuantity = quantity;
this.drink = new Drink(DrinkType.SOFT_DRINK, pricingTables.getPrice(DrinkType.SOFT_DRINK));
return checkout();
}
@Override
public Checkout cocktail(int quantity) {
if (quantity <= 0) {
throw new IllegalArgumentException("You must request at least one sandwich");
}
this.drinkQuantity = quantity;
this.drink = new Drink(DrinkType.COCKTAIL, pricingTables.getPrice(DrinkType.COCKTAIL));
return checkout();
}
@Override
public Checkout softDrink() {
return softDrink(1);
}
@Override
public Checkout cocktail() {
return cocktail(1);
}
@Override
public Checkout noBeveragesThanks() {
return checkout();
}
private Checkout checkout() {
MonetaryAmount total = sandwich.getPrice().multiply(quantity);
if (drink != null) {
MonetaryAmount drinkTotal = drink.getPrice().multiply(drinkQuantity);
total = total.add(drinkTotal);
}
return new Checkout(sandwich, quantity, drink, drinkQuantity, total);
}
private void createSandwich(SandwichStyle style) {
MonetaryAmount breadPrice = pricingTables.getPrice(this.bread);
MonetaryAmount sizePrice = pricingTables.getPrice(this.size);
MonetaryAmount stylePrice = pricingTables.getPrice(SandwichStyle.VEGAN);
MonetaryAmount total = breadPrice.add(sizePrice).add(stylePrice);
this.sandwich = new Sandwich(style, this.bread, this.size, total);
}
}結(jié)果是一個 API，它將直接直觀地將請求返回給我們。
Checkout checkout = Order.bread(Bread.PLAIN)
.size(Size.SMALL)
.meat()
.quantity(2)
.softDrink(2);Fluent API 與其他模式有何不同？
對兩種 API 標(biāo)準(zhǔn)進行比較是很普遍的，它們是 Builder 和 Fluent-API。原因是它們在創(chuàng)建實例的過程中都按順序使用方法。
但是，F(xiàn)luent-API 是“與 DSL 相關(guān)聯(lián)的”，它強制采用一種簡單的方法來實現(xiàn)這一點。但為了使這些差異更加明顯，我們?yōu)槊總€模式分別列出了亮點：
Builder 模式：
- 它往往更容易實施；
- 不清楚需要哪些施工方法；
- 絕大多數(shù)問題都會在運行時發(fā)生；
- 一些工具和框架會自動創(chuàng)建它；
- 它需要在 build 方法中進行更健壯的驗證，以檢查哪些強制方法沒有被調(diào)用。
流利的API：
- 重要的是，對于每個方法，都有驗證，如果參數(shù)無效則拋出錯誤，記住快速失敗的前提；
- 它必須在過程結(jié)束時返回一個有效的對象。
現(xiàn)在，是否更容易理解模式之間的異同？
這就是我們對 fluent-API 概念的介紹。與所有解決方案一樣，沒有“靈丹妙藥”，因為整個過程通常不合理。
它是一個出色的工具，有助于為你和其他用戶創(chuàng)建故障保護。
