Note | 前端項目中AWS AppSync的GraphQL API連結

至少還順利的Query和Mutation實現

由於Query和Mutation與Subscription的原理不同，其請求幾乎可以理解為和RESTful API一樣，所以不同的host也不能搞出花樣來。這裡貼一個簡單的Query的例子：

javascriptCopied!
const apolloClient = new ApolloClient({
  uri: 'https://rtapi.example.endpoint/graphql',
  headers: {
    'X-Api-Key': 'some_api_key',
  },
  cache: new InMemoryCache(),
});

provideApolloClient(apolloClient);

const { onResult } = useQuery(
  gql`
    query listData($someInput: String!) {
      listData(someInput: $someInput) {
        result {
          property1
          property2
          property3
          property4
        }
        statusCode
      }
    }
  `,
  {
    someInput: someInput.value,
  },
);

onResult((result) => {
  dataToDisplay.value = result.data.listData.result;
});

基本實現方法是首先定義一個ApolloClient並且用provideApolloClient將其投入使用，再用useQuery方法進行數據請求。其中useQuery的返回值不僅有onResult，還有isLoading: Boolean用於判定數據是否已經到位，subscribeToMore用於後續的數據訂閱。

其中用到一個叫做graphql-tag的庫來進行query字符串的預處理（gql方法），它將把它包起來的GraphQL查詢字符串解析為標準GraphQL AST用於發送請求。

Subscription怎麼就搞不動了？

先說結論，失敗的原因是因為AppSync接收Subscription請求的形式和Apollo發送的請求形式不吻合。

AppSync接受的請求形式：

jsonCopied!
{
  "id": id,
  "type": "start",
  "payload": {
    "data": {
      "query": query,
      "variables": { variable: variable },
    },
    "extensions": {
      authorization: {
        host: endpoint,
        "x-api-key": apikey,
      }
    },
  }
}

Apollo發送的請求形式：

jsonCopied!
{
  "id": subscriptionId,
  "type": "start",
  "payload": {
    "variables": {},
    "extensions": {},
    "operationName": subscriptionName,
    "query": query
  }
}

AppSync接受的请求形式中，本该直接出现query的地方多了一层data，结果就导致了UnsupportedOperation错误的发生：

jsonCopied!
{
  "type": "error",
  "id": "",
  "payload": {
    "errors": [
      {
        "errorType": "UnsupportedOperation",
        "message": "unknown not supported through the realtime channel"
      }
    ]
  }
}

除此之外，AppSync還會返回start_ack信息，而這不在Apollo所使用的WebSocket方法的生命週期里，所以可以說兩者几乎是完全不適配。並且，向GraphQL端點發送請求時，需要在端點的字符串後自行處理加上轉換成base64的頭部（包括header和payload）。由於gql是自動生成，並沒有找到可以自定義請求體結構的方法，所以這條路以失敗告終。

Schema的自動取得等

首先按照AppSync Console的教程，先把GraphQL的Schema全部拉取下來。

shellCopied!
npm install -g @aws-amplify/cli
amplify init
amplify add codegen --apiId some_api_id
amplify codegen

讓我直接暈死的點就在這裡，根據步驟會生成一大堆文件，甚至還會直接告訴你需要部署一個Amplify App在AWS。由於生成的大部分文件都在.gitignore裡，當下我就陷入思考：這麼多本地文件，部署的時候該怎麼辦？？

其實到此為止，我們其實只需要用到Amplify cli幫忙取得的Schema文件，也就是./src/graphql中的文件，除此之外，還有一個叫做aws-exports.js的文件，當API KEY之類的過期或更新的時候，amplify codegen會重新幫我們生成這些文件。

.gitignore裡面被添加的那些本地配置文件通通都可以刪除，那些都是需要部署Amplify APP才需要用到的文件。

為了讓全局都可以使用這個GraphQL端點，首先在app.js裡進行配置：

javascriptCopied!
import Amplify from 'aws-amplify';

Amplify.configure({
  aws_appsync_graphqlEndpoint: process.env.GRAPHQL_ENDPOINT || '',
  aws_appsync_authenticationType: 'API_KEY',
  aws_appsync_apiKey: process.env.APPSYNC_API_KEY || '',
});

各大教程裡面都是這樣寫：Amplify.configure(aws_exports);，但如果我需要在部署的時候再多生成一個aws_exports.js文件，那需要很多額外設置，所以aws_appsync_graphqlEndpoint和aws_appsync_apiKey就交給環境變量來解決了。

API請求

設置結束之後，我們就可以在組件裡進行API請求了。比起Apollo，由於我們有自動生成的Schema文件（其實Apollo也可以使用提前定義的Schema，但是實在是太多我又很懶，所以沒弄），所以實現起來非常快。

首先，編寫這樣的方法：

javascriptCopied!
import { API, graphqlOperation } from 'aws-amplify';
import { listUserData } from '@/../src/graphql/queries';

const fetchUserData = async () => {
  await API.graphql(
    graphqlOperation(listUserData, {
      userGroupId: userGroupId.value,
    }),
  ).then((res) => {
    userData.value = res.data.listUserData.result.sort((a, b) => {
      return a.userId - b.userId;
    });
  });
};

其中，像一般的promise一樣，用then()來指定有響應之後的操作。同理，mutation也用類似的方法實現：

javascriptCopied!
import { updateUserStatus } from '@/../src/graphql/mutations';

const mutateUserData = async () => {
  await API.graphql(
    graphqlOperation(updateTicketStatus, {
      input: {
        userId: userId.value,
        groupId: groupId,
        userStatus: userStatus,
      },
    }),
  )
    .then(() => {
      console.log('user status updated!');
    })
    .catch(() => {
      console.log('user status update failed!');
    });
};

subscribe的實現方法也類似，不過需要加上subscribe()處理：

javascriptCopied!
import { subscribeUserData } from '@/../src/graphql/subscriptions';

const subscribeToUserData = async () => {
  await API.graphql(
    graphqlOperation(subscribeUserData, {
      userGroupId: userGroupId.value,
    }),
  ).subscribe({
    next: (res) => {
      if (!res.value.data.subscribeUserData) return;
      const changedUser = res.value.data.subscribeUserData.result;
      const changedUserIndex = users.value?.findIndex(
        (user) => user.userId === changedUser.userId,
      );
      if (changedUserIndex === -1) {
        users.value.push(changedUser);
        users.value.sort((a, b) => a.userId - b.userId);
      } else {
        users.value[changedUserIndex] = changedUser;
      }
    },
    error: () => {
      console.log('error occurred!');
    },
  });
};

在subscribe()方法中，next用於定義正常獲得更新數據之後的操作，error用於定義異常的處理。在上面的例子中，數據更新時只返回一個用戶的數據，所以在next的定義中找到有更新的用戶，並用新數據替換舊數據。

最後，為了讓數據獲取和訂閱的方法在插入組件樹的時候運行，把上面的fetchUserData()和subscribeToUserData()放進onMounted()中：

javascriptCopied!
onMounted(async () => {
  await fetchUserData();
  await subscribeToUserData();
});

這樣一來，數據獲取和訂閱就完成了。

實時監測WebSocket的連結狀況

按照項目需求，當網絡出現狀況，WebSocket的網絡連結狀況處於pending的時候，需要顯示網絡故障的文字。可是，網絡故障時，本身就不會返回新數據，所以不能在subscribe()的error中定義行為。

這裡可以用到Amplify的Hub.listen()來實時監聽api的連結情況。

javascriptCopied!
import { Hub } from 'aws-amplify';
import { CONNECTION_STATE_CHANGE, ConnectionState } from '@aws-amplify/pubsub';

Hub.listen('api', async (data) => {
  if (data.payload.event === CONNECTION_STATE_CHANGE) {
    if (
      data.payload.data.connectionState ===
      ConnectionState.ConnectedPendingNetwork
    ) {
      shouldDisplayConnectionError.value = true;
    } else {
      shouldDisplayConnectionError.value = false;
      await fetchUserData();
    }
  }
});

在Hub監聽api的過程中，有各種各樣的事件數據返回，其中要提取的就是CONNECTION_STATE_CHANGE即網絡連結狀態改變事件，當事件發生時，事件本身作為觸發器觸發狀態的改變。

ConnectionState有以下狀態，可以結合實際需求和情境用於判定等。

markdownCopied!
- Connected - Connected and working with no issues.
- ConnectedPendingDisconnect - The connection has no active subscriptions and is disconnecting.
- ConnectedPendingKeepAlive - The connection is open, but has missed expected keep alive messages.
- ConnectedPendingNetwork - The connection is open, but the network connection has been disrupted. When the network recovers, the connection will continue serving traffic.
- Connecting - Attempting to connect.
- ConnectionDisrupted - The connection is disrupted and the network is available.
- ConnectionDisruptedPendingNetwork - The connection is disrupted and the network connection is unavailable.
- Disconnected - Connection has no active subscriptions and is disconnecting.