跳到主要內容

產生的 API 區塊

API 區塊概觀​

當您呼叫 createApi 時，它會自動產生並傳回一個 API 服務「區塊」物件結構，其中包含 Redux 邏輯，可讓您用來與您定義的端點互動。此區塊物件包含一個 Reducer，用於管理快取資料，一個用於管理快取生命週期和訂閱的中介軟體，以及每個端點的選取器和 thunk。如果您從 React 專用的進入點匯入 createApi，它也會包含自動產生的 React hook，供您在元件中使用。

此區段說明該 API 結構的內容，並將不同的欄位依類別分組。API 類型和說明會在每個類別的個別頁面上列出。

提示

通常，您應該只有一個 API 區塊，對應於應用程式需要通訊的每個基本 URL。例如，如果您的網站從 /api/posts 和 /api/users 擷取資料，您會有一個以 /api/ 為基本 URL 的單一 API 區塊，以及針對 posts 和 users 的個別端點定義。這讓您可以透過在端點間定義 自動重新擷取 的 標籤 關係，有效利用自動重新擷取。

為了維護的目的，您可能希望將端點定義分割成多個檔案，同時仍然維護一個包含所有這些端點的單一 API 區段。請參閱 程式碼分割，了解如何使用 injectEndpoints 屬性將其他檔案中的 API 端點注入到單一 API 區段定義中。

API 區段內容
const api = createApi({
  baseQuery: fetchBaseQuery({ baseUrl: '/' }),
  endpoints: (build) => ({
    // ...
  }),
})

type Api = {
  // Redux integration
  reducerPath: string
  reducer: Reducer
  middleware: Middleware

  // Endpoint interactions
  endpoints: Record<string, EndpointDefinition>

  // Code splitting and generation
  injectEndpoints: (options: InjectEndpointsOptions) => UpdatedApi
  enhanceEndpoints: (options: EnhanceEndpointsOptions) => UpdatedApi

  // Utilities
  utils: {
    updateQueryData: UpdateQueryDataThunk
    patchQueryData: PatchQueryDataThunk
    prefetch: PrefetchThunk
    invalidateTags: ActionCreatorWithPayload<
      Array<TagTypes | FullTagDescription<TagTypes>>,
      string
    >
    selectInvalidatedBy: (
      state: FullState,
      tags: Array<TagTypes | FullTagDescription<TagTypes>>,
    ) => Array<{
      endpointName: string
      originalArgs: any
      queryCacheKey: string
    }>
    selectCachedArgsForQuery: (
      state: FullState,
      endpointName: EndpointName,
    ) => Array<QueryArg>
    resetApiState: ActionCreator<ResetAction>
    getRunningQueryThunk(
      endpointName: EndpointName,
      args: QueryArg,
    ): ThunkWithReturnValue<QueryActionCreatorResult | undefined>
    getRunningMutationThunk(
      endpointName: EndpointName,
      fixedCacheKeyOrRequestId: string,
    ): ThunkWithReturnValue<MutationActionCreatorResult | undefined>
    getRunningQueriesThunk(): ThunkWithReturnValue<
      Array<QueryActionCreatorResult<any>>
    >
    getRunningMutationsThunk(): ThunkWithReturnValue<
      Array<MutationActionCreatorResult<any>>
    >
  }

  // Internal actions
  internalActions: InternalActions

  // React hooks (if applicable)
  [key in GeneratedReactHooks]: GeneratedReactHooks[key]
}

Redux 整合​

在內部，createApi 將呼叫 Redux Toolkit createSlice API 來產生一個區段 reducer 和對應的動作建立器，並具備適當的快取已擷取資料的邏輯。它也會自動產生一個自訂的 Redux 中介軟體，用來管理訂閱計數和快取生命週期。

所產生的區段 reducer 和中介軟體都需要新增到您在 configureStore 中的 Redux 儲存設定中，才能正確運作。

API 參考

端點​

API 區段物件內部將有一個 endpoints 欄位。此區段會將您提供給 createApi 的端點名稱對應到用於觸發資料擷取和讀取該端點快取資料的核心 Redux 邏輯（thunk 和選取器）。如果您使用的是 createApi 的 React 特定版本，每個端點定義也將包含該端點的自動產生 React 勾子。

API 參考

程式碼分割和產生​

每個 API 區段允許 在執行階段注入其他端點定義，在最初的 API 區段定義之後。這對於可能具有許多端點的應用程式來說是有益的。

個別 API 區段端點定義也可以分割成多個檔案。這對於使用 從 API 架構檔案產生程式碼 的 API 區段特別有用，讓您可以為一組自動產生的端點定義新增其他自訂行為和組態。

每個 API 區段物件都有 injectEndpoints 和 enhanceEndpoints 函式來支援這些使用案例。

API 參考

API Slice 工具​

util 欄位包含各種可管理快取的工具函式，包括手動更新查詢快取資料、觸發資料預先擷取、手動使標籤失效，以及手動重設 API 狀態，以及其他可在各種情境中使用的工具函式，包括 SSR。

API 參考

內部動作​

internalActions 欄位包含一組用於內部行為的其他 thunk，例如管理基於焦點的更新。

React Hook​

RTK Query 核心 createApi 方法與 Redux 核心函式庫和 Redux Toolkit 一樣，與 UI 無關。它們都是純粹的 JS 邏輯，可在任何地方使用。

然而，RTK Query 也提供自動為每個端點產生 React Hook 的功能。由於這特別取決於 React 本身，RTK Query 提供一個替代進入點，公開一個包含該功能的 createApi 自訂版本

import { createApi } from '@reduxjs/toolkit/query/react'

如果您已使用 createApi 的 React 特定版本，產生的 Api slice 結構也會包含一組 React Hook。這些端點 Hook 可用於 api.endpoints[endpointName].useQuery 或 api.endpoints[endpointName].useMutation，與您定義該端點的方式相符。

相同的 Hook 也會新增至 Api 物件本身，並根據端點名稱和查詢/變異類型給予自動產生的名稱。

例如，如果您有 getPosts 和 updatePost 的端點，這些選項將會可用

產生的 React Hook 名稱
// Hooks attached to the endpoint definition
const { data } = api.endpoints.getPosts.useQuery()
const { data } = api.endpoints.updatePost.useMutation()

// Same hooks, but given unique names and attached to the API slice object
const { data } = api.useGetPostsQuery()
const [updatePost] = api.useUpdatePostMutation()

createApi 的 React 特定版本也會產生一個 usePrefetch Hook，附加至 Api 物件，可提前用來初始化擷取資料。

API 參考
最後更新於