Transactions事务

Core API

The Core API features methods to start, cancel, or commit a transaction. 核心API具有启动、取消或提交事务的方法。When you commit the transaction, you send a request to the server to make the changes from your operations atomically. 当您提交事务时，您会向服务器发送一个请求，以原子方式对操作进行更改。When using this API, you must handle certain transaction errors returned by the server manually.使用此API时，必须手动处理服务器返回的某些事务错误。

See TransientTransactionError and UnknownTransactionCommitResult for more information on these errors.有关这些错误的详细信息，请参阅TransientTransactionError和UnknownTransactionCommitResult。

To start, cancel, or commit your transaction, you can call the corresponding method on the Session object:要启动、取消或提交事务，可以在Session对象上调用相应的方法：

• startTransaction()
• commitTransaction()
• abortTransaction()

See the Core API example for a sample transaction implementation.有关示例事务实现，请参阅核心API示例。

Sample Data示例数据

The code examples require the following sample data in the testdb database to run the multi-document payment transaction:代码示例需要testdb数据库中的以下示例数据来运行多文档支付事务：

• A document in the customers collection that describes a customer and their orders.customers集合中描述客户及其订单的文档。
• Documents in the inventory collection that each track quantity and description of an item.inventory集合中的文档，每个文档跟踪物料的数量和描述。

The document in the customers collection in this example contains the following:本例中customers集合中的文档包含以下内容：

{ _id: 98765, orders: [] }

The documents in the inventory collection in this example contain the following:本例中inventory集合中的文档包含以下内容：

[
 { name: "sunblock", sku: 5432, qty: 85 },
 { name: "beach towel", sku: 7865, qty: 41 }
]

The code examples also perform operations on the orders collection, but do not require any prior sample documents.代码示例还对orders集合执行操作，但不需要任何先前的示例文档。

The code examples use the cart and payment variables to represent a sample list of items purchased and the order payment details as follows:代码示例使用cart和payment变量来表示所购买物品的示例列表和订单付款详细信息，如下所示：

const cart = [
  { name: 'sunblock', sku: 5432, qty: 1, price: 5.19 },
  { name: 'beach towel', sku: 7865, qty: 2, price: 15.99 }
];
const payment = { customer: 98765, total: 37.17 };

Core API Implementation核心API实现

The code example in this section demonstrates how you can use the Core API to run the multi-document payment transaction in a session. 本节中的代码示例演示了如何使用Core API在会话中运行多文档支付事务。This function shows how you can perform the following:此功能显示如何执行以下操作：

1. Start a session启动会话
2. Start a transaction, specifying transaction options启动事务，指定事务选项
3. Perform data operations in the same session在同一会话中执行数据操作
4. Commit a transaction, or cancel it if the driver encounters an error提交事务，或者在驱动程序遇到错误时取消事务
5. End a session结束会话

async function placeOrder(client, cart, payment) {
  const transactionOptions = {
    readConcern: { level: 'snapshot' },
    writeConcern: { w: 'majority' },
    readPreference: 'primary'
  };

  const session = client.startSession();
  try {
    session.startTransaction(transactionOptions);

    const ordersCollection = client.db('testdb').collection('orders');
    const orderResult = await ordersCollection.insertOne(
      {
        customer: payment.customer,
        items: cart,
        total: payment.total,
      },
      { session }
    );

    const inventoryCollection = client.db('testdb').collection('inventory');
    for (let i=0; i<cart.length; i++) {
      const item = cart[i];

      // Cancel the transaction when you have insufficient inventory库存不足时取消事务
      const checkInventory = await inventoryCollection.findOne(
        {
          sku: item.sku,
          qty: { $gte: item.qty }
        },
        { session }
      )
      if (checkInventory === null) {
        throw new Error('Insufficient quantity or SKU not found.');
      }

      await inventoryCollection.updateOne(
        { sku: item.sku },
        { $inc: { 'qty': -item.qty }},
        { session }
      );
    }

    const customerCollection = client.db('testdb').collection('customers');
    await customerCollection.updateOne(
      { _id: payment.customer },
      { $push:  { orders: orderResult.insertedId }},
      { session }
    );
    await session.commitTransaction();
    console.log('Transaction successfully committed.');

  } catch (error) {
    if (error instanceof MongoError && error.hasErrorLabel('UnknownTransactionCommitResult')) {
      // add your logic to retry or handle the error添加逻辑以重试或处理错误
    }
    else if (error instanceof MongoError && error.hasErrorLabel('TransientTransactionError')) {
      // add your logic to retry or handle the error添加逻辑以重试或处理错误
    } else {
      console.log('An error occured in the transaction, performing a data rollback:' + error);
    }
    await session.abortTransaction();
  } finally {
    await session.endSession();
  }
}

Note that you must pass the session object to each CRUD operation that you want to run on that session.请注意，必须将会话对象传递给要在该会话上运行的每个CRUD操作。

The code and comments in the catch block demonstrate how you can identify the server transaction errors and where you can place your logic to handle them. catch块中的代码和注释演示了如何识别服务器事务错误，以及如何放置逻辑来处理这些错误。Make sure to include the MongoError type from the driver in your code as shown in the following sample import statement:请确保在代码中包含驱动程序中的MongoError类型，如以下示例导入语句所示：

const { MongoError, MongoClient } = require('mongodb');

See the Payment Transaction Result section to see what your collections should contain after you run the transaction.请参阅付款事务结果部分，查看运行事务后您的收款应包含哪些内容。

Payment Transaction Result付款事务结果

If your application completes the payment transaction, your database should contain all the updates, and if an exception interrupted your transaction, none of the changes should exist in your database.如果您的应用程序完成了支付事务，则您的数据库应包含所有更新，如果异常中断了您的事务，则数据库中不应存在任何更改。

The customers collection should contain the customer document with an order id appended to the orders field:customers集合应包含在订单字段后附加订单id的客户文档：

{
  "_id": 98765,
  "orders": [
    "61dc..."
  ]
}

The inventory collection should contain updated quantities for the items "sunblock" and "beach towel":inventory清单应包含“防晒霜”和“沙滩巾”的最新数量：

[
  {
    "_id": ...,
    "name": "sunblock",
    "sku": 5432,
    "qty": 84
  },
  {
    "_id": ...,
    "name": "beach towel",
    "sku": 7865,
    "qty": 39
  }
]

The orders collection should contain the order and payment information:orders集合应包含订单和付款信息：

[
  {
    "_id": "...",
    "customer": 98765,
    "items": [
      {
        "name": "sunblock",
        "sku": 5432,
        "qty": 1,
        "price": 5.19
      },
      {
        "name": "beach towel",
        "sku": 7865,
        "qty": 2,
        "price": 15.99
      }
    ],
    "total": 37.17
  }
]