本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

Amazon QLDB 司機推薦

本節說明針對任何支援的語言設定和使用 Amazon QLDB 驅動程式的最佳實務。所提供的程式碼範例專為 Java 而設。

這些建議適用於大多數典型的使用案例，但一種大小並不適合所有使用案例。根據您認為適合您的應用程式，請使用下列建議。

配置對 QldbDriver 象

該QldbDriver對象通過維護跨交易重複使用的會話集區來管理與分類帳的連接。會話表示到分類帳的單個連接。QLDB每個會話支持一個主動運行的事務。

配置 QldbDriver 為全域物件

若要最佳化驅動程式和工作階段的使用，請確定應用程式執行個體中只有一個驅動程式的全域執行個體。例如在 Java 中，您可以使用依賴注入框架，如 S pring，谷歌 Guice 或匕首。下面的代碼示例演示了如何配置QldbDriver為單例。

@Singleton
public QldbDriver qldbDriver (AWSCredentialsProvider credentialsProvider,
                                    @Named(LEDGER_NAME_CONFIG_PARAM) String ledgerName) {
    QldbSessionClientBuilder builder = QldbSessionClient.builder();
    if (null != credentialsProvider) {
        builder.credentialsProvider(credentialsProvider);
    }
    return QldbDriver.builder()
            .ledger(ledgerName)
            .transactionRetryPolicy(RetryPolicy
                .builder()
                .maxRetries(3)
                .build())
            .sessionClientBuilder(builder)
            .build();
}

設定重試嘗試

當發生常見的暫時性例外狀況 (例如SocketTimeoutException或NoHttpResponseException) 時，驅動程式會自動重試交易。若要設定重試嘗試的次數上限，您可以在建立的執行個體時使用transactionRetryPolicy組態物件的maxRetries參數QldbDriver。(如果是上一節所列的舊版驅動程式版本，請使用的retryLimit參數PooledQldbDriver。)

maxRetries 的預設值為 4。

用戶端錯誤 (例如InvalidParameterException無法重試)。當它們發生時，事務被中止，會話返回到池，並將異常拋出到驅動程序的客戶端。

設定同時工作階段和交易的最大數目

執行環境用QldbDriver來執行交易的分類帳階段作業數目上限是由其maxConcurrentTransactions參數所定義。(對於上一節所列的舊版驅動程式版本，這是由的poolLimit參數定義PooledQldbDriver。)

此限制必須大於零且小於或等於工作階段用戶端允許的開啟HTTP連線數目上限 (如具體的定義) AWS SDK。例如，在 Java 中，在ClientConfiguration對象中設置了最大連接數。

的預設值maxConcurrentTransactions是您的最大連線設定 AWS SDK。

在應用程式QldbDriver中設定時，請考慮下列擴展考量：

重試例外

重試中發生的例外狀況時QLDB，請考慮下列建議。

重試 OccConflictException

當交易所存取的資料自交易開始以來已變更時，就會發生最佳並行控制 (OCC) 衝突例外狀況。QLDB嘗試提交交易時拋出此異常。驅動程式會根據設定的次數重試交易。maxRetries

如需使用索引來限制OCC衝突的詳細資訊OCC和最佳作法，請參閱Amazon QLDB 并发模型。

重試以外的其他例外 QldbDriver

若要在執行階段期間擲回自訂、應用程式定義的例外狀況時，重試驅動程式外部的交易，您必須封裝交易。例如，在 Java 中，下面的代碼演示了如何使用 Reslience4j 庫重試中的事務。QLDB

private final RetryConfig retryConfig = RetryConfig.custom()
        .maxAttempts(MAX_RETRIES)
        .intervalFunction(IntervalFunction.ofExponentialRandomBackoff())
        // Retry this exception
        .retryExceptions(InvalidSessionException.class, MyRetryableException.class)
        // But fail for any other type of exception extended from RuntimeException
        .ignoreExceptions(RuntimeException.class)
        .build();

// Method callable by a client
public void myTransactionWithRetries(Params params) {
    Retry retry = Retry.of("registerDriver", retryConfig);

    Function<Params, Void> transactionFunction = Retry.decorateFunction(
            retry,
            parameters ->  transactionNoReturn(params));
    transactionFunction.apply(params);
}

private Void transactionNoReturn(Params params) {
    try (driver.execute(txn -> {
            // Transaction code
        });
    }
    return null;
}

使交易冪等

作為最佳實踐，使寫入事務具有冪等性，以避免在重試的情況下出現任何意外的副作用。如果事務可以運行多次並每次產生相同的結果，則事務是冪等的。

如需進一步了解，請參閱Amazon QLDB 并发模型。

最佳化效能

若要在使用驅動程式執行交易時最佳化效能，請考量下列事項：

每個交易執行多個陳述式

如上一節所述，您可以針對每個交易執行多個陳述式，以最佳化應用程式的效能。在下列程式碼範例中，您會查詢資料表，然後在交易中更新該資料表中的文件。您可以通過將 lambda 表達式傳遞給操作來完成此execute操作。

Java

// This code snippet is intentionally trivial. In reality you wouldn't do this because you'd
// set your UPDATE to filter on vin and insured, and check if you updated something or not.
public static boolean InsureCar(QldbDriver qldbDriver, final String vin) {
    final IonSystem ionSystem = IonSystemBuilder.standard().build();
    final IonString ionVin = ionSystem.newString(vin);

    return qldbDriver.execute(txn -> {
        Result result = txn.execute(
                "SELECT insured FROM Vehicles WHERE vin = ? AND insured = FALSE",
                ionVin);
        if (!result.isEmpty()) {
            txn.execute("UPDATE Vehicles SET insured = TRUE WHERE vin = ?", ionVin);
            return true;
        }
        return false;
    });
}

.NET

// This code snippet is intentionally trivial. In reality you wouldn't do this because you'd
// set your UPDATE to filter on vin and insured, and check if you updated something or not.
public static async Task<bool> InsureVehicle(IAsyncQldbDriver driver, string vin)
{
    ValueFactory valueFactory = new ValueFactory();
    IIonValue ionVin = valueFactory.NewString(vin);

    return await driver.Execute(async txn =>
    {
        // Check if the vehicle is insured.
        Amazon.QLDB.Driver.IAsyncResult result = await txn.Execute(
            "SELECT insured FROM Vehicles WHERE vin = ? AND insured = FALSE", ionVin);

        if (await result.CountAsync() > 0)
        {
            // If the vehicle is not insured, insure it.
            await txn.Execute(
                "UPDATE Vehicles SET insured = TRUE WHERE vin = ?", ionVin);
            return true;
        }
        return false;
    });
}

Go

// This code snippet is intentionally trivial. In reality you wouldn't do this because you'd
// set your UPDATE to filter on vin and insured, and check if you updated something or not.
func InsureCar(driver *qldbdriver.QLDBDriver, vin string) (bool, error) {
    insured, err := driver.Execute(context.Background(), func(txn qldbdriver.Transaction) (interface{}, error) {

        result, err := txn.Execute(
            "SELECT insured FROM Vehicles WHERE vin = ? AND insured = FALSE", vin)
        if err != nil {
            return false, err
        }

        hasNext := result.Next(txn)
        if !hasNext && result.Err() != nil {
            return false, result.Err()
        }

        if hasNext {
            _, err = txn.Execute(
                "UPDATE Vehicles SET insured = TRUE WHERE vin = ?", vin)
            if err != nil {
                return false, err
            }
            return true, nil
        }
        return false, nil
    })
    if err != nil {
        panic(err)
    }

    return insured.(bool), err
}

Node.js

// This code snippet is intentionally trivial. In reality you wouldn't do this because you'd
// set your UPDATE to filter on vin and insured, and check if you updated something or not.
async function insureCar(driver: QldbDriver, vin: string): Promise<boolean> {

    return await driver.executeLambda(async (txn: TransactionExecutor) => {
        const results: dom.Value[] = (await txn.execute(
            "SELECT insured FROM Vehicles WHERE vin = ? AND insured = FALSE", vin)).getResultList();

        if (results.length > 0) {
            await txn.execute(
                "UPDATE Vehicles SET insured = TRUE WHERE vin = ?", vin);
            return true;
        }
        return false;
    });
};

Python

# This code snippet is intentionally trivial. In reality you wouldn't do this because you'd
# set your UPDATE to filter on vin and insured, and check if you updated something or not.

def do_insure_car(transaction_executor, vin):
    cursor = transaction_executor.execute_statement(
        "SELECT insured FROM Vehicles WHERE vin = ? AND insured = FALSE", vin)
    first_record = next(cursor, None)
    if first_record:
        transaction_executor.execute_statement(
            "UPDATE Vehicles SET insured = TRUE WHERE vin = ?", vin)
        return True
    else:
        return False

def insure_car(qldb_driver, vin_to_insure):
    return qldb_driver.execute_lambda(
        lambda executor: do_insure_car(executor, vin_to_insure))

驅動程序的execute操作隱式啟動會話和該會話中的事務。您在 lambda 運算式中執行的每個陳述式都會包裝在交易中。執行所有陳述式之後，驅動程式會自動提交交易。如果在自動重試限制用盡之後有任何陳述式失敗，就會中止交易。

在交易中傳播例外

當每個交易執行多個陳述式時，我們通常不建議您在交易中 catch 並吞下例外狀況。

例如，在 Java 中，下列程式會擷取的任何執行個體RuntimeException、記錄錯誤並繼續。這個程式碼範例被認為是不好的做法，因為即使UPDATE陳述式失敗，交易也會成功。因此，用戶端可能會假設更新沒有成功。

// DO NOT USE this code example because it is considered bad practice
public static void main(final String... args) {
    ConnectToLedger.getDriver().execute(txn -> {
        final Result selectTableResult = txn.execute("SELECT * FROM Vehicle WHERE VIN ='123456789'");
        // Catching an error inside the transaction is an anti-pattern because the operation might
        // not succeed.
        // In this example, the transaction succeeds even when the update statement fails.
        // So, the client might assume that the update succeeded when it didn't.
        try {
            processResults(selectTableResult);
            String model = // some code that extracts the model
            final Result updateResult = txn.execute("UPDATE Vehicle SET model = ? WHERE VIN = '123456789'",
                    Constants.MAPPER.writeValueAsIonValue(model));
        } catch (RuntimeException e) {
            log.error("Exception when updating the Vehicle table {}", e.getMessage());
        }
    });
    log.info("Vehicle table updated successfully.");
}

傳播（冒泡）異常。如果交易的任何部分失敗，讓execute作業中止交易，以便用戶端可以相應地處理例外狀況。