共享的 Prisma 客戶端擴充套件

你可以將你的 Prisma 客戶端擴充套件作為包或模組與他人共享，也可以將其他使用者建立的擴充套件匯入到你的專案中。

如果你想構建一個可共享的擴充套件，我們也推薦使用 prisma-client-extension-starter 模板。

要探索 Prisma 官方客戶端擴充套件和社群製作的擴充套件示例，請訪問此頁面。

安裝一個共享的打包擴充套件

在你的專案中，你可以安裝任何其他使用者已釋出到 npm 的 Prisma 客戶端擴充套件。為此，請執行以下命令

npm install prisma-extension-<package-name>

例如，如果一個可用擴充套件的包名為 prisma-extension-find-or-create，你可以按如下方式安裝它

npm install prisma-extension-find-or-create

要從上面的示例中匯入 find-or-create 擴充套件，並用它包裝你的客戶端例項，你可以使用以下程式碼。此示例假定副檔名為 findOrCreate。

import findOrCreate from 'prisma-extension-find-or-create'

const prisma = new PrismaClient().$extends(findOrCreate)
const user = await prisma.user.findOrCreate()

當你呼叫擴充套件中的方法時，請使用 $extends 語句中的常量名，而不是 prisma。在上述示例中，xprisma.user.findOrCreate 有效，但 prisma.user.findOrCreate 無效，因為原始的 prisma 未被修改。

建立可共享的擴充套件

當你想要建立其他使用者可以使用且不只為你的模式定製的擴充套件時，Prisma ORM 提供了實用工具來幫助你建立可共享的擴充套件。

要建立可共享的擴充套件

使用 Prisma.defineExtension 將擴充套件定義為模組
使用以 $all 字首開頭的方法，例如 $allModels 或 $allOperations

定義擴充套件

使用 Prisma.defineExtension 方法使你的擴充套件可共享。你可以用它來打包擴充套件，以便將你的擴充套件分離到單獨的檔案中，或者作為 npm 包與其它使用者共享。

Prisma.defineExtension 的好處在於它為開發中的擴充套件作者和共享擴充套件的使用者提供了嚴格的型別檢查和自動補全功能。

使用通用方法

包含 $allModels 下方法的擴充套件適用於每個模型，而不是特定的模型。同樣，$allOperations 下的方法適用於整個客戶端例項，而不是命名元件，例如 result 或 query。

你不需要在 client 元件中使用 $all 字首，因為 client 元件始終適用於客戶端例項。

例如，一個通用擴充套件可能採用以下形式

export default Prisma.defineExtension({
  name: 'prisma-extension-find-or-create', //Extension name
  model: {
    $allModels: {
      // new method
      findOrCreate(/* args */) {
        /* code for the new method */
        return query(args)
      },
    },
  },
})

請參閱以下頁面，瞭解修改 Prisma 客戶端操作的不同方式

對於早於 4.16.0 的版本

Prisma 匯入可從以下程式碼片段中顯示的不同路徑獲取

import { Prisma } from '@prisma/client/scripts/default-index'

export default Prisma.defineExtension({
  name: 'prisma-extension-<extension-name>',
})

將可共享的擴充套件釋出到 npm

然後你可以在 npm 上共享該擴充套件。選擇包名時，我們建議你使用 prisma-extension-<package-name> 約定，以便於查詢和安裝。

從你的打包擴充套件中呼叫客戶端級別方法

警告

目前，對於引用 PrismaClient 並呼叫客戶端級別方法的擴充套件存在限制，如下例所示。

如果你從事務內部觸發擴充套件（互動式或批處理），擴充套件程式碼將在新連線中發出查詢，並忽略當前的事務上下文。

在 GitHub 上的此問題中瞭解更多：需要使用客戶端級別方法的客戶端擴充套件會靜默忽略事務。

在以下情況下，你需要引用你的擴充套件所包裝的 Prisma 客戶端例項

當你想在打包的擴充套件中使用客戶端級別方法，例如 $queryRaw 時。
當你想在打包的擴充套件中鏈式呼叫多個 $extends 時。

然而，當有人在他們的專案中包含你的打包擴充套件時，你的程式碼無法知道 Prisma 客戶端例項的詳細資訊。

你可以按如下方式引用此客戶端例項

Prisma.defineExtension((client) => {
  // The Prisma Client instance that the extension user applies the extension to
  return client.$extends({
    name: 'prisma-extension-<extension-name>',
  })
})

例如

export default Prisma.defineExtension((client) => {
  return client.$extends({
    name: 'prisma-extension-find-or-create',
    query: {
      $allModels: {
        async findOrCreate({ args, query, operation }) {
          return (await client.$transaction([query(args)]))[0]
        },
      },
    },
  })
})

高階型別安全：用於定義通用擴充套件的型別工具

你可以使用型別工具來提高共享擴充套件的型別安全。

安裝一個共享的打包擴充套件​

建立可共享的擴充套件​

定義擴充套件​

使用通用方法​

將可共享的擴充套件釋出到 npm​

從你的打包擴充套件中呼叫客戶端級別方法​

高階型別安全：用於定義通用擴充套件的型別工具​