OpenCLI 携程(Ctrip)适配器实战指南:13 个命令把整个携程变成你的 CLI 查询接口

原创2026-09-18 19:21:152,956 阅读
文章标签:CLI浏览器控制GUI 自动化开发工具AI 技能网页爬虫

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 个命令全部走浏览器桥,但数据来源形态各异,这是本适配器最有技术含金量的部分。从源码可以归纳出四类取数策略:

  1. SSR 直读:hotel-search、hotel 直接读取页面内嵌的 window.__NEXT_DATA__。
  2. 网络拦截:flight 用 Strategy.INTERCEPT 通过 CDP 捕获携程自己的 batchSearch 接口响应,不重建请求参数。
  3. SPA 深链直跳:bus、ferry 的落地页是纯客户端 SPA,浏览器桥下无法水合(hydrate),于是命令直接导航到携带 ?param=<json> 深链的结果路由。
  4. 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 为键。这些页面会把每个出发港都列成链接,因此命令分两步走:

  1. 先加载上海港页面(s2,PORT_INDEX_CODE)作为港口代码索引,用 buildCruisePortLookupJs 将请求的港口名解析为 sN 代码;
  2. 再加载该港口的 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 与源码交叉印证,可以总结出三条贯穿整个适配器的设计原则:

  1. 统一联想端点 + searchType 判别:search 与 hotel-suggest 共用 gaHotelSearchEngine 端点,D/H 决定实体类型(酒店与商圈只出现在 H 口味)。
  2. 坐标优先级可预期:大陆联想行携带高德 gdLat/gdLon,国际行携带 wgs84 gLat/gLon,适配器取首个非零对;酒店坐标则在 mapCoordinate 数组中按 WGS84(1) → GCJ02(2) → BD09(3) 排序取首个非零(pickHotelMapCoords)。
  3. 类型化错误替代静默降级: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__、类名键控卡片)四种取数范式,并对验证码、空结果、参数越界做了类型化错误治理。想深入源码的读者可以从以下文件入手:

结合本文的命令示例与列结构说明,你可以直接用 opencli ctrip 完成一次完整的"机票→酒店→景点→餐饮"行程规划查询,或将这套双模式适配器设计迁移到其他站点。

登录后查看全文
OpenCLI