name: graphql-design description: GraphQL schema设计、resolver模式、订阅、用于N+1预防的DataLoader以及错误处理
GraphQL设计
Schema设计
type Query {
user(id: ID!): User
users(filter: UserFilter, first: Int = 20, after: String): UserConnection!
}
type Mutation {
createUser(input: CreateUserInput!): CreateUserPayload!
updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
}
type Subscription {
orderStatusChanged(orderId: ID!): Order!
}
type User {
id: ID!
email: String!
name: String!
orders(first: Int = 10, after: String): OrderConnection!
createdAt: DateTime!
}
input CreateUserInput {
email: String!
name: String!
}
type CreateUserPayload {
user: User
errors: [UserError!]!
}
type UserError {
field: String!
message: String!
}
type UserConnection {
edges: [UserEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type UserEdge {
node: User!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
endCursor: String
}
使用Relay风格的连接进行分页。从变体返回负载类型，包括结果和错误。
Resolvers
const resolvers: Resolvers = {
Query: {
user: async (_, { id }, ctx) => {
return ctx.dataloaders.user.load(id);
},
users: async (_, { filter, first, after }, ctx) => {
const cursor = after ? decodeCursor(after) : undefined;
const users = await ctx.db.user.findMany({
where: buildFilter(filter),
take: first + 1,
cursor: cursor ? { id: cursor } : undefined,
orderBy: { createdAt: "desc" },
});
const hasNextPage = users.length > first;
const edges = users.slice(0, first).map(user => ({
node: user,
cursor: encodeCursor(user.id),
}));
return {
edges,
pageInfo: {
hasNextPage,
endCursor: edges[edges.length - 1]?.cursor ?? null,
},
};
},
},
Mutation: {
createUser: async (_, { input }, ctx) => {
const existing = await ctx.db.user.findUnique({ where: { email: input.email } });
if (existing) {
return { user: null, errors: [{ field: "email", message: "Already taken" }] };
}
const user = await ctx.db.user.create({ data: input });
return { user, errors: [] };
},
},
User: {
orders: async (parent, { first, after }, ctx) => {
return ctx.dataloaders.userOrders.load({ userId: parent.id, first, after });
},
},
};
用于N+1预防的DataLoader
import DataLoader from "dataloader";
function createLoaders(db: Database) {
return {
user: new DataLoader<string, User>(async (ids) => {
const users = await db.user.findMany({ where: { id: { in: [...ids] } } });
const userMap = new Map(users.map(u => [u.id, u]));
return ids.map(id => userMap.get(id) ?? new Error(`User ${id} not found`));
}),
userOrders: new DataLoader<{ userId: string }, Order[]>(async (keys) => {
const userIds = keys.map(k => k.userId);
const orders = await db.order.findMany({
where: { userId: { in: userIds } },
orderBy: { createdAt: "desc" },
});
const grouped = new Map<string, Order[]>();
orders.forEach(o => {
const list = grouped.get(o.userId) ?? [];
list.push(o);
grouped.set(o.userId, list);
});
return keys.map(k => grouped.get(k.userId) ?? []);
}),
};
}
为每个请求创建新的DataLoader实例，以避免跨用户使用陈旧的缓存。
订阅
const pubsub = new PubSub();
const resolvers = {
Subscription: {
orderStatusChanged: {
subscribe: (_, { orderId }) => {
return pubsub.asyncIterableIterator(`ORDER_STATUS_${orderId}`);
},
},
},
Mutation: {
updateOrderStatus: async (_, { id, status }, ctx) => {
const order = await ctx.db.order.update({ where: { id }, data: { status } });
await pubsub.publish(`ORDER_STATUS_${id}`, { orderStatusChanged: order });
return { order, errors: [] };
},
},
};
反模式
- 直接将数据库模式暴露为GraphQL模式
- 没有使用DataLoader解析嵌套字段（导致N+1查询）
- 对于大型数据集使用基于偏移的分页而不是基于游标的分页
- 从解析器抛出原始错误而不是返回类型化的错误负载
- 创建单个整体式模式文件而不是模块化的类型定义
- 允许无限制的查询而没有深度或复杂性限制
检查清单
- [ ] 所有列表字段使用Relay风格的游标分页
- [ ] 所有批处理实体查找使用DataLoader
- [ ] 变体返回负载类型，包括结果和错误字段
- [ ] 使用输入类型作为变体参数
- [ ] 配置查询深度和复杂性限制
- [ ] DataLoader实例在上下文中按请求创建
- [ ] 模式拆分为领域特定的模块
- [ ] 订阅使用过滤主题以避免向所有客户端广播