API 设计 / 系统课时

搭建 TypeScript GraphQL 服务

搭建 TypeScript GraphQL 服务

这一课从空目录搭建一个可运行的 TypeScript GraphQL 服务:使用 Node.js 24 LTS、Apollo Server 5、GraphQL.js 16.11+,定义最小 Schema 与 resolver,并通过本地请求验证查询链路。

学习目标

  • 完成 Node.js、TypeScript、Apollo Server 与 GraphQL.js 的最小项目配置
  • 能定义 Schema、resolver 并启动独立 GraphQL HTTP 服务
  • 能通过 HTTP 请求验证查询结果并定位常见启动失败

检查运行环境

先确认 Node.js 与 npm 可用。下面命令假设已经安装 Node.js 24 LTS;补丁版本会随安装时间不同。

bash
node --version
npm --version

预期输出类似:

text
v24.<VALUE>
<VALUE>

只要 Node.js 主版本为 24 即满足本课环境。Apollo Server 5 运行在现代 Node.js 环境中,而本课显式安装 GraphQL.js 16.11 或更高的 16.x 版本。

初始化项目与依赖

创建目录、初始化包并安装运行依赖与 TypeScript 工具链。这里固定使用 ESM,避免 CommonJS 与 ESM 混用造成导入问题。

bash
mkdir graphql-ts-service
cd graphql-ts-service
npm init -y
npm install @apollo/server@^5 graphql@^16.11.0
npm install -D typescript@^5 @types/node@^24

预期结果是依赖安装成功,并在当前目录生成 package.json 与 package-lock.json;npm 显示的包数量和审计信息会随时间变化,不应作为验收条件。

接着把 package.json 调整为下面的最小配置。它是完整文件示例,保留 npm 安装后生成的依赖版本即可,只需要确保 type 和 scripts 与示例一致。

json
{
  "name": "graphql-ts-service",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "@apollo/server": "^5.0.0",
    "graphql": "^16.11.0"
  },
  "devDependencies": {
    "@types/node": "^24.0.0",
    "typescript": "^5.0.0"
  }
}

再创建 tsconfig.json。NodeNext 让 TypeScript 按 Node.js 的 ESM 规则解析模块,输出目录集中到 dist。

json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*.ts"]
}

配置生效后,npm run build 会只编译 src 下的 TypeScript,并把 JavaScript 写到 dist。

编写最小 GraphQL 服务

创建 src/index.ts。Schema 定义一个 hello 查询字段,resolver 返回固定字符串;startStandaloneServer 会启动 Apollo Server 自带的独立 HTTP 服务。

ts
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';

const typeDefs = `#graphql
  type Query {
    hello(name: String!): String!
  }
`;

const resolvers = {
  Query: {
    hello: (_parent: unknown, args: { name: string }) => {
      // resolver 的职责是把 Schema 字段映射到真实数据或业务逻辑。
      return `Hello, ${args.name}!`;
    },
  },
};

const server = new ApolloServer({
  typeDefs,
  resolvers,
});

const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
});

console.log(`GraphQL server ready at ${url}`);

预期结果:该文件在依赖与配置正确时可以通过 TypeScript 编译;启动后会监听 http://localhost:4000/。Apollo Server 会根据 Schema 校验操作,再调用与字段同名的 resolver;若以后接数据库或其他服务,应把连接对象放进 context,而不是写成全局可变状态。

编译并启动服务

先执行 TypeScript 编译,再启动输出文件。

bash
npm run build
npm start

预期输出中应看到构建脚本完成,并出现本地服务地址;具体日志前缀可能随版本不同。

text
> graphql-ts-service@1.0.0 build
> tsc

> graphql-ts-service@1.0.0 start
> node dist/index.js

GraphQL server ready at http://localhost:4000/

如果 tsc 报模块解析错误,优先检查 package.json 是否包含 "type": "module",以及 tsconfig.json 是否同时使用 "module": "NodeNext" 和 "moduleResolution": "NodeNext"。

发送查询验证链路

保持服务进程运行,在另一个终端向根路径发送 GraphQL HTTP POST 请求。请求体包含 query 与 variables,动态输入不直接拼进查询文本。

bash
curl -sS http://localhost:4000/ \
  -H 'content-type: application/json' \
  --data '{"query":"query Hello($name: String!) { hello(name: $name) }","variables":{"name":"Anystack"}}' \
  -w '\nHTTP %{http_code}\n'

预期输出为:

text
{"data":{"hello":"Hello, Anystack!"}}
HTTP 200

如果返回 ECONNREFUSED,说明服务没有监听 4000 端口,应先检查启动终端;如果响应中出现 GraphQL errors,则 HTTP 链路通常已经通了,应继续核对字段名、变量类型和 Schema。能稳定得到上面的 data.hello 后,这个 TypeScript GraphQL 项目就具备了继续添加 Query、Mutation、context 与数据源的可靠基础。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

搭建 TypeScript GraphQL 服务

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通