Để hiển thị tình trạng xe đạp thời gian thực trong một ứng dụng, hãy kết hợp số lượng trả về với độ tươi mới và khả năng lấy xe. Một quan sát mô tả những gì nguồn biết vào một thời điểm; nó không đảm bảo rằng một chiếc xe đạp sẽ còn ở đó khi bạn đến nơi.
Hợp đồng di chuyển ROOTE phân biệt giữa các trạm, từng chiếc xe riêng lẻ và trạng thái của chúng. Giao diện phải thể hiện sự khác biệt này mà không nhầm lẫn giá trị chưa biết, trạm trống và nguồn tạm thời không khả dụng.
Phân biệt trạm và chiếc xe riêng lẻ
Một trạm có thể xuất ra các bộ đếm xe đạp và số chỗ trả xe. Một chiếc xe riêng có trạng thái khả dụng và các thông tin khác nếu có. Tránh đếm một trạm như một xe đạp hoặc cộng các bộ đếm đại diện cho cùng một số lượng tồn kho.
Trong DTO di chuyển ROOTE, availability.bikes và availability.docks có thể là giá trị chưa biết. Các trường về hệ thống động cơ hoặc pin chỉ được hiển thị nếu chúng tồn tại và được hiểu theo hợp đồng.
Đọc độ tươi mới và thời gian đánh dấu
| Trường | Giải thích |
|---|---|
| freshness.state | Trạng thái thông báo: fresh (mới), stale (cũ), unknown (chưa biết) hoặc static (tĩnh) |
| freshness.source_updated_at | Ngày cập nhật nguồn, nếu biết |
| freshness.received_at | Ngày nhận được theo hợp đồng |
| freshness.expires_at | Hạn sử dụng được chỉ định, nếu biết |
| availability.bikes | Số lượng biết hoặc giá trị chưa biết |
| pickup.enabled và pickup.state | Thông tin về việc lấy xe đạp tại trạm |
Thời gian gọi của bạn không tự động trùng với thời điểm quan sát. Kết quả nhận lúc 10 giờ có thể chứa nguồn cập nhật lúc 9 giờ 45 phút. Không hiển thị “cập nhật ngay bây giờ” chỉ dựa trên thời gian nhận của giao diện bạn.
Dự kiến trạng thái hiển thị riêng biệt
| Dữ liệu nhận được | Hiển thị cần dự kiến |
|---|---|
| Số lượng biết và dữ liệu mới | Số lượng quan sát được và chỉ dẫn về thời gian |
| Số lượng bằng không | Không có xe đạp quan sát được, kèm bối cảnh thời gian |
| Số lượng null | Khả năng có xe đạp chưa biết |
| Trạng thái stale hoặc quá hạn | Dữ liệu cũ; đề nghị làm mới |
| pickup.enabled=false | Lấy xe không khả dụng dù bộ đếm vẫn có giá trị dương |
| Lỗi truy vấn | Tình trạng không khả dụng tạm thời, không chuyển thành số 0 |
Không phân loại trạng thái unknown hoặc static là mới. Thông tin trạm có thể ổn định trong khi bộ đếm thay đổi nhanh. Cũng giữ lại cảnh báo và các chỉ dẫn bắt buộc trong phản hồi.
Ví dụ chuẩn hóa trước khi hiển thị
Hàm sau đây tạo ra trạng thái trình bày từ một trạm đã được xác nhận theo sơ đồ ROOTE. Nó không phải bộ kiểm tra phản hồi đầy đủ. Các nhãn hiển thị phải lấy từ các khóa dịch thuật trong giao diện của bạn.
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
};
}Ngay cả khi trạng thái là observed (quan sát), đừng biến pickupState=unknown thành lấy xe đã xác nhận. Bộ đếm vẫn chỉ là một quan sát. Hiển thị bối cảnh lấy xe nếu sản phẩm của bạn giúp người dùng chọn trạm.
Làm mới mà không gây thừa gọi API
Điều chỉnh làm mới theo hạn hết hạn đã công bố, điều kiện dịch vụ và hành vi người dùng. Gom nhóm các yêu cầu giống nhau, tránh gọi ngầm khi trang không hoạt động và hủy các yêu cầu tìm kiếm bị thay thế.
Độ trễ cache cục bộ không chứng minh được độ tươi mới của nguồn. Sau lỗi, bạn có thể giữ lại quan sát cuối cùng có đánh dấu thời gian nếu giao diện trình bày rõ ràng đó là dữ liệu cũ. Đừng xóa sự khác biệt này ngay khi có lần truy cập thành công đầu tiên nếu nguồn vẫn stale.
Hiểu mối liên hệ với GBFS
GBFS mô tả dịch vụ di chuyển chia sẻ và các trạng thái của chúng được công bố. Việc tích hợp trực tiếp phải hiểu tệp, phiên bản và thời gian đánh dấu của luồng. Với API chuẩn hóa, hãy dùng hợp đồng API; không thêm trường GBFS không có trong phản hồi của nó.
Chọn giữa GTFS, GTFS Realtime và GBFS
Kiểm thử các trường hợp gây nhầm lẫn cho người đọc
Kiểm thử số 0 thực, giá trị chưa biết, quá hạn, lấy không kích hoạt và lỗi sau kết quả hợp lệ. Cũng kiểm tra múi giờ hiển thị. Bộ đếm dương không bao giờ hiển thị “xe đã được đặt” và tình trạng không khả dụng không bao giờ chuyển thành số 0 sai lệch.
Áp dụng các quy tắc này trong trợ lý AI
Hướng dẫn người dùng tìm xe đạp
Câu hỏi thường gặp
Số lượng dương có đảm bảo có xe khi tôi đến không?
Không. Nó chỉ mô tả một quan sát, có thể thay đổi giữa lúc tìm kiếm và khi bạn đến.
Có thể thay null bằng số 0 không?
Không. null biểu thị giá trị chưa biết; số 0 là số lượng biết và mang ý nghĩa khác.
Có cần làm mới mỗi vài giây không?
Hãy dùng chỉ dẫn về tính hiệu lực, giới hạn dịch vụ và nhu cầu giao diện của bạn. Tần suất tự ý không đảm bảo nguồn tươi hơn.