# @aws-amplify/graphql-transformer-core 中文文档

规范地址：https://npmcn.com/package/%40aws-amplify/graphql-transformer-core/

版本：3\.6\.2
npm 元数据更新时间：2026-09-30T16:48:49.801Z
中文译文更新时间：2026-11-07T09:14:43.946Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws-amplify/graphql-transformer-core
原文对照：https://npmcn.com/package/%40aws-amplify/graphql-transformer-core/?lang=original
项目主页：https://github.com/aws-amplify/amplify-category-api#readme
源码仓库：https://github.com/aws-amplify/amplify-category-api

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：715 kB，226 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：11 个
- peer 依赖：constructs ^10\.3\.0，aws-cdk-lib ^2\.224\.0
- 首次发布：2020-11-07T22:56:44.337Z
- 最新版本发布：2026-09-30T16:48:49.554Z
- 近 30 天下载量：963384（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：462（近 12 个月 8 个）

## 中文简介

从 GraphQL SDL 转换为 AWS Cloud Formation 的框架 .

## 安装

```sh
npm install @aws-amplify/graphql-transformer-core
```

也可以使用：`pnpm add @aws-amplify/graphql-transformer-core`、`yarn add @aws-amplify/graphql-transformer-core`、`bun add @aws-amplify/graphql-transformer-core`

## README

# 图QL 变形

# 参考文件

### @ 模式

附加注释的对象类型 `@model` 属于 生成 API。 注释对象 `@model` 存放在迪纳摩DB 能够通过 `@auth`,通过 `@connection`, (中文(简体) ), 并流经 `@searchable`。 。 。 .

#### 定义

```graphql
directive @model(queries: ModelQueryMap, mutations: ModelMutationMap) on OBJECT
input ModelMutationMap {
  create: String
  update: String
  delete: String
}
input ModelQueryMap {
  get: String
  list: String
}
```

#### 使用量

定义一个 GraphQL 对象类型,并用 `@model` 要存储的命令 dynataB中该类型对象并自动配置 CRUDL 查询和 变相.

```graphql
type Post @model {
  id: ID! # id: ID! is a required attribute.
  title: String!
  tags: [String!]!
}
```

也可以推翻任何产生的查询和突变的名称 完全删除操作.

```graphql
type Post @model(queries: { get: "post" }, mutations: null) {
  id: ID!
  title: String!
  tags: [String!]!
}
```

这将创建和配置单个查询字段 `post(id: ID!): Post` 财务报告和审定财务报表 无变异字段.

### @ 奥斯

附加注释的对象类型 `@auth` 受其中一种保护 支持授权战略。 附加说明的类型 `@auth` 还必须附加说明 `@model`。 。 。 .

#### 定义

```graphql
# When applied to a type, augments the application with
# owner and group based authorization rules.
directive @auth(rules: [AuthRule!]!) on OBJECT

input AuthRule {
  allow: AuthStrategy!
  ownerField: String = "owner"
  identityField: String = "username"
  groupsField: String
  groups: [String]
  queries: [ModelQuery]
  mutations: [ModelMutation]
}
enum AuthStrategy {
  owner
  groups
}
enum ModelQuery {
  get
  list
}
enum ModelMutation {
  create
  update
  delete
}
```

#### 授权战略

##### 所有者授权

```graphql
# The simplest case
type Post @model @auth(rules: [{ allow: owner }]) {
  id: ID!
  title: String!
}

# The long form way
type Post @model @auth(rules: [{ allow: owner, ownerField: "owner", mutations: [create, update, delete], queries: [get, list] }]) {
  id: ID!
  title: String!
  owner: String
}
```

所有者授权指定一个用户(或一组用户)可以访问一个对象. 改为: 这样做,每个对象都有 _拥有者字段_ 存储所有权信息的(默认为“所有者”) 并在解密者执行期间以各种方式加以核实.

你可以用这个 _查询_ 财务报告和审定财务报表 _变异_ 参数以指定哪些操作被扩展 :

**起来**: 如果记录的所有人与用户登录的不相同(通过 `$ctx.identity.username`),抛出 `$util.unauthorized()`。 。 。 . **列表**过滤器 `$ctx.result.items` 用于自有物品. **创建**: 输入用户登录的 `$ctx.identity.username` 作为 _拥有者字段_ 自动. **更新**: 添加检查存储的有条件更新 _拥有者字段_ 与 `$ctx.identity.username`。 。 。 . **删除**: 添加检查存储的有条件更新 _拥有者字段_ 与 `$ctx.identity.username`。 。 。 .

**进展**

```graphql
# TODO: (WORK IN PROGRESS) Does not yet support multi-owner
type Post @model @auth(rules: [{ allow: owner, ownerField: "owners", mutations: [create, update, delete], queries: [get, list] }]) {
  id: ID!
  title: String!
  owners: [String]
}
```

##### 分组授权

**静态小组 Auth**

```graphql
# Static group auth
type Post @model @auth(rules: [{ allow: groups, groups: ["Admin"] }]) {
  id: ID!
  title: String
}
```

如果用户证书(由解析器指定) `$ctx.identity`则不是 入学人数 _管理员_ 组合,通过 `$util.unauthorized()`。 。 。 .

**动态组 Auth**

```graphql
# Dynamic group auth with multiple groups
type Post @model @auth(rules: [{ allow: groups, groupsField: "groups" }]) {
  id: ID!
  title: String
  groups: [String]
}

# Dynamic group auth with a single group
type Post @model @auth(rules: [{ allow: groups, groupsField: "group" }]) {
  id: ID!
  title: String
  group: String
}
```

在动态组授权下,每个记录包含一个属性指定 哪些团体应该能够利用它。 使用 _实地_ 参数到 指定基础数据库中哪些属性持有此组 资料。 指定单个群体应可使用以下域: 类型 `String`。指定多个群体应使用以下领域: 类型 `[String]`。 。 。 .

### @ 连接

这个 `@connection` 指令允许您指定 `@model` 对象类型. 目前,这支持一对一,一对一关系和多对一关系. 错误 当尝试配置多对多关系时, 将会被扔出 .

#### 定义

```graphql
directive @connection(name: String) on FIELD_DEFINITION
```

#### 使用量

关系由注释字段在 `@model` 对象类型为 页:1 `@connection` 指令.

##### 未命名的连接

在最简单的情况下,您可以定义一对一的连接:

```graphql
type Project @model {
  id: ID!
  name: String
  team: Team @connection
}
type Team @model {
  id: ID!
  name: String!
}
```

一旦转型,你就可以通过下列方式与团队创建项目:

```graphql
mutation CreateProject {
  createProject(input: { name: "New Project", projectTeamId: "a-team-id" }) {
    id
    name
    team {
      id
      name
    }
  }
}
```

> 说明: **项目.团队** 解析器将预先配置,以配合定义的连接.

同样,你可以做一个简单的一对一连接:

```graphql
type Post {
  id: ID!
  title: String!
  comments: [Comment] @connection
}
type Comment {
  id: ID!
  content: String!
}
```

一个转变,你会用一个帖子来创建评论:

```graphql
mutation CreateCommentOnPost {
  createComment(input: { content: "A comment", postCommentsId: "a-post-id" }) {
    id
    content
  }
}
```

> 注:“后评论” 输入上的 Id"字段可能看起来是个奇怪的名字,而且确实如此. 在未提供"姓名"论据的一对一案件中,只有部分信息可以配合导致这个奇怪名称. 要修复, 请为 @ connection 提供一个值 _名称_ 参数,并通过在 **注释** 类型.

##### 命名的连接

这个 **名称** 参数指定名称 连接和用于创建参考的双向关系 同样的外国钥匙.

比如说,如果你想要你的 `Post.comments` 财务报告和审定财务报表 `Comment.post` 字段来指同一种关系的相向 你会提供一个名字.

```graphql
type Post @model {
  id: ID!
  title: String!
  comments: [Comment] @connection(name: "PostComments")
}
type Comment @model {
  id: ID!
  content: String!
  post: Post @connection(name: "PostComments")
}
```

一个转变,你会用一个帖子来创建评论:

```graphql
mutation CreateCommentOnPost {
  createComment(input: { content: "A comment", commentPostId: "a-post-id" }) {
    id
    content
    post {
      id
      title
      comments {
        id
        # and so on...
      }
    }
  }
}
```

#### 业绩

为了保持连接查询的速度和效率,图克l转换管理 代表您在生成的表格上显示 GSI 。 我们烤在最佳做法 保持 您的询问很有效, 但这也会带来额外的成本.

### @ 可搜索

这个 `@searchable` 指令处理源源流中的数据 `@model` 对象类型 并配置搜索该信息的解析器.

#### 定义

```graphql
# Streams data from dynamodb into opensearch and exposes search capabilities.
directive @searchable(queries: SearchableQueryMap) on OBJECT
input SearchableQueryMap {
  search: String
}
```

**什么是放大图形QL 变换**

放大图形QL变换(Amplify GraphQL Transform)是一组致力于简化在AWS上开发,部署,维持API的过程的库. 通过它,您使用 GraphQL Schema 定义语言( SDL) 定义您的 API, 然后传递到这个库中, 它被扩展并转换为一个完全描述的云形模板, 用于执行您的 API 数据模型 .

例如,您可以定义这样的应用程序的数据模型 :

```graphql
type Blog @model @searchable {
  id: ID!
  name: String!
  posts: [Post] @connection(name: "BlogPosts")
}
type Post @model @searchable {
  id: ID!
  title: String!
  tags: [String]
  blog: Blog @connection(name: "BlogPosts")
  comments: [Comment] @connection
  createdAt: String
  updatedAt: String
}
type Comment @model {
  id: ID!
  content: String!
}
```

然后把计划传给一个实例 `GraphQLTransform` 有迪纳摩DB的班级, `@searchable`,并启用了连接变压器:

```javascript
import GraphQLTransform from 'graphql-transformer-core';
import AppSyncDynamoDBTransformer from 'graphql-dynamodb-transformer';
import SearchableModelTransformer from 'amplify-graphql-searchable-transformer';
import AppSyncConnectionTransformer from 'graphql-connection-transformer';
import AppSyncAuthTransformer from 'graphql-auth-transformer';

const transformer = new GraphQLTransform({
  transformers: [
    new AppSyncDynamoDBTransformer(),
    new SearchableModelTransformer(),
    new AppSyncAuthTransformer(),
    new AppSyncConnectionTransformer(),
  ],
});
const cfdoc = transformer.transform(schema.readSync());
const out = await createStack(cfdoc, name, region);
console.log('Application creation successfully started. It may take a few minutes to finish.');
```

这个 `GraphQLTransform` 类执行单 `transform()` 函数,当引用解析文档时,行走 AST,当指令如 **@ 模式** 中查找任何相关的变压器. 在这种情况下,变压器是为您定义的,但代码的结构使得写自定义变压器尽可能简单. 上面代码的输出是一个完整的CloudFormation文档,它定义了DynamoDB表格,OpenSearch集群,从DynamoDB流出的一个lambda函数 -> 打开搜索器, a AppSync API, AppSync 数据源, CRUD 解析器(创建,更新,删除,获取,列表,搜索),执行存储在不同DynamoDB表格中的类型间连接的解析器, 一些最小范围的IAM角色,

## 图QL 变形库

该代码被包含在单回波中,包含一些与变换相关的包件和一些没有的包件. 相关套件细分如下:

**图ql- 转换**

该套件包含库的核心,并起到切换的切入点的作用. 核心类 `GraphQLTransform` 作为配置一个变压器列表,并处理解析输入SDL的逻辑,走AST,并引导指令到变压器.

**图ql- dynamodb- 转换器**

本套件执行了一系列针对迪纳摩DB的指令. 框外,此执行 **@ 模式** 财务报告和审定财务报表 **连接** 指令。 。 .

**放大- ql- 可搜索- 转换器**

此软件包执行处理可搜索数据源的任何指令。 框外,此执行 **@ 可搜索** 指令.

**图ql- auth 转换器**

此软件包执行任何与authN或authZ工作流程相关的指令. 框外,它配置一个 _亚马逊- 科尼托用户Pool_ 执行 **@ 奥斯** 指令.

**图ql- 转换- e2e- 测试**

这个pakge为变换库执行端到端测试. 它与变换一起构建出API,通过CloudFormation部署,并点击AppSync数据平面来测试所有生成的代码路径.

**图克l-映射-模板**

此包提供AppSync Conclationr VTL周围的轻量级包装机,被变压器库用作方便.

### 先决条件

-   你需要拥有 [已安装节点和npm](https://nodejs.org/en/download/)。 。 。 .
-   您需要安装 `lerna` 财务报告和审定财务报表 `yarn` 作为 npm 全局软件包.

```
npm install -g lerna
npm install -g yarn
```

### 安装

安装依赖关系

```
lerna bootstrap
```

和建设

```
lerna run build
```

## 运行测试

测试用 [欢笑](https://facebook.github.io/jest/) 可以运行到所有软件包

```
lerna run test
```

或者,有些调试配置在 [.vscode/launch.json (英语)](https://npmcn.com/package/%40aws-amplify/graphql-transformer-core/.vscode/launch.json) 您可以使用Visual Studio代码添加调试断点来调试代码.

## 捐款

开始

## 版本

开始

## 许可证

这个项目根据麻省理工学院许可证颁发——见 [利比里亚](https://npmcn.com/package/%40aws-amplify/graphql-transformer-core/LICENSE.md) 详细文件

## 常见问题

### @aws-amplify/graphql-transformer-core 是什么？

从 GraphQL SDL 转换为 AWS Cloud Formation 的框架 \.

### 如何安装 @aws-amplify/graphql-transformer-core？

在项目目录运行 npm install @aws-amplify/graphql-transformer-core，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：constructs（^10\.3\.0）、aws-cdk-lib（^2\.224\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-amplify/graphql-transformer-core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws-amplify/graphql-transformer-core 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws-amplify/graphql-transformer-core 可以商用吗？

@aws-amplify/graphql-transformer-core 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-amplify/graphql-transformer-core 的下载量有多少？

根据 npm 官方下载统计，@aws-amplify/graphql-transformer-core 在 2026/10/07 – 2026/11/05 这 30 天内被下载 963,384 次，日均约 32,113 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws-amplify/graphql-transformer-core 还在维护吗？

最新版本 3\.6\.2 发布于 2026/10/01（1 个月前）；至今共发布 462 个版本，其中过去 12 个月发布了 8 个；首次发布于 2020/11/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。