GraphQL Schema 设计

Schema 设计主流程（skill-flow-block）

  [ 领域模型 / 用例 ]
              │
              ▼
    [ 划分子图或单体 Schema：Query 入口、Mutation、Subscription 边界 ]
              │
              ▼
    [ 类型：Object / Input / Enum；列表 → Connection 或明确 limit+offset+上限 ]
              │
         ┌──────┴──────┐
         ▼             ▼
  [ 联邦：@key / @external / 解析器归属 ]   [ 解析器：DataLoader、分页游标稳定、max first ]
         │             │
         └──────┬──────┘
                ▼
    [ @deprecated + reason；Schema Registry / 契约测试在 CI 拦截 breaking ]
                │
                ▼
    [ 深度 / 复杂度 / introspection 策略；生产与预发一致 ]

DataLoader 解决 N+1 问题

// DataLoader 完整实现：批量加载解决 N+1 问题
import DataLoader from 'dataloader';

// 批量加载函数：将 N 次单独查询合并为 1 次 IN 查询
const userLoader = new DataLoader<string, User>(async (userIds) => {
  // userIds 是同一 tick 内所有请求的 id 集合（自动去重）
  const users = await db.users.findMany({
    where: { id: { in: [...userIds] } }
  });
  // 必须按 userIds 顺序返回，缺失项用 null 占位
  return userIds.map(id => users.find(u => u.id === id) ?? null);
}, {
  cache: true,       // 请求内缓存（每次请求新建 loader 实例）
  maxBatchSize: 100,  // 单批最大 100 条，防止超大 IN 查询
});

// Resolver 中使用：每次调用 .load()，DataLoader 自动批量
const resolvers = {
  Post: {
    // 查询 100 篇文章，不会触发 100 次 user 查询
    author: (post, _, { loaders }) => loaders.user.load(post.authorId),
  },
};

// 每次 HTTP 请求创建新的 DataLoader 实例（避免跨请求缓存污染）
function createContext(req) {
  return {
    loaders: {
      user: new DataLoader(async (ids) => batchLoadUsers(ids)),
      post: new DataLoader(async (ids) => batchLoadPosts(ids)),
    }
  };
}

• 实体与 @key：可跨服务解析的类型使用 @key 声明主键字段；扩展子图用 @external 引用他图字段，仅在本地添加增量字段或解析逻辑。
• 变更协调：改 key 或移动字段归属是 breaking 级操作；SKILL 应要求同步更新子图清单、兼容性检查与回滚策略。

游标分页 Schema 与查询防护

# 游标分页 Connection/Edge/PageInfo 标准模式（Relay 规范）
"""分页信息（全图唯一定义，其他 Connection 复用）"""
type PageInfo {
  hasNextPage:     Boolean!
  hasPreviousPage: Boolean!
  startCursor:     String
  endCursor:       String  # 不透明游标，客户端不解析内容
}

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

type UserConnection {
  edges:      [UserEdge!]!
  pageInfo:   PageInfo!
  totalCount: Int  # 高成本，按需启用；避免默认触发 COUNT(*)
}

extend type Query {
  """列出用户（first 最大 100，超限返回 BAD_USER_INPUT）"""
  users(
    first: Int!  # 必填，解析器强制上限
    after: String
    filter: UserFilter
  ): UserConnection!
}

// 查询深度限制（depth-limit 中间件）+ 复杂度分析
import depthLimit from 'graphql-depth-limit';
import { createComplexityRule } from 'graphql-query-complexity';

const server = new ApolloServer({
  validationRules: [
    depthLimit(5),  // 最大嵌套深度 5 层，防止深度嵌套攻击
    createComplexityRule({
      maximumComplexity: 1000,  // 最大复杂度分值
      variables: {},
      onComplete: (complexity) => console.log(`Query complexity: ${complexity}`),
      estimators: [
        fieldExtensionsEstimator(),
        simpleEstimator({ defaultComplexity: 1 }),
      ],
    }),
  ],
  plugins: [
    {
      requestDidStart: () => ({
        didResolveOperation({ request, document }) {
          // 生产环境禁用 introspection（防止 schema 泄露）
          if (process.env.NODE_ENV === 'production' &&
              request.operationName === 'IntrospectionQuery') {
            throw new ForbiddenError('Introspection disabled in production');
          }
        }
      })
    }
  ],
});

// Resolver 级别鉴权：在 resolver 内检查权限，不依赖调用方自觉
const resolvers = {
  Query: {
    adminUsers: (_, __, { user }) => {
      if (!user || user.role !== 'admin')
        throw new ForbiddenError('Admin access required');  // 403
      return db.users.findAll();
    }
  },
  Mutation: {
    deletePost: async (_, { id }, { user, loaders }) => {
      const post = await loaders.post.load(id);
      if (!post) throw new UserInputError('Post not found');
      // ABAC：检查资源属性，不仅仅检查角色
      if (post.authorId !== user.id && user.role !== 'admin')
        throw new ForbiddenError('Can only delete your own posts');
      return db.posts.delete({ where: { id } });
    }
  }
};

弃用、Registry 与安全成本

对即将删除的字段使用 @deprecated 并注明替代字段；重大变更通过 Schema Registry 或契约测试在 CI 中拦截。多子图场景下 composition 失败或版本漂移须在流水线中显式报错。

安全与成本：在技能描述中要求校验查询深度、复杂度与 introspection 策略，防止开放端点被滥用拖垮解析层。

Connection SDL 片段实验室（gql-page）

填写节点类型名与列表字段名，生成可粘贴进子图的 Relay 风格 Connection 骨架（含注释提醒在解析器内强制 first 上限）。生成仅在浏览器本地完成。