# GraphQL 技能 ## 总结 GraphQL 是一种 API 查询语言和运行时，使客户端能够准确请求他们需要的数据。它提供了强类型模式、单端点架构，并消除了 REST API 中常见的过度获取/不足获取问题。 ## 何时使用 * 为多种客户端类型（网络、移动、物联网）构建灵活的 API * 具有嵌套关系的复杂数据需求 * 需要带宽效率的移动优先应用程序 * 降低API版本控制的复杂性 * 订阅实时数据 * 微服务聚合和联合 * 具有强大打字和内省能力的开发人员经验 ## 快速入门 ### 1\.定义架构 (SDL) # schema.graphql 类型用户{ 身份证：身份证！名称：字符串！电子邮件：字符串！帖子：[帖子！]！ } 输入帖子{ 身份证：身份证！标题：字符串！内容：字符串！作者：用户！发布时间：日期时间 } 类型查询{ user(id: ID!): 用户用户：[用户！]！ post(id: ID!): 发布 } 类型突变 { createPost（标题：字符串！，内容：字符串！，authorId：ID！）：发布！ updatePost(id: ID!, title: String, content: String): 发布！ deletePost(id: ID!): 布尔值！ } ### 2\.编写解析器（TypeScript + Apollo 服务器）从 '@apollo/server' 导入 { ApolloServer }；从 '@apollo/server/standalone' 导入 { startStandaloneServer }；从 'fs' 导入 { readFileSync }； // 加载模式 const typeDefs = readFileSync('./schema.graphql', 'utf-8'); // 模拟数据常量用户 = [ { id: '1', 姓名: 'Alice', 电子邮件: 'alice@example.com' }, { id: '2', 姓名: 'Bob', 电子邮件: 'bob@example.com' }, ]; 常量帖子 = [ { id: '1', title: 'GraphQL 介绍', content: '学习 GraphQL...',authorId: '1' }, { id: '2', title: 'Apollo Server', content: '构建 API...',authorId: '1' }, ]; // 解析器常量解析器 = { 查询：{ 用户： (_, { id }) => users.find(u => u.id === id), 用户：() => 用户，帖子： (_, { id }) => posts.find(p => p.id === id), }, 突变：{ createPost: (_, { 标题, 内容, 作者Id }) => { 常量帖子 = { id: String(posts.length + 1), 标题，内容，作者ID, }; posts.push(post); 返回帖子； }, updatePost: (_, { id, 标题, 内容 }) => { const post = posts.find(p => p.id === id); if (!post) throw new Error('帖子未找到'); if (标题) post.title = 标题; if (内容) post.content = 内容; 返回帖子； }, 删除帖子: (_, { id }) => { const index = posts.findIndex(p => p.id === id); if (index === -1) 返回 false; posts.splice(索引, 1); 返回真； }, }, 用户：{ posts: (user) => posts.filter(p => p.authorId === user.id), }, 帖子：{ 作者：(post) => users.find(u => u.id === post.authorId), }, }; // 创建服务器 const server = new ApolloServer({ typeDefs, 解析器 }); 启动StandaloneServer（服务器，{ 听：{端口：4000}， }).then(({ url }) => { console.log(`🚀 服务器已在 ${url}` 准备就绪`); }); ### 3\.查询数据（客户端） // 使用 Apollo 客户端从 '@apollo/client' 导入 { ApolloClient, InMemoryCache, gql }; const 客户端 = 新 ApolloClient({ uri: 'http://localhost:4000', 缓存：new InMemoryCache(), }); // 查询常量 GET_USER = gql` 查询 GetUser($id: ID!) { 用户（id：$id）{ 编号姓名电子邮件帖子{ 编号标题发表于 } } } `; const { 数据 } = 等待 client.query({ 查询：GET_USER，变量：{id：'1'}， }); // 变异常量 CREATE_POST = gql` 突变 CreatePost($title: 字符串!, $content: 字符串!, $authorId: ID!) { createPost(标题：$title，内容：$content，authorId：$authorId) { 编号标题内容 } } `; const { data: postData } = 等待 client.mutate({ 突变：CREATE_POST，变量：{ 标题：“新帖子”，内容：'你好 GraphQL！'，作者 ID: '1', }, }); ** ** ## 核心概念 ### GraphQL 基础知识 * **模式优先设计** ：使用模式定义语言 (SDL) 定义 API 合约 * **类型安全**：在运行时和构建时强制执行强类型模式 * **单一端点**：所有查询和突变都通过一个 URL（例如，`/graphql`） * **客户指定的查询**：客户准确地请求他们需要的内容 * **分层数据**：查询反映返回数据的形状 * **内省** ：模式是自记录且可查询的 ### 运营 # 查询 - 读取数据（类似 GET）查询获取用户{ 用户（ID：“1”）{ 姓名 } } # Mutation - 修改数据（类似 POST/PUT/DELETE）突变创建用户{ createUser(姓名：“Alice”，电子邮件：“alice@example.com”) { 编号姓名 } } # 订阅 - 实时更新 (WebSocket) 订阅 OnPostCreated { 帖子创建{ 编号标题作者{ 姓名 } } } ### 字段和参数类型查询{ # 带参数的字段 user(id: ID!): 用户用户（限制：Int = 10，偏移：Int = 0）：[用户！]！ # 使用多个参数进行搜索搜索帖子( 查询：字符串！类别：字符串限制：智力 = 20 ）：[发帖！]！ } ** ** ## 模式定义语言 (SDL) ### 基本类型定义类型用户{ 身份证：身份证！ # 非空 ID 标量名称：字符串！ # 非空字符串电子邮件：字符串！年龄：Int # Nullable Int isActive：布尔值！帖子：[帖子！]！ # 非空帖子的非空列表 profile: Profile # 可空对象类型 } 类型配置文件{ 简介：字符串头像网址：字符串网站：字符串 } 输入帖子{ 身份证：身份证！标题：字符串！内容：字符串！作者：用户！ Tags: [String!] # 非空列表，可为空元素发布时间：日期时间 } ### 输入类型（用于突变）输入创建用户输入{ 名称：字符串！电子邮件：字符串！年龄：内科 } 输入更新用户输入{ 名称：字符串电子邮件：字符串年龄：内科 } 类型突变 { createUser（输入：CreateUserInput！）：用户！ updateUser(id: ID!, 输入: UpdateUserInput!): 用户！ } ### 接口接口节点{ 身份证：身份证！创建于：日期时间！更新时间：日期时间！ } 类型用户实现节点{ 身份证：身份证！创建于：日期时间！更新时间：日期时间！名称：字符串！电子邮件：字符串！ } 类型 Post 实现 Node { 身份证：身份证！创建于：日期时间！更新时间：日期时间！标题：字符串！内容：字符串！ } 类型查询{ node(id: ID!): Node # 可以返回 User 或 Post } ### 工会联合搜索结果=用户|帖子 |评论类型查询{ 搜索（查询：字符串！）：[搜索结果！]！ } # 带片段的客户端查询查询搜索{ 搜索（查询：“graphql”）{ ...关于用户{ 姓名电子邮件 } ...在帖子{ 标题内容 } ...关于评论{ 文本作者{姓名} } } } ### 枚举枚举角色{ 管理员主持人用户来宾 } 枚举 PostStatus { 草案已发表存档 } 类型用户{ 身份证：身份证！名称：字符串！角色：角色！ } 输入帖子{ 身份证：身份证！标题：字符串！状态：帖子状态！ } ** ** ## 类型系统 ### 标量类型 # 内置标量标量 Int # 有符号 32 位整数 scalar Float # 有符号双精度浮点标量 String # UTF-8 字符序列标量布尔值 # true 或 false 标量 ID # 唯一标识符（序列化为字符串） # 自定义标量标量 DateTime # ISO 8601 时间戳标量电子邮件# 电子邮件地址标量 URL # 有效 URL 标量 JSON # 任意 JSON 标量上传 # 文件上传 ### 自定义标量实现 // 日期时间标量 (TypeScript) 从 'graphql' 导入 { GraphQLScalarType, Kind }; const DateTimeScalar = new GraphQLScalarType({ name: '日期时间', 描述：“ISO 8601 日期时间”， // 序列化到客户端（输出）序列化（值：日期）{ 返回值.toISOString(); }, // 从客户端解析（输入）解析值（值：字符串）{ 返回新日期（值）； }, // 从查询文字中解析解析文字（ast）{ if (ast.kind === Kind.STRING) { 返回新日期（ast.value）； } 返回空值； }, }); // 添加到解析器常量解析器 = { 日期时间：日期时间标量， // ...其他解析器 }; ### 非空和列表类型用户{ 名称：字符串！ # 非空字符串 email: String # 可为空的字符串标签：[字符串！]！ # 非空字符串的非空列表 Friends: [User!] # 非空用户的可为空列表帖子：[帖子]！ # 可为空帖子的非空列表 comments: [Comment] # 可为空的评论的可为空列表 } ** ** ## 查询和变更 ### 查询变量 // 使用变量定义查询常量 GET_USER = gql` 查询 GetUser($id: ID!, $includePosts: Boolean = false) { 用户（id：$id）{ 编号姓名电子邮件帖子 @include(if: $includePosts) { 编号标题 } } } `; // 使用变量执行 const { 数据 } = 等待 client.query({ 查询：GET_USER，变量：{ id: '1', 包含帖子：真实， }, }); ### 别名查询{ # 使用不同的参数获取相同的字段用户1：用户（id：“1”）{ 姓名 } 用户2：用户（id：“2”）{ 姓名 } # 为清楚起见使用别名当前用户：我{ 编号姓名 } } ### 碎片 # 定义可重用的片段用户 { 上的片段 UserFields 编号姓名电子邮件创建于 } 帖子上的片段帖子摘要 { 编号标题发表于作者{ ...用户字段 } } # 在查询中使用片段查询{ 用户（ID：“1”）{ ...用户字段帖子{ ...帖子总结 } } } ### 指令 # 内置指令查询 GetUser($id: ID!, $withPosts: 布尔值!, $skipEmail: 布尔值!) { 用户（id：$id）{ 姓名电子邮件@skip（如果：$skipEmail）帖子 @include(if: $withPosts) { 标题 } } } # 自定义指令定义 FIELD_DEFINITION 上的指令 @auth（需要：角色 = USER）类型查询{ 用户：[用户！]！ @auth（需要：管理员）我：用户！ @auth } ### 突变最佳实践 # 输入类型的单突变类型突变 { createPost（输入：CreatePostInput！）：CreatePostPayload！ updatePost(id: ID!, 输入: UpdatePostInput!): UpdatePostPayload! deletePost(id: ID!): 删除PostPayload！ } 输入 CreatePostInput { 标题：字符串！内容：字符串！类别ID：ID！标签：[字符串！] } # 突变的有效负载模式类型 CreatePostPayload { 帖子：帖子 # 创建的资源用户错误：[用户错误！]！ # 客户端错误成功：布尔值！ } 类型用户错误{ 字段：字符串！ # 哪个字段导致错误消息：字符串！ # 人类可读的消息 } ** ** ## 解析器和数据加载器 ### 解析器签名类型解析器 = ( Parent: TParent, // 父对象 args: TArgs, // 字段参数 context: TContext, // 共享上下文（auth、db 等） info: GraphQLResolveInfo // 查询元数据 ) => TResult |承诺 ; ### 基本解析器常量解析器 = { 查询：{ 用户：异步（_，{id}，{db}）=>{ 返回 db.users.findById(id); }, 用户： async (_, { limit = 10, offset = 0 }, { db }) => { 返回 db.users.findMany({ limit, offset }); }, }, 突变：{ createUser: async (_, { 输入 }, { db, userId }) => { if (!userId) { 抛出新错误（'需要身份验证'）； } const user =等待db.users.create(input); 返回 { user, userErrors: [], success: true }; }, }, 用户：{ // 字段解析器 - 仅在客户端请求“posts”时调用帖子： async (user, _, { db }) => { 返回 db.posts.findByAuthorId(user.id); }, // 计算域全名：（用户）=> { 返回 `${user.firstName} ${user.lastName}`; }, }, }; ### N+1 问题 // ❌ 不好 - N+1 查询常量解析器 = { 查询：{ users: () => db.users.findMany(), // 1 条查询 }, 用户：{ // 为每个用户调用 - N 个查询！帖子：（用户）=> db.posts.findByAuthorId(user.id), }, }; // 查询 100 个用户 = 1 + 100 = 101 次数据库查询！ ### 数据加载器解决方案从“数据加载器”导入数据加载器； // 批处理函数 - 接收键数组异步函数batchLoadPosts(authorIds: string[]) { const posts =等待db.posts.findByAuthorIds(authorIds); // 按作者 ID 分组 const postsByAuthor =authorIds.map(authorId => posts.filter(post => post.authorId ===authorId) ）；返回作者的帖子； } // 使用加载器创建上下文函数createContext({ req }) { 返回{ 分贝，用户Id：req.userId，装载机：{ 帖子：新的DataLoader（batchLoadPosts）， }, }; } // ✅ 好 - 批量查询常量解析器 = { 查询：{ users: () => db.users.findMany(), // 1 条查询 }, 用户：{ // 使用 DataLoader - 将所有请求批处理为 1 个查询！帖子：（用户，_，{加载器}）=> { 返回 loaders.posts.load(user.id); }, }, }; // 查询 100 个用户 = 1 + 1 = 2 次数据库查询！ ### 高级 DataLoader 模式 // 带缓存的 DataLoader const userLoader = 新的 DataLoader( 异步（ID）=> { const users = wait db.users.findByIds(ids); return ids.map(id => users.find(u => u.id === id)); }, { cache: true, // 启用缓存（默认） maxBatchSize: 100, // 限制批量大小 batchScheduleFn: (cb) => setTimeout(cb, 10), // 去抖批处理 } ）； // 缓存操作 userLoader.clear(id); // 清除单键 userLoader.clearAll(); // 清除整个缓存 userLoader.prime(id, 用户); // 用值来初始化缓存 ** ** ## 订阅 ### WebSocket 设置（Apollo 服务器）从 '@apollo/server' 导入 { ApolloServer }；从'@apollo/server/express4'导入{expressMiddleware}；从 '@apollo/server/plugin/drainHttpServer' 导入 { ApolloServerPluginDrainHttpServer }；从'http'导入{createServer}；从 'ws' 导入 { WebSocketServer }；从 'graphql-ws/lib/use/ws' 导入 { useServer } ；从'@graphql-tools/schema'导入{makeExecutableSchema}；从“快递”进口快递；常量应用程序 = Express(); const httpServer = createServer(应用程序); const schema = makeExecutableSchema({ typeDefs, 解析器 }); // 用于订阅的 WebSocket 服务器 const wsServer = new WebSocketServer({ 服务器：http服务器，路径：'/graphql'， }); const serverCleanup = useServer({ schema }, wsServer); const 服务器 = 新 ApolloServer({ 模式，插件：[ ApolloServerPluginDrainHttpServer({ httpServer }), { 异步 serverWillStart() { 返回{ 异步排水服务器（）{ 等待 serverCleanup.dispose(); }, }; }, }, ], }); 等待服务器.start(); app.use('/graphql',express.json(),expressMiddleware(server)); httpServer.listen(4000); ### 订阅模式类型订阅{ 帖子创建：发帖！ postUpdated(id: ID!): 发帖！ messageAdded(channelId: ID!): 消息！ userStatusChanged(userId: ID!): 用户状态！ } 类型消息{ 身份证：身份证！文本：字符串！作者：用户！频道ID：ID！创建于：日期时间！ } 枚举用户状态{ 在线离线离开 } ### 订阅解析器 (PubSub) 从'graphql-subscriptions'导入{PubSub}； const pubsub = new PubSub(); 常量解析器 = { 突变：{ createPost: async (_, { 输入 }, { db }) => { const post =等待db.posts.create(input); // 发布给订阅者 pubsub.publish('POST_CREATED', { postCreated: 发布 }); 返回 { post, success: true, userErrors: [] }; }, sendMessage: async (_, { channelId, text }, { db, userId }) => { const 消息 = 等待 db.messages.create({ 频道ID, 文字，作者 ID：用户 ID， }); pubsub.publish(`MESSAGE_${channelId}`, { 消息添加：消息， }); 返回消息； }, }, 订阅：{ 帖子创建：{ 订阅: () => pubsub.asyncIterator(['POST_CREATED']), }, 更新后：{ 订阅: (_, { id }) => pubsub.asyncIterator([`POST_UPDATED_${id}`]), }, 消息已添加：{ 订阅：(_, {channelId }) => { 返回 pubsub.asyncIterator([`MESSAGE_${channelId}`]); }, }, }, }; ### 客户端订阅（Apollo 客户端）从 '@apollo/client' 导入 { ApolloClient, InMemoryCache, split, HttpLink }; 从 '@apollo/client/link/subscriptions' 导入 { GraphQLWsLink }；从 '@apollo/client/utilities' 导入 { getMainDefinition }；从'graphql-ws'导入{createClient}； // 用于查询和变更的 HTTP 链接常量 httpLink = 新 HttpLink({ uri: 'http://localhost:4000/graphql', }); // 用于订阅的 WebSocket 链接 const wsLink = 新 GraphQLWsLink( 创建客户端（{ url: 'ws://localhost:4000/graphql', }) ）； // 根据操作类型进行拆分常量 splitLink = split( ({ 查询 }) => { const 定义 = getMainDefinition(query); 返回（ Definition.kind === '操作定义' && definition.operation === '订阅' ）； }, wsLink, http链接）； const 客户端 = 新 ApolloClient({ 链接： splitLink，缓存：new InMemoryCache(), }); // 使用订阅 const MESSAGES_SUBSCRIPTION = gql` 订阅 OnMessageAdded($channelId: ID!) { 消息已添加（频道 ID：$频道 ID）{ 编号文本作者{ 姓名 } 创建于 } } `; 函数ChatComponent（{channelId}）{ const { 数据，加载 } = useSubscription(MESSAGES_SUBSCRIPTION, { 变量：{channelId}， }); if (正在加载) return

正在加载...

; return

新消息：{data.messageAdded.text}

; } ### Redis PubSub（生产）从'graphql-redis-subscriptions'导入{RedisPubSub}；从 'ioredis' 导入 Redis；常量选项 = { 主机：'本地主机'，端口：6379， retryStrategy: (次) => Math.min(次 * 50, 2000), }; const pubsub = 新的 RedisPubSub({ 发布者：新的Redis（选项），订阅者：新的Redis（选项）， }); // 使用与内存中 PubSub 相同的方式 pubsub.publish('POST_CREATED', { postCreated: 发布 }); pubsub.asyncIterator(['POST_CREATED']); ** ** ## 错误处理 ### 错误类型从'graphql'导入{GraphQLError}； // 自定义错误类类 AuthenticationError 扩展 GraphQLError { 构造函数（消息：字符串）{ 超级（消息，{ 扩展名：{ 代码：“未经身份验证”， http：{状态：401}， }, }); } } 类 ForbiddenError 扩展 GraphQLError { 构造函数（消息：字符串）{ 超级（消息，{ 扩展名：{ 代码：“禁止”， http：{状态：403}， }, }); } } 类 ValidationError 扩展 GraphQLError { 构造函数（消息：字符串，invalidFields：记录<字符串，字符串>）{ 超级（消息，{ 扩展名：{ 代码：'BAD_USER_INPUT'，无效字段， }, }); } } ### 在解析器中抛出错误常量解析器 = { 查询：{ 用户： async (_, { id }, { db, userId }) => { if (!userId) { throw new AuthenticationError('必须登录'); } const user = wait db.users.findById(id); 如果（！用户）{ throw new GraphQLError('未找到用户', { 扩展名：{代码：'NOT_FOUND'}， }); } 返回用户； }, }, 突变：{ createPost: async (_, { 输入 }, { db, userId }) => { const 错误：Record = {}； if (!input.title || input.title.length < 3) { error.title = '标题必须至少为 3 个字符'; } if (!input.content) { error.content = '内容为必填项'; } if (Object.keys(errors).length > 0) { throw new ValidationError('无效输入', 错误); } const post = wait db.posts.create({ ...input,authorId: userId }); 返回 { post, success: true, userErrors: [] }; }, }, }; ### 错误响应格式 { “错误”：[ { "message": "未找到用户", “位置”：[{“行”：2，“列”：3 }]， “路径”：[“用户”]， “扩展”：{ “代码”：“NOT_FOUND” } } ], “数据”：{ “用户”：空 } } ### 字段级错误处理 // 可空字段允许部分结果类型查询{ user(id: ID!): User # 错误时为 null 用户：[用户！]！ # 出错时抛出 post(id: ID!): 错误时发布 # null } // 解析器可以返回 null 而不是抛出异常常量解析器 = { 查询：{ 用户：异步（_，{id}，{db}）=>{ 尝试{ 返回等待db.users.findById(id); } 捕获（错误）{ console.error('获取用户失败：', error); 返回空值； // 返回 null 而不是错误 } }, }, }; ** ** ## 架构设计模式 ### 中继光标连接输入页面信息{ hasNextPage：布尔值！有上一页：布尔值！开始光标：字符串结束光标：字符串 } 输入 PostEdge { 节点：发帖！光标：字符串！ } 类型 PostConnection { 边缘：[PostEdge！]！页面信息：页面信息！总数：整数！ } 类型查询{ 帖子（第一：整数之后：字符串最后：Int 之前：字符串 ): 连接后！ } ### 中继连接解析器从 'graphql-relay' 导入 { fromGlobalId, toGlobalId }; 函数encodeCursor（id：字符串）：字符串{ return Buffer.from(`光标:${id}`).toString('base64'); } 函数decodeCursor（光标：字符串）：字符串{ return Buffer.from(cursor, 'base64').toString('utf-8').replace('cursor:', ''); } 常量解析器 = { 查询：{ 帖子： async (_, { 第一个 = 10, 之后 }, { db }) => { const startId = 之后？解码游标（之后）：空； // 获取first + 1来确定hasNextPage const posts =等待db.posts.findMany({ 其中：startId ？ { id: { gt: startId } } : {}, 取：第一个+1， orderBy: { createAt: 'desc' }, }); const hasNextPage = posts.length > 第一个； const 节点 = hasNextPage ？ posts.slice(0, -1) : 帖子； const 边 = 节点.map(节点 => ({ 节点，光标：encodeCursor(node.id), })); 返回{ 边缘，页面信息：{ 有下一页，有上一页：！！之后， startCursor: 边[0]?.cursor, endCursor: 边缘[edges.length - 1]?.cursor, }, 总计数：等待 db.posts.count(), }; }, }, }; ### 偏移分页（更简单）类型帖子响应{ 帖子：[帖子！]！总计：Int！ hasMore：布尔值！ } 类型查询{ 帖子（限制：Int = 10，偏移量：Int = 0）：PostsResponse！ } ### 全局对象识别（中继）接口节点{ 身份证：身份证！ # 全球唯一ID } 类型用户实现节点{ 身份证：身份证！名称：字符串！ } 类型 Post 实现 Node { 身份证：身份证！标题：字符串！ } 类型查询{ 节点（id：ID！）：节点 } 常量解析器 = { 查询：{ 节点： async (_, { id }, { db }) => { const { 类型，id: rawId } = fromGlobalId(id); 开关（类型）{ 案例“用户”：返回 db.users.findById(rawId); 案例“帖子”：返回 db.posts.findById(rawId); 默认：返回空值； } }, }, 用户：{ id: (用户) => toGlobalId('用户', user.id), }, 帖子：{ id: (post) => toGlobalId('Post', post.id), }, }; ** ** ## 服务器实现 ### Apollo 服务器（TypeScript）从 '@apollo/server' 导入 { ApolloServer }；从 '@apollo/server/standalone' 导入 { startStandaloneServer }； const 服务器 = 新 ApolloServer({ 类型定义，解析器，内省：process.env.NODE_ENV !== '生产', 插件：[ // 自定义插件 { 异步 requestDidStart() { 返回{ 异步 willSendResponse({ 响应 }) { console.log('响应：', 响应); }, }; }, }, ], }); const { url } = 等待 startStandaloneServer(服务器, { 听：{端口：4000}，上下文： async ({ req }) => ({ 令牌：req.headers.authorization，数据库：数据库， }), }); ### GraphQL Yoga（现代替代）从'graphql-yoga'导入{createYoga，createSchema}；从 'node:http' 导入 { createServer }; 常量瑜伽 = createYoga({ 架构：createSchema({ 类型定义，解析器， }), 图形：正确，上下文：（{请求}）=>（{ userId: request.headers.get('x-user-id'), }), }); const server = createServer(瑜伽); 服务器.listen(4000, () => { console.log('服务器位于 http://localhost:4000/graphql'); }); ### 石墨烯（Python/Django）进口石墨烯从 graphene_django 导入 DjangoObjectType 从 .models 导入用户、帖子类 UserType(DjangoObjectType): 类元：模型=用户字段 = '__all__' 类 PostType(DjangoObjectType): 类元：型号 = 帖子字段 = '__all__' 类查询（石墨烯.ObjectType）：用户 = graphene.List(UserType) user = graphene.Field(UserType, id=graphene.ID(required=True)) posts = graphene.List(PostType) defresolve_users（自我，信息）：返回 User.objects.all() defresolve_user（自我，信息，id）：返回 User.objects.get(pk=id) defresolve_posts（自我，信息）：返回 Post.objects.all() 类 CreateUser(graphene.Mutation): 类参数：名称=石墨烯.String（必需= True）电子邮件= graphene.String（必需= True） user = graphene.Field(用户类型) 成功 = graphene.Boolean() def mutate(自我、信息、姓名、电子邮件)： user = User.objects.create(名称=名称，电子邮件=电子邮件) 返回CreateUser(用户=用户，成功=True) 类突变（石墨烯.ObjectType）： create_user = CreateUser.Field() schema = graphene.Schema（查询=查询，突变=突变） ### 草莓（Python，现代）进口草莓从输入导入列表，可选从日期时间导入日期时间 @草莓.类型班级用户： id: 草莓.ID 名称：str 电子邮件：str 创建时间：日期时间 @草莓.类型班级岗位： id: 草莓.ID 标题：str 内容：str 作者id: 草莓.ID @strawberry.input 类创建用户输入：名称：str 电子邮件：str @草莓.类型类查询： @strawberry.field def users(self) -> 列表[用户]: 返回 User.objects.all() @strawberry.field def user(self, id: Strawberry.ID) -> 可选[用户]: 返回 User.objects.get(pk=id) @草莓.类型类突变： @草莓.突变 def create_user(self, 输入：CreateUserInput) -> 用户： return User.objects.create(**input.__dict__) schema = Strawberry.Schema（查询=查询，突变=突变） # FastAPI 集成从草莓.fastapi 导入 GraphQLRouter 应用程序 = FastAPI() app.include_router（GraphQLRouter（架构），前缀=“/ graphql”） ** ** ## 客户端集成 ### Apollo 客户端（React）从 '@apollo/client' 导入 { ApolloClient, InMemoryCache, ApolloProvider, useQuery, useMutation }; const 客户端 = 新 ApolloClient({ uri: 'http://localhost:4000/graphql', 缓存：new InMemoryCache(), }); 函数应用程序（）{ 返回（ <用户列表/> ）； } 函数用户列表（）{ const { 加载、错误、数据、重新获取 } = useQuery(GET_USERS); const [createUser] = useMutation(CREATE_USER, { refetchQueries: [{ 查询: GET_USERS }], }); if (正在加载) return

正在加载...

; if (error) return

错误: {error.message}

; 返回（

{data.users.map(用户=>(

{user.name}

))}

）； } ### urql（轻量级替代方案）从 'urql' 导入 { createClient, Provider, useQuery, useMutation }; 常量客户端 = createClient({ url: 'http://localhost:4000/graphql', }); 函数应用程序（）{ 返回（ <提供者值={客户端}> <用户列表/> ）； } 函数用户列表（）{ const [结果，reexecuteQuery] = useQuery({ 查询：GET_USERS }); const [, createUser] = useMutation(CREATE_USER); const { 数据，获取，错误 } = 结果； if (正在获取) return

正在加载...

; if (error) return

错误: {error.message}

; 返回（

{data.users.map(用户=>(

{user.name}

))}

）； } ### graphql-request（最小）从 'graphql-request' 导入 { GraphQLClient, gql }; const client = new GraphQLClient('http://localhost:4000/graphql'); 异步函数 fetchUsers() { 常量查询= gql` 查询{ 用户{ 编号姓名 } } `; const data = 等待 client.request(query); 返回数据.用户； } 异步函数 createUser(name: string) { 常量突变 = gql` 突变 CreateUser($name: String!) { 创建用户（名称：$名称）{ 编号姓名 } } `; const data =等待client.request(mutation, { name }); 返回数据.createUser; } ### TanStack 查询 + GraphQL 从 '@tanstack/react-query' 导入 { useQuery, useMutation, QueryClient, QueryClientProvider }; 从“graphql-request”导入{GraphQLClient}； const graphQLClient = new GraphQLClient('http://localhost:4000/graphql'); 函数 useUsers() { 返回 useQuery({ 查询键：['用户']， queryFn: async () => { const { 用户 } = 等待 graphQLClient.request(GET_USERS); 返回用户； }, }); } 函数 useCreateUser() { const queryClient = useQueryClient(); 返回 useMutation({ mutationFn：异步（名称：字符串）=> { const { createUser } = 等待 graphQLClient.request(CREATE_USER, { name }); 返回创建用户； }, 成功：() => { queryClient.invalidateQueries({ queryKey: ['users'] }); }, }); } ** ** ## TypeScript 代码生成 ### GraphQL 代码生成器设置 npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typescript-react-apollo ### 代码生成.yml 架构：http://localhost:4000/graphql 文档：'src/**/*.graphql' 生成： src/生成/graphql.ts：插件： - 打字稿 - 打字稿操作 - 打字稿反应阿波罗配置： withHooks: true 与组件：假跳过类型名称： false 枚举类型：true ### 生成的类型 // src/queries/users.graphql // 查询 GetUsers { // 用户{ // 编号 // 名称 // 电子邮件 // } // } // 生成的类型导出类型 GetUsersQuery = { __typename?: '查询'; 用户：数组<{ __typename?: '用户'; id：字符串；名称：字符串；电子邮件：字符串； }>; }; 导出函数 useGetUsersQuery( baseOptions?: Apollo.QueryHookOptions ）{ 返回 Apollo.useQuery( 获取用户文档，基本选项）； } ### 生成类型的用法从'./ generated/graphql'导入{useGetUsersQuery，useCreateUserMutation}；函数用户列表（）{ const { 数据、加载、错误 } = useGetUsersQuery(); const [createUser] = useCreateUserMutation(); // 完全输入！ const 用户 = 数据？.用户； // 类型：用户[] |未定义 } ** ** ## 身份验证和授权 ### 基于上下文的身份验证从 'jsonwebtoken' 导入 jwt；异步函数 createContext({ req }) { const token = req.headers.authorization?.replace('承载', ''); 如果（！令牌）{ 返回 { userId: null, db }; } 尝试{ const { userId } = jwt.verify(token, process.env.JWT_SECRET); 返回 { userId, db }; } 捕获（错误）{ 返回 { userId: null, db }; } } const 服务器 = 新 ApolloServer({ 类型定义，解析器， }); 等待启动StandaloneServer（服务器，{ 上下文：创建上下文， }); ### 解析器级身份验证常量解析器 = { 查询：{ 我：(_, __, { userId }) => { if (!userId) { throw new AuthenticationError('未验证'); } 返回 db.users.findById(userId); }, 用户：(_, __, { userId, db }) => { if (!userId) { throw new AuthenticationError('未验证'); } const user = db.users.findById(userId); if (user.role !== 'ADMIN') { throw new ForbiddenError('需要管理员访问权限'); } 返回 db.users.findMany(); }, }, }; ### 基于指令的身份验证从'@graphql-tools/utils'导入{mapSchema，getDirective，MapperKind}； // 带指令的模式 const typeDefs = gql` FIELD_DEFINITION 上的指令 @auth（需要：角色 = USER）枚举角色{ 管理员用户 } 类型查询{ 用户：[用户！]！ @auth（需要：管理员）我：用户！ @auth } `; // 指令变压器函数 authDirectiveTransformer（模式，directiveName = 'auth'）{ 返回mapSchema（模式，{ [MapperKind.OBJECT_FIELD]: (fieldConfig) => { const authDirective = getDirective(schema, fieldConfig,directiveName)?.[0]; 如果（authDirective）{ const { 需要 } = authDirective; const { 解析 = defaultFieldResolver } = fieldConfig; fieldConfig.resolve = async (源、参数、上下文、信息) => { if (!context.userId) { throw new AuthenticationError('未验证'); } 如果（要求）{ const user = wait context.db.users.findById(context.userId); if (user.role !== 需要) { throw new ForbiddenError(`${requires} 需要角色`); } } 返回解析（源，参数，上下文，信息）； }; } 返回字段配置； }, }); } 让 schema = makeExecutableSchema({ typeDefs, 解析器 }); 架构 = authDirectiveTransformer(架构); ** ** ## 性能优化 ### 查询复杂度分析从'graphql-validation-complexity'导入{createComplexityLimitRule}； const 服务器 = 新 ApolloServer({ 类型定义，解析器，验证规则：[ 创建复杂性限制规则（1000，{ 标量成本：1，对象成本：2，列表系数：10， }), ], }); ### 持久查询 (APQ) 从 '@apollo/server' 导入 { ApolloServer }；从 '@apollo/server/plugin/disabled' 导入 { ApolloServerPluginInlineTraceDisabled }； const 服务器 = 新 ApolloServer({ 类型定义，解析器，持久查询：{ 缓存: new Map(), // 或 Redis }, }); // 客户端发送哈希而不是完整查询 // 将有效负载大小减少约 80% ### 响应缓存从“@apollo/server-plugin-response-cache”导入responseCachePlugin； const 服务器 = 新 ApolloServer({ 类型定义，解析器，插件：[ 响应缓存插件({ sessionId: (上下文) => context.userId ||空， shouldReadFromCache: (context) => !context.userId, // 仅缓存公共查询 }), ], }); // 缓存控制的模式指令 const typeDefs = gql` 类型查询{ 帖子：[帖子！]！ @cacheControl（最大年龄：60）用户（id：ID！）：用户@cacheControl（maxAge：30） } `; ### 字段级缓存从 '@apollo/utils.keyvaluecache' 导入 { InMemoryLRUCache }； const 缓存 = 新 InMemoryLRUCache({ maxSize: Math.pow(2, 20) * 100, // 100 MB ttl: 300, // 5 分钟 }); 常量解析器 = { 查询：{ 用户： async (_, { id }, { 缓存, db }) => { const cacheKey = `用户：${id}`; const 缓存 = 等待缓存.get(cacheKey); 如果（缓存）{ 返回 JSON.parse(缓存); } const user = wait db.users.findById(id); 等待cache.set(cacheKey, JSON.stringify(user), { ttl: 60 }); 返回用户； }, }, }; ** ** ## 文件上传 ### 架构标量上传类型突变 { uploadFile(文件：上传！)：文件！ uploadMultiple(文件: [上传!]!): [文件!]! } 类型文件{ 文件名：字符串！模仿类型：字符串！编码：字符串！网址：字符串！ } ### 服务器（graphql-上传）从'graphql-upload/graphqlUploadExpress.mjs'导入graphqlUploadExpress；从 'graphql-upload/GraphQLUpload.mjs' 导入 { GraphQLUpload }；从 'fs' 导入 fs；从“路径”导入路径； app.use('/graphql', graphqlUploadExpress({ maxFileSize: 10000000, maxFiles: 10 })); 常量解析器 = { 上传：GraphQLUpload，突变：{ uploadFile: async (_, { 文件 }) => { const { createReadStream, 文件名, mimetype, 编码 } = 等待文件; const 流 = createReadStream(); const uploadPath = path.join(__dirname, '上传', 文件名); 等待新的 Promise((解决，拒绝) => { 流 .pipe(fs.createWriteStream(uploadPath)) .on('完成', 解决) .on('错误', 拒绝); }); 返回{ 文件名，模仿类型，编码， url: `/uploads/${文件名}`, }; }, }, }; ### 客户端（Apollo 客户端）从'@apollo/client'导入{useMutation}；常量 UPLOAD_FILE = gql` 突变 UploadFile($file: 上传！) { 上传文件（文件：$文件）{ 文件名网址 } } `; 函数文件上传() { const [uploadFile] = useMutation(UPLOAD_FILE); const handleFileChange = (e: React.ChangeEvent) => { const 文件 = e.target.files?.[0]; if (!file) 返回； uploadFile({ 变量: { 文件 } }); }; 返回 ; } ** ** ## 测试 ### 单元测试解析器从 'vitest' 导入 { 描述、it、期望、vi }；描述（'用户解析器'，（）=> { it('应该通过 ID 获取用户', async () => { 常量模拟数据库 = { 用户：{ findById: vi.fn().mockResolvedValue({ id: '1', 名称：“爱丽丝”，电子邮件：'alice@example.com', }), }, }; const 结果 = 等待解析器.Query.user( 空， { id: '1' }, { db:mockDb, userId: '1' }, {} 任意）； Expect(result.name).toBe('Alice'); 期望（mockDb.users.findById）.toHaveBeenCalledWith（'1'）; }); it('未经身份验证时应该抛出错误', async () => { 等待期待（ solvers.Query.me(null, {}, { userId: null }, {} 任意) ).rejects.toThrow('未通过身份验证'); }); }); ### 集成测试（Apollo 服务器）从 '@apollo/server' 导入 { ApolloServer }；从“断言”导入断言； it('获取用户', async () => { const server = new ApolloServer({ typeDefs, 解析器 }); const 响应 = 等待 server.executeOperation({ 查询：'查询{用户{id名称}}'， }); 断言（response.body.kind === '单一'）; 期望(response.body.singleResult.errors).toBeUndefined(); 期望（response.body.singleResult.data？.users）.toHaveLength（2）; }); it('创建用户', async () => { const 响应 = 等待 server.executeOperation({ 查询：` 突变 CreateUser($input: CreateUserInput!) { 创建用户（输入：$输入）{ 用户 { ID 名称 } 成功 } } `, 变量：{ 输入：{ 姓名：'查理'，电子邮件：'charlie@example.com' }， }, }); 断言（response.body.kind === '单一'）; 期望（response.body.singleResult.data？.createUser.success）.toBe（true）; }); ### E2E测试（超级测试）从“超级测试”导入请求；从'./server'导入{app}；描述('GraphQL API', () => { it('应该查询用户', async () => { const 响应 = 等待请求（应用程序） .post('/graphql') .发送({ 查询：'{用户{id名称}}'， }) .期望(200); 期望(response.body.data.users).toBeDefined(); }); it('应该需要身份验证', async () => { const 响应 = 等待请求（应用程序） .post('/graphql') .发送({ 查询：'{我{id}}'， }) .期望(200); Expect(response.body.errors[0].extensions.code).toBe('未经身份验证'); }); }); ** ** ## 生产模式 ### 模式拼接从'@graphql-tools/stitch'导入{stitchSchemas}； const userSchema = makeExecutableSchema({ typeDefs: userTypeDefs, 解析器: userResolvers }); const postSchema = makeExecutableSchema({ typeDefs: postTypeDefs, 解析器: postResolvers }); 常量模式=stitchSchemas({ 子模式：[ { 架构：用户架构 }, { 架构：postSchema }， ], }); ### 阿波罗联盟 // 用户服务从 '@apollo/subgraph' 导入 { buildSubgraphSchema }； const typeDefs = gql` 类型用户@key（字段：“id”）{ 身份证：身份证！名称：字符串！电子邮件：字符串！ } `; 常量解析器 = { 用户：{ __resolveReference(用户, { db }) { 返回 db.users.findById(user.id); }, }, }; const schema = buildSubgraphSchema({ typeDefs, 解析器 }); // 后期服务 const typeDefs = gql` 扩展类型 User @key(fields: "id") { 身份证：身份证！ @外部帖子：[帖子！]！ } 输入 Post @key(字段: "id") { 身份证：身份证！标题：字符串！作者ID：ID！ } `; // 网关从 '@apollo/gateway' 导入 { ApolloGateway }； const 网关 = 新 ApolloGateway({ supergraphSdl: readFileSync('./supergraph.graphql', 'utf-8'), }); const server = new ApolloServer({ 网关 }); ### 速率限制从 'graphql-rate-limit-directive' 导入 { GraphQLRateLimitDirective }； const typeDefs = gql` 指令@rateLimit( 限制：智力 = 10 持续时间：智力 = 60 ) 在 FIELD_DEFINITION 上类型查询{ 用户：[用户！]！ @rateLimit（限制：100，持续时间：60）搜索（查询：字符串！）：[结果！]！ @rateLimit（限制：10，持续时间：60） } `; 让 schema = makeExecutableSchema({ typeDefs, 解析器 }); 架构 = GraphQLRateLimitDirective()(架构); ### 监控（Apollo Studio）从 '@apollo/server/plugin/usageReporting' 导入 { ApolloServerPluginUsageReporting }； const 服务器 = 新 ApolloServer({ 类型定义，解析器，插件：[ ApolloServerPluginUsageReporting({ sendVariableValues: { 全部: true }, sendHeaders: { 全部: true }, }), ], }); ** ** ## 框架集成 ### Next.js 应用程序路由器 // 应用程序/api/graphql/route.ts 从 '@apollo/server' 导入 { ApolloServer }；从“@as-integrations/next”导入{startServerAndCreateNextHandler}； const 服务器 = 新 ApolloServer({ 类型定义，解析器， }); const handler = startServerAndCreateNextHandler(服务器); 导出 { 处理程序为 GET，处理程序为 POST }; ### Next.js 与 Apollo 客户端 (SSR) // lib/apollo-client.ts 从 '@apollo/client' 导入 { ApolloClient, InMemoryCache, HttpLink }; 从'@apollo/experimental-nextjs-app-support/rsc'导入{registerApolloClient}；导出 const { getClient } = registerApolloClient(() => { 返回新的 ApolloClient({ 缓存：new InMemoryCache(), 链接：新的 HttpLink({ uri: 'http://localhost:4000/graphql', }), }); }); // 应用程序/用户/page.tsx 从 '@/lib/apollo-client' 导入 { getClient }；从'@apollo/client'导入{gql}；导出默认异步函数 UsersPage() { const { 数据 } = 等待 getClient().query({ 查询：gql` 查询获取用户{ 用户{ 编号姓名 } } `, }); 返回（

{data.users.map(用户=>(

{user.name}

))}

）； } ### FastAPI + 草莓从 fastapi 导入 FastAPI 从草莓.fastapi 导入 GraphQLRouter 应用程序 = FastAPI() graphql_app = GraphQLRouter（架构） app.include_router（graphql_app，前缀=“/ graphql”）如果 __name__ == "__main__": 进口uvicorn uvicorn.run（应用程序，主机=“0.0.0.0”，端口= 8000） ** ** ## 与 REST 和 tRPC 的比较 ### GraphQL 与 REST 特色| GraphQL |休息 ---|---|--- 端点 |单端点|多个端点数据获取|客户端指定字段 |服务器确定响应过度获取 |没有 |是（额外字段）获取不足 |没有 |是（多个请求）版本控制 |不需要 |必需（v1、v2）缓存 |复杂|简单（HTTP 缓存）类型系统 |内置|外部（开放 API）实时 |订阅 | SSE/WebSocket ### GraphQL 与 tRPC 特色| GraphQL |远程过程调用 ---|---|--- 类型安全 |需要代码生成 |原生 TypeScript 语言支持 |任何 |仅限 TypeScript 客户端-服务器耦合 |宽松|紧架构|需要 SDL |从代码推断学习曲线|陡峭 |温柔模具|广泛 |成长使用案例|公共 API、移动 |全栈 TypeScript ** ** ## 迁移策略 ### REST 到 GraphQL（渐进） // 1. 包装现有的 REST 端点常量解析器 = { 查询：{ 用户：异步（_，{id}）=>{ const 响应 = 等待 fetch(`https://api.example.com/users/${id}`); 返回response.json(); }, }, }; // 2. 在 REST 旁边添加 GraphQL 层 app.use('/api/rest',restRouter); app.use('/graphql', graphqlMiddleware); // 3. 增量迁移客户端 // 4. 准备好后弃用 REST 端点 ### 将 GraphQL 添加到现有应用程序 // Express + GraphQL 从“快递”进口快递；从'@apollo/server/express4'导入{expressMiddleware}；常量应用程序 = Express(); // 现有路线 app.use('/api',现有ApiRouter); // 添加 GraphQL app.use('/graphql',express.json(),expressMiddleware(server)); ** ** ## 最佳实践 ### 架构设计 * 使用语义字段名称（“createdAt”，而不是“created_at”） * 优先选择特定类型而不是通用 JSON * 使用枚举作为固定值集 * 为客户用例设计，而不是数据库结构 * 使用输入类型进行复杂的突变 * 实现列表分页 * 遵循继电器规范进行连接 ### 解析器模式 * 保持解析器精简，委托给服务层 * 使用 DataLoader 进行所有数据库获取 * 验证解析器中的输入，而不是数据库层 * 返回负载中的错误，而不仅仅是异常 * 使用共享依赖项的上下文（db、auth、loaders） ### 错误处理 * 使用带有错误代码的自定义错误类型 * 返回突变的字段级错误 * 在服务器端记录错误，为客户端清理 * 使用可空字段来允许部分结果 * 不要暴露内部实现细节 ### 性能 * 始终使用DataLoader来防止N+1 * 实现查询复杂度限制 * 缓存经常访问的数据 * 在生产中使用持久查询 * 监控慢查询并优化 * 尽可能批量突变 ### 安全 * 实现认证和授权 * 验证所有输入 * 使用查询深度限制 * 对每个用户实施速率限制 * 在生产中禁用自省（可选） * 清理错误消息 ### 测试 * 隔离测试解析器 * 模拟外部依赖 * 测试错误条件 * 集成测试关键流程 * 与真实客户端进行E2E测试 ### 文档 * 写出清晰的字段描述 * 使用“@deprecated”记录弃用情况 * 在模式注释中提供使用示例 * 保持架构文档最新 ** ** ## 总结 GraphQL 提供了强大、灵活的 API 层，具有强大的类型、高效的数据获取和出色的开发人员体验。主要优点包括： * **客户端控制**：准确获取您需要的内容 * **类型安全**：模式优先设计与内省 * **单一端点**：简化的 API 界面 * **实时**：内置订阅支持 * **工具**：优秀的生态系统（Apollo、Relay、codegen） **需要考虑的权衡**： * 对于简单的 CRUD 来说，比 REST 更复杂 * 缓存比HTTP缓存需要更多的思考 * GraphQL 新手团队的学习曲线 * 查询复杂性会影响性能 **最适合**： * 需要带宽效率的移动应用程序 * 具有不同数据需求的复杂前端 * 微服务聚合 * 实时应用 * 多平台客户端（网络、移动、物联网） **从简单开始**： 1. 定义核心实体的模式 2. 使用DataLoader编写解析器 3.添加认证/授权 4. 实施错误处理 5. 缓存优化 6. 如果需要添加订阅 7. 监控和迭代当 API 灵活性和开发人员体验优先时，GraphQL 就会大放异彩。与 TypeScript 代码生成相结合，它提供了从数据库到 UI 的端到端类型安全。

图ql

包含技能