如何为AppSync所用的GraphQL Schema添加类型描述？

当然可以！AppSync完全支持给GraphQL Schema中的类型、字段甚至枚举值添加描述，而且这些描述能通过GraphQL自省查询正常获取到，和你提到的ApolloServer、graphql-js的实现思路是一致的。

下面是两种常用的实现方式：

• SDL（Schema Definition Language）直接定义
  你可以在Schema里用多行注释"""包裹描述内容，单行注释#也支持（更适合简短描述），示例如下：

  """
  存储平台用户核心信息的实体类型，包含身份标识、基本资料等关键字段
  """
  type User {
    """用户在平台内的唯一ID，由系统自动生成且不可修改"""
    id: ID!
    """用户的完整姓名，支持中英文及特殊字符"""
    name: String!
    """用户的注册邮箱，用于登录验证和接收系统通知"""
    email: String!
    """用户的账号状态，区分正常使用、临时冻结、已注销三种状态"""
    status: UserStatus!
  }
  
  """用户账号状态枚举集合"""
  enum UserStatus {
    """账号正常，可使用全部平台功能"""
    ACTIVE
    """账号被临时冻结，无法登录平台"""
    SUSPENDED
    """账号已注销，所有数据将被归档"""
    DELETED
  }
  

  写完后，你可以通过自省查询验证描述是否生效：

  query GetTypeDescriptions {
    __type(name: "User") {
      description
      fields {
        name
        description
      }
    }
    __type(name: "UserStatus") {
      description
      enumValues {
        name
        description
      }
    }
  }
  

• 代码优先方式（如AWS CDK、Amplify）
  如果你用基础设施即代码的方式定义AppSync Schema，也可以直接给类型和字段指定description属性。比如AWS CDK中的示例：

  import * as appsync from 'aws-cdk-lib/aws-appsync';
  import { Stack, StackProps } from 'aws-cdk-lib';
  import { Construct } from 'constructs';
  
  export class AppSyncSchemaStack extends Stack {
    constructor(scope: Construct, id: string, props?: StackProps) {
      super(scope, id, props);
  
      // 直接用代码定义类型并添加描述
      const userType = new appsync.GraphQLType(this, 'UserType', {
        definition: appsync.TypeDefinition.object({
          id: appsync.GraphqlType.id({ 
            isRequired: true, 
            description: '用户在平台内的唯一ID，由系统自动生成且不可修改' 
          }),
          name: appsync.GraphqlType.string({ 
            isRequired: true, 
            description: '用户的完整姓名，支持中英文及特殊字符' 
          }),
        }),
        description: '存储平台用户核心信息的实体类型'
      });
    }
  }
  

需要注意的是，AppSync对SDL注释的支持和graphql-js完全兼容，所以如果你之前在其他GraphQL服务中写的带描述的Schema，迁移到AppSync时几乎不需要做修改就能直接生效。

内容的提问来源于stack exchange，提问作者Tom Q.