claude-skills 中 GraphQL 架构师的 Schema 设计实战指南从类型系统到分页与命名规范【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills导读本文是 claude-skills 仓库中graphql-architect技能的配套参考文档 schema-design.md 的深度展开版。它系统讲解 GraphQL Schema 的完整设计方法对象类型、接口、联合类型、枚举、输入类型、自定义标量、游标分页、可空性语义、字段废弃与自文档化并给出可直接复制到项目中的 SDL 代码。读完本文你将掌握一套经实战验证的 Schema-first 设计范式并能理解这些设计如何在graphql-architect技能的实际工作流schema 校验、resolver 实现、Apollo Federation 组合中落地。一、GraphQL Schema 设计的定位与整体脉络在 SKILL.md 中graphql-architect被定义为一位专门从事 Schema 设计与分布式图架构的资深 GraphQL 架构师其核心工作流为领域建模 → 设计 Schema类型、接口、联合类型、Federation 指令→ 校验 Schema 组合 → 实现 resolverDataLoader 模式→ 安全加固 → 性能优化。其中 Schema 设计环节正是通过按需加载references/schema-design.md来获得详细指导。因此本篇对应的 schema-design.md 是整个技能体系中最基础、最常被触发的参考文档它定义了图Graph的数据契约。本文按原文档的十个主题逐一展开每个主题均保留完整 SDL 示例并结合仓库中其他参考文档resolvers、federation、security、migration-from-rest补充实现层面的纵深细节。二、Object Types领域实体的基本建模单元对象类型是 GraphQL Schema 的基石。schema-design.md 用一个User / Profile / Post的博客系统模型展示了标准建模方式 User account with authentication and profile information. All users must have a unique email address. type User { Unique user identifier id: ID! Users email address (unique) email: String! Display name (optional) username: String Account creation timestamp createdAt: DateTime! Users posts (paginated) posts(first: Int 10, after: String): PostConnection! Users profile (nullable if not completed) profile: Profile } type Profile { id: ID! bio: String avatarUrl: URL website: URL location: String } type Post { id: ID! title: String! content: String! author: User! publishedAt: DateTime status: PostStatus! tags: [Tag!]! comments(first: Int, after: String): CommentConnection! }建模要点原文档隐含、本文显式化唯一标识用ID!ID类型是 GraphQL 内置标量序列化时以字符串返回专用于标识符字段便于缓存与key实体关联。关系字段即解析入口posts、author、comments等关联字段本身就是解析器的声明。例如Post.author对应到 resolvers.md 中通过 DataLoader 批量加载作者的典型实现const resolvers { Post: { author: async (post, args, context: Context): PromiseUser { // Batches multiple requests into single DB query return context.loaders.userLoader.load(post.authorId); }, }, };也就是说Schema 中每一条关联字段都对应一个 resolverSchema 设计是否按图导航直接决定了 resolver 层的复杂度。聚合关系使用 Connection 类型posts: PostConnection!与comments: CommentConnection!表明一对多关系应走游标分页详见第七节而不是裸数组。三、Interfaces抽取公共字段的契约抽象当多个类型共享一组字段时应抽象为接口。原文档给出的两个接口示例极具代表性 Common interface for all content that can be timestamped interface Timestamped { id: ID! createdAt: DateTime! updatedAt: DateTime! } Interface for searchable content interface Searchable { id: ID! title: String! description: String } type Article implements Timestamped Searchable { id: ID! title: String! description: String content: String! createdAt: DateTime! updatedAt: DateTime! author: User! } type Video implements Timestamped Searchable { id: ID! title: String! description: String url: URL! duration: Int! createdAt: DateTime! updatedAt: DateTime! uploader: User! } # Query returning interface type Query { search(query: String!): [Searchable!]! }要点多接口实现GraphQL 允许一个类型同时实现多个接口implements Timestamped Searchable实现类型必须完整声明接口中的全部字段。接口作为返回类型search(query: String!): [Searchable!]!使查询可以返回异构内容文章、视频……客户端用内联片段inline fragment按具体类型取字段。需要__resolveType接口在服务端必须有类型解析器。resolvers.md 给出的标准实现是通过字段特征判断具体类型Searchable: { __resolveType(obj: Article | Video | Podcast): string { if (content in obj) return Article; if (duration in obj) return Video; if (audioUrl in obj) return Podcast; throw new Error(Unknown Searchable type); }, },四、Union Types无公共字段的多态返回联合类型适用于返回多种类型但各类型之间没有公共字段的场景。原文档示例 Result of a content search - can be Article, Video, or Podcast union SearchResult Article | Video | Podcast Notification types that users can receive union Notification CommentNotification | LikeNotification | FollowNotification type CommentNotification { id: ID! comment: Comment! post: Post! createdAt: DateTime! } type LikeNotification { id: ID! liker: User! post: Post! createdAt: DateTime! } type Query { searchContent(query: String!): [SearchResult!]! notifications(first: Int): [Notification!]! }接口与联合类型的选型准则设计原则第 5、6 条需要客户端对公共字段做统一处理 → 用Interface返回类型之间毫无共同字段、客户端只按类型分支消费 → 用Union。同样地Union 也需要__resolveType。resolvers.md 中searchContent的实现展示了服务端如何并行查询多个数据源并混合返回Query: { searchContent: async (parent, args, context) { const [articles, videos, podcasts] await Promise.all([ context.dataSources.articles.search(args.query), context.dataSources.videos.search(args.query), context.dataSources.podcasts.search(args.query), ]); return [...articles, ...videos, ...podcasts]; }, },五、Enums枚举在查询参数与状态建模中的应用枚举类型让字段取值固定且有语义同时在 GraphQL 工具链代码生成、校验、文档中享有头等公民待遇。原文档示例 Post publication status enum PostStatus { DRAFT PUBLISHED ARCHIVED DELETED } User role for authorization enum UserRole { ADMIN MODERATOR USER GUEST } Sort direction for queries enum SortOrder { ASC DESC } type Query { posts( status: PostStatus orderBy: SortOrder DESC ): [Post!]! }使用要点枚举值全部大写GraphQL 惯例见设计原则第 4 条的配套约定。枚举可作为参数默认值orderBy: SortOrder DESC展示了声明式默认排序避免在 resolver 内硬编码。枚举与服务端授权联动UserRole这类枚举经常与 security.md 中的指令级授权配合。security.md 展示了auth(requires: Role)指令如何复用枚举作为角色参数directive auth(requires: Role) on FIELD_DEFINITION enum Role { ADMIN USER GUEST } type Query { publicData: String! userData: String! auth(requires: USER) adminData: String! auth(requires: ADMIN) }可见把角色建模成枚举正是为后续基于 Schema 指令的授权体系铺路。六、Input TypesMutation 入参的规范容器GraphQL 规范要求 mutation 的入参必须是 input 类型input关键字定义而不能复用对象类型。原因在于对象类型带有解析语义与嵌套关系input 类型则是纯数据容器。原文档示例 Input for creating a new user input CreateUserInput { email: String! password: String! username: String profile: ProfileInput } input ProfileInput { bio: String avatarUrl: URL website: URL location: String } Input for updating a post input UpdatePostInput { title: String content: String status: PostStatus tags: [ID!] } Pagination and filtering input input PostFilterInput { status: PostStatus authorId: ID tags: [String!] search: String createdAfter: DateTime createdBefore: DateTime } type Mutation { createUser(input: CreateUserInput!): User! updatePost(id: ID!, input: UpdatePostInput!): Post! } type Query { posts(filter: PostFilterInput, first: Int, after: String): PostConnection! }输入类型的设计建议结合原文档与 resolvers 参考Create 与 Update 输入分离CreateUserInput必填字段多、UpdatePostInput全部可空二者语义不同不应混用。输入嵌套输入profile: ProfileInput说明 input 可以递归嵌套用于构建结构化参数。输入校验前置input 只是 Schema 层契约业务校验仍需在 resolver 内完成。resolvers.md 与 security.md 都给出了用 Zod 校验输入并抛出BAD_USER_INPUT扩展错误的模式const CreatePostSchema z.object({ title: z.string().min(3).max(200), content: z.string().min(10).max(10000), tags: z.array(z.string()).max(5), isPublic: z.boolean(), }); // 校验失败时抛出 GraphQLErrorextensions.code BAD_USER_INPUT七、Custom Scalars为领域类型定制语义内置标量只有Int、Float、String、Boolean、ID五种无法表达日期、URL、JSON 等领域概念。自定义标量弥补了这一缺口。原文档示例 ISO 8601 date-time string scalar DateTime Valid URL string scalar URL Valid email address scalar Email JSON object scalar JSON Positive integer scalar PositiveInt type User { id: ID! email: Email! createdAt: DateTime! website: URL metadata: JSON age: PositiveInt }注意三处细节标量本身也要写文档注释这样生成 API 文档时读者能立刻知道合法格式如ISO 8601 date-time string。自定义标量必须有序列化/反序列化实现。服务端需为DateTime、URL等提供serialize、parseValue、parseLiteral实现通常由graphql-scalars等库提供Schema 中只声明类型不落地实现运行时会报错。JSON 标量的取舍metadata: JSON很灵活但会牺牲类型安全。设计上应优先用结构化 input/type 表达数据仅在前端确实需要自由结构如配置快照时使用 JSON 标量。八、Pagination Patterns遵循 Relay 规范的游标分页原文档给出的是 Relay 连接规范的完整实现这也是 SKILL.md 在 resolver 输出模板中要求的标准分页形态 Cursor-based pagination (Relay specification) type PostConnection { edges: [PostEdge!]! pageInfo: PageInfo! totalCount: Int! } type PostEdge { node: Post! cursor: String! } type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String } type Query { posts( first: Int after: String last: Int before: String ): PostConnection! }三层结构的意义Connection分页结果整体携带edges、pageInfo与可选的totalCount。Edgenode真正的数据cursor不透明游标通常是对主键做 base64 编码。PageInfohasNextPage/hasPreviousPage驱动客户端加载更多startCursor/endCursor支持向前翻页。为什么用游标而非offsetoffset 分页在数据频繁变动时会重复或漏掉记录而基于游标的上次看到的最后一条记录天然稳定。resolvers.md 给出了对应的服务端实现范式——多取一条来确定hasNextPage并对first做上限钳制const limit Math.min(args.first || 10, 100); const cursor args.after ? decodeCursor(args.after) : null; // Fetch one extra to determine hasNextPage const posts await context.dataSources.posts.findAll({ limit: limit 1, cursor, }); const hasNextPage posts.length limit; const edges posts.slice(0, limit).map((post) ({ node: post, cursor: encodeCursor(post.id), }));九、Nullable vs Non-NullableSchema 的信任边界设计这是 GraphQL Schema 设计中最容易被忽视、影响却最深远的决策之一。原文档用一条User类型完整演示了四种可空性组合type User { # Non-nullable: guaranteed to exist id: ID! email: String! createdAt: DateTime! # Nullable: optional or may not exist yet username: String bio: String avatarUrl: URL # Non-null list of nullable items # List always exists but can be empty, items can be null tags: [String]! # Non-null list of non-null items # List always exists, all items guaranteed non-null roles: [UserRole!]! # Nullable list of non-null items # List may be null, but if exists, all items non-null posts: [Post!] } type Query { # Non-null: query always returns result (empty list if none) users: [User!]! # Nullable: may return null if not found user(id: ID!): User # Non-null: guaranteed to return result or error currentUser: User! }需要准确区分的六种形态声明含义适用场景String!字段必然存在主键、唯一邮箱、创建时间String字段可为 null选填资料、未填写的 bio[String]!列表必然存在元素可 null列表本身有值个别项缺失[UserRole!]!列表必然存在且元素非空角色集合[Post!]列表可为 null存在则元素非空尚未加载或确实没有数据的关联User单值可 null按 ID 查找的查询未找到返回 null决策准则对应原文档设计原则第 1、2 条字段默认可空除非该字段在业务上保证永远存在列表字段推荐[Type!]!列表要么存在可为空数组、其中元素要么一定非空注意非空会放大错误一个!字段的 resolver 一旦抛错会导致整条路径被置 null 或请求整体失败向上冒泡到最近的 nullable 父级。因此对可靠性要求高的字段应谨慎使用!这与 SKILL.md 中不得对非空字段返回 null的约束相互呼应。十、Field Deprecation优雅的 Schema 演进机制GraphQL 没有传统 REST 那样的 URL 版本号它的演进方式就是在 Schema 内做向后兼容的废弃。原文档示例type User { id: ID! email: String! # Deprecated field with migration path name: String deprecated(reason: Use username instead) # Deprecated with specific date legacyId: String deprecated( reason: Migrating to UUID. Will be removed 2025-06-01 ) }deprecated(reason: ...)是 GraphQL 内置指令两个用法要点reason 必须写明迁移路径Use username instead 比 Dont use 对客户端友好得多可以约定明确的移除时间如Migrating to UUID. Will be removed 2025-06-01让客户端有清晰的升级窗口。配合上REST 迁移场景中 migration-from-rest.md 明确将API versioning → Schema evolution / Deprecation over versions列为概念映射——即用字段废弃替代 REST 的多版本并存。十一、Schema Documentation让 Schema 自文档化GraphQL SDL 的双引号注释或...会被解析进 introspection 结果因此写好注释就等于生成了 API 文档。原文档展示了两种级别 User represents an authenticated account in the system. Users can create posts, comments, and interact with content. Example query: query GetUser { user(id: 123) { email username posts(first: 10) { edges { node { title } } } } } type User { Unique identifier for the user id: ID! Email address (must be unique across all users) email: String! Optional display name (defaults to email if not set) username: String }要点对应设计原则第 3、10 条类型级用三引号...字段级用单行双引号...注释中直接内嵌示例查询是强烈推荐的实践——它同时服务人类读者与 AI 编程助手后者可以通过 introspection 直接读到这些示例从而生成正确的调用代码。SKILL.md 的 MUST DO 约束为所有操作提供示例查询Provide example queries for all operations正是对这一实践的强制化。十二、十项设计原则速查原文档收尾精华原文档以十条设计原则收束全文这里逐条注解可空字段Nullable Fields默认可空除非必然存在——错误隔离的根基列表字段List Fields用[Type!]!表达必然存在且元素非空的列表文档Documentation所有类型与字段都要有描述见第十一节命名Naming字段用 camelCase类型用 PascalCase——GraphQL 社区共识可被工具与 codegen 依赖接口Interfaces跨类型共享字段时优先抽象接口见第三节联合类型Unions无公共字段的多态返回用 union见第四节输入类型Input Typesmutation 入参一律创建独立 input见第六节自定义标量Scalars领域类型用自定义标量表达语义见第七节废弃Deprecation标记废弃字段并提供迁移路径见第十节示例Examples文档注释中内置示例查询见第十一节。这十条原则在技能工作流中的落点清晰可见SKILL.md 的 MUST DO 约束schema-first 设计、可空字段模式、命名约定、全字段文档、示例查询几乎逐条对应上述原则而schema-design.md则被技能在类型、接口、联合、枚举、输入类型讨论场景中按需加载。十三、如何在 claude-skills 中激活并使用这套 Schema 设计graphql-architect是 claude-skills 插件67 个专业技能的组成部分详见 SKILLS_GUIDE.md中的一个角色型技能。按 QUICKSTART.md 安装后当你的请求涉及 Schema 设计、Apollo Federation、GraphQL subscriptions 时该技能会被自动激活并按上下文加载references/schema-design.md等参考文档。安装方式任选其一# 方式一Marketplace推荐 /plugin marketplace add jeffallan/claude-skills /plugin install fullstack-dev-skillsjeffallan # 方式二从 GitHub 安装 claude plugin install https://github.com/jeffallan/claude-skills # 方式三本地开发 cp -r ./skills/* ~/.claude/skills/激活后技能会遵循 SKILL.md 定义的工作流产出四类交付物①SDL 类型定义含指令②resolver 实现DataLoader 模式③query/mutation/subscription 示例④设计决策说明。将本文的 Schema 设计规范与 resolvers.md、security.md、federation.md 配合阅读即可在具体项目中得到端到端的架构指导。结语Schema 是 GraphQL 服务的公共契约它的质量直接决定客户端体验、resolver 复杂度与 API 演进成本。schema-design.md 所沉淀的这套方法——对象类型建模、接口/联合多态、枚举语义、input 容器、自定义标量、Relay 游标分页、可空性边界、字段废弃与自文档化——构成了一个完整、可复制、可验证的 Schema 设计范式。把它与 claude-skills 中graphql-architect的校验、resolver、安全与 Federation 工作流结合使用你可以在真实项目中稳定地产出高质量、可维护、对 AI 工具友好的 GraphQL API。【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 claude-skills 中 GraphQL 架构师的 Schema 设计实战指南：从类型系统到分页与命名规范
claude-skills 中 GraphQL 架构师的 Schema 设计实战指南从类型系统到分页与命名规范【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills导读本文是 claude-skills 仓库中graphql-architect技能的配套参考文档 schema-design.md 的深度展开版。它系统讲解 GraphQL Schema 的完整设计方法对象类型、接口、联合类型、枚举、输入类型、自定义标量、游标分页、可空性语义、字段废弃与自文档化并给出可直接复制到项目中的 SDL 代码。读完本文你将掌握一套经实战验证的 Schema-first 设计范式并能理解这些设计如何在graphql-architect技能的实际工作流schema 校验、resolver 实现、Apollo Federation 组合中落地。一、GraphQL Schema 设计的定位与整体脉络在 SKILL.md 中graphql-architect被定义为一位专门从事 Schema 设计与分布式图架构的资深 GraphQL 架构师其核心工作流为领域建模 → 设计 Schema类型、接口、联合类型、Federation 指令→ 校验 Schema 组合 → 实现 resolverDataLoader 模式→ 安全加固 → 性能优化。其中 Schema 设计环节正是通过按需加载references/schema-design.md来获得详细指导。因此本篇对应的 schema-design.md 是整个技能体系中最基础、最常被触发的参考文档它定义了图Graph的数据契约。本文按原文档的十个主题逐一展开每个主题均保留完整 SDL 示例并结合仓库中其他参考文档resolvers、federation、security、migration-from-rest补充实现层面的纵深细节。二、Object Types领域实体的基本建模单元对象类型是 GraphQL Schema 的基石。schema-design.md 用一个User / Profile / Post的博客系统模型展示了标准建模方式 User account with authentication and profile information. All users must have a unique email address. type User { Unique user identifier id: ID! Users email address (unique) email: String! Display name (optional) username: String Account creation timestamp createdAt: DateTime! Users posts (paginated) posts(first: Int 10, after: String): PostConnection! Users profile (nullable if not completed) profile: Profile } type Profile { id: ID! bio: String avatarUrl: URL website: URL location: String } type Post { id: ID! title: String! content: String! author: User! publishedAt: DateTime status: PostStatus! tags: [Tag!]! comments(first: Int, after: String): CommentConnection! }建模要点原文档隐含、本文显式化唯一标识用ID!ID类型是 GraphQL 内置标量序列化时以字符串返回专用于标识符字段便于缓存与key实体关联。关系字段即解析入口posts、author、comments等关联字段本身就是解析器的声明。例如Post.author对应到 resolvers.md 中通过 DataLoader 批量加载作者的典型实现const resolvers { Post: { author: async (post, args, context: Context): PromiseUser { // Batches multiple requests into single DB query return context.loaders.userLoader.load(post.authorId); }, }, };也就是说Schema 中每一条关联字段都对应一个 resolverSchema 设计是否按图导航直接决定了 resolver 层的复杂度。聚合关系使用 Connection 类型posts: PostConnection!与comments: CommentConnection!表明一对多关系应走游标分页详见第七节而不是裸数组。三、Interfaces抽取公共字段的契约抽象当多个类型共享一组字段时应抽象为接口。原文档给出的两个接口示例极具代表性 Common interface for all content that can be timestamped interface Timestamped { id: ID! createdAt: DateTime! updatedAt: DateTime! } Interface for searchable content interface Searchable { id: ID! title: String! description: String } type Article implements Timestamped Searchable { id: ID! title: String! description: String content: String! createdAt: DateTime! updatedAt: DateTime! author: User! } type Video implements Timestamped Searchable { id: ID! title: String! description: String url: URL! duration: Int! createdAt: DateTime! updatedAt: DateTime! uploader: User! } # Query returning interface type Query { search(query: String!): [Searchable!]! }要点多接口实现GraphQL 允许一个类型同时实现多个接口implements Timestamped Searchable实现类型必须完整声明接口中的全部字段。接口作为返回类型search(query: String!): [Searchable!]!使查询可以返回异构内容文章、视频……客户端用内联片段inline fragment按具体类型取字段。需要__resolveType接口在服务端必须有类型解析器。resolvers.md 给出的标准实现是通过字段特征判断具体类型Searchable: { __resolveType(obj: Article | Video | Podcast): string { if (content in obj) return Article; if (duration in obj) return Video; if (audioUrl in obj) return Podcast; throw new Error(Unknown Searchable type); }, },四、Union Types无公共字段的多态返回联合类型适用于返回多种类型但各类型之间没有公共字段的场景。原文档示例 Result of a content search - can be Article, Video, or Podcast union SearchResult Article | Video | Podcast Notification types that users can receive union Notification CommentNotification | LikeNotification | FollowNotification type CommentNotification { id: ID! comment: Comment! post: Post! createdAt: DateTime! } type LikeNotification { id: ID! liker: User! post: Post! createdAt: DateTime! } type Query { searchContent(query: String!): [SearchResult!]! notifications(first: Int): [Notification!]! }接口与联合类型的选型准则设计原则第 5、6 条需要客户端对公共字段做统一处理 → 用Interface返回类型之间毫无共同字段、客户端只按类型分支消费 → 用Union。同样地Union 也需要__resolveType。resolvers.md 中searchContent的实现展示了服务端如何并行查询多个数据源并混合返回Query: { searchContent: async (parent, args, context) { const [articles, videos, podcasts] await Promise.all([ context.dataSources.articles.search(args.query), context.dataSources.videos.search(args.query), context.dataSources.podcasts.search(args.query), ]); return [...articles, ...videos, ...podcasts]; }, },五、Enums枚举在查询参数与状态建模中的应用枚举类型让字段取值固定且有语义同时在 GraphQL 工具链代码生成、校验、文档中享有头等公民待遇。原文档示例 Post publication status enum PostStatus { DRAFT PUBLISHED ARCHIVED DELETED } User role for authorization enum UserRole { ADMIN MODERATOR USER GUEST } Sort direction for queries enum SortOrder { ASC DESC } type Query { posts( status: PostStatus orderBy: SortOrder DESC ): [Post!]! }使用要点枚举值全部大写GraphQL 惯例见设计原则第 4 条的配套约定。枚举可作为参数默认值orderBy: SortOrder DESC展示了声明式默认排序避免在 resolver 内硬编码。枚举与服务端授权联动UserRole这类枚举经常与 security.md 中的指令级授权配合。security.md 展示了auth(requires: Role)指令如何复用枚举作为角色参数directive auth(requires: Role) on FIELD_DEFINITION enum Role { ADMIN USER GUEST } type Query { publicData: String! userData: String! auth(requires: USER) adminData: String! auth(requires: ADMIN) }可见把角色建模成枚举正是为后续基于 Schema 指令的授权体系铺路。六、Input TypesMutation 入参的规范容器GraphQL 规范要求 mutation 的入参必须是 input 类型input关键字定义而不能复用对象类型。原因在于对象类型带有解析语义与嵌套关系input 类型则是纯数据容器。原文档示例 Input for creating a new user input CreateUserInput { email: String! password: String! username: String profile: ProfileInput } input ProfileInput { bio: String avatarUrl: URL website: URL location: String } Input for updating a post input UpdatePostInput { title: String content: String status: PostStatus tags: [ID!] } Pagination and filtering input input PostFilterInput { status: PostStatus authorId: ID tags: [String!] search: String createdAfter: DateTime createdBefore: DateTime } type Mutation { createUser(input: CreateUserInput!): User! updatePost(id: ID!, input: UpdatePostInput!): Post! } type Query { posts(filter: PostFilterInput, first: Int, after: String): PostConnection! }输入类型的设计建议结合原文档与 resolvers 参考Create 与 Update 输入分离CreateUserInput必填字段多、UpdatePostInput全部可空二者语义不同不应混用。输入嵌套输入profile: ProfileInput说明 input 可以递归嵌套用于构建结构化参数。输入校验前置input 只是 Schema 层契约业务校验仍需在 resolver 内完成。resolvers.md 与 security.md 都给出了用 Zod 校验输入并抛出BAD_USER_INPUT扩展错误的模式const CreatePostSchema z.object({ title: z.string().min(3).max(200), content: z.string().min(10).max(10000), tags: z.array(z.string()).max(5), isPublic: z.boolean(), }); // 校验失败时抛出 GraphQLErrorextensions.code BAD_USER_INPUT七、Custom Scalars为领域类型定制语义内置标量只有Int、Float、String、Boolean、ID五种无法表达日期、URL、JSON 等领域概念。自定义标量弥补了这一缺口。原文档示例 ISO 8601 date-time string scalar DateTime Valid URL string scalar URL Valid email address scalar Email JSON object scalar JSON Positive integer scalar PositiveInt type User { id: ID! email: Email! createdAt: DateTime! website: URL metadata: JSON age: PositiveInt }注意三处细节标量本身也要写文档注释这样生成 API 文档时读者能立刻知道合法格式如ISO 8601 date-time string。自定义标量必须有序列化/反序列化实现。服务端需为DateTime、URL等提供serialize、parseValue、parseLiteral实现通常由graphql-scalars等库提供Schema 中只声明类型不落地实现运行时会报错。JSON 标量的取舍metadata: JSON很灵活但会牺牲类型安全。设计上应优先用结构化 input/type 表达数据仅在前端确实需要自由结构如配置快照时使用 JSON 标量。八、Pagination Patterns遵循 Relay 规范的游标分页原文档给出的是 Relay 连接规范的完整实现这也是 SKILL.md 在 resolver 输出模板中要求的标准分页形态 Cursor-based pagination (Relay specification) type PostConnection { edges: [PostEdge!]! pageInfo: PageInfo! totalCount: Int! } type PostEdge { node: Post! cursor: String! } type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String } type Query { posts( first: Int after: String last: Int before: String ): PostConnection! }三层结构的意义Connection分页结果整体携带edges、pageInfo与可选的totalCount。Edgenode真正的数据cursor不透明游标通常是对主键做 base64 编码。PageInfohasNextPage/hasPreviousPage驱动客户端加载更多startCursor/endCursor支持向前翻页。为什么用游标而非offsetoffset 分页在数据频繁变动时会重复或漏掉记录而基于游标的上次看到的最后一条记录天然稳定。resolvers.md 给出了对应的服务端实现范式——多取一条来确定hasNextPage并对first做上限钳制const limit Math.min(args.first || 10, 100); const cursor args.after ? decodeCursor(args.after) : null; // Fetch one extra to determine hasNextPage const posts await context.dataSources.posts.findAll({ limit: limit 1, cursor, }); const hasNextPage posts.length limit; const edges posts.slice(0, limit).map((post) ({ node: post, cursor: encodeCursor(post.id), }));九、Nullable vs Non-NullableSchema 的信任边界设计这是 GraphQL Schema 设计中最容易被忽视、影响却最深远的决策之一。原文档用一条User类型完整演示了四种可空性组合type User { # Non-nullable: guaranteed to exist id: ID! email: String! createdAt: DateTime! # Nullable: optional or may not exist yet username: String bio: String avatarUrl: URL # Non-null list of nullable items # List always exists but can be empty, items can be null tags: [String]! # Non-null list of non-null items # List always exists, all items guaranteed non-null roles: [UserRole!]! # Nullable list of non-null items # List may be null, but if exists, all items non-null posts: [Post!] } type Query { # Non-null: query always returns result (empty list if none) users: [User!]! # Nullable: may return null if not found user(id: ID!): User # Non-null: guaranteed to return result or error currentUser: User! }需要准确区分的六种形态声明含义适用场景String!字段必然存在主键、唯一邮箱、创建时间String字段可为 null选填资料、未填写的 bio[String]!列表必然存在元素可 null列表本身有值个别项缺失[UserRole!]!列表必然存在且元素非空角色集合[Post!]列表可为 null存在则元素非空尚未加载或确实没有数据的关联User单值可 null按 ID 查找的查询未找到返回 null决策准则对应原文档设计原则第 1、2 条字段默认可空除非该字段在业务上保证永远存在列表字段推荐[Type!]!列表要么存在可为空数组、其中元素要么一定非空注意非空会放大错误一个!字段的 resolver 一旦抛错会导致整条路径被置 null 或请求整体失败向上冒泡到最近的 nullable 父级。因此对可靠性要求高的字段应谨慎使用!这与 SKILL.md 中不得对非空字段返回 null的约束相互呼应。十、Field Deprecation优雅的 Schema 演进机制GraphQL 没有传统 REST 那样的 URL 版本号它的演进方式就是在 Schema 内做向后兼容的废弃。原文档示例type User { id: ID! email: String! # Deprecated field with migration path name: String deprecated(reason: Use username instead) # Deprecated with specific date legacyId: String deprecated( reason: Migrating to UUID. Will be removed 2025-06-01 ) }deprecated(reason: ...)是 GraphQL 内置指令两个用法要点reason 必须写明迁移路径Use username instead 比 Dont use 对客户端友好得多可以约定明确的移除时间如Migrating to UUID. Will be removed 2025-06-01让客户端有清晰的升级窗口。配合上REST 迁移场景中 migration-from-rest.md 明确将API versioning → Schema evolution / Deprecation over versions列为概念映射——即用字段废弃替代 REST 的多版本并存。十一、Schema Documentation让 Schema 自文档化GraphQL SDL 的双引号注释或...会被解析进 introspection 结果因此写好注释就等于生成了 API 文档。原文档展示了两种级别 User represents an authenticated account in the system. Users can create posts, comments, and interact with content. Example query: query GetUser { user(id: 123) { email username posts(first: 10) { edges { node { title } } } } } type User { Unique identifier for the user id: ID! Email address (must be unique across all users) email: String! Optional display name (defaults to email if not set) username: String }要点对应设计原则第 3、10 条类型级用三引号...字段级用单行双引号...注释中直接内嵌示例查询是强烈推荐的实践——它同时服务人类读者与 AI 编程助手后者可以通过 introspection 直接读到这些示例从而生成正确的调用代码。SKILL.md 的 MUST DO 约束为所有操作提供示例查询Provide example queries for all operations正是对这一实践的强制化。十二、十项设计原则速查原文档收尾精华原文档以十条设计原则收束全文这里逐条注解可空字段Nullable Fields默认可空除非必然存在——错误隔离的根基列表字段List Fields用[Type!]!表达必然存在且元素非空的列表文档Documentation所有类型与字段都要有描述见第十一节命名Naming字段用 camelCase类型用 PascalCase——GraphQL 社区共识可被工具与 codegen 依赖接口Interfaces跨类型共享字段时优先抽象接口见第三节联合类型Unions无公共字段的多态返回用 union见第四节输入类型Input Typesmutation 入参一律创建独立 input见第六节自定义标量Scalars领域类型用自定义标量表达语义见第七节废弃Deprecation标记废弃字段并提供迁移路径见第十节示例Examples文档注释中内置示例查询见第十一节。这十条原则在技能工作流中的落点清晰可见SKILL.md 的 MUST DO 约束schema-first 设计、可空字段模式、命名约定、全字段文档、示例查询几乎逐条对应上述原则而schema-design.md则被技能在类型、接口、联合、枚举、输入类型讨论场景中按需加载。十三、如何在 claude-skills 中激活并使用这套 Schema 设计graphql-architect是 claude-skills 插件67 个专业技能的组成部分详见 SKILLS_GUIDE.md中的一个角色型技能。按 QUICKSTART.md 安装后当你的请求涉及 Schema 设计、Apollo Federation、GraphQL subscriptions 时该技能会被自动激活并按上下文加载references/schema-design.md等参考文档。安装方式任选其一# 方式一Marketplace推荐 /plugin marketplace add jeffallan/claude-skills /plugin install fullstack-dev-skillsjeffallan # 方式二从 GitHub 安装 claude plugin install https://github.com/jeffallan/claude-skills # 方式三本地开发 cp -r ./skills/* ~/.claude/skills/激活后技能会遵循 SKILL.md 定义的工作流产出四类交付物①SDL 类型定义含指令②resolver 实现DataLoader 模式③query/mutation/subscription 示例④设计决策说明。将本文的 Schema 设计规范与 resolvers.md、security.md、federation.md 配合阅读即可在具体项目中得到端到端的架构指导。结语Schema 是 GraphQL 服务的公共契约它的质量直接决定客户端体验、resolver 复杂度与 API 演进成本。schema-design.md 所沉淀的这套方法——对象类型建模、接口/联合多态、枚举语义、input 容器、自定义标量、Relay 游标分页、可空性边界、字段废弃与自文档化——构成了一个完整、可复制、可验证的 Schema 设计范式。把它与 claude-skills 中graphql-architect的校验、resolver、安全与 Federation 工作流结合使用你可以在真实项目中稳定地产出高质量、可维护、对 AI 工具友好的 GraphQL API。【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考