Claude Code + GraphQL全链路实战：Schema设计到实时订阅推送

mkdir graphql-blog-api && cd graphql-blog-api
npm init -y

claude

初始化一个 TypeScript + Apollo Server 5 的 GraphQL 项目。
使用 pnpm 作为包管理器，配置 tsconfig.json 支持ESM模块。
项目结构按 src/schema、src/resolvers、src/models、src/utils 分层。

src/
├── schema/         # GraphQL Schema 定义
├── resolvers/      # Resolver 实现
├── models/         # 数据模型（Prisma）
├── utils/          # 工具函数（auth、dataloader）
├── context.ts      # GraphQL Context 定义
└── index.ts        # 入口文件

# 方式一：通过 Skills CLI
npx skills add apollographql/skills

# 方式二：通过 Claude Code Plugin
# 在 Claude Code 中执行：
/plugin marketplace add apollographql/skills
/plugin install apollo-skills@apollo-marketplace

设计一个博客系统的 GraphQL Schema，包含以下实体：
- User: id, email, name, avatar, posts, createdAt
- Post: id, title, content, status(DRAFT/PUBLISHED/ARCHIVED), author, comments, tags, createdAt, updatedAt
- Comment: id, content, author, post, createdAt
- Tag: id, name, posts

支持的 Query：
- user(id), users(pagination, filter), me
- post(id), posts(pagination, filter)
- searchPosts(query)

支持的 Mutation：
- createPost, updatePost, deletePost
- createComment, updateComment
- login, register, updateProfile

支持的 Subscription：
- onPostPublished
- onCommentAdded(postId)

使用 Cursor-based 分页（Relay-style connections）

# src/schema/types.graphql
scalar DateTime
scalar Cursor

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  email: String!
  name: String
  avatar: String
  posts(first: Int, after: Cursor): PostConnection!
  createdAt: DateTime!
}

type Post implements Node {
  id: ID!
  title: String!
  content: String!
  status: PostStatus!
  author: User!
  comments(first: Int, after: Cursor): CommentConnection!
  tags: [Tag!]!
  createdAt: DateTime!
  updatedAt: DateTime!
}

type Comment implements Node {
  id: ID!
  content: String!
  author: User!
  post: Post!
  createdAt: DateTime!
}

type Tag implements Node {
  id: ID!
  name: String!
  posts(first: Int, after: Cursor): PostConnection!
}

# src/schema/connections.graphql
type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type PostEdge {
  node: Post!
  cursor: Cursor!
}

type CommentConnection {
  edges: [CommentEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type CommentEdge {
  node: Comment!
  cursor: Cursor!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: Cursor
  endCursor: Cursor
}

/apollo-skills:graphql-schema

配置 Prisma 连接 PostgreSQL，定义与 GraphQL Schema 对应的数据模型。
使用 docker-compose.yml 启动 PostgreSQL。
支持软删除、自动时间戳、全文搜索索引。

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  avatar    String?
  password  String
  posts     Post[]
  comments  Comment[]
  createdAt DateTime @default(now()) @map("created_at")

  @@map("users")
}

model Post {
  id        String      @id @default(cuid())
  title     String
  content   String
  status    PostStatus  @default(DRAFT)
  authorId  String      @map("author_id")
  author    User        @relation(fields: [authorId], references: [id])
  comments  Comment[]
  tags      PostTag[]
  createdAt DateTime    @default(now()) @map("created_at")
  updatedAt DateTime    @updatedAt @map("updated_at")

  @@index([status])
  @@index([authorId])
  @@map("posts")
}

model Comment {
  id        String   @id @default(cuid())
  content   String
  authorId  String   @map("author_id")
  postId    String   @map("post_id")
  author    User     @relation(fields: [authorId], references: [id])
  post      Post     @relation(fields: [postId], references: [id], onDelete: Cascade)
  createdAt DateTime @default(now()) @map("created_at")

  @@map("comments")
}

model Tag {
  id    String    @id @default(cuid())
  name  String    @unique
  posts PostTag[]

  @@map("tags")
}

model PostTag {
  postId String @map("post_id")
  tagId  String @map("tag_id")
  post   Post   @relation(fields: [postId], references: [id], onDelete: Cascade)
  tag    Tag    @relation(fields: [tagId], references: [id], onDelete: Cascade)

  @@id([postId, tagId])
  @@map("post_tags")
}

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: graphql_blog
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: devpass
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  pgdata:

docker compose up -d
npx prisma migrate dev --name init
npx prisma generate

实现所有 GraphQL Resolver，包含：
1. Query resolvers: user, users(带分页), me(需认证), post, posts(带过滤), searchPosts
2. Mutation resolvers: register, login(返回JWT), createPost, updatePost, deletePost, createComment
3. Field resolvers: User.posts, Post.author, Post.comments, Post.tags
4. 分页使用 cursor-based，基于 Prisma cursor API

import { Resolvers } from '../generated/graphql';
import { GraphQLError } from 'graphql';

export const postResolvers: Resolvers = {
  Query: {
    posts: async (_, { first = 10, after, filter }, { prisma }) => {
      const where = filter ? {
        status: filter.status || undefined,
        authorId: filter.authorId || undefined,
      } : {};

      const posts = await prisma.post.findMany({
        where,
        take: first + 1,
        cursor: after ? { id: after } : undefined,
        orderBy: { createdAt: 'desc' },
        include: { author: true, tags: { include: { tag: true } } },
      });

      const hasNextPage = posts.length > first;
      const edges = hasNextPage ? posts.slice(0, -1) : posts;

      return {
        edges: edges.map(post => ({
          node: post,
          cursor: post.id,
        })),
        pageInfo: {
          hasNextPage,
          hasPreviousPage: !!after,
          startCursor: edges[0]?.id,
          endCursor: edges[edges.length - 1]?.id,
        },
        totalCount: await prisma.post.count({ where }),
      };
    },

    searchPosts: async (_, { query }, { prisma }) => {
      return prisma.post.findMany({
        where: {
          status: 'PUBLISHED',
          OR: [
            { title: { contains: query, mode: 'insensitive' } },
            { content: { contains: query, mode: 'insensitive' } },
          ],
        },
        take: 20,
        orderBy: { createdAt: 'desc' },
      });
    },
  },

  Mutation: {
    createPost: async (_, { input }, { prisma, userId }) => {
      if (!userId) {
        throw new GraphQLError('Unauthorized', {
          extensions: { code: 'UNAUTHENTICATED' },
        });
      }

      const { tagIds, ...postData } = input;

      return prisma.post.create({
        data: {
          ...postData,
          authorId: userId,
          tags: tagIds
            ? { create: tagIds.map(tagId => ({ tagId })) }
            : undefined,
        },
        include: { author: true, tags: { include: { tag: true } } },
      });
    },
  },
};

为 User、Post、Tag 创建 DataLoader，支持批量加载。
将 DataLoader 实例挂载到 GraphQL Context。
确保同一请求内缓存有效，请求间不缓存。

import DataLoader from 'dataloader';
import { PrismaClient } from '@prisma/client';

export function createLoaders(prisma: PrismaClient) {
  return {
    userLoader: new DataLoader<string, any>(async (ids) => {
      const users = await prisma.user.findMany({
        where: { id: { in: ids as string[] } },
      });
      const map = new Map(users.map(u => [u.id, u]));
      return ids.map(id => map.get(id) ?? null);
    }),

    postLoader: new DataLoader<string, any>(async (ids) => {
      const posts = await prisma.post.findMany({
        where: { id: { in: ids as string[] } },
        include: { author: true },
      });
      const map = new Map(posts.map(p => [p.id, p]));
      return ids.map(id => map.get(id) ?? null);
    }),

    postsByAuthorLoader: new DataLoader<string, any[]>(async (authorIds) => {
      const posts = await prisma.post.findMany({
        where: { authorId: { in: authorIds as string[] } },
      });
      const map = new Map<string, any[]>();
      for (const post of posts) {
        const list = map.get(post.authorId) ?? [];
        list.push(post);
        map.set(post.authorId, list);
      }
      return authorIds.map(id => map.get(id) ?? []);
    }),
  };
}

// src/context.ts
import { PrismaClient } from '@prisma/client';
import { createLoaders } from './utils/dataloaders';

const prisma = new PrismaClient();

export interface GraphQLContext {
  prisma: PrismaClient;
  userId?: string;
  loaders: ReturnType<typeof createLoaders>;
}

export function createContext({ req }: any): GraphQLContext {
  const authHeader = req?.headers?.authorization || '';
  const token = authHeader.replace('Bearer ', '');
  const userId = verifyJWT(token); // 自行实现

  return {
    prisma,
    userId: userId || undefined,
    loaders: createLoaders(prisma),
  };
}

# 无 DataLoader: 查询 20 篇文章的作者
SQL Queries: 1 (posts) + 20 (authors) = 21 次

# 有 DataLoader: 查询 20 篇文章的作者
SQL Queries: 1 (posts) + 1 (batch authors WHERE id IN (...)) = 2 次

实现 JWT 认证：
1. register mutation: 邮箱密码注册，bcrypt 加密
2. login mutation: 返回 JWT token
3. Context 中解析 token 获取 userId
4. 未认证访问受保护资源时抛出 UNAUTHENTICATED 错误
5. 使用 @auth directive 标记需要认证的字段

// src/resolvers/auth.resolver.ts
import bcrypt from 'bcryptjs';
import jwt from 'jsonwebtoken';
import { GraphQLError } from 'graphql';

const JWT_SECRET = process.env.JWT_SECRET || 'change-me-in-production';

export const authResolvers = {
  Mutation: {
    register: async (_, { input }, { prisma }) => {
      const existing = await prisma.user.findUnique({
        where: { email: input.email },
      });
      if (existing) {
        throw new GraphQLError('Email already registered', {
          extensions: { code: 'CONFLICT' },
        });
      }

      const password = await bcrypt.hash(input.password, 12);
      const user = await prisma.user.create({
        data: { email: input.email, name: input.name, password },
      });

      const token = jwt.sign({ userId: user.id }, JWT_SECRET, {
        expiresIn: '7d',
      });

      return { token, user };
    },

    login: async (_, { email, password }, { prisma }) => {
      const user = await prisma.user.findUnique({ where: { email } });
      if (!user || !(await bcrypt.compare(password, user.password))) {
        throw new GraphQLError('Invalid credentials', {
          extensions: { code: 'UNAUTHENTICATED' },
        });
      }

      const token = jwt.sign({ userId: user.id }, JWT_SECRET, {
        expiresIn: '7d',
      });

      return { token, user };
    },
  },
};

deletePost: async (_, { id }, { prisma, userId }) => {
  if (!userId) throw unauthorized();

  const post = await prisma.post.findUnique({ where: { id } });
  if (!post) throw notFound('Post');
  if (post.authorId !== userId) throw forbidden('Not your post');

  return prisma.post.delete({ where: { id } });
},

sequenceDiagram
    participant Client as 客户端
    participant Server as Apollo Server
    participant PubSub as Redis PubSub
    participant Resolver as Resolver

    Client->>Server: WebSocket 连接 + subscription onPostPublished
    Server-->>Client: subscription 确认 (ws://)

    Note over Client,Server: 另一个客户端操作...

    Client->>Server: mutation createPost
    Server->>Resolver: createPost resolver
    Resolver->>PubSub: publish("POST_PUBLISHED", payload)
    PubSub->>Server: 消息广播
    Server->>Client: subscription 触发: onPostPublished { ... }

实现两个 GraphQL Subscription：
1. onPostPublished - 新文章发布时通知
2. onCommentAdded(postId) - 特定文章收到新评论时通知

使用 Redis PubSub 作为消息后端（支持多实例部署）。
配置 WebSocket 握手时验证 JWT token。

import { Redis } from 'ioredis';
import { PubSubAsyncIterator } from './pubsub-async-iterator';

const PUBSUB_PREFIX = 'graphql:';

export class RedisPubSub {
  private publisher: Redis;
  private subscriber: Redis;

  constructor(redisUrl: string) {
    this.publisher = new Redis(redisUrl);
    this.subscriber = new Redis(redisUrl);
  }

  async publish(trigger: string, payload: any): Promise<void> {
    await this.publisher.publish(
      `${PUBSUB_PREFIX}${trigger}`,
      JSON.stringify(payload)
    );
  }

  asyncIterator(trigger: string): PubSubAsyncIterator {
    return new PubSubAsyncIterator(this.subscriber, `${PUBSUB_PREFIX}${trigger}`);
  }
}

import { Resolvers } from '../generated/graphql';

export const subscriptionResolvers: Resolvers = {
  Subscription: {
    onPostPublished: {
      subscribe: (_, __, { pubsub }) => pubsub.asyncIterator('POST_PUBLISHED'),
      resolve: (payload) => payload,
    },
    onCommentAdded: {
      subscribe: (_, { postId }, { pubsub }) =>
        pubsub.asyncIterator(`COMMENT_ADDED_${postId}`),
      resolve: (payload) => payload,
    },
  },
};

// 在 createPost resolver 中
createPost: async (_, { input }, { prisma, userId, pubsub }) => {
  // ...创建文章逻辑...

  if (post.status === 'PUBLISHED') {
    await pubsub.publish('POST_PUBLISHED', post);
  }
  return post;
},

// 在 createComment resolver 中
createComment: async (_, { input }, { prisma, userId, pubsub }) => {
  // ...创建评论逻辑...

  await pubsub.publish(`COMMENT_ADDED_${input.postId}`, comment);
  return comment;
},

// src/index.ts
import { ApolloServer } from '@apollo/server';
import { expressMiddleware } from '@apollo/server/express4';
import { createServer } from 'http';
import { WebSocketServer } from 'ws';
import { useServer } from 'graphql-ws/lib/use/ws';
import { makeExecutableSchema } from '@graphql-tools/schema';

const app = express();
const httpServer = createServer(app);

// WebSocket 服务器
const wsServer = new WebSocketServer({
  server: httpServer,
  path: '/graphql',
});

useServer(
  {
    schema,
    context: async (ctx) => {
      // 从 WebSocket 连接参数中提取 token
      const token = ctx.connectionParams?.authorization?.replace('Bearer ', '');
      const userId = token ? verifyJWT(token) : null;
      return { prisma, userId, loaders: createLoaders(prisma), pubsub };
    },
  },
  wsServer
);

// Apollo Server
const server = new ApolloServer({ schema });
await server.start();
app.use('/graphql', express.json(), expressMiddleware(server, { context }));

httpServer.listen(4000, () => {
  console.log('Server ready at http://localhost:4000/graphql');
  console.log('Subscriptions ready at ws://localhost:4000/graphql');
});

配置 GraphQL Code Generator：
1. 从 schema.graphql 生成 TypeScript 类型
2. 生成类型安全的 Resolver 签名
3. 在 package.json 中添加 codegen 脚本
4. 配置 watch 模式用于开发

import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: './src/schema/**/*.graphql',
  generates: {
    './src/generated/graphql.ts': {
      plugins: [
        'typescript',
        'typescript-resolvers',
        'typescript-operations',
      ],
      config: {
        contextType: '../context#GraphQLContext',
        useIndexSignature: true,
        enumValues: {
          PostStatus: '@prisma/client#PostStatus',
        },
        mappers: {
          User: '@prisma/client#User as UserModel',
          Post: '@prisma/client#Post as PostModel',
          Comment: '@prisma/client#Comment as CommentModel',
        },
      },
    },
  },
};

export default config;

{
  "scripts": {
    "codegen": "graphql-codegen --config codegen.ts",
    "codegen:watch": "graphql-codegen --config codegen.ts --watch",
    "dev": "concurrently \"npm run codegen:watch\" \"tsx watch src/index.ts\""
  }
}

// src/generated/graphql.ts（自动生成）
export type Resolvers<TContext = GraphQLContext> = {
  Query: {
    posts: Resolver<Promise<PostConnection>, {}, TContext,
      { first?: number; after?: string; filter?: PostFilterInput }>;
    post: Resolver<Promise<Post | null>, {}, TContext, { id: string }>;
    me: Resolver<Promise<User | null>, {}, TContext>;
  };
  Mutation: {
    createPost: Resolver<Promise<Post>, {}, TContext,
      { input: CreatePostInput }>;
    // ...
  };
};

// ✅ 正确：返回类型匹配
posts: async (_, { first = 10, after, filter }, { prisma }) => {
  // TypeScript 知道 first 是 number，filter 是 PostFilterInput | undefined
  // ...
},

// ❌ 编译错误：返回类型不匹配
posts: async () => {
  return { wrong: 'field' }; // Error: Type '{ wrong: string }' is not assignable to 'PostConnection'
},

构建一个生产级 GraphQL 博客 API，要求：

1. 技术栈：Apollo Server 5 + Prisma + PostgreSQL + TypeScript + Redis
2. 数据模型：User、Post、Comment、Tag
3. 功能：
   - Cursor-based 分页的查询
   - JWT 认证（register/login）
   - 权限控制（只能编辑自己的文章）
   - DataLoader 解决 N+1 查询
   - GraphQL Subscriptions（新文章/评论通知）
   - GraphQL Code Generator 类型安全
4. 部署：Docker Compose 一键启动
5. 测试：Vitest 单元测试 + 集成测试

输出完整的项目代码，包含所有文件。

# 启动基础设施
docker compose up -d

# 数据库迁移
npx prisma migrate dev

# 生成类型
npm run codegen

# 启动开发服务器
npm run dev

# 验证：打开 Apollo Sandbox
# 浏览器访问 http://localhost:4000/graphql

# 注册用户
mutation Register {
  register(input: {
    email: "[email protected]"
    name: "Test User"
    password: "password123"
  }) {
    token
    user { id email name }
  }
}

# 创建文章
mutation CreatePost($token: String!) {
  createPost(input: {
    title: "My First Post"
    content: "Hello GraphQL!"
    status: PUBLISHED
  }) @auth(token: $token) {
    id title status createdAt
    author { name }
  }
}

# 查询文章列表（带分页）
query Posts {
  posts(first: 10) {
    edges {
      node { id title createdAt }
      cursor
    }
    pageInfo { hasNextPage endCursor }
    totalCount
  }
}

# 订阅新文章
subscription OnPostPublished {
  onPostPublished {
    id title
    author { name }
  }
}

graph TB
    subgraph 开发环境
        A[Schema .graphql 文件] -->|graphql-codegen| B[TypeScript 类型]
        B --> C[类型安全 Resolver]
        C --> D[Apollo Server]
        D --> E[HTTP: Query/Mutation]
        D --> F[WebSocket: Subscription]
    end

    subgraph 数据层
        C -->|Prisma Client| G[PostgreSQL]
        C -->|DataLoader| G
    end

    subgraph 实时推送
        C -->|publish| H[Redis PubSub]
        H -->|asyncIterator| F
    end

    subgraph Claude Code 工作流
        I[Claude Code CLI] -->|生成 Schema| A
        I -->|生成 Resolver| C
        I -->|生成 DataLoader| C
        I -->|运行 codegen| B
        I -->|生成测试| J[Vitest 测试]
    end

    style I fill:#f9a825,stroke:#333
    style D fill:#42b883,stroke:#333
    style G fill:#336791,stroke:#333
    style H fill:#dc382d,stroke:#333

当前的 GraphQL Schema 如下：
[粘贴 schema 内容]

需要新增以下功能：
- [描述新需求]

请更新 Schema，确保：
1. 遵循 Relay 风格 connections
2. 添加对应的 Input 类型
3. 保持与现有类型的一致性
4. 更新 codegen 配置

这个 GraphQL Query 返回了错误：
query { posts(first: 5) { edges { node { author { posts { edges { node { id } } } } } } } }

错误信息：[粘贴错误]

相关的 Resolver 代码：
[粘贴 resolver 代码]

Prisma Schema：
[粘贴 prisma schema]

请诊断 N+1 问题并提供修复方案。

分析以下 GraphQL Resolver 的性能问题：

[粘贴代码]

数据库查询日志显示：
[粘贴日志]

要求：
1. 识别 N+1 查询
2. 添加适当的 DataLoader
3. 优化 Prisma include 策略
4. 添加查询复杂度限制