בירור | קובץ הוראות לצורת עבודה נכונה בjs
-
לאור המסקנות מהשרשור הקודם, בקשתי מAI שינסח לי כללים לעבודה נכונה + הוראות לAI.
מאחר ואני לא סומך על AI כזה או אחר הייתי שמח אם מישהו יוכל לעבור על זה לראות שכל תקין ונכון, וכמובן אם יש הערות.
מעולה.
הנה ערכת כללים מותאמת במיוחד לפרויקט שלך (Node.js + MySQL + API + מערכת טלפונית).
לא דוגמטית, לא בירוקרטית — אבל מקצועית, נקייה ובטוחה.
ערכת כללים לפרויקט API (Node + MySQL)
1️⃣ ארכיטקטורה (חובה)
שכבות קבועות
Route → Controller → Service → Repository → DB
אסור:- SQL בתוך Controller
- לוגיקה עסקית בתוך Route
- בדיקות ולידציה בתוך Repository
אחריות כל שכבה
Route
- ניתוב בלבד
- חיבור middleware
Controller
- request / response
- קודי סטטוס
- העברת נתונים ל-Service
Service
- כל הלוגיקה העסקית
- בדיקות תנאים
- חוקים מורכבים
- שילוב כמה repositories
Repository
- שאילתות בלבד
- אין if עסקי
- אין החלטות
2️⃣ ולידציה (קריטי)
כלל ברזל:
כל קלט חיצוני עובר ולידציה לפני שהוא מגיע ל-Service.
חובה:
- שימוש בסכמה (Zod / Joi)
- בדיקה של ערכים ריקים
- בדיקת טיפוסים
- בדיקת טווחים
- בדיקת פורמט (טלפון, זמן וכו')
אסור:- לבדוק טיפוס בתוך Service
- לסמוך על הלקוח
3️⃣ עבודה עם SQL
חובה:
Prepared Statements בלבד
שימוש ב־? placeholders
אין שרשור מחרוזות ל-SQL
אין הכנסת ערכים ישירות ל-ORDER BY אסור:const sql = "SELECT * FROM ads WHERE phone = " + phone;
כלל חשוב נוסף
אם שאילתה חוזרת על עצמה ביותר ממקום אחד →
להוציא אותה ל-Repository פונקציה ייעודית.
4️⃣ שגיאות (Error Handling)
סוגי שגיאות
Business Error
- משתמש חרג ממגבלה
- ערך לא חוקי לפי כללי מערכת
- פעולה כפולה
→ מחזירים 400 עם הודעה ברורה
System Error
- DB לא עונה
- קריסה לא צפויה
- בעיית קישוריות
→ לוג ERROR
→ מחזירים 500 כללי
כלל ברזל:
לא לבלוע שגיאות.
אסור:
catch (e) {}
5️⃣ לוגים
רמות:
- INFO → אירועים עסקיים תקינים
- WARN → חריגה לא קריטית
- ERROR → תקלה מערכתית
אסור:
- console.log בפרודקשן
- לוגים מפוצצים בלי צורך
6️⃣ מבנה פונקציות
כללים פשוטים:
פונקציה עושה דבר אחד
שם מסביר למה היא קיימת
עדיף פחות מ-30 שורות
יותר מ-3 פרמטרים? שקול להעביר אובייקט
7️⃣ שמות
אסור:
- data
- temp
- info
- manager
- handler
כן:
- createAdIfAllowed
- validateRingModeForPublisher
- findAdsByPhone
שם צריך להסביר כוונה.
8️⃣ Hard Coding
אסור:
- ערכי DB בקוד
- URL בקוד
- מפתחות API בקוד
- מספרי קסם (magic numbers)
כן:
- משתני סביבה
- קובץ config מרכזי
9️⃣ בדיקות (בצורה ריאלית)
לא צריך 3 רמות לכל פונקציה.
כן צריך:
בדיקות לפונקציות לוגיקה מורכבות
בדיקות למקרים חריגים
בדיקה לפחות ל-happy path
ביצועים וניקיון לא לבצע שאילתות מיותרות
לא לטעון הכל לזיכרון אם לא צריך
לא לבצע לולאות על תוצאות DB בלי סיבה
להשתמש ב-LIMIT כשאפשר
1️⃣1️⃣ אבטחה (קריטי למערכת טלפונית)
כל קלט מסונן
אין echo של שגיאת DB
אין חשיפת stack trace
Rate limit ל-API אם רלוונטי
לא לסמוך על client-side validation
1️⃣2️⃣ עקרון הזהב
אם אתה שואל את עצמך:
"איפה לשים את הקוד הזה?"
שאל:
- האם זו החלטה עסקית? → Service
- האם זו שאילתת DB? → Repository
- האם זו בדיקת קלט? → Validator
- האם זו תגובת HTTP? → Controller
גרסה מקוצרת במיוחד (לשים מול העיניים)- אין SQL מחוץ ל-Repository
- אין לוגיקה מחוץ ל-Service
- אין קלט בלי ולידציה
- אין שרשור SQL
- אין בליעת שגיאות
- אין Hard Coding
- פונקציות ברורות וקצרות
- לוגים ברמות נכונות
או באנגליתAI_RULES.md
תודה
-
בגדול נכון
את ההפרדה בין Controller ל-Service ולRepository לא תמיד עושים, זה יותר נפוץ בפרויקטים גדולים
לשאילתות תשתמש בספריה מוכנה של query builder, לדוגמה https://github.com/knex/knex, ולפרויקט עתידי כדאי לשקול ORM -
בגדול נכון
את ההפרדה בין Controller ל-Service ולRepository לא תמיד עושים, זה יותר נפוץ בפרויקטים גדולים
לשאילתות תשתמש בספריה מוכנה של query builder, לדוגמה https://github.com/knex/knex, ולפרויקט עתידי כדאי לשקול ORM@צדיק-תמים את ההפרדה בין Controller ל-Service ולRepository לא תמיד עושים, זה יותר נפוץ בפרויקטים גדולים
לא מדוייק
זה סגנון עבודה שתמיד כדאי לעשות
להתחיל בצורה מסודרת מאפשר לך להחליף חלקים בצורה קלה בלי לפגוע במבנה כלל
או בדוגמה בפייתון
להחליף בין fastAPI לפלאסק לכל מנגנון אחר בלי להשפיע על כל המערכת
לשנות לוגיקה בלי לגעת בראוטים או בDB
להחליף DB בלי לשנות לוגיקה של התוכנה
וכן הלאהבמיוחד שעובדים עם AI אים שום סיבה לא לנהל את הפרוייקט בצורה מלאה ותקינה לא משנה מה גודל הפרוייקט
-
@צדיק-תמים את ההפרדה בין Controller ל-Service ולRepository לא תמיד עושים, זה יותר נפוץ בפרויקטים גדולים
לא מדוייק
זה סגנון עבודה שתמיד כדאי לעשות
להתחיל בצורה מסודרת מאפשר לך להחליף חלקים בצורה קלה בלי לפגוע במבנה כלל
או בדוגמה בפייתון
להחליף בין fastAPI לפלאסק לכל מנגנון אחר בלי להשפיע על כל המערכת
לשנות לוגיקה בלי לגעת בראוטים או בDB
להחליף DB בלי לשנות לוגיקה של התוכנה
וכן הלאהבמיוחד שעובדים עם AI אים שום סיבה לא לנהל את הפרוייקט בצורה מלאה ותקינה לא משנה מה גודל הפרוייקט
@A0533057932 להחליף פריימוורק זה לא בשכבת ה Service או ה Repository
להחליף DB זה לא צורך נפוץ, בפרויקט קטן זה לא שווה את המורכבות של לעטוף הכל במעין ORM במימוש עצמי
להפריד לסרוויס כן יותר נפוץ, אבל להפריד ריפוזיטורי זה שימושי בעיקר אם אתה עושה טסטים מלאים עם DI אחרת זה סתם שכבה מיותרת שמפריעה להבנה של הקוד -
בגדול נכון
את ההפרדה בין Controller ל-Service ולRepository לא תמיד עושים, זה יותר נפוץ בפרויקטים גדולים
לשאילתות תשתמש בספריה מוכנה של query builder, לדוגמה https://github.com/knex/knex, ולפרויקט עתידי כדאי לשקול ORM@צדיק-תמים כתב בבירור | קובץ הוראות לצורת עבודה נכונה בjs:
ולפרויקט עתידי כדאי לשקול ORM
מה זה?
בגדול לא אמור להיות, אבל בכל זאת...
 { const baseUrl = "https://www.google.co.il/search?q=site:mitmachim.top"; const m = location.pathname.match(/^\/(topic|category)\/(\d+)/); const type = m ? m[1] : null; const id = m ? m[2] : null; let searchInput; function search(path = "") { const query = searchInput.value.trim(); if (query) { window.open(`${baseUrl}${path}%20${encodeURIComponent(query)}`, "_blank"); } } let buttons = {}; buttons.searchAll = { id: "bb-search-all", label: `חיפוש ${type ? "בכל הפורום" : ""}`, className: type ? "btn-secondary" : "btn-primary", callback: () => search(), }; if (type === "topic") { buttons.searchTopic = { label: "חיפוש בנושא זה", className: "btn-primary", callback: () => search(`/topic/${id}`), }; } else if (type === "category") { buttons.searchCategory = { label: "חיפוש בקטגוריה זו", className: "btn-primary", callback: () => search(`/category/${id}`), }; } buttons.cancel = { label: "ביטול", className: "btn-default", "data-bs-dismiss": "modal" }; const dialog = bootbox.dialog({ title: '<div style="text-align:center;"><img src="/assets/uploads/files/1625950269825-mt-google.png" width="400" alt="חיפוש בגוגל"></div>', message: '<input id="bb-inp" class="bootbox-input bootbox-input-text form-control" placeholder="הקלידו כדי לחפש בגוגל" autocomplete="off"/>', buttons, backdrop: true, show: true, onEscape: true }); dialog.on("shown.bs.modal", function () { searchInput = document.getElementById("bb-inp"); if (searchInput) { searchInput.focus(); searchInput.addEventListener("keydown", function (e) { if (e.key === "Enter") { e.preventDefault(); const query = this.value.trim(); if (query) { search(); dialog.modal("hide"); } } else if (e.key === "Escape") { e.preventDefault(); dialog.modal("hide"); } }); } const searchAllButton = document.getElementById("bb-search-all"); if (searchAllButton) { searchAllButton.title = "לחצו על אנטר כדי לחפש"; } }); })(); void 0;){kind=link}