Για να εμφανίσετε τη διαθεσιμότητα ποδηλάτων σε πραγματικό χρόνο σε μια εφαρμογή, συσχετίστε τον αριθμό που επιστρέφεται με τη φρεσκάδα του και τις πιθανότητες παραλαβής του οχήματος. Μια παρατήρηση περιγράφει όσα γνώριζε η πηγή σε μια δεδομένη στιγμή· δεν εγγυάται ότι ένα ποδήλατο θα είναι ακόμη διαθέσιμο στην άφιξη.
Το συμβόλαιο κινητικότητας 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 μπορεί να περιέχει πηγή ενημερωμένη στις 9: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 σε επιβεβαιωμένη παραλαβή. Ο μετρητής παραμένει παρατήρηση. Εμφανίστε το πλαίσιο παραλαβής αν το προϊόν σας βοηθά τον χρήστη να επιλέξει σταθμό.
Ανανέωση χωρίς περιττή πολλαπλή κλήση
Προσαρμόστε την ανανέωση στην ανακοινωμένη λήξη, στις συνθήκες της υπηρεσίας και στη συμπεριφορά του χρήστη. Ομαδοποιήστε όμοια αιτήματα, αποφύγετε κλήσεις στο παρασκήνιο σε ανενεργή σελίδα και ακυρώστε αυτές μιας αντικατασταθείσας αναζήτησης.
Μια τοπική καθυστέρηση cache δεν αποδεικνύει τη φρεσκάδα της πηγής. Μετά από σφάλμα, μπορείτε να διατηρήσετε την τελευταία παρατήρηση με ημερομηνία αν η διεπαφή σας τη παρουσιάζει ρητά ως παλιά. Μην αφαιρείτε αυτή τη διάκριση στην πρώτη επιτυχημένη ανάκτηση αν η πηγή παραμένει stale.
Κατανόηση της σχέσης με GBFS
Το GBFS περιγράφει τις υπηρεσίες κοινής χρήσης κινητικότητας και τις δημοσιευμένες καταστάσεις τους. Μια απευθείας ενσωμάτωση πρέπει να ερμηνεύει τα αρχεία, την έκδοση και τα χρονικά σημεία ροής. Με ένα τυποποιημένο API, χρησιμοποιήστε το συμβόλαιο API· μην προσθέτετε πεδίο GBFS που υποτίθεται λείπει από την απόκρισή του.
Επιλογή ανάμεσα σε GTFS, GTFS Realtime και GBFS
Δοκιμή καταστάσεων που παραπλανούν τον χρήστη
Δοκιμάστε αληθινό μηδέν, άγνωστη τιμή, υπερωριακή λήξη, απενεργοποιημένη παραλαβή και σφάλμα μετά από έγκυρο αποτέλεσμα. Ελέγξτε επίσης τις ζώνες ώρας εμφάνισης. Θετικός μετρητής δεν πρέπει ποτέ να παράγει «ποδήλατο κρατημένο» και μη διαθεσιμότητα δεν πρέπει ποτέ να παράγει επινοημένο μηδέν.
Διαχείριση κενών απαντήσεων και σφαλμάτων
Εφαρμογή αυτών των κανόνων με βοήθεια ΤΝ
Οδηγός χρήστη για εύρεση ποδηλάτου
Συχνές ερωτήσεις
Εξασφαλίζει η θετική ποσότητα ένα ποδήλατο κατά την άφιξή μου;
Όχι. Περιγράφει μια παρατήρηση, που μπορεί να αλλάξει μεταξύ της αναζήτησης και της άφιξής σας.
Μπορεί το null να αντικατασταθεί με μηδέν;
Όχι. Το null δείχνει άγνωστη τιμή· το μηδέν είναι γνωστή ποσότητα και έχει διαφορετική σημασία.
Πρέπει να ανανεώνω κάθε λίγα δευτερόλεπτα;
Χρησιμοποιήστε τις ενδείξεις εγκυρότητας, τους περιορισμούς υπηρεσίας και τις ανάγκες της διεπαφής σας. Μια τυχαία συχνότητα δεν εγγυάται πιο φρέσκια πηγή.