nuxt-graphql-server

使用 Nuxt 轻松实现 GraphQL 服务器
2.3K 下载38 星v3.1.6
tobiasdieztobiasdiez

适用于 Nuxt 的 GraphQL 服务器工具包

npm versionnpm downloadsGithub ActionsCodecov

此包允许您在 Nuxt 3 应用程序中轻松开发 GraphQL 服务器。

要在客户端使用 GraphQL API，我们推荐模块 Nuxt Apollo、Nuxt GraphQL Client 或 nuxt/graphql-client。

功能

  • 提供一个虚拟模块 #graphql/schema，您可以从中导入您的模式。在底层，它会自动将多个模式文件合并为一个完整的模式。此外，您不再需要担心部署模式 graphql 文件。
  • 通过虚拟模块 #graphql/resolver 自动为您的解析器生成 TypeScript 定义。
  • 支持 GraphQL 订阅。
  • Nuxt Devtools 集成：直接在 devtools 中添加 Apollo Studio Sandbox。

安装

# nuxi
npx nuxi@latest module add graphql-server

# npm
npm install @apollo/server graphql @as-integrations/h3 nuxt-graphql-server

# yarn
yarn add @apollo/server graphql @as-integrations/h3 nuxt-graphql-server

# pnpm
pnpm add @apollo/server graphql @as-integrations/h3 nuxt-graphql-server

使用

  1. 如果不是使用 nuxi 进行安装，请在 nuxt.config.ts 中添加模块
    export default defineNuxtConfig({
  modules: ['nuxt-graphql-server'],
  // Optional top-level config
  graphqlServer: {
    // config
  },
})

// or

export default defineNuxtConfig({
  modules: [
    [
      'nuxt-graphql-server',
      {
        /* Optional inline config */
      },
    ],
  ],
})
  2. 在 server 文件夹中的 .graphql 文件中定义 GraphQL 模式。
  3. 通过创建包含以下内容的 server/api/graphql.ts 文件来暴露 GraphQL API 端点
    import { Resolvers } from '#graphql/resolver'
import { typeDefs } from '#graphql/schema'
import { ApolloServer } from '@apollo/server'
import { startServerAndCreateH3Handler } from '@as-integrations/h3'

const resolvers: Resolvers = {
  Query: {
    // Typed resolvers
  },
}

const apollo = new ApolloServer({ typeDefs, resolvers })

export default startServerAndCreateH3Handler(apollo, {
  // Optional: Specify context
  context: (event) => {
    /*...*/
  },
})
  4. 可选地，在 nuxt.config.ts 中指定 GraphQL 端点的（相对）URL 以启用 Nuxt Devtools 集成。
    graphqlServer: {
   url: '/api/graphql',
}

订阅

要启用订阅，您需要安装更多依赖项

# npm
npm install graphql-ws graphql-subscriptions

# yarn
yarn add graphql-ws graphql-subscriptions

# pnpm
pnpm add graphql-ws graphql-subscriptions

包 graphql-ws 是一个轻量级 WebSocket 服务器，可用于处理 GraphQL 订阅。包 graphql-subscriptions 提供了 PubSub 类，可用于发布和订阅事件。

请注意，默认的 PubSub 实现仅用于演示目的。它只适用于您只有一个服务器实例的情况，并且无法扩展到少量连接之外。对于生产用途，您需要使用由外部存储（例如 Redis）支持的 PubSub 实现之一。

在您的 nuxt.config.ts 中激活 WebSocket 支持

nitro: {
  experimental: {
    websocket: true,
  },
},

然后，创建包含以下内容的端点 server/api/graphql.ts

import { ApolloServer } from '@apollo/server'
import {
  startServerAndCreateH3Handler,
  defineGraphqlWebSocket,
} from '@as-integrations/h3'
import { makeExecutableSchema } from '@graphql-tools/schema'
import type { Resolvers } from '#graphql/resolver'
import { typeDefs } from '#graphql/schema'

const resolvers: Resolvers = {
  Query: {
    // Typed resolvers
  },
  Subscription: {
    // Typed resolvers
  },
}

const schema = makeExecutableSchema({ typeDefs, resolvers })
const apollo = new ApolloServer({ schema })
export default startServerAndCreateH3Handler(apollo, {
  websocket: defineGraphqlWebSocket({ schema }),
})

完整的示例可以在 playground 文件夹下的 server/api/subscription.ts 中找到。

选项

graphqlServer: {
  url: '/relative/path/to/your/graphql/endpoint',
  schema: './server/**/*.graphql',
  codegen: {
    maybeValue: T | null | undefined
  }
}

url

GraphQL 端点的相对 URL，用于启用 Nuxt Devtools 集成。

schema

用于定位您的 GraphQL 模式 (.graphql) 文件的 glob 模式。

默认值：'./server/**/*.graphql'

代码生成

此模块底层使用 GraphQL Code Generator，并利用 TypeScript 和 TypeScript Resolvers 插件，这意味着这些插件的任何选项都可以根据您的需求在此处传递。

例如，您可能希望

export default defineNuxtConfig({
  modules: ['nuxt-graphql-server'],

  graphqlServer: {
    codegen: {
      // Map your internal enum values to your GraphQL's enums.
      enumValues: '~/graphql/enums/index',

      // Make use of your custom GraphQL Context type and let codegen use it so that the
      // generated resolvers automatically makes use of it.
      contextType: '~/server/graphql/GraphQLContext#GraphQLContext',

      // Change the naming convention of your enum keys
      namingConvention: {
        enumValues: 'change-case-all#constantCase',
      },

      // ... and many more, refer to the plugin docs!
    },
  },
})

💻 开发

  • 克隆此仓库
  • 使用 corepack enable 启用 Corepack（对于 Node.js < 16.10，请使用 npm i -g corepack）。
  • 使用 pnpm install 安装依赖项。
  • 运行 pnpm dev:prepare 以生成类型存根。
  • 使用 pnpm dev 在开发模式下启动 playground。

许可证

用心制作 💛

根据 MIT 许可证发布。