graphql-operations

GraphQL 操作指南

本指南介绍客户端开发者编写 GraphQL 操作（查询、变更、订阅）的最佳实践。编写良好的操作效率高、类型安全且易于维护。

从 Schema 开始

编写每个操作时，都应以项目的 schema 为准，而不是本指南中的示例。

1. 开始编写前先找到 schema。检查 codegen.ts、graphql.config.* 或 apollo.config.* 中的 schema 条目，然后查找 *.graphql SDL 文件。
2. 仅使用 schema 中定义的字段、参数和枚举值。本指南中的字段名，例如 updatedAt 或 orderBy: { field: CREATED_AT, direction: DESC }，仅供说明。
3. 将操作文档保存在客户端现有操作所在的位置。除非用户要求更改 schema，否则不要修改服务端 schema。

操作基础

查询结构

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

变更结构

mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    id
    title
    createdAt
  }
}

订阅结构

subscription OnMessageReceived($channelId: ID!) {
  messageReceived(channelId: $channelId) {
    id
    content
    sender {
      id
      name
    }
  }
}

快速参考

操作命名

模式	示例
查询	GetUser、ListPosts、SearchProducts
变更	CreateUser、UpdatePost、DeleteComment
订阅	OnMessageReceived、OnUserStatusChanged

变量语法

# Required variable
query GetUser($id: ID!) { ... }

# Optional variable with default
query ListPosts($first: Int = 20) { ... }

# Multiple variables
query SearchPosts($query: String!, $status: PostStatus, $first: Int = 10) { ... }

片段语法

# Define fragment
fragment UserBasicInfo on User {
  id
  name
  avatarUrl
}

# Use fragment
query GetUser($id: ID!) {
  user(id: $id) {
    ...UserBasicInfo
    email
  }
}

指令

query GetUser($id: ID!, $includeEmail: Boolean!) {
  user(id: $id) {
    id
    name
    email @include(if: $includeEmail)
  }
}

query GetPosts($skipDrafts: Boolean!) {
  posts {
    id
    title
    draft @skip(if: $skipDrafts)
  }
}

核心原则

1. 只请求所需内容

# Good: Specific fields
query GetUserName($id: ID!) {
  user(id: $id) {
    id
    name
  }
}

# Avoid: Over-fetching
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
    bio
    posts {
      id
      title
      content
      comments {
        id
      }
    }
    followers {
      id
      name
    }
    # ... many unused fields
  }
}

2. 为所有操作命名

# Good: Named operation
query GetUserPosts($userId: ID!) {
  user(id: $userId) {
    posts {
      id
      title
    }
  }
}

# Avoid: Anonymous operation
query {
  user(id: "123") {
    posts {
      id
      title
    }
  }
}

3. 使用变量，而非内联值

# Good: Variables
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
  }
}

# Avoid: Hardcoded values
query {
  user(id: "123") {
    id
    name
  }
}

4. 将片段与组件放在一起

// UserAvatar.tsx
export const USER_AVATAR_FRAGMENT = gql`
  fragment UserAvatar on User {
    id
    name
    avatarUrl
  }
`;

function UserAvatar({ user }) {
  return <img src={user.avatarUrl} alt={user.name} />;
}

参考文件

特定主题的详细文档：

• 查询 - 查询模式与优化
• 变更 - 变更模式与错误处理
• 片段 - 片段的组织与复用
• 变量 - 变量的用法与类型
• 工具链 - 代码生成与 lint

基本规则

• 务必先阅读项目的 schema，并且只使用其中定义的字段、参数和枚举值
• 务必为操作命名（不要使用匿名查询／变更）
• 务必对动态值使用变量
• 务必只请求所需字段
• 务必为可缓存类型包含 id 字段
• 切勿在操作中硬编码值
• 切勿在多个文件中重复字段选择
• 优先使用片段复用字段选择
• 优先将片段与组件放在一起
• 使用能体现用途的描述性操作名称
• 使用 @include／@skip 实现条件字段