כדי להציג זמינות אופניים בזמן אמת באפליקציה, חבר את הכמות שהוחזרה לרעננות שלה ולאפשרויות לקיחת הרכב. תצפית מתארת מה שהמקור ידע ברגע מסוים; זה אינו מבטיח שאופניים יישארו זמינים בהגעה.
חוזה התנועה ROOTE מבדיל בין תחנות, רכבים בודדים והמצבים שלהם. הממשק צריך לתרגם הבדלים אלה מבלי לבלבל ערך לא ידוע, תחנה ריקה או מקור שאינו זמין זמנית.
להפריד בין תחנה לרכב בודד
תחנה יכולה לחשוף מונים של אופניים ומקומות החזרה. רכב בודד יש מצב זמינות ומידע נוסף אפשרי. הימנע לספור תחנה כאופניים או לחבר מונים המייצגים את אותו המלאי.
ב-DTO התנועה של ROOTE, availability.bikes ו-availability.docks יכולים להיות לא ידועים. שדות הנעה או סוללה יופיעו רק אם קיימים ומפורשים בהתאם לחוזה.
קרא רעננות וחותמות זמן
| שדה | פירוש |
|---|---|
| freshness.state | מצב מודיע: fresh, stale, unknown או static |
| freshness.source_updated_at | תאריך עדכון המקור, אם ידוע |
| freshness.received_at | תאריך קבלה שמוצהר בחוזה |
| freshness.expires_at | תאריך תפוגה או תוקף, אם ידוע |
| availability.bikes | כמות ידועה או ערך לא ידוע |
| pickup.enabled ו-pickup.state | מידע על לקיחת אופניים בתחנה |
שעת הקריאה שלך אינה בהכרח שעת התצפית. תוצאה שהתקבלה בשעה 10:00 יכולה להכיל מקור שנעדכן בשעה 09:45. אל תציג "עודכן עכשיו" רק לפי זמן הקבלה של הממשק שלך.
תכנון מצבי הצגה נפרדים
| נתונים שהתקבלו | תצוגה צפויה |
|---|---|
| כמות ידועה ונתונים טריים | כמות שנצפתה והצגת זמן |
| כמות שווה לאפס | אופניים לא נצפו, עם ההקשר הזמני |
| כמות null | זמינות לא ידועה |
| מצב stale או עבר מועד התפוגה | נתונים ישנים; הצע עדכון |
| pickup.enabled=false | לקיחה אינה זמינה אפילו אם המונה חיובי |
| שגיאת חיפוש | זמינות זמנית לא זמינה, מבלי להמיר לאפס |
אל תסווג מצב unknown או static כטרי. מידע על תחנה יכול להיות יציב בעוד המונה משתנה במהירות. שמור גם על אזהרות והקצאות הנדרשות בתשובה.
דוגמה לנירמול לפני הרינדור
הפונקציה הבאה מייצרת מצב תצוגה מתחנה שכבר אומתה מול סכימת ROOTE. היא אינה מאמתת תגובה באופן מלא. התוויות הנראות צריכות להגיע ממפתחות התרגום בממשק שלך.
function availabilityView(station, now = Date.now()) {
const freshness = station.freshness;
const expiresAt = freshness.expires_at
? Date.parse(freshness.expires_at) : null;
const expired = expiresAt !== null &&
Number.isFinite(expiresAt) && expiresAt <= now;
if (station.pickup.enabled === false ||
station.pickup.state === 'unavailable_now') {
return { state: 'pickup_unavailable', count: null };
}
if (expired || freshness.state === 'stale') {
return { state: 'stale', count: null };
}
const count = station.availability.bikes;
if (freshness.state !== 'fresh' || count === null ||
!Number.isFinite(count) || count < 0) {
return { state: 'unknown', count: null };
}
return {
state: count === 0 ? 'empty' : 'observed', count,
sourceUpdatedAt: freshness.source_updated_at,
receivedAt: freshness.received_at,
pickupState: station.pickup.state
};
}גם עם מצב observed, אל תהפוך pickupState=unknown לאישור לקיחה. המונה נשאר תצפית. הצג את ההקשר של הלקיחה אם המוצר שלך מסייע למשתמש לבחור תחנה.
רענון מבלי להכפיל קריאות מיותרות
התאם את הרענון לתוקף שפורסם, לתנאי השירות ולהתנהגות המשתמש. ארגן בקשות זהות, הימנע מקריאות ברקע בדף לא פעיל ובטל חיפושים מוחלפים.
זמן אחסון מקומי אינו מוכיח את טריות המקור. אחרי שגיאה, אפשר לשמור תצפית אחרונה עם תאריך אם הממשק מציג אותה במפורש כישנה. אל תבטל הבחנה זו בהצלחה ראשונה אם המקור נשאר stale.
הבנת הקשר עם GBFS
GBFS מתאר את שירותי השיתוף והמצבים שפורסמו. אינטגרציה ישירה צריכה לפרש קבצים, גרסה וחותמות זמן של הזרם. עם API מנורמל, השתמש בחוזה ה-API; אל תוסיף שדה GBFS שמניחים חסר בתגובתו.
בחירה בין GTFS, GTFS Realtime ו-GBFS
בדיקת מצבים שמטעות את הקורא
בדוק אפס אמיתי, ערך לא ידוע, תפוגת תוקף, לקיחה מושבתת ושגיאה אחרי תוצאה תקינה. וודא גם אזורי זמן להצגה. מונה חיובי לא יפיק 'אופניים שמורים' וזמינות לא תפיק אפס מזויף.
שאלות נפוצות
כמות חיובית מבטיחה אופניים בהגעתי?
לא. היא מתארת תצפית שיכולה להשתנות בין החיפוש להגעתך.
האם ניתן להחליף null באפס?
לא. null מציין ערך לא ידוע; אפס הוא כמות ידועה ומשמעותה שונה.
האם יש לרענן כל כמה שניות?
השתמש בהוראות התוקף, מגבלות השירות וצורכי הממשק. תדירות שרירותית אינה מבטיחה מקור טרי יותר.