google-api-nodejs-client 子包 cloudlocationfinder 版本演进解读:从 1.0.0 到 10.1.1 的 API 更新与破坏性变更全记录
google-api-nodejs-client 子包 cloudlocationfinder 版本演进解读:从 1.0.0 到 10.1.1 的 API 更新与破坏性变更全记录
本篇文章以 src/apis/cloudlocationfinder/CHANGELOG.md 为核心骨架,完整梳理 Cloud Location Finder API 官方 Node.js 客户端(@googleapis/cloudlocationfinder)自 2025 年 7 月 1.0.0 发布以来的全部版本记录,并结合仓库源码解读每次 Feature / Bug Fixes / Breaking Changes 背后的实际影响。读完本文,你将能够:看懂该子包每个版本升级点与升级风险、掌握其 projects.locations.cloudLocations 资源下 get / list / search 三个核心方法的使用方式、理解 Node.js 最低版本要求为何被提升到 22,以及了解该库处于维护模式时如何规划迁移。
一、版本演进总览:21 个版本节点的时间线
cloudlocationfinder 子包从 2025-07-08 发布 1.0.0 到 2026-10-07 发布 10.1.1,约 15 个月内经历了 21 个版本节点(含重复的 2.0.0 版本号)。下表完整覆盖 CHANGELOG 中的全部版本:
| 版本 | 发布日期 | 类型 | 关键内容 |
|---|---|---|---|
| 1.0.0 | 2025-07-08 | 首个正式版 | 首次发布,含 cloudlocationfinder: update the API(commit 52d4878) |
| 1.0.1 | 2025-08-07 | Bug Fixes | googleapis-common 升级到 8.0.0(PR #3731) |
| 2.0.0 | 2025-08-21 | BREAKING | run the generator(PR #3749,commit 716b41c) |
| 2.0.0(重复号) | 2025-09-16 | BREAKING | 同一 PR #3749 生成 + releasing for our libraries(PR #3769,commit 27f5cf0);googleapis-common 升级到 8.0.0 |
| 3.0.0 | 2025-09-16 | BREAKING | releasing for our libraries(PR #3769) |
| 4.0.0 | 2025-09-30 | BREAKING | run the generator(PR #3795,commit c47e53a) |
| 5.0.0 | 2025-10-15 | BREAKING | run the generator(PR #3814,commit 4ba19d0) |
| 5.0.1 | 2025-11-04 | Bug Fixes | update the API(commit caf859a) |
| 5.0.2 | 2025-12-05 | Bug Fixes | update the API(commit 3daf4a1) |
| 5.1.0 | 2026-02-05 | Features | run the generator(PR #3886,commit 5612fac) |
| 5.1.1 | 2026-05-19 | Bug Fixes | update the API(commit 1bb94a7) |
| 6.0.0 | 2026-08-03 | BREAKING | run the generator(PR #3955,commit c429a9b) |
| 6.1.0 | 2026-09-02 | Features | run the generator(PR #3992);依赖升级到 Node 22(commit de9d20d) |
| 6.1.1 | 2026-09-09 | Bug Fixes | 恢复对 Node 18 的支持(commit eccac1d) |
| 7.0.0 | 2026-09-09 | BREAKING | 最小 Node 版本提升到 22(PR #4011);run the generator;恢复 Node 18 支持;依赖升级到 Node 22 |
| 8.0.0 | 2026-09-10 | BREAKING | 最小 Node 版本提升到 22(PR #4011);恢复 Node 18 支持 |
| 9.0.0 | 2026-09-10 | BREAKING | 最小 Node 版本提升到 22(PR #4011);run the generator;恢复 Node 18 支持;update the API(commit 1bb94a7) |
| 10.0.0 | 2026-09-14 | BREAKING | 全部包再次要求最小 Node 版本 22(PR #4020,commit 4e5bae0) |
| 10.1.0 | 2026-09-23 | Features | update the API(commit f9d1ac2) |
| 10.1.1 | 2026-10-07 | Bug Fixes | update the API(commit 1ec7644),即当前仓库版本 |
可以看到版本节奏非常密集:2025 年下半年几乎每月一个版本,2026 年 9 月更是出现 6.0.0 → 10.1.1 的一周内连续五次发版,属于典型的 API 变更联动客户端自动发版节奏。
二、Breaking Changes 深度解读:Node.js 最低版本要求为何提升到 22
CHANGELOG 中所有 ⚠ BREAKING CHANGES 段落都围绕两条主线:Node 版本要求 与 generator 重新生成代码。
2.1 Node 22 成为硬性门槛
7.0.0(2026-09-09)与8.0.0(2026-09-10):Update apiary to minimum Node version of 22.(PR #4011),apiary 层面将 Node 最低版本提升到 22;9.0.0(2026-09-10)再次确认该要求;10.0.0(2026-09-14):Update apiary to minimum Node version of 22 again - all packages(PR #4020),"again" 说明这是第二次整体收紧,且明确针对"所有包"(all packages),范围覆盖整个 google-api-nodejs-client 全家桶而非仅 cloudlocationfinder。
这一要求在仓库中有直接证据:src/apis/cloudlocationfinder/package.json 中 engines 字段为:
"engines": {
"node": ">=22.0.0"
}
也就是说,使用 @googleapis/cloudlocationfinder@10.x 必须在 Node.js 22 及以上版本运行,低于 22 的运行时(Node 18/20)会直接不满足依赖引擎声明。升级到 10.x 前请先核对 CI/CD 与生产环境的 Node 版本。
2.2 "run the generator" 意味着什么
CHANGELOG 中大量版本标注为 run the generator(如 PR #3749、#3795、#3814、#3955、#3992)。结合仓库代码可以印证:子包的 TypeScript 源码带有 /*! THIS FILE IS AUTO-GENERATED */ 标记,src/apis/cloudlocationfinder/index.ts 顶部即声明文件由生成器自动产出。
这意味着每次 Google 后端 API(apiary / discovery 文档)发生变更后,官方会重新运行代码生成器,把新的 API 定义同步为客户端代码,再以新版本号发布。因此"Breaking Changes"并不一定代表方法签名变化,也可能是 Node 运行时要求收紧 或 API 行为变更 触发的版本号跃迁——具体差异需要查看对应版本的 diff 才能确定。例如 discovery/cloudlocationfinder-v1.json 的 revision 为 20260930(2026-09-30),正好对应 10.1.0 的 API 更新窗口(commit f9d1ac2,2026-09-23 发布,其生成的发现文档修订于 9 月 30 日前后)。
2.3 依赖链升级:googleapis-common 8.0.0
1.0.1 和 2.0.0(2025-09-16)两个版本都包含 upgrade googleapis-common to 8.0.0(PR #3731)。googleapis-common 是子包共享的底层基础设施(createAPIRequest、AuthPlus、GoogleConfigurable 等均来自该包,见 src/apis/cloudlocationfinder/index.ts 的 import 语句),它的主版本升级会直接影响所有依赖它的 API 子包行为。当前 src/apis/cloudlocationfinder/package.json 中依赖为 "googleapis-common": "^9.0.0",说明在 10.x 时代已进一步跟进到 9.x 主版本线。
三、围绕 CHANGELOG 源码级展开:这个子包到底提供了什么
要理解 CHANGELOG 中每次 "update the API" 的具体对象,需要看子包的代码结构。从 src/apis/cloudlocationfinder/index.ts 可以确认该子包同时封装了 v1 与 v1alpha 两个版本:
export const VERSIONS = {
v1: cloudlocationfinder_v1.Cloudlocationfinder,
v1alpha: cloudlocationfinder_v1alpha.Cloudlocationfinder,
};
3.1 资源层级:projects → locations → cloudLocations
src/apis/cloudlocationfinder/v1.ts(v1alpha.ts 结构与之完全一致)中,Cloudlocationfinder 类的构造器只挂载了一个资源:
export class Cloudlocationfinder {
context: APIRequestContext;
projects: Resource$Projects;
constructor(options: GlobalOptions, google?: GoogleConfigurable) {
this.context = {_options: options || {}, google};
this.projects = new Resource$Projects(this.context);
}
}
资源层级为 Resource$Projects → Resource$Projects$Locations → Resource$Projects$Locations$Cloudlocations,最终对外暴露的方法路径是:
cloudlocationfinder.projects.locations.get(...)/list(...)—— 标准 GCP Location 查询(对应 discovery 中的cloudresourcemanager风格ListLocations语义);cloudlocationfinder.projects.locations.cloudLocations.get(...)—— 获取单个 cloud location 详情;cloudlocationfinder.projects.locations.cloudLocations.list(...)—— 列出某 project/location 下的全部 cloud locations;cloudlocationfinder.projects.locations.cloudLocations.search(...)—— 从指定源位置搜索云位置(例如按延迟寻找附近的区域)。
3.2 核心方法的请求参数(来自 v1.ts 方法级文档)
以 search 方法为例,src/apis/cloudlocationfinder/v1.ts 中实现的 HTTP 调用为 GET https://cloudlocationfinder.googleapis.com/v1/{+parent}/cloudLocations:search,其参数含义如下:
| 参数 | 必填 | 说明 |
|---|---|---|
parent |
是 | 格式 projects/{project}/locations/{location},拥有该 cloudLocations 集合的父资源 |
query |
否 | 搜索查询语法字符串,用于指定搜索需求(与 filter 的角色不同:filter 过滤属性,query 指定需求) |
sourceCloudLocation |
是 | 搜索的源云位置,例如按延迟从源位置搜索附近的云位置 |
pageSize |
否 | 每页返回数量,默认最多 500,最大值 1000,超过 1000 会被强制到 1000 |
pageToken |
否 | 上一页响应 nextPageToken 返回的分页令牌 |
list 方法(src/apis/cloudlocationfinder/v1.ts)除 parent、pageSize、pageToken 外还支持 filter,过滤表达式形如 cloud_location_type=CLOUD_LOCATION_TYPE_REGION 或 territory_code="US",多个过滤条件以空格分隔,默认按 AND 组合,也可显式使用 AND/OR。
3.3 CloudLocation 数据模型(Schema)
get 与 list 返回的核心对象是 Schema$CloudLocation(src/apis/cloudlocationfinder/v1.ts),字段包括:
| 字段 | 类型 | 说明 |
|---|---|---|
name |
string | 唯一标识,格式 projects/{project_id}/locations/{location}/cloudLocations/{cloud_location} |
displayName |
string | 人类可读名称,如 us-east-2、us-east1 |
cloudProvider |
string | 云提供商,可为 Google Cloud 或第三方(AWS、Azure、Oracle Cloud Infrastructure) |
cloudLocationType |
string | 云位置类型 |
containingCloudLocation |
string | 严格嵌套层级中的上级位置(zone 的上级是 region),仅输出 |
territoryCode |
string | 两位 ISO 3166-1 alpha-2 国家/地区码,如 US、JP、KR |
carbonFreeEnergyPercentage |
number | 碳免费能源百分比,即客户应用运行在碳免费能源上的平均时间占比;0 与未设置含义不同:0 表示碳免费能源占比为 0%,未设置表示碳足迹数据不可用 |
gcpAttributes |
object | GCP 专属属性(当前含 zoneType 字段) |
列表与搜索响应统一使用 Schema$ListCloudLocationsResponse / Schema$SearchCloudLocationsResponse:均含 cloudLocations 数组与 nextPageToken 续页令牌。
四、"update the API" 的 Bug Fixes 与 Features 规律
从 CHANGELOG 中可以归纳出两类自动化发版:
* **cloudlocationfinder:** update the API(Bug Fixes / Features):发生在 1.0.0、5.0.1、5.0.2、5.1.1、9.0.0、10.1.0、10.1.1 等版本,即 Google 后端发现文档更新后由机器人同步生成客户端代码并打补丁版本或特性版本;run the generator(Features / BREAKING):出现在 2.0.0、4.0.0、5.0.0、6.0.0、6.1.0、7.0.0、9.0.0 等版本,属于全仓库范围的生成器重跑,通常会附带跨子包一致的依赖或运行时策略变更(如 Node 22 门槛、googleapis-common 升级)。
这种"上游 API 变更 → 自动生成 → 自动发版"的机制,意味着 CHANGELOG 本身就是跟踪 Cloud Location Finder API 演进的最直接窗口。若你的业务依赖该服务的字段或方法,建议在每次升级时优先比对 discovery/cloudlocationfinder-v1.json 与 discovery/cloudlocationfinder-v1alpha.json 的 revision 时间戳,确认后端 API 是否发生了你想追踪的变更。
五、升级指引与维护状态提示
5.1 当前版本与安装
仓库当前锁定版本为 10.1.1(见 src/apis/cloudlocationfinder/package.json),独立安装方式(子包 README 中给出):
$ npm install @googleapis/cloudlocationfinder
在 monorepo 式的 google-api-nodejs-client 主包中则通过命名空间访问:
const {google} = require('googleapis');
const cloudlocationfinder = google.cloudlocationfinder('v1'); // 或 'v1alpha'
5.2 重要:该库处于维护模式
src/apis/cloudlocationfinder/README.md 的 Support status 明确声明:该库处于维护模式(maintenance mode),仅继续为已有应用提供可用性;Google 官方建议新应用或正在现代化的存量应用改用 @google-cloud/locationfinder(更快、更易用、维护更积极)。
因此对于 CHANGELOG 中的大版本跃迁(尤其 7.0.0 / 10.0.0 的 Node 22 门槛),可以这样决策:
- 存量应用且运行在 Node 22+:按 CHANGELOG 逐版本评估后平滑升级,关注
update the API版本中的字段变更; - 新项目:优先评估
@google-cloud/locationfinder,避免基于维护模式库搭建新架构; - 短期无法迁移:锁定一个满足 Node 环境的稳定版本(如 6.1.1 之前兼容 Node 18 的版本线),并规划迁移。
5.3 验证版本与 Node 环境
升级后建议通过以下方式确认版本符合预期:
$ npm ls @googleapis/cloudlocationfinder
$ node -v # 需 >= 22.0.0(10.x 版本线)
六、小结
cloudlocationfinder 子包的 CHANGELOG 虽是一份版本记录,却完整折射了 Google API 客户端自动生成的发版链路:上游发现文档修订(update the API)→ 全仓库 generator 重跑(run the generator)→ 共享依赖升级(googleapis-common)→ 运行时策略收紧(Node 22)。本文结合 v1.ts 与 index.ts 源码,将每条版本记录落到了具体的资源方法、请求参数与数据模型上,使你可以基于同一份 CHANGELOG 做出准确的升级与迁移判断。后续版本变化请持续关注仓库根目录 CHANGELOG.md 与 src/apis/cloudlocationfinder/CHANGELOG.md。