GraphQL API 设计最佳实践

GraphQL vs REST

REST 痛点

• 多次请求获取关联数据（N+1 问题）
• 返回过多或过少数据
• 版本管理复杂

GraphQL 优势

• 单次请求获取所需数据
• 客户端决定返回字段
• 强类型 Schema
• 自文档化

Schema 定义

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]
  createdAt: DateTime!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  comments: [Comment!]
}

type Query {
  user(id: ID!): User
  users(limit: Int, offset: Int): [User!]!
  post(id: ID!): Post
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User
  deleteUser(id: ID!): Boolean!
}

input CreateUserInput {
  name: String!
  email: String!
}

input UpdateUserInput {
  name: String
  email: String
}

Resolver 实现

const resolvers = {
  Query: {
    user: async (_, { id }, { db }) => {
      return db.users.findById(id);
    },
    users: async (_, { limit, offset }, { db }) => {
      return db.users.find().limit(limit).skip(offset);
    }
  },
  
  Mutation: {
    createUser: async (_, { input }, { db }) => {
      return db.users.insert(input);
    }
  },
  
  User: {
    posts: async (user, _, { db }) => {
      return db.posts.findByAuthor(user.id);
    }
  }
};

N+1 问题解决

使用 DataLoader

const DataLoader = require('dataloader');

const userLoader = new DataLoader(async (userIds) => {
  const users = await db.users.findByIds(userIds);
  return userIds.map(id => users.find(u => u.id === id));
});

// Resolver 中使用
User: {
  posts: async (user, _, { loaders }) => {
    return loaders.postLoader.load(user.id);
  }
}

分页策略

Cursor 分页（推荐）

type Query {
  users(first: Int, after: String): UserConnection!
}

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
}

type UserEdge {
  node: User!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}

错误处理

interface Error {
  message: String!
  code: String!
}

type ValidationError implements Error {
  message: String!
  code: String!
  field: String!
}

type MutationResponse {
  success: Boolean!
  data: User
  errors: [Error!]
}

认证授权

// Context 中注入用户
const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: ({ req }) => {
    const token = req.headers.authorization;
    const user = verifyToken(token);
    return { user, db };
  }
});

// Resolver 中检查权限
Mutation: {
  deleteUser: async (_, { id }, { user, db }) => {
    if (!user || user.role !== 'ADMIN') {
      throw new AuthenticationError('Unauthorized');
    }
    return db.users.delete(id);
  }
}

性能优化

1. 查询复杂度限制 - 防止深度查询
2. 字段级缓存 - Redis 缓存
3. 持久化查询 - 预注册查询
4. Rate Limiting - 限制请求频率

工具推荐

• Apollo Server/Client - 完整解决方案
• GraphiQL - 交互式 IDE
• graphql-code-generator - 类型生成

GraphQL 让 API 更灵活高效，适合复杂数据关系场景！