שורת קודשורת קוד

יסודות איתנים: בניית שרת API איכותי ב-Node.js עם Express ו-TypeScript

Shaked Eyal's photo
Shaked Eyal
·

7 דקות קריאה

אמ;לק

כשהתחלתי פרויקט צד חדש, החלטתי לצאת מאזור הנוחות וללמוד Node.js. הפוסט הזה הוא התוצר של המסע: מדריך מעשי שמראה איך בניתי מאפס בסיס (boileplate) איכותי, מאובטח, ומוכן לפרודקשן עם Express ו-TypeScript. נצלול להסבר של כל רכיב מרכזי, עם דגש על Best Practices מהיום הראשון.

הקדמה - למה לנסות משהו חדש?

לאחרונה, התחיל לדגדג לי בקצות האצבעות רעיון לפרויקט צדדי חדש שדרש שרת API. באופן טבעי, עמדתי בפני צומדת דרכים מוכרת לכל מפתח: האם ללכת על המוכר והבטוח, הטכנולוגיות שאני חי ונושם ביום-יום, או לנצל את ההזדמנות כדי לצאת מאזור הנוחות וללמוד משהו חדש?

אחד הטיפים שאני הכי אוהב מהספר הקלאסי "The Pragmatic Programmer" הוא להשקיע בלימוד שפה חדשה באופן קבוע. לאו דווקא כדי להפוך למומחה בה, אלא כי כל שפה וכל-ecosystem חושפים אותך לפרדיגמות חשיבה שונות, לדרכים חדשות לפתור בעיות, ובסופו של דבר - הופכים אותך למפתח טוב יותר גם ב״שפת האם״ שלך.

ההחלטה נפלה: הפרוקיט הזה יהיה מגרש המשחקים שלי לטכנולוגיה חדשה. בחרתי באחת האופציות הפופלריות ביותר בעולם ה-backend כיום: Node.js יחד עם TypeScript ו-Express.

הפוסט הזה הוא פרק ראשון בתיעוד המסע. המטרה שלי מהרגע הראשון לא הייתה רק ״להרים משהו שעובד״, אלא לבנות בסיס נכון, יציב ואיכותי. כזה שמיישם Best Practices מהשורה הראשונה בתחומים של אבטחה, טיפול בשגיאות, ומוכנות לפרודקשיין. רציתי ליצור משהו שאוכל להיות גאב בו ולהשתמש בו בביטחון כנקודת פתיחה לפרויקט שלי.

אז בואו נצלול יחד לתהליך ולתצואה - בניית יסודות איתנים לשרת API מודרני.

אבני הבניין - סקירת התלויות (Dependencies) המרכזיות

לפני שנראה שורת קוד אחת, בואו נכיר את השחקנים המרכזיים הזירה. פרוקיט Node.js איכותי מתחיל מבחירה נכונה של התלויות שלו

Express

זהו הלב הפועם של השרת שלנו. Express הוא micro-framework מינימליסטי וגמיש שמספק לנו את הכלים הבסיסיים לניהול בקשות HTTP, ניתוב (routing), וטיפול ב-Middleware. הוא לא כופה עלינו דרך עבודה אחת, אלא נותן לנו את החופש לבנות את השרת כראות עינינו.

TypeScript ו-TS-Node

אם JavaScript היא שדה פתוח, TypeScript היא שדה עם גדרות בטיחות, שילוט ברור ושומר בכניסה. היא מוסיפה מערכת טיפוסים (types) חזקה מעל JavaScript, מה שמאפשר לנו לתפוס טעויות בזמן כתיבת הקוד (compilation) ולא בזמן ריצה (runtime). ts-node הוא כלי עזר שמאפשר לנו להריץ קוד TypeScript ישירות, ללא צורך לקמפל אותו ל-JavaScript באופן ידני בכל שינוי/

רביעיית ה-Middleware החיונית

  • helmet: תחשבו על helmet כשומר הראש של האפליקציה שלכם. באמצעות שורה אחת (app.use(helmet())), הוא מוסיף לכל תשובה מהשרת סט של HTTP headers חיוניים שמגנים עלינו מפני התקפות נפוצות כמו XSS, Clickjacking ועוד. זוהי שכבת אבטחה בסיסית שאין שום סיבה לוותר עליה.

  • cors (Cross-Origin Resource Sharing) : בעידן ה-web המודרני, ה-frontend שלכם (למשל אפליקציית React שרצה על המכשיר של המשתמש) וה-backend (שרת ה-API שרץ על שרת ב-AWS) חיים בדומיינים שונים. כברירת מחדל, דפדפנים חוסמים בקשות כאלה מטעמי אבטחה. cors הוא ה-Middleware שמאפשר לנו להגדיר בצורה מבוקרת ובטוחה אילו דומיינים חיצוניים רשאים ״לדבר״ עם ה-API שלנו.

  • compression: מידלוור פשוט ויעיל שעושה בדיוק מה ששמו מרמז: הוא דוחס (באמצעות Gzip) את גוף התשובה (response body) לפני שליחתו לקליינט. התוצאה? payload קטן יותר, תגובות מהירות יותר, וחווית משתמש טובה יותר, במיוחד ברשתות איטיות.

  • morgan: ״הקופסה השחורה״ של השרת שלנו. morgan הוא logger של בקשות HTTP. הוא יודע לתעד כל בקשה שנכנסת לשרת - מה הייתה המתודה (GET/POST), לאיזה נתיב (URL), מה היה ה-status code של התשובה וכמה זמן לקח לשרת לענות. מידע זה קריטי ל-debugging ומעקב בזמן פיתוח.

ה-Pipeline בפעולה: הבנת Middleware

הבנת המושג Middleware היא המפתח להבנת אופן הפעולה של Express. אפשר לחשוב על זה כמו פס ייצור במפעל. כל הקשת HTTP שנכנסת לשרת היא חומר גלם שמונח בתחילת הפס. לאורך הפס, ישנן מספר ״תחנות עבודה״ (אלו ה-Middlewares). כל תחנה עושה משהו קטן לבקשה: בודקת משהו, מוסיפה מידע, משנה משהו, ואז מעבירה אותה לתחנה הבאה בשרשרת.

הסדר שבוא אנחנו מגדירים את ה-Middlewares באמצעות app.use() הוא קריטי, כי הוא קובע את סדר התחנות בפס הייצור. בואו ננתח את הסדר בקוד של השרת:

  1. app.use(helmet()): התחנה הראשונה היא האבטחה. אנחנו רוצים לוודא שהגנות בסיסיות קיימות עוד לפני שנעשה כל דבר אחר.

  2. app.use(cors()): מיד לאחר מכן, נגדיר את הרשאות הגישה. אם בקשה מגיעה מדומיין לא מורשה, אין טעם להמשיך לעבד אותה.

  3. app.use(compression()): דחיסה

  4. app.use(morgan('combined'): נרצה לתעד את הבקשה כמו שהיא נכנסה, לפני שאנחנו מתחילים לעבד אותה לעומק. הפורמט combined הוא סטנדרט ותיק ופופולרי, המבוסס על פורמט הלוגים המשולב של שרת Apache.

  5. app.use(express.json()): זו תחנה קריטית. היא בודקת אם גוף הבקשה (body) הוא בפורמט JSON, ואם כן, היא ״מפענחת״ אותו והופכת אותו לאובייקט JavaScript זמין תחת req.body. אם לא נשים את המידלוור הזה, כל ניסיון לגשת למידע בבקשות POST או PUT ייכשל.

רק אחרי שהבקשה עברה את כל שרשרת ה-Middleware הזו, היא תגיע סוף סוף ללגיקה העסקית שלנו - ה-Route Handler.

הגדרת נתיבים (Routes) - נקודות הקצה של ה-API

אחרי שטיפלנו בכל התשתיות, הגיע הזמן להגדיר את נקודות הקצה (Endpoints) שה-API שלנו חושף לעולם. ב-Express, זה נעשה באמצעות פונקציות כמו app.post(), app.get() וכו׳.

האנטומיה של הגדרת Route היא פשוטה:

TypeScript

app.get('/path', (req, res) => {
  // Business logic here
});

app.get('/path', (req, res) => {
  // Business logic here
});

הפונקציה מקבלת שני ארגומנטים עיקריים:

  • הנתיב (Path): כתובת ה-URL של ה-Endpoint (למשל 'api/users/).

  • ה-Handler: פונקציה (callback) שמקבלת את אובייקט הבקשה (req) ואובייקט התשובה (res).

    • req (Request): מכיל את כל המידע על הבקשה שהגיעה מהקליינט - headers, פרמטרים ב-URL, גוף הבקשה, ועוד.

    • res (Response): האובייקט שדרכו אנחנו שולחים תשובה חזרה לקליינט. אנחנו משתמשים בו כדי לקבוע את ה-status code (למשל res.status(200)), ולשלוח את גוף התשובה (למשל res.json({ message: 'Success' }).

בשרת שלי הגדרתי endpoint ראשוני של /health

TypeScript

app.get5('/health', (_req, res) => {
  res.status(200).json({
    status: 'ok',
    uptime: process.uptime(),
  });
});

app.get5('/health', (_req, res) => {
  res.status(200).json({
    status: 'ok',
    uptime: process.uptime(),
  });
});

ה-endpoint הזו היא לא סתם nice to have, אלא best practice קריטי בארכיטקטורות מודרניות. מערכות כמו Kubernetes משתמשות ב-Health Checks (הנקראים liveness and readiness probes) כדי לדעת אם הקונטיינר שלנו ״חי״ ומסוגל לקבל תעבורה. אם ה-endpoint הזה לא מחזיר תשובה עם סטאטוס של 200, המערכת תדע להרוג את הקונטיינר הבעייתי ולהרים אחד חדש במקומו.

ניהול שגיאות למקצוענים

מערכת שלא יודעת להתמודד עם שגיאות היא מערכת שבורה שמחכה לתקלות. הקוד של השרת הראשוני שכתבתי מטפל בשגיאות בשתי רמות

טיפול ב-404 (Not Found):

מה קורה אם משתמש מנסה לגשת ל-api/non-existent-route? אם לא נטפל בזה, הבקשה פשוט ״תיתקע״ והקליינט יקבל timeout. הפתרון הוא להוסיף, בסוף שרשרת ה-routes שלנו, ״רשת ביטחון״ שתופסת כל בקשה שלא תאמה לאף אחד מה-routes שהגדרנו לפניה:

TypeScript

app.use('*', (req, res) => {
  res.status(404).json({
    error: 'Not Found',
    message: `The requested URL ${req.originalUrl} was not found on this server.`,
  });
});

app.use('*', (req, res) => {
  res.status(404).json({
    error: 'Not Found',
    message: `The requested URL ${req.originalUrl} was not found on this server.`,
  });
});

הכוכבית (*) משמשת כ-wildcard שתופס הכל. מכיוון שהוא מוגדר אחרון, הוא יופעל רק אם שום route אחר לא תפס את הבקשה.

ה-Global Error Handler:

ומה קורה אם מתרחשת שגיאה בתוך אחד ה-Route Handlers שלנו? למשל, שגיאה בגישה לבסיס הנתונים או שגיאת לוגיקה בלתי צפויה? אם לא נטפל בזה, התהליך של Node.js יקרוס וכל השרת יפסיק לעבוד.

כאן נכנס לפעולה ה-Middleware המיוחד לטיפול שגיאות. מזהים אותו לפי העובדה שהוא מקבל ארבעה ארגומנטים (err, req, res, next):

TypeScript

app.use((err: Error, _req, res, _next) => {
  console.error('Error:', err.stack) //Log the full error for debugging

  // Send a generic message in production to avoid leaking detail
  const message = process.env.[NODE_ENV] === 'development'
    ? err.message
    : 'An unexpected error occurred.';

  res.status(500).json({ error: 'Internal Server Error', message });
});

app.use((err: Error, _req, res, _next) => {
  console.error('Error:', err.stack) //Log the full error for debugging

  // Send a generic message in production to avoid leaking detail
  const message = process.env.[NODE_ENV] === 'development'
    ? err.message
    : 'An unexpected error occurred.';

  res.status(500).json({ error: 'Internal Server Error', message });
});

רשת ביטחון אחרונה זו תתפוס כל שגיאה שתתרחש באפליקציה, תרשום אותם ללוגים (כדי שאנחנו המפתחים נראה אותה), ותחזיר לקליינט תשובת 500 מסודרת במקום להתרסק. שימו לב לפרקטיקת האבטחה החשובה: בסביבת פיתוח, נחזיר את הודעת השגיאה המקורית כדי להקל על ה-debugging. בסביבת prod, נחזיר הודעה גנרית כדי לא לחשוב פרטים פנימיים על המערכת שעלולים להיות מנוצלים לרעה.

הדלקת האורות ומה הלאה?

החלק האחרון בקוד של השרת אחראי על הפעלת השרת, אבל הוא מכיל פרט קטן וחכם שמעיד על חשיבה לטווח ארוך - הכנה לבדיקות אוטומטיות.

TypeScript

if (process.env[NODE_ENV] !== 'test') {
  app.listen(PORT, () => {
    console.log(`Server is running on http://localhost:${PORT}`);
  }
}
<div></div>
export default app;

if (process.env[NODE_ENV] !== 'test') {
  app.listen(PORT, () => {
    console.log(`Server is running on http://localhost:${PORT}`);
  }
}

export default app;

התנאי מונע מהשרת להתחיל ״להאזין״ על פורט HTTP כאשר אנחנו מריצים בדיקות. למה זה חשוב? כי בסביבת בדיקות (integration tests), אנחנו רוצים לייבא את אובייקט ה-app שלנו ולהריץ עליו בקשות באופן פרוגרמטי (למשל עם ספרייה כמו supertest), מבלי לפתוח פורט אמיתי שעלול להתנגש על תהליכים אחרים. השורה export default app מאפשר לנו לעשות בדיוק את זה.

סיכום התובנות:

בנינו שרת שהוא הרבה יותר מ-"Hello World״. בנינו בסיס חזק שכולל:

  • מבנה מודולרי המבוסס על Middleware.

  • אבטחה וביצועים מהרגע הראשון.

  • לוגינג וניטור בסיסיים.

  • מנגנון טיפול בשגיאות אמין וחסין

  • ארכיטקטורה שקל לבדוק אותה באופן אוטומטי.

הצעדים הבאים:

הבסיס הזה הוא נקודת זינוק מציונת. מכאן, הדרך הטבעית להמשיך היא להוסיף עוד ״קוביות לגו״. בפוסטים הבאים בסדרה נדבר על ה-unit testing שכתבתי לשרת הזה, ומבוא קצר ל node.js עם ניהול התלויות שלו.
וכמובן אני אעדכן את הסדרה הזאת ככל שאני מתקדם בפרויקט שלי ולומד עוד דברים.