跳到主要内容
博客

酒店房态API:为慢供应商而设计的客户端

Tekravel 编辑部
借助 AI 撰写

需求单通常看起来人畜无害:“在预订页加上酒店搜索——供应商给了我们一个酒店房态API,有沙箱环境,一个迭代就能搞定。”你读完文档,发了一个上海两位成人、入住三晚的请求,响应很快回来了。接着你对一个酒店数量多得多的城市发同样的请求,结果很长一段时间什么都没有,久到让人尴尬。等它终于回来,是一份大到足以让你的JSON解析器怀疑人生的文档。

工作的性质就在这一刻变了。酒店房态查询不是一次简单的读取,而是一次fan-out:用户的一个问题,变成发给许多供应商的许多问题,每家按自己的速度、用自己的术语、带着自己对“房间”的理解来回答。你写的客户端,必须在这次扇出尚未结束时依然有用。本文讲的就是如何设计这样的客户端,写给熟悉REST和JSON、却从未需要向酒店解释“为什么不可退的价格被显示成了免费取消”的开发者。

为什么酒店房态API比你熟悉的接口慢

从外面看,机票搜索和酒店搜索很像:一个查询发出去,带价格的选项返回来。可内部并不是同一个问题。如果你读过我们关于机票预订API对接到底涉及什么的文章,就已经知道搜索时的价格不一定是预订时的价格。酒店在此之上又加了第二个难题:量。

一座城市可能有数百家酒店。每家酒店卖好几种房型。每种房型又挂着多个价格计划——含早或不含早、可退或不可退、会员价、打包价。每个价格计划还可能来自不止一家供应商:bedbank、渠道管理系统、直签合同,或者某家批发商——你和它签约,只因为它在某家酒店的allotment比别人都好。把这些乘起来,一次“简单”的搜索就是一棵很大的树,由几家在名称和ID上都对不上的数据源拼接而成。

所以慢的部分很少是你的代码,而是你选择去等待的那家最慢的供应商。

渐进式结果还是完整答案:要有意识地选择

返回酒店搜索结果有两种诚实的做法,而大多数对接最后都卡在两者之间一个别扭的位置。

等所有人。后端把请求分发出去,等每家供应商应答或超时,然后合并、去重、排序,返回一份完整列表。结果很干净:一次请求,一次响应,价格可以横向比较,因为全都摆在桌面上。代价是:用户每一次都要盯着加载动画,盯多久取决于你最慢的那家供应商。

来多少推多少。后端启动分发后立即返回一个搜索句柄。客户端轮询这个句柄,或者保持一条流式连接,随着供应商陆续应答分批接收结果。第一批酒店很快就出现。代价是其他所有地方的复杂度:用户正在看的列表会重新排序,“最低价”标签可能挪位置,一家从某个供应商来的酒店,稍后可能从另一家拿到更便宜的价格。

如果你的界面是摆在真人面前的搜索页,渐进式几乎总是对的——人在浏览,不是在跑批处理,一个看得见在干活的页面,胜过一个默默思考的页面。如果消费方是另一台机器——比价任务,或需要一个确定答案的企业差旅预订工具——等全部结果往往更简单,也更正确。

无论选哪种,三条规则能让渐进式客户端保持清醒:

  • 每一批结果都带上整个搜索的完成状态,让客户端分得清“暂时没有更多结果”和“不会再有结果了”。
  • 结果在服务端按稳定的酒店键合并,而不是简单追加。客户端永远不该自己去推断两张卡片是同一栋楼。
  • 按价格排序在搜索完成前只是临时的,界面要明说。用户能原谅一个逐渐稳定下来的列表,却不会原谅一个最后被证明是错的“最低价”标签。

房型与价格计划的建模:别让它塌掉

大多数酒店对接就是在这里悄无声息地失败的,而失败往往在几个月后以客服工单而不是缺陷报告的形式出现。

诱人的模型是扁平的:酒店有一个报价列表,每个报价有房型名和价格。渲染出来很好看。然后一家供应商对明显是同一间房返回了“Deluxe King”和“Deluxe Room, 1 King Bed”,另一家对两间确实不同的房(一间看城景,一间没有)用了同一个名字,第三家返回的是每晚价,而其他所有家给的都是整段入住的总价。扁平列表没法告诉你眼前是哪一种情况,它只会把它们都显示出来。

能经得起真实供应商考验的模型至少有四层,而且层与层分开:

层级保存什么要避免的错误
酒店你自己的稳定ID,映射到每家供应商的编码把某家供应商的酒店ID当作主键
房型入住人数、床型配置,以及供应商原始房型描述原样保留“清洗”房型名称,直到两间不同的房被合成一间
价格计划餐食类型、是否可退、付款方式、来源供应商把早餐或可退性当成房型名称的一部分
价格整段入住总价、币种、包含哪些税费、哪些需到店支付把每晚价和总价并排显示,或隐藏到店支付的费用

你可以不同意这些边界划在哪里——有的团队把入住人数单独拆成一层,一旦你卖多间房的订单,这很合理。不能做的是因为界面只展示两层,就把层级合并。界面可以在渲染时拍平,数据不行。

有个细节值得单独说一句:无论你做了什么标准化,都要把供应商原始的房型描述一起存下来。客人到店后拿到的房间和确认单上的不一样时,所有人问的第一个问题都是:供应商当时到底发了什么?

取消政策是数据,不是一段文字

很多供应商以自由文本返回取消条款:“入住前3天可免费取消,之后收取1晚罚金。”最省事的做法是把这串文字直接显示出来,然后继续往下做。

别这么做。文本无法比较、排序、筛选,也无法执行。用户想筛出可退的价格;财务想知道哪些订单明天会变成不可退,好让旅行社在截止前联系客户;售后流程需要在客户点“取消”的那一刻准确告诉对方会被扣多少钱。这些在一句话上都做不到。

把每条政策建模为一组有序的罚金窗口:从某个时刻到某个时刻,罚金是这个金额(或入住费用的某个比例,或若干晚)。边界是带时区的时间戳——用酒店的时区,而不是你服务器的,也不是用户的——因为“入住前3天”按谁的午夜来算,指的是不同的时刻。把供应商原文和结构化版本放在一起保存,展示结构化版本,两者不一致时把它当作需要排查的问题,而不是需要掩盖的东西。

而且要在预订时再核对一次政策,不能只在搜索时看。两次调用之间政策变化的频率,比任何人预想的都高。

做错的真实代价

搜索慢会损失转化,这很糟,但看得见——总会有人抱怨。真正昂贵的是那些无声的失败。

显示为可退、供应商却按不可退处理的价格,意味着和一位手里握着截图的客户起争执,罚金通常由旅行社自己掏。把每晚价当成总价显示,会一直亏本卖房,直到财务有人发现。被合并到另一间房的房型,会把一家四口送进双人间。到店才支付、却从未展示过的费用,会把五星好评变成拒付。每一种都是第一个迭代里做出的建模决定,通常挂着“以后再清理”的标签。

缓存:哪些能存,哪些绝不能存

每个对接酒店API的团队,迟早都会问能不能缓存结果,让搜索更快、更省钱。答案是:有些可以,而两者之间的界线比任何性能数字都重要。

静态内容——酒店名称、地址、坐标、图片、设施列表、房型描述——很少变化,正应该积极地缓存在你自己的存储里。先查看供应商关于存储和展示方式的条款,有些授权会对此设限。每次搜索都实时拉取,只会变慢,毫无好处。

实时价格和房态则是另一回事。缓存的价格只是对供应商要价的猜测,而供应商不会认你的猜测。为了展示页面,对搜索结果做短时缓存可以接受——前提是每条预订路径在收款前都向供应商重新询价,并且界面把价格变化当作正常结果,而不是错误。有些供应商还会限制搜索与预订的比例;用激进缓存把真实流量藏起来,并不是一个靠得住的漏洞。

绝对不能缓存的是任何代表承诺的东西:被锁定的价格令牌、预订编号、取消报价。它们只属于某一个用户、某一个时刻。

宣布完成之前

在你的对接承载真实订单之前,值得逐条过一遍的简短清单:

  • 搜索返回完成状态,客户端在完成前后的行为不同。
  • 酒店以你自己的ID为键,每家供应商的编码都映射到它。
  • 不管屏幕上显示什么,房型、价格计划和价格在数据里是三个独立对象。
  • 每个价格都标明是每晚价还是总价,以及哪些需到店支付。
  • 取消政策按酒店时区存为带时间的罚金窗口,并保留原文。
  • 预订路径在向任何人扣款前,都会重新询价并重新读取政策。
  • 任何代表承诺的东西,都绝不从缓存中返回。

如果你在权衡:是逐家供应商自己搭建这一切,还是从一个已经踩过这些坑的平台起步,那么合同层面和代码同样重要——我们关于酒店批发商平台的合同价与bedbank价格的文章讲了该提什么要求。我们自己的机票和酒店API通过沟通开通,而不是自助申请密钥;如果这是你想探索的方向,请从旅游API页面开始沟通。

扇出永远不会消失。好的客户端只是不再假装它不存在。

Tekravel 编辑部

旅游技术组

Tekravel 旅游技术组面向业内读者写作:代理商老板、票代批发商,以及为他们做对接的开发者。每篇文章在发布前都会在其所描述的平台上核对。