AWS Amplify在Next.js服务端组件中使用REST API的实践指南

背景介绍

AWS Amplify是一个流行的前端开发框架，它简化了与AWS云服务的集成。在Next.js应用中，特别是使用App Router架构时，开发者经常需要在服务端组件中调用REST API。然而，由于Amplify的客户端和服务端配置方式不同，这可能会带来一些挑战。

问题核心

在Next.js应用中，当尝试在服务端组件中使用Amplify的REST API时，开发者可能会遇到"API name is invalid"的错误。这是因为Amplify的配置在客户端和服务端需要不同的处理方式。

解决方案

1. 服务端配置

首先，我们需要创建一个专门用于服务端的Amplify配置工具。这个工具使用createServerRunner来初始化Amplify服务端环境：

import { createServerRunner } from "@aws-amplify/adapter-nextjs";
import { ResourcesConfig } from "aws-amplify";

export const amplifyResourceConfig: ResourcesConfig = {
  Auth: {
    Cognito: {
      userPoolId: process.env.NEXT_PUBLIC_USER_POOL_ID,
      userPoolClientId: process.env.NEXT_PUBLIC_USER_POOL_CLIENT_ID,
    },
  },
  API: {
    REST: {
      PlatformCoreOldRestApi: {
        endpoint: process.env.NEXT_PUBLIC_PLATFORM_CORE_OLD_REST_API_URL,
      },
      PlatformCoreNewRestApi: {
        endpoint: process.env.NEXT_PUBLIC_PLATFORM_CORE_NEW_REST_API_URL,
      },
    },
  },
};

export const { runWithAmplifyServerContext } = createServerRunner({
  config: amplifyResourceConfig,
});

2. REST API封装

接下来，我们封装一个通用的REST API调用工具，专门用于服务端调用：

import { get, del } from "aws-amplify/api/server";

export function platformAPI({ apiName }: { apiName: string }) {
  return {
    get: async <T>(contextSpec: any, path: string, options?: any) =>
      get(contextSpec, {
        apiName,
        path,
        options,
      }).response.then(async (res) => (await res.body.json()) as T),
    delete: async <T>(contextSpec: any, path: string, queryParams?: Record<string, string>) =>
      del(contextSpec, {
        apiName,
        path,
        options: {
          queryParams: queryParams || undefined,
        },
      }).response.then(async (res) => (await res.statusCode) as T),
  };
}

export const PlatformCoreOldRestApi = platformAPI({
  apiName: "PlatformCoreOldRestApi",
});

export const PlatformCoreNewRestApi = platformAPI({
  apiName: "PlatformCoreNewRestApi",
});

3. 服务端组件中的使用

在服务端组件中，我们需要使用runWithAmplifyServerContext来执行API调用，并处理认证：

import { fetchAuthSession } from "aws-amplify/auth/server";
import { runWithAmplifyServerContext } from "./AmplifyServerUtils";
import { PlatformCoreOldRestApi } from "./RestAPIs";

export default async function UsersPage({ searchParams, cookies }) {
  const { query } = searchParams;
  
  const users = await runWithAmplifyServerContext({
    nextServerContext: { cookies },
    operation: async (contextSpec) => {
      const session = await fetchAuthSession(contextSpec);
      const token = session.tokens?.idToken?.toString();
      
      return await PlatformCoreOldRestApi.get<UserData[]>(
        contextSpec,
        `/platform/people/search?email=${query}`,
        {
          headers: {
            Authorization: `Bearer ${token}`,
          },
        }
      );
    },
  });

  // 使用users数据渲染组件
}

关键点解析

1. 上下文隔离：服务端每个请求都需要独立的Amplify上下文，这是通过runWithAmplifyServerContext实现的。

2. 认证处理：服务端需要显式获取认证token并附加到请求头，这与客户端自动处理不同。

3. API封装：通过封装通用的API调用方法，可以提高代码复用性和可维护性。

4. 环境变量：确保所有必要的环境变量都已正确配置，特别是在服务端使用的变量。

最佳实践

1. 将Amplify服务端配置与客户端配置分开管理
2. 为不同类型的API创建专门的封装函数
3. 在服务端组件中处理错误和边界情况
4. 考虑添加请求日志记录以便调试
5. 对于频繁调用的API，可以考虑添加缓存机制

通过遵循这些实践，开发者可以更高效地在Next.js服务端组件中使用AWS Amplify的REST API功能，同时保持代码的清晰和可维护性。