google-api-nodejs-client 的 apikeys 子包:从 CHANGELOG 读懂版本演进、破坏性变更与 v2 API 全貌

原创2026-10-14 14:41:091,853 阅读
文章标签:后端

google-api-nodejs-client 的 apikeys 子包:从 CHANGELOG 读懂版本演进、破坏性变更与 v2 API 全貌

导读

src/apis/apikeys/ 是 google-api-nodejs-client 仓库中负责 Google Cloud API Keys 服务的独立子包,其 CHANGELOG.md 记录了该包从 1.0.0 到 13.0.1 的完整发布历史。本文以这份变更日志为骨架,逐条拆解其中的破坏性变更(BREAKING CHANGES)、Node.js 版本门槛的演进脉络与 API 更新节奏,并结合仓库中的 v2.ts、index.ts、package.json 与 discovery/apikeys-v2.json 等源码与元数据,还原 @googleapis/apikeys 包背后的 API Keys v2 REST 接口全貌。读完本文,你将掌握如何解读这份变更日志、判断某个版本升级是否会影响你的应用,以及该子包实际暴露的完整方法面与数据模型。

一、关联文档定位:一份「发布史即 API 演进史」的变更日志

在 google-api-nodejs-client 这个单体仓库中,每个 API 子包都拥有独立的 CHANGELOG.md、README.md、package.json 与生成源码。apikeys 子包对应 Google Cloud 的 API Keys API,官方描述为"Manages the API keys associated with developer projects"(管理开发者项目关联的 API 密钥),以 npm 包名 @googleapis/apikeys 独立发布,当前仓库版本为 13.0.1(见 package.json)。

与普通手写文档不同,这份 CHANGELOG 由 release-please 与代码生成流水线自动产出,因此它精确记录了每次发版的时间、类型(feature / bug fix / breaking change)与触发原因,是可以反推出 API 演进路线的一手资料。其时间跨度从 2023-08-17 的 1.0.0 一路延伸到 2026-09-23 的 13.0.1,恰好覆盖了 API Keys v2 接口从初版发布到 2026 年的全部迭代。

注:该包在 README.md 中被标注为 maintenance mode(维护模式)。README 明确建议新应用改用 Google 官方提供的 @google-cloud/apikeys 库,本包则继续服务于已有存量应用。这也是解读这份变更日志时必须先了解的背景。

二、CHANGELOG 内容总览:全量版本清单

为完整继承原文档信息,先将 CHANGELOG.md 中全部版本按时间倒序整理如下(提交哈希均出自原文档,在此仅作记录,不附外部链接):

版本 日期 类型 核心变更
13.0.1 2026-09-23 Bug Fixes apikeys 更新 API(630a4fd)
13.0.0 2026-09-14 ⚠ BREAKING / Features 再次将 apiary 最低 Node 版本提升至 22,波及全部包(#4020,4e5bae0)
12.0.0 2026-09-10 ⚠ BREAKING / Features / Bug Fixes 最低 Node 版本提升至 22(#4011);apikeys 三次更新 API(0316790 / 602fdeb / e212177);运行生成器;升级依赖至 Node 22
11.0.0 2026-09-10 ⚠ BREAKING / Features / Bug Fixes 最低 Node 版本提升至 22(#4011);加回 Node 18 支持
10.0.0 2026-09-09 ⚠ BREAKING / Features / Bug Fixes 最低 Node 版本提升至 22;更新 API;运行生成器;升级依赖至 Node 22;加回 Node 18 支持
9.1.1 2026-09-09 Bug Fixes 加回 Node 18 支持(eccac1d)
9.1.0 2026-09-02 Features / Bug Fixes 运行生成器(#3992,5f7d438);升级依赖至 Node 22(de9d20d)
9.0.0 2026-08-31 ⚠ BREAKING / Features apikeys 更新 API(0316790 / 602fdeb / e212177);运行生成器(#3955)
8.2.0 2026-08-28 Features apikeys 更新 API(0316790)
8.1.0 2026-08-14 Features apikeys 更新 API(602fdeb)
8.0.0 2026-08-03 ⚠ BREAKING / Features 运行生成器(#3955,c429a9b)
7.0.0 2026-05-19 ⚠ BREAKING / Features apikeys 更新 API(e212177)
6.0.0 2026-01-28 ⚠ BREAKING / Features apikeys 更新 API(43eff2a)
5.0.1 2025-12-05 Bug Fixes apikeys 更新 API(998bb0e)
5.0.0 2025-10-15 ⚠ BREAKING / Features 运行生成器(#3814,4ba19d0)
4.0.0 2025-09-16 ⚠ BREAKING / Bug Fixes 为库统一发版(#3769);升级 googleapis-common 至 8.0.0(#3731)
3.0.1 2025-07-08 Bug Fixes apikeys 更新 API(ec54b77)
3.0.0 2025-06-30 ⚠ BREAKING / Features / Bug Fixes 升级至 Node 18(682fbb8);更新 API(a25ed5a);依赖 googleapis-common 8.0.2-rc
2.0.1 2025-06-04 Bug Fixes 依赖升级 googleapis-common 8.0.2-rc(f4b0990)
2.0.0 2025-05-29 ⚠ BREAKING / Features 升级至 Node 18(682fbb8)
1.1.0 2025-02-04 Features apikeys 更新 API(49e5f04)
1.0.7 2024-08-16 Bug Fixes apikeys 更新 API(6fd74d0)
1.0.6 2024-08-16 Bug Fixes apikeys 更新 API(6fd74d0)
1.0.5 2024-05-02 Bug Fixes apikeys 更新 API(f2ab501)
1.0.4 2024-05-02 Bug Fixes apikeys 更新 API(f2ab501)
1.0.3 2023-10-11 Bug Fixes 依赖 googleapis-common 升级至 v7(9491ec1)
1.0.2 2023-08-25 Bug Fixes 依赖 googleapis-common 升级至 v7(9491ec1)
1.0.1 2023-08-17 Bug Fixes apikeys 更新 API(18e475b)
1.0.0 2023-08-17 Bug Fixes apikeys 更新 API(18e475b)

另有一处记录上的特殊条目:1.0.0 (2025-08-07) 出现在 1.0.5 与 3.0.1 之间(见 CHANGELOG.md)。这是 release-please 在历史版本整理时产生的时间戳回填现象,其内容(apikeys 更新 API、googleapis-common 8.0.0)与 1.0.x 系列一致,读者按 1.0.x 系列理解即可,不影响变更语义。

三、破坏性变更的两条主线:Node 版本门槛与 API Schema 更新

纵观全表,"⚠ BREAKING CHANGES" 几乎贯穿每个大版本,其成因可归纳为两条清晰主线:

3.1 Node.js 最低版本门槛的两次跃升

这是影响面最大的破坏性来源,时间线为:

  • 2025-05-29(2.0.0)与 2025-06-30(3.0.0):将最低 Node 版本从 16 升级至 18,对应提交 682fbb8;
  • 2026-09-02(9.1.0)起:生成包依赖逐步升级至 Node 22(de9d20d),随后 9.1.1 / 10.0.0 / 11.0.0 出现"加回 Node 18 支持"(eccac1d)的过渡性修复;
  • 2026-09-14(13.0.0):将 apiary(生成工具链)最低 Node 版本再次提升至 22(#4020,4e5bae0),并明确标注"all packages"——即全仓库所有子包统一执行。

这一演进在 package.json 中有最直接的落点:当前 engines.node 为 >=22.0.0。对使用者而言,升级到 13.x 之前必须先确认运行环境的 Node 主版本满足要求,否则将直接触发 npm 的 engines 校验失败。

3.2 由上游 Discovery 文档驱动的 API 更新

另一类破坏性变更来自服务端 API 本身的 Schema 变化,CHANGELOG 中以 "apikeys: update the API" 形式出现的提交(如 0316790、602fdeb、e212177、43eff2a、630a4fd 等)即为此类。它的产生机制是:上游 API 的 Discovery 文档更新后,仓库通过生成器重新生成 v2.ts,再以 feature 或 breaking change 形式发版。由于 API Keys 服务端的字段增减、参数标注(如 required / optional)变化都会导致客户端类型定义变化,TypeScript 用户升级后可能出现类型不兼容,这是需要特别留意的兼容性风险点。

四、由 CHANGELOG 反推的 API 全貌:apikeys v2 的资源与方法面

CHANGELOG 中的 "update the API" 条目本身不披露细节,但仓库源码完整保留了当前 API 面,可作为解读这些更新的基准。

4.1 包入口与版本注册

src/apis/apikeys/index.ts 是子包入口,它从 googleapis-common 引入 getAPI / AuthPlus 等基础设施,注册了唯一版本 v2:

export const VERSIONS = {
  v2: apikeys_v2.Apikeys,
};

使用时可通过 google.apikeys('v2') 或直接 new apikeys({version: 'v2'}) 方式实例化(见 v2.ts 中 Options 接口与构造函数)。

4.2 三层资源结构与八个核心方法

从 v2.ts 的 Apikeys 类可以看到,客户端暴露了三个顶层资源:keys、operations、projects,其中 projects 下再嵌套 locations → keys(v2.ts)。与 discovery/apikeys-v2.json 中的 REST 定义逐一对应,完整方法清单如下:

资源路径 方法 HTTP 端点(REST) 返回类型
keys.lookupKey GET v2/keys:lookupKey V2LookupKeyResponse(v2.ts)
operations.get GET v2/{+name} Operation(v2.ts)
projects.locations.keys.create POST v2/{+parent}/keys Operation(v2.ts)
projects.locations.keys.get GET v2/{+name} V2Key(v2.ts)
projects.locations.keys.getKeyString GET v2/{+name}/keyString V2GetKeyStringResponse(v2.ts)
projects.locations.keys.list GET v2/{+parent}/keys V2ListKeysResponse(v2.ts)
projects.locations.keys.patch PATCH v2/{+name} Operation(v2.ts)
projects.locations.keys.delete DELETE v2/{+name} Operation(v2.ts)
projects.locations.keys.undelete POST v2/{+name}:undelete Operation(v2.ts)

几点值得注意的细节:

  • create / delete / patch / undelete 均返回 Schema$Operation 长时任务对象,而非直接返回 V2Key。这是 API Keys 服务采用异步资源操作模型的体现,客户端需要配合 operations.get 轮询任务完成状态(done 字段为 false 表示仍在进行,见 v2.ts)。
  • keyString(密钥明文)永远不会出现在常规读接口中:get、list 的响应均不含密钥值,只有专用的 getKeyString 才返回"加密并签名后的密钥值"(Schema$V2GetKeyStringResponse.keyString,v2.ts)。
  • Key 是全局资源:所有接口都注明 location 唯一支持值为 global,资源名形如 projects/{project}/locations/global/keys/{keyId}(v2.ts)。
  • 删除有 30 天软删除窗口:delete 说明文档指出删除后 30 天内可恢复,之后将被彻底清除;list 支持 showDeleted 参数把近 30 天内删除的 key 一并列出(v2.ts)。

4.3 核心数据模型:V2Key 与 V2Restrictions

Schema$V2Key(v2.ts)是管理对象的核心,字段包括:

  • displayName:可修改的人类可读名称,最大长度 63 字符;
  • annotations:非查询性的任意键值元数据,修改对象时应保留;
  • etag:服务端校验和,用于 update / delete 时的乐观并发控制(详见 AIP-154 语义,源码注释中给出);
  • restrictions:密钥使用限制(见下);
  • serviceAccountEmail:密钥绑定的服务账号邮箱(可选);
  • 只读字段:createTime / deleteTime / updateTime、uid(UUID4)、keyString、name。

Schema$V2Restrictions(v2.ts)定义了四类限制,对应密钥的四种应用场景:

限制类型 Schema 允许字段
Android V2AndroidKeyRestrictions allowedApplications[],内含 packageName 与 sha1Fingerprint(两种格式均接受:DA:39:...:09 或 DA39A3...D80709,输出统一为后者)
iOS V2IosKeyRestrictions allowedBundleIds[](Bundle ID 列表)
浏览器 V2BrowserKeyRestrictions allowedReferrers[](Referrer URL 正则表达式列表)
服务器 V2ServerKeyRestrictions allowedIps[](调用方 IP 地址列表)

另有 apiTargets(V2ApiTarget<a href="https://link.gitcode.com/i/0cb58f0cba2f4af8133cecabd039894e" target="_blank">],[v2.ts)用于将密钥限定到特定服务与方法:service 使用规范服务名(如 translate.googleapis.com),methods 为空表示允许该服务的全部方法,支持 Get*、translate.googleapis.com.Get* 这类通配写法。语义上"请求命中任一限制即被放行;若未指定任何限制,则全部目标均被允许"(v2.ts)。

4.4 方法级参数细节(来自 Params 接口)

  • create.keyId:可选的自定义 ID,须匹配正则 a-z?,不能是 UUID 形态,长度上限 63(v2.ts);
  • patch.updateMask:字段掩码,可修改字段为 display_name、restrictions、annotations;缺省时按 wire 上设置的允许字段隐式处理,特殊值 "*" 表示替换全部可修改字段(v2.ts);
  • delete / patch 均支持 checkExistingUsage(定义检查既有使用行为)与 etag(乐观并发);
  • list.pageSize / pageToken / showDeleted 用于分页与软删除过滤(v2.ts);
  • lookupKey.keyString:传入密钥明文,反向查找其所属项目与资源名,若密钥已被彻底清除则 name 为空(v2.ts)。

五、认证与授权:OAuth 2.0 作用域全集

所有 apikeys 方法都需要 OAuth 2.0 或服务账号凭证,这在 discovery/apikeys-v2.json 与源码示例中保持一致。可用的作用域共四个:

Scope 权限描述
https://www.googleapis.com/auth/apikeys 查看、编辑、配置和删除你的 Google Cloud API Keys 数据
https://www.googleapis.com/auth/apikeys.readonly 只读查看你的 Google Cloud API Keys 数据
https://www.googleapis.com/auth/cloud-platform 查看、编辑、配置和删除 Google Cloud 数据
https://www.googleapis.com/auth/cloud-platform.read-only 只读查看 Google Cloud 服务数据

在 v2.ts 的每个方法示例中可以看到完整调用范式:先通过 google.auth.GoogleAuth 构造认证客户端并指定 scopes,再通过 google.options({auth: authClient}) 绑定全局,最后调用具体方法。例如 lookupKey 的典型用法:

const {google} = require('googleapis');
const apikeys = google.apikeys('v2');

async function main() {
  const auth = new google.auth.GoogleAuth({
    scopes: [
      'https://www.googleapis.com/auth/apikeys',
      'https://www.googleapis.com/auth/apikeys.readonly',
      'https://www.googleapis.com/auth/cloud-platform',
      'https://www.googleapis.com/auth/cloud-platform.read-only',
    ],
  });
  const authClient = await auth.getClient();
  google.options({auth: authClient});

  const res = await apikeys.keys.lookupKey({
    keyString: 'your-api-key-string', // 必填:查找拥有该密钥值的项目
  });
  console.log(res.data);
  // 期望响应: { name: "projects/.../keys/...", parent: "projects/..." }
}

写操作类方法(create / patch / delete / undelete)通常只需 apikeys 与 cloud-platform 两个作用域,只读方法(get / list / getKeyString / lookupKey / operations.get)还可选用两个只读 scope,源码中的示例注释已按此区分。

六、安装、环境要求与升级实践

6.1 安装与最低环境

独立安装该子包:

npm install @googleapis/apikeys

当前 package.json 表明:包主入口为 build/index.js(编译产物),类型声明为 build/index.d.ts,运行时依赖 googleapis-common@^9.0.0,engines 要求 Node.js >= 22.0.0。若希望随整个 google-api-nodejs-client 一起使用,也可以直接 npm install googleapis 后通过 google.apikeys('v2') 调用。仓库同时提供了 webpack.config.js 与 webpack 脚本,供浏览器端打包场景使用。

6.2 依据 CHANGELOG 制定升级策略

结合前文的两条破坏性变更主线,升级决策可以简化为两步判断:

  1. 先看运行时:目标版本的 engines.node 是否与你的 Node 环境匹配。2.x / 3.x 要求 Node 18,13.x 要求 Node 22,中间 9.1.x~12.x 存在"加回 Node 18 支持"的过渡状态,若停留在 Node 18 可优先选择这些过渡版本或更早版本;
  2. 再看类型面:大版本中的 "apikeys: update the API" 条目意味着 Schema 类型可能变化,TypeScript 项目升级后应重新执行类型检查,重点核对 V2Key / V2Restrictions 相关字段是否仍在。

此外,README 已声明该库处于维护模式,官方推荐新项目评估迁移至 @google-cloud/apikeys(详见 README.md);存量项目则可继续锁定本包版本,并定期关注 CHANGELOG.md 中标注 ⚠ 的条目来判断是否触发升级。

七、结语:一份变更日志的完整解读闭环

src/apis/apikeys/CHANGELOG.md 的价值在于:它把版本号、Node 环境门槛、服务端 Schema 变更与生成器流水线四者绑定在一起,构成了 apikeys 子包最权威的演进档案。结合仓库内的 index.ts(入口注册)、v2.ts(完整方法面与数据模型)、package.json(版本与环境约束)以及 discovery/apikeys-v2.json(REST 元数据),任何开发者都能从"该不该升级、升级什么、升级后 API 长什么样"三个层面快速定位答案。这也是 Google API 客户端生成式仓库中,以 CHANGELOG 为抓手理解子包技术面的通用方法论。

登录后查看全文
google-api-nodejs-client