TypeGraphQL项目启动指南：从构建Schema到服务部署

TypeGraphQL项目启动指南：从构建Schema到服务部署

type-graphql 项目地址: https://gitcode.com/gh_mirrors/typ/type-graphql

前言

TypeGraphQL是一个强大的库，它允许开发者使用TypeScript类和装饰器来构建GraphQL API。本文将详细介绍如何启动一个基于TypeGraphQL的项目，包括构建可执行Schema、处理孤立类型以及部署GraphQL服务。

构建可执行Schema

基本配置

在TypeGraphQL中，构建Schema的核心是buildSchema函数。这个异步函数接收一个配置对象，其中最重要的是resolvers数组，它包含了所有的解析器类：

import { buildSchema } from "type-graphql";
import { UserResolver, PostResolver } from "./resolvers";

async function initializeSchema() {
  const schema = await buildSchema({
    resolvers: [UserResolver, PostResolver],
  });
  return schema;
}

处理孤立类型

在实际开发中，你可能会遇到一些定义但未被直接引用的类型（称为"孤立类型"）。这些类型需要显式声明在orphanedTypes选项中：

const schema = await buildSchema({
  resolvers: [UserResolver, PostResolver],
  orphanedTypes: [Category, Tag], // 未被直接引用的类型
});

TypeScript类型提示

为了确保TypeScript能正确推断解析器数组类型，建议使用as const断言：

// resolvers.ts
export const resolvers = [UserResolver, PostResolver] as const;

// schema.ts
import { resolvers } from "./resolvers";

const schema = await buildSchema({ resolvers });

服务部署方案

使用Apollo Server

Apollo Server是部署GraphQL服务的流行选择。以下是如何将其与TypeGraphQL结合使用的示例：

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

async function startServer() {
  const schema = await initializeSchema();
  
  const server = new ApolloServer({ schema });
  
  const { url } = await startStandaloneServer(server, {
    listen: { port: 4000 },
  });
  
  console.log(`服务已启动，访问地址: ${url}`);
}

startServer();

其他部署选项

TypeGraphQL具有很好的灵活性，可以与多种GraphQL服务器实现配合使用：

1. Express中间件：使用express-graphql
2. GraphQL Yoga：一个全功能的GraphQL服务器
3. WebSocket服务：实现实时GraphQL订阅
4. MQTT：物联网场景下的轻量级消息协议

替代方案：构建类型定义和解析器映射

除了直接构建Schema外，TypeGraphQL还提供了buildTypeDefsAndResolvers函数，它返回类型定义和解析器映射，可以与其他工具链集成：

import { makeExecutableSchema } from "@graphql-tools/schema";

const { typeDefs, resolvers } = await buildTypeDefsAndResolvers({
  resolvers: [UserResolver, PostResolver],
});

const schema = makeExecutableSchema({ typeDefs, resolvers });

同步版本

对于不需要异步操作的情况，可以使用同步版本：

const { typeDefs, resolvers } = buildTypeDefsAndResolversSync({
  resolvers: [UserResolver, PostResolver],
});

最佳实践建议

1. 项目结构：保持清晰的目录结构，将解析器、类型定义和服务配置分开
2. 环境变量：使用环境变量管理端口等配置
3. 错误处理：实现全局错误处理中间件
4. 性能监控：考虑添加Apollo Studio或GraphQL Playground进行调试
5. 生产准备：禁用开发环境专用的GraphQL工具

总结

TypeGraphQL提供了灵活的方式来构建和部署GraphQL服务。无论是直接构建可执行Schema，还是生成类型定义和解析器映射与其他工具集成，开发者都可以根据自己的需求选择最适合的方案。通过本文介绍的方法，你应该能够顺利启动并运行一个基于TypeGraphQL的GraphQL服务。

type-graphql 项目地址: https://gitcode.com/gh_mirrors/typ/type-graphql