OpenCLI 携程(Ctrip)适配器实战指南:13 个命令把整个携程变成你的 CLI 查询接口
OpenCLI 携程(Ctrip)适配器实战指南:13 个命令把整个携程变成你的 CLI 查询接口
导读
本文全面讲解 OpenCLI 项目中携程(Ctrip)适配器的完整用法与底层实现原理。该适配器以 opencli ctrip 为统一入口,提供 13 个只读查询命令,覆盖目的地联想、酒店搜索与详情、单程/往返机票、火车票、汽车票、船票、邮轮、跟团游/自由行套餐以及城市热门景点等场景,是 OpenCLI 将"任意网站变成 CLI、让 AI Agent 复用你已登录的浏览器会话"这一理念在旅游垂类上的完整落地案例。读完本文,你将掌握每个命令的参数规则、输出列结构、限制边界,并理解公开接口直连(Public)与浏览器+Cookie 驱动(Browser)两种模式的源码级分工,可以直接复制示例命令投入实战,也能据此为自己的业务开发类似的站点适配器。
适配器全景:两种访问模式、三个站点域
从官方适配器文档与源码元信息可以确认,携程适配器被刻意拆分为两种运行模式:
- 🌐 Public(公开接口直连):
search、hotel-suggest两个命令直接 POST 携程公开的联想接口,无需登录会话,适合目的地/酒店名称的快速补全与 ID 发现。 - 🖥️ Browser + Cookie(浏览器+登录态):其余 11 个命令(
hotel-search、hotel、flight、flight-round、train、bus、ferry、cruise、tour、package、attraction)通过 OpenCLI 的浏览器桥复用你已登录的浏览器会话,在真实页面/SSR 数据中提取结构化行。
涉及的主域有三个:m.ctrip.com(联想接口)、hotels.ctrip.com(酒店)、flights.ctrip.com(机票),此外还有 trains.ctrip.com、bus.ctrip.com、ship.ctrip.com、cruise.ctrip.com、vacations.ctrip.com、you.ctrip.com 等子域承担各业务线的数据来源。
命令一览表
| 命令 | 模式 | 说明 |
|---|---|---|
opencli ctrip search |
Public | 联想城市、景区、火车站与地标 |
opencli ctrip hotel-suggest |
Public | 联想城市、商圈与单酒店 |
opencli ctrip hotel-search |
Browser (cookie) | 按城市 + 入住/离店日期列出酒店 |
opencli ctrip hotel |
Browser (cookie) | 单酒店详情:评分细分、设施、入离政策 |
opencli ctrip flight |
Browser (cookie) | 按 IATA 航线 + 日期搜索单程机票 |
opencli ctrip flight-round |
Browser (cookie) | 按 IATA 航线 + 去/返日期搜索往返机票 |
opencli ctrip train |
Browser (cookie) | 按站名/城市名 + 日期搜索火车票 |
opencli ctrip bus |
Browser (cookie) | 按城市名 + 日期搜索城际大巴 |
opencli ctrip ferry |
Browser (cookie) | 按城市名 + 日期搜索客滚船班次 |
opencli ctrip cruise |
Browser (cookie) | 按出发港名称搜索邮轮线路 |
opencli ctrip tour |
Browser (cookie) | 按目的地关键词搜索跟团/自由行套餐 |
opencli ctrip package |
Browser (cookie) | 按目的地关键词搜索机酒自由行套餐 |
opencli ctrip attraction |
Browser (cookie) | 按城市 ID 列出热门景点(评分/点评数/详情链接) |
快速上手:完整使用示例
以下命令均来自官方文档并可在真实会话中直接运行:
# 目的地联想(城市/景区/火车站/地标)
opencli ctrip search 苏州 --limit 10
# 酒店上下文联想(城市/商圈/单酒店)
opencli ctrip hotel-suggest 陆家嘴 --limit 5
# 酒店列表(city ID 来自 search / hotel-suggest)
opencli ctrip hotel-search 2 --checkin 2026-05-20 --checkout 2026-05-21 --limit 10
# 单酒店详情(hotel id 来自 hotel-suggest)
opencli ctrip hotel 375539
opencli ctrip hotel 375539 -f json
# 单程机票
opencli ctrip flight BJS SHA --date 2026-05-20 --limit 20
# 往返机票(去程 + 返程日期)
opencli ctrip flight-round SHA BJS --depart 2026-08-15 --return 2026-08-22 --limit 20
# 火车票(站名或城市名)
opencli ctrip train 北京 上海 --date 2026-05-20 --limit 20
opencli ctrip train 杭州 上海虹桥 --date 2026-05-20 -f json
# 城际汽车票(城市名)
opencli ctrip bus 北京 天津 --date 2026-05-20 --limit 20
# 客滚船票(城市名)
opencli ctrip ferry 大连 烟台 --date 2026-05-20 --limit 20
# 邮轮线路(出发港名称)
opencli ctrip cruise 上海 --limit 20
# 跟团/自由行套餐(目的地关键词)
opencli ctrip tour 北京 --limit 20
# 机酒自由行套餐(目的地关键词)
opencli ctrip package 三亚 --limit 20
# 城市热门景点(数字城市 ID 来自 ctrip search,如 1 代表北京)
opencli ctrip attraction 1 --limit 20
# JSON 输出
opencli ctrip search 上海 -f json
公开接口直连:search 与 hotel-suggest
这两个命令共享同一个后端端点与响应结构,差异仅在一个 searchType 判别参数上,源码集中在 clis/ctrip/utils.js 与 clis/ctrip/search.js、clis/ctrip/hotel-suggest.js。
底层端点与请求信封
从 utils.js 可以看到,唯一后端端点是:
POST https://m.ctrip.com/restapi/soa2/21881/json/gaHotelSearchEngine
请求体是一个固定信封(envelope):
{
"keyword": "<查询词>",
"searchType": "D", // D=目的地联想;H=酒店上下文联想
"platform": "online",
"pageID": "102001",
"head": {
"Locale": "zh-CN",
"LocaleController": "zh_cn",
"Currency": "CNY",
"PageId": "102001",
"clientID": "opencli-ctrip",
"group": "ctrip",
"Frontend": { "sessionID": 1, "pvid": 1 },
"HotelExtension": { "group": "CTRIP", "WebpSupport": false }
}
}
其中 searchType=D(search)与 searchType=H(hotel-suggest)是唯一区别;酒店(Hotel)与商圈(BusinessArea)行只在 H 口味中出现,这是文档 Notes 中特别标注的判别点。
参数与错误语义
--limit接受<a href="https://link.gitcode.com/i/83d094bab7efafde9d6b8068b989835c" target="_blank">1, 50]区间的整数(默认 15,见 [search.js 与 hotel-suggest.js)。越界值直接抛出ArgumentError,不做静默截断——这是parseStrictIntegerRange(utils.js)的既定行为。- 上游返回
Result: false时被映射为COMMAND_EXEC类型错误(携带ErrorCode),HTTP 非 2xx 则抛FETCH_ERROR,对应文档 Notes 中的错误分类说明(见 utils.js)。 - 结果为空时抛
EmptyResultError,并附带可操作的提示词。
Suggest 统一列结构
两个联想命令输出完全一致的 14 列,逐列说明如下:
| 列名 | 说明 |
|---|---|
rank |
上游列表中的 1 基位置 |
id |
上游实体 ID(会回填进 URL) |
type |
原始类型标签(City / Markland / Hotel / BusinessArea / RailwayStation) |
displayType |
本地化标签(城市 / 地标 / 酒店 / 商圈 / 火车站) |
name |
本地化显示名 |
eName |
英文名(可能为空) |
cityId, cityName, provinceName, countryName |
地理上下文 |
lat, lon |
可用坐标(gaode → google → 扁平字段 → null) |
score |
commentScore / cStar 中首个非零值;两者均未评分时为 null |
url |
规范的携程 URL;实体类型无公开网页时为 null |
坐标优先级与 URL 构造的源码细节
文档 Notes 中提到"大陆行返回 gdLat/gdLon(高德),国际行返回 gLat/gLon(wgs84)"。在 utils.js 的 pickCoords 中,适配器按 [gdLat,gdLon] → [gLat,gLon] → [lat,lon] 的顺序取第一组非零有限值,0.0 被视为"缺失"哨兵。
url 的构造也完全类型驱动(buildUrl):City 拼 you.ctrip.com/place/…、Markland 拼 /sight/…、Hotel 拼 hotels.ctrip.com/hotels/detail/?hotelid=…、BusinessArea/Zone 拼酒店列表筛选页、RailwayStation 拼 trains.ctrip.com/trainstation/…,未知类型返回 null——绝不虚构 URL。
浏览器 + Cookie 模式的数据来源总览
其余 11 个命令全部走浏览器桥,但数据来源形态各异,这是本适配器最有技术含金量的部分。从源码可以归纳出四类取数策略:
- SSR 直读:
hotel-search、hotel直接读取页面内嵌的window.__NEXT_DATA__。 - 网络拦截:
flight用Strategy.INTERCEPT通过 CDP 捕获携程自己的batchSearch接口响应,不重建请求参数。 - SPA 深链直跳:
bus、ferry的落地页是纯客户端 SPA,浏览器桥下无法水合(hydrate),于是命令直接导航到携带?param=<json>深链的结果路由。 - DOM 卡片解析:
flight-round、train、cruise、tour、package、attraction等待渲染完成后按稳定的 CSS 类名/结构化文本提取行。
几乎所有浏览器命令都内置了"等待渲染 + 验证码检测"双保险:一旦页面出现 /captcha 路径或 验证码 / verify the human / 安全验证 等文本,立即抛出 AuthRequiredError,提示在真实浏览器会话中完成人机验证后重试(各命令的 WAIT_FOR_*_JS 常量即为此而设)。
酒店列表:hotel-search
hotel-search.js 将浏览器导航到 https://hotels.ctrip.com/hotels/list?city=<cityId>&checkin=<checkin>&checkout=<checkout>,等待 SSR 状态就绪后,直接读取 window.__NEXT_DATA__.props.pageProps.initListData.hotelList(见 EXTRACT_HOTELS_JS),再经 mapHotelRow 投影为稳定列。
输出列
| 列名 | 说明 |
|---|---|
rank |
上游列表中的 1 基位置 |
hotelId |
回填进 https://hotels.ctrip.com/hotels/detail/?hotelid=… |
name, enName |
本地化 + 英文名(英文可能为 null) |
star |
1–5;未评级 / 客栈为 null |
score, scoreLabel |
例如 4.8 / "超棒";未评级时两者均为 null |
reviewCount |
从 "13,966条点评" 解析出的整数 |
cityName, district, address |
地理上下文 |
lat, lon |
WGS84 (1) → GCJ02 (2) → BD09 (3) 优先级选择;全为 0 时为 null |
price, currency |
首个房型的报价;搜索日期无房时为 null |
url |
规范详情 URL;hotelId 缺失时为 null |
参数规则
<city>(位置参数,必填):数字城市 ID,通过ctrip search/ctrip hotel-suggest发现。--checkin,--checkout(必填):YYYY-MM-DD格式,按真实日历校验且强制checkin < checkout(assertCheckinBeforeCheckout)。日期校验由 parseIsoDate 完成,它会用 UTC 日期数学交叉验证,杜绝2026-02-30这类假日期。--limit(1-30,默认 10):携程 SSR 首页约返回 13 条(10 条自然结果 + 约 3 条推广位)。由于服务端忽略 URL 上的pageSize参数,v1 不支持更大的 limit,这是文档 Caveats 明确记录的服务器侧限制。
单酒店详情:hotel
hotel.js 导航到详情页后,从 window.__NEXT_DATA__.props.pageProps.hotelDetailResponse 提取画像——与 hotel-search 同源的 SSR 数据风格(见 buildHotelDetailExtractJs),补齐列表行不携带的字段。
输出列
| 列名 | 说明 |
|---|---|
hotelId |
回显请求的 ID |
name, enName |
本地化 + 英文名(英文可能为 null) |
star |
1–5;未评级 / 客栈为 null |
score, scoreLabel |
综合评分(例如 4.8 / "超棒");未评级时均为 null |
reviewCount |
整数点评总数 |
ratingBreakdown |
四个子分拼接(例如 卫生 4.8 / 设施 4.8 / 环境 4.8 / 服务 4.8) |
facilities |
热门设施拼接(例如 接机服务 / 无线WIFI免费 / 行李寄存) |
checkInOut |
入住/退房政策行拼接 |
cityName, address |
地理上下文 |
lat, lon |
详情页坐标;缺失为 null |
url |
规范详情 URL |
参数规则
<id>(位置参数,必填):数字酒店 ID(通过ctrip hotel-suggest发现,例如375539),由 parseHotelId 校验为正整数。
需要说明的是:房级每晚价格是通过 SSR 之后的 XHR 加载到哈希 CSS-module 卡片里的,不在本命令作用域内;列表命令 hotel-search 已给出每酒店的代表性每晚报价。
单程机票:flight
flight.js 是本适配器中技术含量最高的一条命令,它没有去解析 DOM,而是采用 Strategy.INTERCEPT 模式:通过 CDP 网络捕获拦下携程页面自己发出的 batchSearch 接口响应(匹配模式为 /international/search/api/search/batchSearch,见 CAPTURE_PATTERN),由携程负责全部请求参数、trace id、风控与会话状态,适配器绝不重建其请求。
捕获与解析要点(源码级)
- 捕获超时 12 秒(CAPTURE_TIMEOUT_SECONDS);页面出现首张
.flight-item卡片只作为就绪信号,行数据仍全部来自结构化响应。 - 对捕获条目逐一校验:HTTP 401/403 抛
AuthRequiredError;非 200、响应体被截断、JSON 非法、payload.status !== 0均抛CommandExecutionError;按itineraryId去重聚合。 - 若
data.context.finished不是true,说明上游搜索尚未报告完成,同样抛错——确保结果完整。 - 排序逻辑模拟页面展示顺序:直飞先于中转,组内按展示起始价、出发时间排序(见 mapItinerary + sort)。
输出列
| 列名 | 说明 |
|---|---|
rank |
过滤不完整行后的 1 基位置 |
airline, flightNo, aircraft |
卡片自由文本;flightNo 与 aircraft 可能为 null(现行 .flight-item 卡片常省略航班号) |
departureTime, arrivalTime |
HH:MM 字符串 |
departureAirport, arrivalAirport, terminal |
机场名 + 可选 T1/T2 航站楼片段 |
price, currency, cabin |
首个报价;cabin 为中文舱位后缀(如 经济舱) |
url |
搜索 URL(携程航班卡片不暴露按行的稳定深链) |
参数规则
<from>,<to>(位置参数,必填):3 字母 IATA 码;BJS/SHA这类都市圈码与PEK/PVG单机场码均可,由 parseIataCode 校验并转大写。--date(必填):YYYY-MM-DD。--limit(1-50,默认 20)。
需要补充说明一个文档提及的实现细节:文档正文说 flight 行取自渲染后的 .flight-item 卡片,但从 flight.js 看,v1 实际通过捕获 batchSearch 结构化响应取数;而 buildFlightExtractJs 中基于 .flight-item 卡片的"位置锚定 innerText 解析器"是给 flight-round 及旧版单程布局(.flight-list > span > div)使用的,两者互为补充。
往返机票:flight-round
flight-round.js 与单程同属 flights.ctrip.com/online/list 应用,URL 形态为 round-<from>-<to>?depdate=<depart>_<return>&cabin=Y_S_C_F,返回去程(去程)腿,但 price 是该去程航班对应的往返总价。
与单程的两点差异
price是往返总价(往返总价),而非单程价。- 往返卡片省略航班号,因此
flightNo与aircraft通常为null(绝不会是哨兵值)——这也是调用解析器时传入requireFlightNo=false的原因(flight-round.js)。
行数据来自 .flight-item 卡片,先经 buildScrollUntilJs 滚动加载直到行数达标或 DOM 平顶,再用位置锚定解析器提取。选择返程腿是携程流程中的第二步,超出本命令作用域。
参数规则
<from>,<to>(位置参数,必填):3 字母 IATA 码。--depart,--return(必填):YYYY-MM-DD,且return不得早于depart。--limit(1-50,默认 20)。
火车票:train
train.js 导航到 https://trains.ctrip.com/webapp/train/list?dStationName=<from>&aStationName=<to>&dDate=<date>&ticketType=1(URL 由 buildTrainListUrl 构造)。与 flight 不同,火车列表页的 .card-white.list-item 卡片暴露稳定的类名叶子字段,因此解析采用按选择器读取而非位置锚定 innerText(见 buildTrainExtractJs)。
输出列
| 列名 | 说明 |
|---|---|
rank |
过滤不完整行后的 1 基位置 |
trainNo |
车次(G531 / D701 / K528);剥离 .checi 图标后缀 |
departureTime, arrivalTime |
HH:MM 字符串 |
departureStation, arrivalStation |
站名(如 北京南, 上海虹桥) |
duration |
页面展示的耗时(如 5时56分);缺失为 null |
fromPrice |
该车次展示的最低票价(数字);非数字为 null |
seats |
席别余票以 / 拼接(如 二等座有票 / 一等座17张 / 商务座(抢)) |
url |
搜索 URL(车次行共享列表页,无按行深链) |
参数规则
<from>,<to>(位置参数,必填):中文站名或城市名(如北京/上海虹桥);列表页与官网搜索框按同一方式解析。--date(必填):YYYY-MM-DD。--limit(1-50,默认 20)。
行解析严格要求车次号、两端时间、两端站名齐全,缺失即丢弃整行(绝不输出空锚点);等待逻辑(WAIT_FOR_TRAINS_JS)同样内置验证码墙检测。
城际汽车票:bus
bus.js 面对的是一个棘手场景:bus.ctrip.com/ 落地页是纯客户端 SPA,在浏览器桥下不水合。解决方案是直接导航到结果路由的 ?param=<json> 深链——这正是 App 自身搜索处理器 POST 到 /list 的负载形态(buildBusListUrl):
// fromCity / toCity 为城市名,fromStation / toStation 留空使查询为城对城
{"fromCity":"北京","toCity":"天津","fromDate":"2026-05-20","fromStation":"","toStation":""}
班次经 busListV2 XHR 到达,渲染进 .list-item-parent 行,按稳定的工具类字段(.list-width150 时间、.list-width200 .cor333 站点、.bus-desc 耗时、.corred 票价、.list-seat-parent 余票)读取(buildBusExtractJs)。
输出列
| 列名 | 说明 |
|---|---|
rank |
过滤不完整行后的 1 基位置 |
departureTime |
HH:MM 发车时间 |
fromStation, toStation |
出发/到达客运站 |
duration |
页面展示的耗时(如 约2时30分);缺失为 null |
price |
票价(数字);非数字为 null |
status |
余票文案(如 暂停网售,或剩余票数) |
url |
结果页 URL(班次共享列表页,无按行深链) |
参数规则
<from>,<to>(位置参数,必填):中文城市名(如北京/天津);结果页返回两地之间的站点级班次。--date(必填):YYYY-MM-DD。--limit(1-50,默认 20)。
客滚船票:ferry
ferry.js 是 bus 的姊妹实现:ship.ctrip.com 落地页同样是浏览器桥下无法水合的 SPA,于是直接导航到结果路由深链(buildFerryListUrl):
{"fromCityName":"大连","toCityName":"烟台","date":"2026-05-20"}
班次经 getShipLineV2 XHR 到达,渲染进 .list-item-parent 行;buildFerryExtractJs 从 .list-width400 块中读取两个 .font600 时间和两个 .font12 港口,用 span.list-width100 中的时长单位来区分船名与耗时(不依赖 span 顺序)。
输出列
| 列名 | 说明 |
|---|---|
rank |
过滤不完整行后的 1 基位置 |
shipName |
船名(如 渤海晶珠);缺失为 null |
departureTime, arrivalTime |
HH:MM 字符串 |
fromPort, toPort |
出发/到达客运港 |
duration |
页面展示的耗时(如 6时30分);缺失为 null |
price |
最低票价(数字);非数字为 null |
status |
余票文案(如 选择舱位, 售罄) |
url |
结果页 URL(班次共享列表页,无按行深链) |
参数规则
<from>,<to>(位置参数,必填):中文城市名(如大连/烟台);结果页返回港口级班次。--date(必填):YYYY-MM-DD。--limit(1-50,默认 20)。
邮轮线路:cruise
cruise.js 针对携程遗留的 newpackage/search/sN.html 页面设计——结果页以不透明的每港代码 sN 为键。这些页面会把每个出发港都列成链接,因此命令分两步走:
- 先加载上海港页面(
s2,PORT_INDEX_CODE)作为港口代码索引,用 buildCruisePortLookupJs 将请求的港口名解析为sN代码; - 再加载该港口的
sN.html结果页,从.route_info卡片读取线路(buildCruiseExtractJs)。
输出列
| 列名 | 说明 |
|---|---|
rank |
过滤不完整行后的 1 基位置 |
title |
航线/船名/行程(如 MSC地中海邮轮·荣耀号·上海-那霸(冲绳)-上海·5天4晚) |
star |
产品星级(1–5);未评级为 null |
boarding |
登船/离船说明(如 上海登船/离船) |
sailingDate |
下一推荐航次日期;缺失为 null |
tags |
卖点标签以 / 拼接(如 免签 / 岸上游 / 船上餐饮) |
price |
最低人均价(数字);非数字为 null |
url |
港口结果页 URL(航线共享列表页,无按行深链) |
参数规则
<port>(位置参数,必填):出发港名称(如上海/威尼斯/罗马),按携程列出的港口匹配(上海承载了大部分中国出发,另有国际港口)。--limit(1-50,默认 20)。
文档明确:已列出但当前无班次的港口会抛 EmptyResultError;长江三峡(三峡)游轮是独立产品线,不在作用域内。
跟团/自由行套餐:tour 与 package
tour.js 与 package 共享同一套 vacations 搜索体系,仅在产品分区(section)上不同(buildVacationsListUrl):
tour→whole(全量跟团游)标签页;package→freetravel(自由行/机酒)标签页。
结果服务端渲染进 .list_product_item 卡片(buildVacationsExtractJs),其中 sold 从 已售N 解析、reviews 从点评数解析(万 会展开为整数)。等待逻辑(WAIT_FOR_VACATIONS_JS)有个精妙之处:卡片先渲染标题/副标题,价格/评分/销量稍后懒加载,所以"内容就绪"的判定条件是每张已渲染卡片都带上了价格节点,而不是第一张裸卡片出现就放行。
输出列(tour 与 package 完全一致)
| 列名 | 说明 |
|---|---|
rank |
过滤不完整行后的 1 基位置 |
title |
套餐标题(如 北京5日4晚跟团游) |
subtitle |
亮点行;缺失为 null |
tags |
卖点标签以 / 拼接(如 0购物 / 成团保障 / 亲子甄选) |
score |
5 分制评分;未评级为 null |
sold |
已售数量(整数,来自 已售N);缺失为 null |
reviews |
点评数(整数);缺失为 null |
price |
最低人均价(数字);非数字为 null |
url |
搜索结果页 URL(套餐共享列表页,无按行深链) |
参数规则
<destination>(位置参数,必填):目的地关键词(如北京/三亚/马尔代夫/曼谷),作为sv传入 vacations 搜索。--limit(1-50,默认 20)。
目的地无套餐时抛 EmptyResultError。
城市热门景点:attraction
attraction.js 导航到 you.ctrip.com 的目的地页(URL 按尾部数字城市 ID 路由,任何 slug 都会被重定向到规范页),从页面中提取形如 /sight/<city><cityId>/<id>.html 的景点链接——这些链接自带名称、评分与点评数摘要。
buildAttractionExtractJs 的解析逻辑非常严谨:锚点限定在 you.ctrip.com 且路径匹配 /sight/([^/]+)/(\d+).html;按链接城市段尾部的数字与请求城市 ID 匹配(过滤掉周边热门、面包屑里其他城市的交叉销售锚点);必须有评分或点评签名;按 sight id 去重;无名称的链接直接丢弃。
输出列
| 列名 | 说明 |
|---|---|
rank |
渲染列表中的 1 基位置 |
name |
景点名称 |
rating |
5 分制游客评分;卡片仅有点评数时为 null |
reviews |
点评数(整数,19.7w / 1.3万 展开为千位);缺失为 null |
url |
景点的 you.ctrip.com/sight/<city>/<id>.html 详情页 |
参数规则
<city>(位置参数,必填):数字城市 ID(经ctrip search发现;如1为北京、2为上海)。--limit(1-50,默认 20)。
注意:景点门票价格位于各景点自己的详情页,不在本命令作用域内。同时该命令没有 EmptyResultError 路径——一个有效的 you.ctrip 城市总有景点,因此"零条城市级结果"意味着城市 ID 过期/无效/页面不可渲染,会以 CommandExecutionError(提示检查城市 ID)的形式呈现,而不是伪装成"真无数据"。
实现要点与错误语义汇总
从文档 Notes 与源码交叉印证,可以总结出三条贯穿整个适配器的设计原则:
- 统一联想端点 + searchType 判别:
search与hotel-suggest共用gaHotelSearchEngine端点,D/H决定实体类型(酒店与商圈只出现在H口味)。 - 坐标优先级可预期:大陆联想行携带高德
gdLat/gdLon,国际行携带 wgs84gLat/gLon,适配器取首个非零对;酒店坐标则在mapCoordinate数组中按 WGS84(1) → GCJ02(2) → BD09(3) 排序取首个非零(pickHotelMapCoords)。 - 类型化错误替代静默降级:
Result: false→COMMAND_EXEC,HTTP 非 2xx →FETCH_ERROR,验证码墙 →AuthRequiredError,空结果 →EmptyResultError,参数越界 →ArgumentError(绝不静默截断 limit)。列值一律string | number | null,绝不用空字符串冒充"无数据"(参见 mapSuggestRow 与 mapHotelRow 的注释约定)。
已知边界与注意事项(Caveats)
最后是官方文档 Caveats 一节明确记录的 v1 边界,务必在使用前了解:
- Cookie 必需:
hotel-search/flight对hotels.ctrip.com/flights.ctrip.com使用Strategy.COOKIE。若携程返回验证码重定向(疑似机器人),会抛AuthRequiredError——请在浏览器会话中完成验证后重试。flight本身用Strategy.INTERCEPT,但其对 401/403 的处理同样要求有效的浏览器登录态。 - 无按航班深链:携程航班卡片将所有行汇聚到共享的预订交接流程。在出现稳定的按航班
bookingId之前,所有行共享搜索 URL。 - 仅单程 + 无航司筛选:
flight只支持单程,v1 固定传cabin=Y_S_C_F(全舱位)。往返与高级筛选在#1481后续跟进项中跟踪。 - 酒店 SSR 页大小由服务端固定:传
&pageSize=N会被上游忽略,首页固定约 13 行。更大的结果集需要滚动分页式 DOM 提取(v1 未实现)。
结语与延伸阅读
携程适配器是 OpenCLI "把一个真实业务网站完整封装成 CLI" 的样板级实现:它同时示范了 Public 直连(公共接口封装)、INTERCEPT(网络捕获结构化响应)、SPA 深链绕过(?param=<json> 直跳)与 SSR/DOM 解析(__NEXT_DATA__、类名键控卡片)四种取数范式,并对验证码、空结果、参数越界做了类型化错误治理。想深入源码的读者可以从以下文件入手:
- 命令入口:全部 13 个命令位于 clis/ctrip/ 目录(如 search.js、hotel-search.js、flight.js、train.js、cruise.js 等);
- 共享逻辑:clis/ctrip/utils.js 集中了端点信封、日期/IATA/城市 ID 校验、所有浏览器侧 IIFE 提取脚本与等待/验证码检测常量;
- 测试佐证:clis/ctrip/ctrip.test.js 覆盖了各命令的参数校验与提取脚本行为;
- 协议设计:适配器的列投影与错误语义遵循 docs/conventions 与 docs/developer 中关于"无哨兵值""类型化错误"等约定。
结合本文的命令示例与列结构说明,你可以直接用 opencli ctrip 完成一次完整的"机票→酒店→景点→餐饮"行程规划查询,或将这套双模式适配器设计迁移到其他站点。