API tình trạng phòng khách sạn: thiết kế cho nhà cung cấp chậm

Ticket thường trông rất vô hại. "Thêm tìm kiếm khách sạn vào trang đặt chỗ — nhà cung cấp đã đưa API tình trạng phòng khách sạn, có sandbox, chắc một sprint là xong." Bạn đọc tài liệu, gửi yêu cầu cho hai người lớn ở Đà Nẵng ba đêm, và phản hồi trả về. Rồi bạn gửi đúng yêu cầu đó cho một thành phố nhiều khách sạn hơn, và chẳng có gì trả về trong một khoảng thời gian dài đến khó chịu. Khi nó tới, đó là một khối dữ liệu đủ lớn để parser JSON của bạn phải suy ngẫm lại cuộc đời.
Đó là lúc bản chất công việc thay đổi. Tình trạng phòng khách sạn không phải một phép tra cứu. Nó là một fan-out: một câu hỏi từ người dùng trở thành nhiều câu hỏi gửi tới nhiều nhà cung cấp, mỗi bên trả lời với tốc độ riêng, bằng từ vựng riêng, với quan niệm riêng về thế nào là một "phòng". Client bạn xây phải vẫn hữu ích trong suốt lúc fan-out đó còn đang được giải quyết. Bài này nói về việc thiết kế client ấy — viết cho lập trình viên đã thạo REST và JSON nhưng chưa từng phải giải thích với khách sạn vì sao một giá không hoàn tiền của khách lại hiển thị là hủy miễn phí.
Vì sao API tình trạng phòng khách sạn chậm hơn những endpoint bạn quen dùng
Nhìn từ ngoài, tìm chuyến bay và tìm khách sạn giống nhau: một truy vấn đi ra, các lựa chọn có giá quay về. Bên dưới, chúng không phải cùng một bài toán. Nếu bạn đã đọc ghi chú của chúng tôi về những gì một tích hợp API đặt vé máy bay thực sự đòi hỏi, bạn biết giá lúc tìm không phải lúc nào cũng là giá lúc đặt. Khách sạn chồng thêm một khó khăn thứ hai: khối lượng.
Một thành phố có thể có hàng trăm cơ sở lưu trú. Mỗi cơ sở bán vài loại phòng. Mỗi loại phòng được bán theo vài rate plan — có bữa sáng, không bữa sáng, hoàn tiền, không hoàn tiền, giá thành viên, giá gói. Mỗi rate plan có thể đến từ hơn một nguồn: một bedbank, một channel manager, một hợp đồng trực tiếp, một nhà bán buôn bạn ký vì allotment của họ ở một khách sạn tốt hơn mọi người. Nhân tất cả lên và một lần tìm "đơn giản" là một cái cây lớn, ráp từ nhiều nguồn không thống nhất về tên lẫn ID.
Vậy phần chậm hiếm khi là code của bạn. Đó là nhà cung cấp chậm nhất mà bạn chọn chờ.
Kết quả lũy tiến hay câu trả lời đầy đủ: hãy chọn có chủ đích
Có hai cách trung thực để trả kết quả tìm khách sạn, và phần lớn tích hợp kết thúc ở một khoảng giữa không mấy vui vẻ.
Chờ tất cả. Backend tỏa yêu cầu, chờ mọi nhà cung cấp trả lời hoặc timeout, gộp, khử trùng lặp, sắp xếp, rồi trả về một danh sách hoàn chỉnh. Kết quả sạch sẽ: một yêu cầu, một phản hồi, giá so sánh được vì tất cả đã nằm trên bàn. Cái giá là người dùng nhìn chằm chằm vào spinner bằng đúng thời gian nhà cung cấp chậm nhất cần, lần nào cũng vậy.
Có gì gửi nấy. Backend khởi động fan-out và trả về ngay một search handle. Client poll handle đó, hoặc giữ một stream mở, và nhận kết quả theo từng đợt khi nhà cung cấp trả lời. Những khách sạn đầu tiên xuất hiện nhanh. Cái giá là sự phức tạp ở mọi chỗ khác: danh sách đổi thứ tự khi người dùng đang đọc, nhãn "rẻ nhất" có thể nhảy chỗ, và một khách sạn xuất hiện từ nhà cung cấp này về sau có thể nhận giá rẻ hơn từ nhà cung cấp khác.
Nếu giao diện của bạn là trang tìm kiếm trước mặt một con người, lũy tiến gần như luôn đúng — người đó đang dạo xem, không chạy batch job, và một trang thấy rõ đang làm việc tốt hơn một trang im lặng suy nghĩ. Nếu bên tiêu thụ là một cỗ máy khác — job so sánh giá, công cụ đặt chỗ doanh nghiệp cần một câu trả lời dứt khoát — thì chờ thường đơn giản hơn và đúng.
Dù chọn cách nào, ba quy tắc giữ cho client lũy tiến tỉnh táo:
- Mỗi đợt mang theo trạng thái hoàn tất của toàn bộ lần tìm, để client phân biệt "chưa có thêm kết quả" với "sẽ không bao giờ có thêm kết quả".
- Kết quả được gộp theo một khóa khách sạn ổn định ở server, không nối thêm vào cuối. Client không bao giờ phải tự suy ra hai thẻ là cùng một tòa nhà.
- Sắp xếp theo giá chỉ là tạm thời cho tới khi lần tìm hoàn tất, và giao diện nói rõ điều đó. Người dùng tha thứ cho một danh sách dần ổn định; họ không tha thứ cho nhãn "giá thấp nhất" hóa ra sai.
Mô hình hóa phòng và rate plan để chúng không sụp
Đây là nơi phần lớn tích hợp khách sạn thất bại trong im lặng, và thất bại lộ ra nhiều tháng sau dưới dạng ticket hỗ trợ chứ không phải báo cáo lỗi.
Mô hình hấp dẫn là mô hình phẳng: khách sạn có danh sách ưu đãi, mỗi ưu đãi có tên phòng và giá. Hiển thị rất đẹp. Rồi một nhà cung cấp trả về "Deluxe King" và "Deluxe Room, 1 King Bed" cho một phòng rõ ràng là một, nhà cung cấp khác trả cùng một tên cho hai phòng thật sự khác nhau (một có view thành phố, một không), và nhà thứ ba trả giá theo đêm trong khi mọi bên khác tính theo cả kỳ lưu trú. Danh sách phẳng không thể cho bạn biết mình đang nhìn trường hợp nào. Nó chỉ hiển thị chúng.
Một mô hình sống sót khi gặp nhà cung cấp thật có ít nhất bốn tầng, và giữ chúng tách biệt:
| Tầng | Chứa gì | Lỗi cần tránh |
|---|---|---|
| Khách sạn | ID ổn định của riêng bạn, ánh xạ tới mã của từng nhà cung cấp | Dùng ID khách sạn của nhà cung cấp làm khóa chính |
| Phòng | Sức chứa, cấu hình giường, mô tả phòng gốc của nhà cung cấp giữ nguyên văn | "Làm gọn" tên phòng tới mức hai phòng khác nhau nhập làm một |
| Rate plan | Board basis, khả năng hoàn tiền, hình thức thanh toán, nhà cung cấp gốc | Coi bữa sáng hay khả năng hoàn tiền là một phần tên phòng |
| Giá | Tổng cho cả kỳ lưu trú, tiền tệ, thuế phí đã gồm và phần trả tại khách sạn | Hiện giá theo đêm cạnh giá cả kỳ, hoặc giấu phí trả khi nhận phòng |
Bạn có thể không đồng ý với chỗ vạch ranh giới — một số đội tách sức chứa thành tầng riêng, điều đó hợp lý khi bạn bán đặt nhiều phòng. Điều bạn không được làm là gộp các tầng chỉ vì giao diện chỉ hiện hai trong số đó. Giao diện có thể làm phẳng lúc render. Dữ liệu thì không.
Một chi tiết đáng có câu riêng: hãy giữ mô tả phòng thô của nhà cung cấp bên cạnh bản đã chuẩn hóa. Khi khách đến và được giao một phòng khác với voucher, câu hỏi đầu tiên ai cũng đặt ra là nhà cung cấp thực sự đã gửi gì.
Chính sách hủy là dữ liệu, không phải một đoạn văn
Nhiều nhà cung cấp trả điều kiện hủy dưới dạng văn bản tự do: "Hủy miễn phí đến 3 ngày trước ngày đến, sau đó phạt 1 đêm." Rất dễ bị cám dỗ hiển thị nguyên chuỗi đó rồi làm việc khác.
Đừng. Văn bản không thể so sánh, sắp xếp, lọc hay thực thi. Người dùng muốn lọc giá hoàn tiền. Bộ phận tài chính muốn biết booking nào sẽ thành không hoàn tiền từ ngày mai để đại lý kịp liên hệ khách trước hạn. Luồng sau đặt chỗ phải nói với khách, ngay lúc họ bấm hủy, chính xác họ sẽ bị tính bao nhiêu. Không thứ nào chạy được trên một câu văn.
Hãy mô hình mỗi chính sách thành một danh sách có thứ tự các khung phạt: từ thời điểm này, đến thời điểm kia, mức phạt là số tiền này (hoặc tỷ lệ này của kỳ lưu trú, hoặc ngần này đêm). Các mốc là timestamp kèm múi giờ — múi giờ của khách sạn, không phải của server hay người dùng — vì "3 ngày trước ngày đến" là những thời điểm khác nhau tùy bạn tính nửa đêm của ai. Lưu văn bản gốc của nhà cung cấp cạnh bản có cấu trúc, hiển thị bản có cấu trúc, và coi sự lệch nhau giữa hai bản là thứ cần điều tra, không phải để giấu.
Và hãy kiểm tra lại chính sách lúc đặt, không chỉ lúc tìm. Chính sách thay đổi giữa hai lời gọi đó thường xuyên hơn bất kỳ ai nghĩ.
Làm sai thật sự tốn bao nhiêu
Tìm kiếm chậm làm bạn mất chuyển đổi — tệ, nhưng thấy được; sẽ có người phàn nàn. Những thất bại đắt giá là những thất bại lặng lẽ.
Một giá hiển thị là hoàn tiền nhưng nhà cung cấp coi là không hoàn tiền là một vụ tranh chấp với khách hàng đang cầm ảnh chụp màn hình, và thường thì chính đại lý phải trả khoản phạt. Giá theo đêm hiển thị như tổng cả kỳ sẽ bán phòng dưới giá vốn cho tới khi ai đó bên kế toán phát hiện. Một phòng bị gộp nhầm với phòng khác đưa gia đình bốn người vào phòng dành cho hai. Phí trả tại khách sạn chưa từng được hiển thị biến đánh giá năm sao thành chargeback. Mỗi cái đều là quyết định mô hình hóa đưa ra ở sprint đầu, thường dưới nhãn "để sau dọn".
Cache: cái gì được giữ, cái gì không
Mọi đội tích hợp API khách sạn rồi cũng hỏi có được cache kết quả để tìm nhanh và rẻ hơn không. Câu trả lời là có, cho một số thứ, và ranh giới giữa chúng quan trọng hơn bất kỳ con số hiệu năng nào.
Nội dung tĩnh — tên khách sạn, địa chỉ, tọa độ, ảnh, danh sách tiện nghi, mô tả phòng — hiếm khi đổi và chính là thứ bạn nên cache mạnh tay trong kho của mình. Kiểm tra điều khoản của nhà cung cấp về cách lưu và hiển thị; một số giấy phép có hạn chế. Lấy trực tiếp mỗi lần tìm là chậm mà chẳng được gì.
Giá và tình trạng phòng trực tiếp thì khác. Giá đã cache là một phỏng đoán về số tiền nhà cung cấp sẽ tính, và nhà cung cấp không tôn trọng phỏng đoán của bạn. Cache ngắn hạn kết quả tìm có thể chấp nhận được để hiển thị trang — miễn là mọi luồng đặt chỗ đều định giá lại với nhà cung cấp trước khi thu tiền, và giao diện coi giá thay đổi là kết quả bình thường chứ không phải lỗi. Một số nhà cung cấp còn giới hạn tỷ lệ tìm trên đặt; cache mạnh tay để giấu lưu lượng thật khỏi họ không phải kẽ hở đáng dựa vào.
Thứ không bao giờ được cache là bất cứ gì đại diện cho một cam kết: token giữ giá, mã đặt chỗ, báo giá hủy. Chúng thuộc về một người dùng và một thời điểm.
Trước khi bạn gọi là xong
Một bước kiểm tra ngắn, đáng chạy trên tích hợp của bạn trước khi nó gánh booking thật:
- Lần tìm trả về trạng thái hoàn tất, và client hành xử khác nhau trước và sau đó.
- Khách sạn được khóa bằng ID của riêng bạn, với mã từng nhà cung cấp ánh xạ vào.
- Phòng, rate plan và giá là các đối tượng tách riêng trong dữ liệu, bất kể màn hình hiện gì.
- Mỗi giá nói rõ là theo đêm hay cả kỳ, và phần nào trả khi đến.
- Chính sách hủy được lưu dưới dạng các khung phạt theo thời gian ở múi giờ khách sạn, giữ cả văn bản gốc.
- Luồng đặt chỗ định giá lại và đọc lại chính sách trước khi thu tiền bất kỳ ai.
- Không thứ gì đại diện cho cam kết từng được phục vụ từ cache.
Nếu bạn đang cân nhắc giữa việc tự xây tất cả với từng nhà cung cấp hay bắt đầu từ một nền tảng đã gặp những vấn đề này, phần hợp đồng quan trọng ngang phần code — bài viết của chúng tôi về hợp đồng hotel consolidator và giá bedbank nói nên đòi hỏi những gì. API vé máy bay và khách sạn của chúng tôi được mở qua trao đổi, không phải bằng khóa tự phục vụ; nếu đó là con đường bạn muốn tìm hiểu, hãy bắt đầu trao đổi trên trang travel APIs.
Fan-out không bao giờ biến mất. Một client tốt chỉ đơn giản là thôi giả vờ rằng nó không có ở đó.