google-api-nodejs-client 的 language 包:从 1.0 到 15.0 的版本演进、破坏性变更与升级指南
google-api-nodejs-client 的 language 包:从 1.0 到 15.0 的版本演进、破坏性变更与升级指南
本篇文章以仓库内 src/apis/language/CHANGELOG.md 为唯一主体脉络,结合 language 子包的 README、package.json 与生成源码,系统梳理 Google Cloud Natural Language API 官方 Node.js 客户端(@googleapis/language)三年来的 37 次发布记录:破坏性变更的主线(Node.js 最低版本从 18 提升到 22)、googleapis-common 依赖升级链、由生成器(generator)驱动的 API 更新模式,以及 v1 / v1beta1 / v1beta2 / v2 四个 API 版本的方法能力差异。读完本文,你将能读懂该 changelog 中每条记录背后的含义,并据此完成版本升级决策与代码迁移。
一、language 包是什么:Cloud Natural Language API 的官方 Node.js 客户端
src/apis/language 是 google-api-nodejs-client(Google 官方 Node.js 客户端库)中按 Cloud Natural Language API 的 Discovery 文档自动生成的一个独立子包。它对外发布为 npm 包 @googleapis/language,向开发者提供自然语言理解能力,包括情感分析(sentiment analysis)、实体识别(entity recognition)、实体情感分析(entity sentiment analysis)以及其他文本标注(text annotations)能力——这一服务描述同时出现在 README.md 与 v2.ts 的 Language 类注释中。
1.1 维护模式与替代库
README.md 明确提示:该库目前处于 maintenance mode(维护模式)。Google 为同一服务提供了多套库,此包仅为已有应用保留;新应用或正在现代化改造的存量应用,应改用 @google-cloud/language(README 称其更快、更易用、维护更好)。这是阅读 changelog 之前必须了解的大背景——后续版本记录中的"API 更新"更多是保持与后端 API 同步的例行维护,而非新增长期演进路线。
1.2 安装与基本用法
$ npm install @googleapis/language
在 googleapis 大包内使用时,通过版本选择器实例化:
const {google} = require('googleapis');
const language = google.language('v2');
package.json 显示当前发布版本为 15.0.1,engines 要求 Node.js >= 22.0.0,运行时唯一核心依赖为 googleapis-common ^9.0.0。入口文件 index.ts 通过 VERSIONS 映射表注册了 v1、v1beta1、v1beta2、v2 四个 API 版本,并导出 auth(AuthPlus 实例)以及 googleapis-common 的公共类型。
二、版本演进全景:三年 37 次发布的时间线
CHANGELOG.md 完整记录了从 2023-08-17 的 1.0.0 到 2026-09-23 的 15.0.1 的全部发布。下表按时间正序整理(类型列中的 F = Features,B = Bug Fixes,⚠ = BREAKING CHANGES):
| 版本 | 日期 | 类型 | 核心内容 |
|---|---|---|---|
| 1.0.0 | 2023-08-17 | B | 首次发布,API 更新(commit 86d4072、585690a) |
| 1.0.1 | 2023-08-17 | B | API 更新(86d4072、585690a) |
| 1.0.2 | 2023-08-25 | B | 依赖升级 googleapis-common 至 v7(9491ec1)、API 更新(86d4072) |
| 1.0.3 | 2023-10-11 | B | 依赖升级 googleapis-common v7、API 更新(b9c3e49、86d4072、585690a) |
| 1.0.4 | 2024-01-03 | B | API 更新(77252e1) |
| 1.0.5 | 2024-01-05 | B | API 更新(77252e1、b9c3e49) |
| 2.0.0 | 2024-03-12 | ⚠ F | 运行 generator(PR #3441、#3447),产生破坏性变更 |
| 3.0.0 | 2024-04-04 | ⚠ F | API 更新(1972ea6)+ generator(#3441、#3447),破坏性变更 |
| 3.0.1 | 2024-05-02 | B | API 更新(91caf34) |
| 4.0.0 | 2024-05-02 | ⚠ F | API 更新(1972ea6)+ generator(#3441、#3447)+ 修复(91caf34),破坏性变更 |
| 4.1.0 | 2024-10-30 | F | API 更新(923b951) |
| 5.0.0 | 2025-02-04 | ⚠ F | API 更新(ab1d906、923b951),破坏性变更 |
| 5.0.1 | 2025-03-18 | B | API 更新(91cfefe) |
| 6.0.0 | 2025-03-18 | ⚠ F | API 更新(ab1d906、923b951、修复 91cfefe),破坏性变更 |
| 7.0.0 | 2025-05-29 | ⚠ F | 升级到 Node 18(682fbb8) |
| 7.0.1 | 2025-06-04 | B | 依赖升级 googleapis-common 8.0.2-rc(f4b0990) |
| 8.0.0 | 2025-06-30 | ⚠ F | 升级到 Node 18;googleapis-common 8.0.2-rc;API 更新(34b2308) |
| 8.0.1 | 2025-07-08 | B | googleapis-common 8.0.0(#3731);API 更新(6153ccd、34b2308) |
| 1.0.0 | 2025-08-07 | B | 版本号重置后的再次 1.0.0;googleapis-common 8.0.0(#3731);API 更新(6153ccd) |
| 1.0.1 | 2025-08-13 | B | 同上 |
| 1.0.2 | 2025-08-21 | B | 同上 |
| 1.0.3 | 2025-08-25 | B | 同上 |
| 1.0.4 | 2025-08-26 | B | 同上 |
| 1.0.5 | 2025-08-27 | B | 同上 |
| 1.0.6 | 2025-08-28 | B | 同上 |
| 9.0.0 | 2025-09-16 | ⚠ B | "releasing for our libraries"(#3769);googleapis-common 8.0.0(#3731),破坏性变更 |
| 10.0.0 | 2025-10-15 | ⚠ F | 运行 generator(#3814),破坏性变更 |
| 10.0.1 | 2025-12-05 | B | API 更新(2eed516) |
| 11.0.0 | 2026-08-03 | ⚠ F | 运行 generator(#3955),破坏性变更 |
| 11.1.0 | 2026-09-02 | F | 运行 generator(#3992);生成包依赖升级至 Node 22(de9d20d) |
| 11.1.1 | 2026-09-09 | B | 回补 Node 18 支持(eccac1d) |
| 12.0.0 | 2026-09-09 | ⚠ F | apiary 最低 Node 版本提升到 22(#4011);generator(#3955);同时含回补 Node 18 与升级 Node 22 两项修复 |
| 13.0.0 | 2026-09-10 | ⚠ F | apiary 最低 Node 版本提升到 22(#4011);回补 Node 18 |
| 14.0.0 | 2026-09-10 | ⚠ F | apiary 最低 Node 版本提升到 22(#4011);generator(#3955);回补 Node 18 + 升级 Node 22 |
| 15.0.0 | 2026-09-14 | ⚠ F | apiary 最低 Node 版本提升到 22(#4020,全包统一) |
| 15.0.1 | 2026-09-23 | B | API 更新(437f9d5) |
从表中可以归纳出 language 包的三种主要变更来源:API 更新(update the API)、运行生成器(run the generator) 与 基础设施升级(Node 版本、googleapis-common)。下面分别展开。
三、破坏性变更主线:Node.js 最低版本从 18 提升到 22
CHANGELOG 中最醒目的 ⚠ BREAKING CHANGES 几乎全部指向同一件事:运行时 Node.js 最低版本要求的提升。
- 2025-05-29 / 06-30(7.0.0、8.0.0):两次标记 "upgrade to node 18"(commit
682fbb8),即最低支持版本提到 Node 18,官方将此类升级视为破坏性变更(旧的 Node 14/16 运行环境将不再受支持)。 - 2026-09-02 起(11.1.0):出现 "upgrade dependencies in generated packages to Node 22"(
de9d20d),生成包的依赖开始向 Node 22 迁移。 - 2026-09-09 至 09-14(12.0.0、13.0.0、14.0.0、15.0.0):连续四个大版本均标注 "Update apiary to minimum Node version of 22"(PR #4011、#4020),其中 15.0.0 的 #4020 明确说明这是 all packages(全部生成包) 的统一升级。
值得注意的是,12.0.0 / 13.0.0 / 14.0.0 的 Bug Fixes 中同时存在 "add back support for node 18"(eccac1d)与 "upgrade dependencies in generated packages to Node 22"(de9d20d)两条方向相反的修复,且 11.1.1 是纯粹的回补 Node 18 支持。从这些记录可以推断:Node 22 迁移在 2026 年 9 月经历了一个反复调整的过程——生成包内部依赖先被升级到 Node 22,随后又短暂回补对 Node 18 的支持,最终在 15.0.0 以全包统一门槛收口。
这一结论与当前仓库状态一致:package.json 中 "engines": {"node": ">=22.0.0"},仓库根目录 package.json(版本 185.0.0)同样声明 ">=22.0.0",并依赖 googleapis-common ^9.0.0。
升级影响:如果你的部署环境是 Node 18 或更低,从 11.x 升级到 12.x 以上将直接面临运行时兼容问题;在 Node 22 环境未就绪前,应将版本锁定在 11.1.1(最后一次明确"回补 Node 18"的版本)。
四、依赖升级:googleapis-common 从 v7 到 ^9.0.0
googleapis-common 是所有生成 API 子包共享的运行时基础设施,提供 createAPIRequest、GoogleConfigurable、getAPI、AuthPlus 以及 GlobalOptions、MethodOptions 等类型——这些在 index.ts 的导入语句中可以一一对应看到。它的每次升级都会以 Bug Fixes 形式出现在 changelog 中:
| 时间 | 版本记录 | 升级目标 |
|---|---|---|
| 2023-08/10 | 1.0.2、1.0.3 | googleapis-common v7(9491ec1) |
| 2025-06 | 7.0.1、8.0.0 | googleapis-common 8.0.2-rc(f4b0990) |
| 2025-07/08/09 | 8.0.1、1.0.x 系列、9.0.0 | googleapis-common 8.0.0(PR #3731,commit c9fdf4b) |
当前 package.json 中该依赖为 ^9.0.0,即随 15.0.x 版本线继续推进。由于 googleapis-common 封装了鉴权、请求调度与重试等核心逻辑,升级它通常不会改变 documents.* 方法的调用签名,但可能影响底层传输行为与类型定义,建议升级 language 包时同步关注其依赖版本。
五、generator 驱动的 API 更新与四个 API 版本的能力差异
5.1 两种 API 同步机制
changelog 中反复出现的两类记录,本质上是同一套自动化流水线的两种产物:
run the generator(运行生成器):当 Google 的 Discovery 文档或生成器模板本身发生变化时,维护者执行生成器重新产出src/apis/language下的全部源码。典型 PR 包括 #3441/#3447(2024-03 起多次)、#3814(10.0.0)、#3955(11.0.0)、#3992(11.1.0)。这类变更往往伴随 ⚠ BREAKING CHANGES 标记,因为端点的增删改都可能改变生成代码的公开 API。update the API(API 更新):针对单个 API 的增量同步,通常以 Bug Fixes 出现(如 15.0.1 的437f9d5),说明后端服务契约有小幅变动,客户端随之更新参数/字段定义。
5.2 从源码确认四版本方法矩阵
入口 index.ts 注册了 v1、v1beta1、v1beta2、v2 四个版本。对照四个生成文件 v1.ts、v1beta1.ts、v1beta2.ts、v2.ts 中 Resource$Documents 资源实际生成的 REST 端点(形如 /v2/documents:analyzeEntities),可得到当前仓库内的方法能力矩阵:
| 方法(documents.*) | v1 | v1beta1 | v1beta2 | v2 |
|---|---|---|---|---|
| analyzeEntities | ✅ | ✅ | ✅ | ✅ |
| analyzeEntitySentiment | ✅ | — | ✅ | — |
| analyzeSentiment | ✅ | ✅ | ✅ | ✅ |
| analyzeSyntax | ✅ | ✅ | ✅ | — |
| annotateText | ✅ | ✅ | ✅ | ✅ |
| classifyText | ✅ | — | ✅ | ✅ |
| moderateText | ✅ | — | ✅ | ✅ |
从源码结构看,v1 与 v1beta2 能力最全(7 个方法),v2 目前只包含 5 个方法(缺 analyzeEntitySentiment 与 analyzeSyntax 两个独立端点;v2 的情感/实体分析能力主要收敛进 analyzeSentiment、analyzeEntities 与统一的 annotateText)。v1beta1 最为精简(4 个方法,无实体情感、分类与内容审核)。这意味着:同样是 google.language('v2') 与 google.language('v1'),可用方法集合是不同的,迁移版本前应先对照上表核对所用端点是否保留。
5.3 一个完整的调用示例(v2)
v2.ts 中 analyzeEntities 的 JSDoc 给出了可直接运行的官方示例,其中 Document 请求体的字段(content、gcsContentUri、languageCode、type)与 encodingType 参数均来自该文件的 Schema$Document / 请求接口定义:
const {google} = require('googleapis');
const language = google.language('v2');
async function main() {
const auth = new google.auth.GoogleAuth({
scopes: [
'https://www.googleapis.com/auth/cloud-language',
'https://www.googleapis.com/auth/cloud-platform',
],
});
const authClient = await auth.getClient();
google.options({auth: authClient});
const res = await language.documents.analyzeEntities({
requestBody: {
document: {
type: 'PLAIN_TEXT',
content: 'Google is located in Mountain View.',
},
encodingType: 'UTF8',
},
});
console.log(res.data);
}
main().catch(e => {
console.error(e);
throw e;
});
由 Schema$Document 的定义可见(v2.ts):type 必填(未设置或为 TYPE_UNSPECIFIED 时返回 INVALID_ARGUMENT);content 与 gcsContentUri 二选一提供输入文本(后者为 gs://bucket_name/object_name 形式的 Cloud Storage URI,且不支持对象版本化);languageCode 可选,缺省时自动检测语言,支持 ISO 与 BCP-47 编码,若检测出的语言不被该方法支持则返回 INVALID_ARGUMENT。
六、值得注意的版本号重置现象(2025-08 的 1.0.x 系列)
在 CHANGELOG 的按时间顺序记录中,8.0.1(2025-07-08)之后并非 9.0.0,而是 2025-08-07 再次出现了一个带链接的 [1.0.0],随后按 1.0.1 → 1.0.6 逐日递增,直到 2025-09-16 才跳到 9.0.0。这 7 个 1.0.x 版本的内容几乎一致:googleapis-common 8.0.0 升级(#3731)与 API 更新(6153ccd)。
从 changelog 本身可以确认的事实是:该版本线确实出现了"8.0.1 之后重新从 1.0.0 起算"的记录,且 9.0.0 的发布说明("releasing for our libraries",#3769)也复用了 #3731。至于这是 release-please 版本管理工具的分支重置,还是发布流程调整导致的独立版本线,changelog 未提供进一步说明,这里不做断言。读者若在依赖中发现 ^1.0.6 与 9.0.0 并存,可结合本仓库 CHANGELOG 的完整记录判断归属。
七、升级与选型实践建议
- 新项目请直接使用
@google-cloud/language:README 明确说明本包处于维护模式,新应用不应再基于@googleapis/language起步(详见 README.md)。 - 存量项目升级前核对 Node 版本:当前版本线(12.x 及以上)要求 Node.js >= 22;若环境仍为 Node 18,锁定在 11.1.1 或 8.0.1(对应 Node 18 时代)更稳妥。
- 升级后复核方法矩阵:不同 API 版本(v1 / v1beta1 / v1beta2 / v2)暴露的
documents.*方法不同,升级生成包后建议对照 v1.ts、v1beta1.ts、v1beta2.ts、v2.ts 中实际生成的端点确认所用方法仍在。 - 关注依赖联动:
googleapis-common的升级(当前 ^9.0.0)可能带来底层鉴权与传输行为变化;与 language 包一同升级并在测试环境回归鉴权与请求流程。 - 持续跟踪 changelog:本包约每月 1~2 次发布,大部分是 API 同步(Bug Fixes),真正的破坏性变更集中在 Node 版本与 generator 运行两类,CHANGELOG.md 是判断升级风险的第一手资料。
八、总结
@googleapis/language 作为 google-api-nodejs-client 的自动生成子包,其 CHANGELOG 完整呈现了一条典型的 Google 官方生成库演进路径:以 Discovery 文档为源头、generator 为引擎、release-please 为版本管理,定期同步 API 契约,并在 2025~2026 年完成了从 Node 18 到 Node 22 的最低版本跃迁。对于使用者而言,读懂这份 changelog 的关键在于区分三类变更——API 增量更新(低风险)、generator 重跑(可能破坏签名)、Node/依赖升级(环境级破坏)——并牢记当前包已进入维护模式、新项目应转向 @google-cloud/language 的官方建议。