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;补丁版本会随安装时间不同。
node --version
npm --version预期输出类似:
v24.<VALUE>
<VALUE>只要 Node.js 主版本为 24 即满足本课环境。Apollo Server 5 运行在现代 Node.js 环境中,而本课显式安装 GraphQL.js 16.11 或更高的 16.x 版本。
初始化项目与依赖
创建目录、初始化包并安装运行依赖与 TypeScript 工具链。这里固定使用 ESM,避免 CommonJS 与 ESM 混用造成导入问题。
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 与示例一致。
{
"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。
{
"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 服务。
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 编译,再启动输出文件。
npm run build
npm start预期输出中应看到构建脚本完成,并出现本地服务地址;具体日志前缀可能随版本不同。
> 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,动态输入不直接拼进查询文本。
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'预期输出为:
{"data":{"hello":"Hello, Anystack!"}}
HTTP 200如果返回 ECONNREFUSED,说明服务没有监听 4000 端口,应先检查启动终端;如果响应中出现 GraphQL errors,则 HTTP 链路通常已经通了,应继续核对字段名、变量类型和 Schema。能稳定得到上面的 data.hello 后,这个 TypeScript GraphQL 项目就具备了继续添加 Query、Mutation、context 与数据源的可靠基础。