Transactions事务

Causal Consistency因果一致性

MongoDB enables causal consistency in certain client sessions. The causal consistency model guarantees that in a distributed system, operations within a session run in a causal order. MongoDB在某些客户端会话中实现了因果一致性。因果一致性模型保证在分布式系统中，会话内的操作按照因果顺序运行。Clients observe results that are consistent with the causal relationships, or the dependencies between operations. 客户观察到的结果与因果关系或操作之间的依赖关系一致。For example, if you perform a series of operations where one operation logically depends on the result of another, any subsequent reads reflect the dependent relationship.例如，如果执行一系列操作，其中一个操作在逻辑上依赖于另一个操作的结果，则任何后续读取都会反映依赖关系。

To guarantee causal consistency, client sessions must fulfill the following requirements:为保证因果一致性，客户会话必须满足以下要求：

• When starting a session, the driver must enable the causal consistency option. This option is enabled by default.开始会话时，驾驶员必须启用因果一致性选项。默认情况下启用此选项。
• Operations must run in a single session on a single thread. Otherwise, the sessions or threads must communicate the operation time and cluster time values to each other. 操作必须在单个线程上的单个会话中运行。否则，会话或线程必须相互传递操作时间和集群时间值。To view an example of two sessions that communicate these values, see the Causal Consistency examples in the MongoDB Server manual.要查看传达这些值的两个会话的示例，请参阅MongoDB服务器手册中的因果一致性示例。
• You must use a majority read concern.你必须使用majority读取关注。
• You must use a majority write concern. This is the default write concern value.你必须使用majority写入关注。这是默认的写入关注值。

The following table describes the guarantees that causally consistent sessions provide:下表描述了因果一致会话提供的保证：

Core API核心api

The Core API provides the following methods to implement transactions:核心API提供以下方法来实现事务：

• startSession(): creates a new ClientSession instance：创建新的ClientSession实例

• startTransaction(): starts a new transaction：启动新事务
• commitTransaction(): commits the active transaction in the session that it was created in：在创建活动事务的会话中提交该事务
• abortTransaction(): ends the active transaction in the session that it was created in：结束创建会话中的活动事务
• endSession(): ends the active session：结束活动会话

You must perform the following steps when using this API:使用此API时，必须执行以下步骤：

• Pass the session instance to each operation that you want to run in that session.将会话实例传递给要在该会话中运行的每个操作。
• Implement a catch block in which you identify server transaction errors and implement error-handling logic.实现一个catch块，在其中识别服务器事务错误并实现错误处理逻辑。

The following code demonstrates how to perform a transaction by using the Core API:以下代码演示了如何使用Core API执行事务：

async function coreTest(client) {
  const session = client.startSession();
  try {
    session.startTransaction();

    const savingsColl = client.db("bank").collection("savings_accounts");
    await savingsColl.findOneAndUpdate(
      {account_id: "9876"}, 
      {$inc: {amount: -100 }}, 
      { session });

    const checkingColl = client.db("bank").collection("checking_accounts");
    await checkingColl.findOneAndUpdate(
      {account_id: "9876"}, 
      {$inc: {amount: 100 }}, 
      { session });

    // ... perform other operations执行其他操作

    await session.commitTransaction();
    console.log("Transaction committed.");
  } catch (error) {
    console.log("An error occurred during the transaction:" + error);
    await session.abortTransaction();
  } finally {
    await session.endSession();
  }
}

const session = client1.startSession();
client2.db('myDB').collection('myColl').insertOne({ name: 'Jane Eyre' }, { session });

To see a fully runnable example that uses this API, see the Use the Core API usage example.要查看使用此API的完全可运行的示例，请参阅使用核心API使用示例。

Convenient Transaction API便捷事务API

The Convenient Transaction API provides the following methods to implement transactions:便捷事务API提供了以下方法来实现事务：

• withSession(): Runs the callback passed to it within a session. The API handles the creation and termination of the session automatically.：在会话中运行传递给它的回调。API自动处理会话的创建和终止。

• withTransaction(): Runs the callback passed to it within a transaction and calls the commitTransaction() method when the callback returns.：在事务中运行传递给它的回调，并在回调返回时调用commitTransaction()方法。

These methods return the value that the callback returns. For example, if a callback you pass to the withTransaction() method returns the document { hello: "world" }, then the withTransaction() method also returns that document.这些方法返回回调函数返回的值。例如，如果传递给withTransactions()方法的回调返回了文档{ hello: "world" }，那么withTransaction()方法也会返回该文档。

When you use the Convenient Transaction API, you can propagate return values from the callback as the return values of the withTransaction() and withSession() methods to work with them elsewhere in your code.当您使用方便事务API时，您可以将回调的返回值传播为withTransaction()和withSession()方法的返回值，以便在代码的其他地方使用它们。

You must perform the following steps when using this API:使用此API时，必须执行以下步骤：

• Pass the session instance to each operation that you want to run in that session.将会话实例传递给要在该会话中运行的每个操作。
• Implement the async await syntax for each operation in the session.为会话中的每个操作实现异步await语法。
• Avoid parallelism, such as calling the Promise.all() method. Using sessions in parallel usually leads to server errors.避免并行，例如调用Promise.all()方法。并行使用会话通常会导致服务器错误。

The following code demonstrates how to perform a transaction by using the Convenient Transaction API:以下代码演示了如何使用便捷事务API执行事务：

async function convTest(client) {
  let txnRes = await client.withSession(async (session) =>
    session.withTransaction(async (session) => {
      const savingsColl = client.db("bank").collection("savings_accounts");
      await savingsColl.findOneAndUpdate(
        {account_id: "9876"}, 
        {$inc: {amount: -100 }}, 
        { session });
  
      const checkingColl = client.db("bank").collection("checking_accounts");
      await checkingColl.findOneAndUpdate(
        {account_id: "9876"}, 
        {$inc: {amount: 100 }}, 
        { session });

      // ... perform other operations执行其他操作

      return "Transaction committed.";
    }, null)
  );
  console.log(txnRes);
}

To see a fully runnable example that uses this API, see the Use the Convenient Transaction API usage example.要查看使用此API的完全可运行的示例，请参阅使用便捷事务API用法示例。

Convenient Transaction API Error Handling方便的事务API错误处理

The Convenient Transaction API incorporates retry logic for these error types. The driver automatically retries the transaction until there is a successful commit.方便事务API包含了这些错误类型的重试逻辑。驱动程序会自动重试事务，直到提交成功。

Core API Error Handling核心API错误处理

If you are using the Core API to perform a transaction, you must add the following error-handling functions to your application:如果使用Core API执行事务，则必须将以下错误处理函数添加到应用程序中：

• A function that retries the entire transaction when the driver encounters a TransientTransactionError当驱动程序遇到TransientTransactionError时重试整个事务的函数
• A function that retries the commit operation when the driver encounters an UnknownTransactionCommitResult当驱动程序遇到UnknownTransactionCommitResult时重试提交操作的函数

These functions must run until there is a successful commit or a different error. For an example of this retry logic, see the Core API section on the Drivers API page in the Server manual.这些函数必须运行，直到成功提交或出现其他错误。有关此重试逻辑的示例，请参阅服务器手册中驱动程序API页上的核心API部分。