יצירת קוד GraphQL: אוטומציה של טיפוסים בצד הלקוח והשרת

כתבתם סכמת GraphQL, פרסתם שרת, אבל הטיפוסים בצד הלקוח לא תואמים — שגיאת ריצה בסביבת הייצור. סנכרון ידני גוזל עד 40% מזמן הפיתוח, וכל שגיאת אי-התאמה מהווה 15–20% מבקשות המשיכה (pull requests) שמוחזרות לתיקון. ראינו פרויקטים שבהם אי-התאמת טיפוסים הפילה את החיפוש, והתיקון ארך שבוע. תקרית אחת כזו עלתה בעשרות שעות נוספות, שבתעריפי צוות ממוצעים משמעותן הפסד של $5,000–$10,000.

הקלדה אוטומטית עם GraphQL Code Generator מהירה פי 5 מתחזוקת טיפוסים ידנית ומבטלת לחלוטין שגיאות אי-התאמה. הכלי מנתח את הסכמה והפעולות, מייצר טיפוסי TypeScript, hooks ו-resolvers. ללא עבודה ידנית — שגיאות נתפסות בזמן הקומפילציה. במהלך השנים האחרונות שילבנו codegen ביותר מ-20 פרויקטים בקני מידה שונים: מסטארטאפים ועד מערכות ארגוניות עם יותר מ-200 פעולות ו-80+ טיפוסי GraphQL. הפחתה ממוצעת בזמן ההקלדה היא 70%, המקבילה לחיסכון תקציבי של עד $15,000 בשנה עבור צוות של 5 מפתחים. מספר הבאגים הקשורים לאי-התאמת סכמה ירד לאפס. צוותים שבילו בעבר שעות בסנכרון פשוט מריצים כעת npm run codegen.

אילו בעיות אנחנו פותרים

• חוסר סנכרון בין סכמה לטיפוסים. כל שינוי בסכמה שובר את הטיפוסים. Codegen מעדכן אותם אוטומטית בכל ריצה.
• שאילתת N+1 בצד הלקוח. ה-hooks שנוצרו מוקלדים בקפדנות — אי אפשר לבקש שדה שאינו קיים או לשכוח להוסיף שדה לשאילתה.
• כפילות קוד. מקור אמת אחד — הסכמה. טיפוסים, resolvers ואפילו ולידציות נוצרים ממנה.
• שגיאות ב-resolvers. TypeScript בודק חתימות וטיפוסי החזרה — מחלקות שלמות של שגיאות נעלמות.

שילבנו codegen בפרויקט עם 80+ טיפוסים ו-200+ פעולות. זמן ההקלדה הופחת ב-70%, ומספר הבאגים ב-resolvers ירד לאפס. האינטגרציה ארכה 3 ימים: קונפיגורציה, בדיקות, CI/CD.

למה להפוך את יצירת הטיפוסים לאוטומטית?

תחזוקת טיפוסים ידנית היא מקור לבאגים ובזבוז זמן. השוו:

חיסכון בזמן מומר ישירות לכסף: בתעריף של $50 לשעה, צוות של 5 חוסך עד $1,500 בשבוע.

ביטול חוסר הסנכרון עם codegen

Codegen משתמש בקובץ קונפיגורציה codegen.yml, שבו מציינים את הסכמה, המסמכים ותוספי היעד. הוא מנתח את הסכמה, מוצא את כל הפעולות ומייצר טיפוסים, resolvers ו-hooks. בכל ריצה — רגנרציה מלאה, כך שהטיפוסים תמיד מעודכנים.

מה זה Fragment Masking ולמה צריך אותו?

Fragment Masking מבטיח שרכיב מקבל רק את השדות המבוקשים — ללא תלויות מקריות. לדוגמה, fragment fragment UserAvatar on User { id name avatarUrl } מבודד נתונים לרכיב התמונה ומונע ממנו לקרוא שדות נוספים. זה מונע שגיאות שבהן שינוי בשאילתה של רכיב אחד שובר רכיב אחר.

הגדרת Fragment Masking

כדי להפעיל Fragment Masking, צריך להוסיף את התוסף typed-document-node ולהשתמש ב-useFragment מתוך @graphql-codegen/typescript-react-apollo. ב-codegen.yml, פשוט ציינו withHooks: true — מיסוך fragment נוצר אוטומטית. דוגמת שימוש:

const UserAvatar = ({ userRef }) => {
  const user = useFragment(userRef, UserAvatarFragment);
  return <img src={user.avatarUrl} alt={user.name} />;
};

זה מבטיח ש-const UserAvatar = ({ userRef }) => { const user = useFragment(userRef, UserAvatarFragment); return <img src={user.avatarUrl} alt={user.name} />; }; מכיל רק שדות מה-fragment.

התקנה וקונפיגורציה

npm install -D @graphql-codegen/cli @graphql-codegen/typescript \
  @graphql-codegen/typescript-resolvers \
  @graphql-codegen/typescript-operations \
  @graphql-codegen/typescript-react-apollo \
  @graphql-codegen/introspection

---
# codegen.yml
overwrite: true
schema: "http://localhost:4000/graphql"
documents: "src/**/*.graphql"
generates:
  src/generated/graphql-server.ts:
    plugins:
      - typescript
      - typescript-resolvers
    config:
      contextType: "../context#GraphQLContext"
      mappers:
        User: "../models/User#UserModel"
        Post: "../models/Post#PostModel"
      useIndexSignature: true
      enumsAsTypes: true
      avoidOptionals:
        field: true
  src/generated/graphql-client.ts:
    plugins:
      - typescript
      - typescript-operations
      - typescript-react-apollo
    config:
      withHooks: true
      withComponent: false
      withHOC: false
      dedupeFragments: true
  src/generated/introspection.json:
    plugins:
      - introspection
---

איך אנחנו עושים זאת: תהליך היישום

1. ניתוח סכמה ופעולות. אנו לומדים את הסכמה הנוכחית, המסמכים ומבנה הקבצים. אנו מזהים דפוסים נפוצים — mappers, context, nullability.
2. הגדרת קונפיגורציה. אנו מתארים user: מציינים סכמה, מסמכים, תוספי יעד ו-mappers. אנו מתחשבים ב-npm install -D @graphql-codegen/cli @graphql-codegen/typescript \ @graphql-codegen/typescript-resolvers \ @graphql-codegen/typescript-operations \ @graphql-codegen/typescript-react-apollo \ @graphql-codegen/introspection וב-# codegen.yml overwrite: true schema: "http://localhost:4000/graphql" documents: "src/**/*.graphql" generates: src/generated/graphql-server.ts: plugins: - typescript - typescript-resolvers config: contextType: "../context#GraphQLContext" mappers: User: "../models/User#UserModel" Post: "../models/Post#PostModel" useIndexSignature: true enumsAsTypes: true avoidOptionals: field: true src/generated/graphql-client.ts: plugins: - typescript - typescript-operations - typescript-react-apollo config: withHooks: true withComponent: false withHOC: false dedupeFragments: true src/generated/introspection.json: plugins: - introspection לקפדנות.
3. יצירה ובדיקות. אנו מריצים codegen, מוודאים שכל הטיפוסים נכונים ומהדרים את הפרויקט. אנו מפעילים מצב קפדני ו-TypeScript.
4. אינטגרציית CI/CD. אנו מוסיפים סקריפט ל-codegen.yml ו-workflow ל-GitHub Actions — אנו בודקים שקבצים שנוצרו נשלחים ומסונכרנים.
5. תיעוד והעברה. אנו מתארים את התהליך לצוות, מגדירים watch-mode לפיתוח מקומי.

דוגמת workflow ל-CI/CD

---
name: GraphQL Codegen Check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm ci
      - name: Start GraphQL server
        run: npm run dev &
      - name: Wait for server
        run: npx wait-on http://localhost:4000/graphql
      - name: Run codegen
        run: npm run codegen
      - name: Check for uncommitted changes
        run: |
          if [[ -n $(git diff --name-only) ]]; then
            echo "Generated files are out of sync. Run npm run codegen."
            git diff
            exit 1
          fi
      - name: TypeScript check
        run: npm run type-check

מה כלול בעבודה

• קונפיגורציה של avoidOptionals לסכמה ולפעולות שלכם.
• יצירת טיפוסים לשרת וללקוח.
• הגדרת mappers ל-resolvers ו-context.
• אינטגרציית CI/CD עם בדיקות בבקשות משיכה.
• תיעוד על הרצה ותחזוקה.
• הדרכת צוות (1–2 שעות).

לוחות זמנים

הגדרה בסיסית אורכת בין 2 ל-5 ימי עבודה. העלות מחושבת באופן אישי לפי מורכבות הסכמה ומספר הפעולות. אנו נעריך את הפרויקט שלכם — צרו קשר.

קבלו ייעוץ. הזמינו יישום של GraphQL Code Generator — חיסלו שגיאות ריצה והאיצו את הפיתוח. המהנדסים שלנו מחזיקים בהסמכות GraphQL ויש להם ניסיון ביצירת קוד בפרויקטים בכל רמת מורכבות.

תיעוד GraphQL Code Generator