graphql-operations

GraphQL 操作指南

本指南涵蓋了客戶端開發人員撰寫 GraphQL 操作（查詢、變更、訂閱）的最佳實務。良好的操作應具備高效、型別安全且易於維護的特性。

操作基礎

查詢結構

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

變數語法

# 必要變數
query GetUser($id: ID!) { ... }

# 可選變數，附帶預設值
query ListPosts($first: Int = 20) { ... }

# 多個變數
query SearchPosts($query: String!, $status: PostStatus, $first: Int = 10) { ... }

片段語法

# 定義片段
fragment UserBasicInfo on User {
  id
  name
  avatarUrl
}

# 使用片段
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. 只請求你需要的資料

# 良好：指定欄位
query GetUserName($id: ID!) {
  user(id: $id) {
    id
    name
  }
}

# 避免：過度擷取
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
    bio
    posts {
      id
      title
      content
      comments {
        id
      }
    }
    followers {
      id
      name
    }
    # ... 許多未使用的欄位
  }
}

2. 為所有操作命名

# 良好：命名操作
query GetUserPosts($userId: ID!) {
  user(id: $userId) {
    posts {
      id
      title
    }
  }
}

# 避免：匿名操作
query {
  user(id: "123") {
    posts {
      id
      title
    }
  }
}

3. 使用變數，而非內嵌值

# 良好：使用變數
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
  }
}

# 避免：硬編碼值
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} />;
}

參考文件

特定主題的詳細文件：

• 查詢 - 查詢模式與最佳化
• 變更 - 變更模式與錯誤處理
• 片段 - 片段組織與重用
• 變數 - 變數使用與型別
• 工具 - 程式碼生成與 linting

基本規則

• 務必為操作命名（不要使用匿名查詢/變更）
• 務必使用變數來處理動態值
• 務必只請求你需要的欄位
• 務必為可快取的型別包含 id 欄位
• 絕對不要在操作中硬編碼值
• 絕對不要在檔案間重複欄位選取
• 偏好使用片段來重用欄位選取
• 偏好將片段與元件放在一起
• 使用描述性的操作名稱來反映用途
• 使用 @include/@skip 處理條件式欄位