GraphQL-Nexus 入门教程：项目初始化与首个查询

GraphQL-Nexus 入门教程：项目初始化与首个查询

前言

GraphQL-Nexus 是一个强大的 TypeScript 优先的 GraphQL 框架，它通过代码优先（Code-First）的方式帮助开发者构建类型安全的 GraphQL API。本文将带你完成 GraphQL-Nexus 项目的初始设置，并实现第一个 GraphQL 查询。

环境准备

项目初始化

首先创建一个新项目目录并初始化 Node.js 项目：

mkdir nexus-tutorial && cd nexus-tutorial
npm init -y

安装核心依赖

安装 GraphQL-Nexus 及其运行时依赖：

npm install nexus graphql apollo-server

这里我们选择 Apollo Server 作为 GraphQL 服务器实现，但 GraphQL-Nexus 兼容任何符合 GraphQL 规范的服务器实现。

开发依赖安装

为了获得更好的开发体验，我们需要安装 TypeScript 相关工具：

npm install --save-dev typescript ts-node-dev

ts-node-dev 是一个开发工具，它能够实时编译 TypeScript 文件并在代码变更时自动重启服务。

TypeScript 配置

创建 tsconfig.json 文件，配置如下：

{
  "compilerOptions": {
    "target": "ES2018",
    "module": "commonjs",
    "lib": ["esnext"],
    "strict": true,
    "rootDir": ".",
    "outDir": "dist",
    "sourceMap": true,
    "esModuleInterop": true
  }
}

这个配置启用了严格的类型检查，并设置了适当的模块系统和目标环境。

添加 NPM 脚本

在 package.json 中添加开发和生产构建脚本：

"scripts": {
  "dev": "ts-node-dev --transpile-only --no-notify api/index.ts",
  "build": "tsc"
}

dev 脚本用于开发环境，build 脚本用于生产环境构建。

项目结构搭建

创建 Schema 文件

首先创建 API 目录和 Schema 文件：

mkdir api && touch api/schema.ts

在 api/schema.ts 中初始化 GraphQL-Nexus Schema：

import { makeSchema } from 'nexus'
import { join } from 'path'

export const schema = makeSchema({
  types: [], // 这里将放置我们的GraphQL类型定义
  outputs: {
    typegen: join(__dirname, '..', 'nexus-typegen.ts'), // 类型生成文件路径
    schema: join(__dirname, '..', 'schema.graphql'), // GraphQL Schema文件路径
  },
})

这里有几个关键点：

1. types 数组用于存放所有 GraphQL 类型定义
2. typegen 指定了类型生成文件的输出路径，这是 Nexus 类型安全系统的核心
3. schema 指定了 GraphQL SDL 文件的输出路径

服务器配置

创建服务器实例文件 api/server.ts：

import { ApolloServer } from 'apollo-server'
import { schema } from './schema'

export const server = new ApolloServer({ schema })

创建应用入口文件 api/index.ts：

import { server } from './server'

server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`)
})

这种分离服务器实例化和启动逻辑的设计，为后续测试提供了便利。

启动应用

运行开发命令启动服务：

npm run dev

成功启动后，终端会显示服务运行地址：

🚀 Server ready at http://localhost:4000

探索 GraphQL Playground

访问 http://localhost:4000 将会看到 GraphQL Playground 界面。这是 Nexus 内置的 GraphQL API 交互界面，开发者可以在这里：

1. 查看自动生成的 API 文档（SCHEMA 标签页）
2. 编写和执行 GraphQL 查询
3. 查看查询执行结果

目前 Playground 会显示一个默认的 Schema，这是 Nexus 提供的占位内容。随着我们添加自定义类型，这个 Schema 会自动更新。

总结

至此，我们已经完成了：

1. GraphQL-Nexus 项目的基本配置
2. TypeScript 环境搭建
3. 基础项目结构创建
4. GraphQL 服务器启动
5. 开发工具链配置

在下一章中，我们将开始构建实际的 GraphQL Schema，定义自己的类型和查询。