google-api-nodejs-client 中的 memcache 服务包:用 Node.js 管理 Google Cloud Memorystore for Memcached 实例
google-api-nodejs-client 中的 memcache 服务包:用 Node.js 管理 Google Cloud Memorystore for Memcached 实例
导读
本文聚焦 google-api-nodejs-client 仓库中自动生成的 memcache API 服务包(src/apis/memcache/README.md),讲解如何通过 @googleapis/memcache 在 Node.js 中创建、查询、更新和删除 Google Cloud Memorystore for Memcached 实例,并深入其源码(v1.ts、index.ts)剖析资源层级、实例模型与参数管理机制。读完本文,你将能够独立完成实例的完整生命周期管理、Memcached 参数的两阶段下发流程,以及理解该服务包当前处于维护模式时的迁移决策。
一、memcache 服务包定位与支持状态
根据 src/apis/memcache/README.md 的定义,memcache 服务包对应 Google Cloud Memorystore for Memcached API,用于在 GCP 中创建和管理 Memcached 实例。它属于 google-api-nodejs-client 按 API Discovery Document 自动生成的一类轻量客户端,与人工维护的高层客户端(如 @google-cloud/memcache)在定位上有明确区别。
README 中的 Support status 明确指出:
- 本库处于维护模式(maintenance mode),仅继续为已有应用提供支持;
- 如果正在构建新应用,或对旧应用做现代化改造,官方建议改用 @google-cloud/memcache(该库更快、更易用、维护更活跃);
- 详细说明可参考 Google Cloud 官方的 Client Libraries Explained 文档。
这是一个重要的工程决策信息:如果你的项目尚未引入该服务包,应优先评估使用 @google-cloud/memcache;如果代码库已基于 @googleapis/memcache 运行且短期内不打算迁移,本文的用法说明仍然完全适用。
二、安装与快速上手
安装
按 README 的标准安装命令:
$ npm install @googleapis/memcache
当前仓库中该子包版本为 17.0.1(见 src/apis/memcache/package.json),它唯一的外部依赖是 googleapis-common(^9.0.0),并要求 Node.js 版本不低于 22.0.0("engines": {"node": ">=22.0.0"})。需要注意:这个 @googleapis/memcache 是独立的单 API 子包;如果使用全家桶 googleapis,则不需要额外安装,直接通过 google.memcache('v1') 调用即可。
初始化与认证
源码中的 JSDoc 示例给出了标准的调用骨架(见 v1.ts):
const {google} = require('googleapis');
const memcache = google.memcache('v1');
认证推荐使用 Application Default Credentials(ADC),结合 GoogleAuth 统一绑定到所有后续请求:
const {google} = require('googleapis');
const memcache = google.memcache('v1');
async function main() {
const auth = new google.auth.GoogleAuth({
// Scopes 可以传数组,也可以传单个以空格分隔的字符串
scopes: ['https://www.googleapis.com/auth/cloud-platform'],
});
// 获取 auth client,并绑定到所有后续调用
const authClient = await auth.getClient();
google.options({auth: authClient});
// 从这里开始调用 memcache API
}
main().catch(e => {
console.error(e);
throw e;
});
运行前需要完成两件事(源码每个方法示例都重复强调的预处理步骤):
- 在 Google Cloud Console 启用 API:
memcache.googleapis.com; - 通过
gcloud auth application-default login登录 ADC。
此外,v1.ts 中的 StandardParameters 展示了所有请求共享的可选参数:auth(OAuth2Client/JWT/Compute/UserRefreshClient/BaseExternalAccountClient/GoogleAuth 或 API Key)、$.xgafv(错误格式)、access_token、alt(响应数据格式)、callback(JSONP)、fields(部分响应字段选择器)、key(API Key)、oauth_token、prettyPrint、quotaUser(配额标识)、uploadType/upload_protocol(上传协议)。
三、资源层级与方法总览
从 v1.ts 的 Memcache 类及后续 Resource$* 类的源码结构可以确认,该 API 的调用层级为:
memcache
└── projects
└── locations
├── instances
│ ├── applyParameters / create / delete / get / getTags
│ ├── list / patch / rescheduleMaintenance / setTags
│ └── updateParameters / upgrade
└── operations
├── cancel / delete / get / list
locations 自身还提供 get(获取区域信息)与 list(列出区域)两个方法。instances 与 operations 是 locations 下的两个子资源,源码分别在 v1.ts 中注册。
将方法、HTTP 语义与返回类型整理如下(依据 v1.ts 中每个方法实现段的 url、method 与泛型):
| 方法 | HTTP 方式 | 请求路径模式(rootUrl 为 https://memcache.googleapis.com/) |
返回类型 |
|---|---|---|---|
projects.locations.get |
GET | /v1/{+name} |
Schema$Location |
projects.locations.list |
GET | /v1/{+name}/locations |
Schema$ListLocationsResponse |
instances.applyParameters |
POST | /v1/{+name}:applyParameters |
Schema$Operation |
instances.create |
POST | /v1/{+parent}/instances |
Schema$Operation |
instances.delete |
DELETE | /v1/{+name} |
Schema$Operation |
instances.get |
GET | /v1/{+name} |
Schema$Instance |
instances.getTags |
GET | /v1/{+name}:getTags |
Schema$SetTagsResponse |
instances.list |
GET | /v1/{+parent}/instances |
Schema$ListInstancesResponse |
instances.patch |
PATCH | /v1/{+name} |
Schema$Operation |
instances.rescheduleMaintenance |
POST | /v1/{+instance}:rescheduleMaintenance |
Schema$Operation |
instances.setTags |
POST | /v1/{+name}:setTags |
Schema$SetTagsResponse |
instances.updateParameters |
POST | /v1/{+name}:updateParameters |
Schema$Operation |
instances.upgrade |
POST | /v1/{+name}:upgrade |
Schema$Operation |
operations.cancel |
POST | /v1/{+name}:cancel |
Schema$Empty |
operations.delete |
DELETE | /v1/{+name} |
Schema$Empty |
operations.get |
GET | /v1/{+name} |
Schema$Operation |
operations.list |
GET | /v1/{+name}/operations |
Schema$ListOperationsResponse |
从源码可以看到,每个方法实现中通过 createAPIRequest<Schema$Xxx> 发起请求,并声明 requiredParams 与 pathParams;例如 create 的必填参数是 parent(v1.ts),get/delete/patch 的必填参数是 name。这意味着调用时缺省会直接报参数错误。
四、核心数据模型:Schema$Instance 详解
理解 Schema$Instance(v1.ts)是使用该 API 的基础。它是创建、查询和更新实例时贯穿始终的核心类型,字段含义如下:
| 字段 | 类型 | 说明 |
|---|---|---|
name |
string | 必填。资源唯一名称,格式 projects/{project_id}/locations/{location_id}/instances/{instance_id};实例按区域管理,但节点可在区域内选择 zone |
authorizedNetwork |
string | 实例连接的 VPC 网络全名,不指定则使用 default 网络 |
nodeConfig |
Schema$NodeConfig |
必填。节点配置:cpuCount(每节点 CPU 数)、memorySizeMb(每节点内存 MiB) |
nodeCount |
number | 必填。实例中的节点数量 |
memcacheVersion |
string | Memcached 主版本,不指定则用最新支持版本,当前最新主版本为 MEMCACHE_1_5;小版本由系统自动决定 |
memcacheFullVersion |
string | 只读。实例上运行的完整 memcached 版本,格式如 memcached-1.5.16 |
parameters |
Schema$MemcacheParameters |
用户定义、将应用到每个节点 memcached 进程的参数集 |
labels |
map<string,string> | 用户提供的资源标签元数据 |
displayName |
string | 仅用于展示的名称,不超过 80 字符 |
zones |
string[] | 节点部署的 zone 列表,节点会在这些 zone 间均匀分布;不指定则默认覆盖区域内所有 zone |
reservedIpRangeId |
string[] | 私有服务接入(Private Service Access)关联的已分配 IP 地址段 ID,如 "test-default" 对应 10.0.0.0/29 |
maintenancePolicy |
Schema$GoogleCloudMemcacheV1MaintenancePolicy |
维护策略;不设置则按 Memorystore 内部灰度计划执行维护 |
maintenanceSchedule |
Schema$MaintenanceSchedule |
只读。已发布的维护时间表 |
maintenanceVersion |
string | 可选。用户手动触发的自助服务维护版本;为空表示未设置 |
availableMaintenanceVersions |
string[] | 只读。可应用到实例的维护版本列表 |
effectiveMaintenanceVersion |
string | 只读。实例当前生效的维护版本 |
memcacheNodes |
Schema$Node[] |
只读。节点列表,含 host、port、nodeId、zone、state、memcacheVersion、memcacheFullVersion、parameters |
instanceMessages |
Schema$InstanceMessage[] |
描述实例当前状态的消息列表(含 code 与 message) |
state |
string | 只读。实例状态 |
createTime / updateTime |
string | 只读。创建/更新时间 |
discoveryEndpoint |
string | 只读。Discovery API 端点 |
satisfiesPzi / satisfiesPzs |
boolean | 保留字段,仅供未来使用 |
补充说明 Schema$MemcacheParameters(v1.ts):它包含只读的 id(参数集唯一标识)和用户自定义的 params(键值对)。id 用于判断实例级参数与节点级参数是否一致——如果两者 id 不一致,说明节点上尚未应用最新参数,需要调用 applyParameters。这一设计正是下一节两阶段参数下发流程的依据。
五、实战:实例生命周期管理
以下示例均从 v1.ts 中各方法的 JSDoc 示例提炼而来,保留完整可运行骨架(认证部分见第二节)。
创建实例
create 的必填参数为 parent(projects/{project_id}/locations/{location_id})与查询参数 instanceId。instanceId 有严格约束(见 v1.ts):只能包含小写字母、数字和连字符;必须以字母开头;长度 1–40 字符;必须以字母或数字结尾;且在项目/区域内唯一,否则 API 会抛出 invalid argument 错误。
const res = await memcache.projects.locations.instances.create({
// Required. 实例逻辑名称
instanceId: 'my-instance',
// Required. 父资源名,location_id 指 GCP 区域
parent: 'projects/my-project/locations/my-location',
// Request body metadata
requestBody: {
authorizedNetwork: 'projects/my-project/global/networks/default',
nodeConfig: {
cpuCount: 1,
memorySizeMb: 1024,
},
nodeCount: 3,
memcacheVersion: 'MEMCACHE_1_5',
zones: ['us-central1-a', 'us-central1-b', 'us-central1-c'],
parameters: {
params: {
'max-item-size': '1048576',
'maxconns-fast-open': '0',
},
},
labels: {env: 'production'},
},
});
console.log(res.data);
// 示例响应(长时运行操作):
// { done: false, error: {}, metadata: {}, name: 'my_name', response: {} }
查询与列表
get 返回的是 Schema$Instance 而非 Operation:
const res = await memcache.projects.locations.instances.get({
name: 'projects/my-project/locations/my-location/instances/my-instance',
});
console.log(res.data.name, res.data.state, res.data.memcacheNodes);
list 的返回类型为 Schema$ListInstancesResponse(v1.ts),包含 instances 数组、nextPageToken(分页续传令牌)与 unreachable(无法访问的位置列表)。注意:如果请求的 parent 中 location_id 为 -,会跨所有区域聚合查询结果。
const res = await memcache.projects.locations.instances.list({
parent: 'projects/my-project/locations/-',
});
for (const instance of res.data.instances || []) {
console.log(instance.name, instance.state);
}
更新实例
patch 采用字段掩码(updateMask)机制进行部分更新,必填参数为 name(v1.ts):
const res = await memcache.projects.locations.instances.patch({
name: 'projects/my-project/locations/my-location/instances/my-instance',
// Required. 要更新的字段掩码,如 displayName、nodeCount、labels 等
updateMask: 'displayName,nodeCount',
requestBody: {
displayName: 'my-renamed-instance',
nodeCount: 5,
},
});
删除实例
const res = await memcache.projects.locations.instances.delete({
name: 'projects/my-project/locations/my-location/instances/my-instance',
});
// 返回 long-running Operation,可通过 operations.get 轮询完成状态
六、参数管理与维护操作
两阶段参数下发:updateParameters + applyParameters
这是 Memorystore for Memcached 的一个关键设计。源码注释(v1.ts)明确说明:updateParameters 只暂存(stage)参数,必须随后调用 applyParameters 才能将参数应用到实例的各节点。
// 阶段一:更新实例级参数定义
const res = await memcache.projects.locations.instances.updateParameters({
name: 'projects/my-project/locations/my-location/instances/my-instance',
requestBody: {
parameters: {
params: {
'max-item-size': '2097152',
'maxconns-fast-open': '1',
},
},
updateMask: 'params',
},
});
// 阶段二:将暂存的参数应用到节点
const res2 = await memcache.projects.locations.instances.applyParameters({
name: 'projects/my-project/locations/my-location/instances/my-instance',
requestBody: {
// 可选:只对指定 nodeIds 应用;不传则应用到所有节点
nodeIds: ['node-1', 'node-2'],
},
});
结合 Schema$MemcacheParameters.id 字段可以推断最佳实践:get 实例后对比实例参数 id 与 memcacheNodes[].parameters.id,若不一致,说明存在已暂存但未下发的参数,应触发 applyParameters。
维护与升级
rescheduleMaintenance:重新安排维护时间。请求体Schema$RescheduleMaintenanceRequest(v1.ts)包含rescheduleType(必填,若为SPECIFIC_TIME则必须同时设置scheduleTime)和scheduleTime(RFC 3339 时间戳,如2012-11-15T16:19:00.094Z)。upgrade:发起实例升级,请求体为Schema$GoogleCloudMemcacheV1UpgradeInstanceRequest(包含latest_memcache_version等目标版本字段),返回Schema$Operation。
资源标签:getTags / setTags
getTags 与 setTags 用于读取和覆盖资源直接绑定的 Tag。setTags 请求体(Schema$SetTagsRequest,见 v1.ts)支持 etag(基于当前绑定的校验和,用于防止并发覆盖的竞态条件)、requestId(UUID,保证幂等)以及 tags(键值对覆盖式写入,格式如 "123/environment": "production")。
七、长时运行操作(Operation)与状态轮询
创建、删除、更新、参数应用、维护重排与升级等方法返回的都是 Schema$Operation(v1.ts):
done:false表示仍在进行,true表示已完成(此时error或response可用);error:失败时的错误详情(Schema$Status);metadata:服务相关元数据,通常含进度信息;name:服务端分配的操作名,格式通常以operations/{unique_id}结尾;response:成功时的正常响应;若原方法成功时不返回数据(如 Delete),则为google.protobuf.Empty。
配套的 Schema$OperationMetadata(v1.ts)提供 apiVersion、cancelRequested、createTime、endTime、statusDetail(人类可读状态)、target(操作目标资源路径)和 verb(执行的动词)等只读字段,可用于观测操作进度。
推荐的轮询模式:
const op = await memcache.projects.locations.instances.create({...});
const opName = op.data.name;
// 轮询直到 done
let state = await memcache.projects.locations.operations.get({
name: opName,
});
while (!state.data.done) {
await new Promise(r => setTimeout(r, 5000));
state = await memcache.projects.locations.operations.get({name: opName});
}
if (state.data.error) {
console.error('操作失败:', state.data.error);
} else {
console.log('操作成功:', state.data.response);
}
operations 子资源还提供 list(按 {+name}/operations 列出操作)与 cancel(取消未完成操作)。
八、源码结构与扩展用法
src/apis/memcache 目录包含:README.md、CHANGELOG.md、index.ts(入口)、v1.ts 与 v1beta2.ts(两个 API 版本)、package.json、tsconfig.json 和 webpack.config.js。
入口文件 src/apis/memcache/index.ts 的核心逻辑:
export const VERSIONS = {
v1: memcache_v1.Memcache,
v1beta2: memcache_v1beta2.Memcache,
};
export function memcache(version: 'v1'): memcache_v1.Memcache;
export function memcache(options: memcache_v1.Options): memcache_v1.Memcache;
export function memcache(version: 'v1beta2'): memcache_v1beta2.Memcache;
// ...
export function memcache<T = ...>(versionOrOptions) {
return getAPI<T>('memcache', versionOrOptions, VERSIONS, this);
}
- 支持两种调用形态:传版本字符串(
'v1'/'v1beta2'),或传Options对象(其中version字段指定版本); - 版本注册表
VERSIONS表明 v1beta2 同样是受支持版本,其方法与 v1 基本对齐(共 17 处方法示例,见 v1beta2.ts); - 模块同时导出了
AuthPlus实例auth以及GlobalOptions、APIRequestContext、MethodOptions、BodyResponseCallback等公共类型,方便做二次封装。
关于底层请求:所有方法都以 rootUrl = options.rootUrl || 'https://memcache.googleapis.com/' 为基准拼接路径(v1.ts 等 17 处),可通过 google.options({rootUrl}) 覆盖(例如使用代理或 API 模拟环境时);每个方法都支持 Promise(async/await)与回调(callback)两种调用方式,并可通过 StreamMethodOptions 获得 Readable 流式响应。
若你的构建环境使用 Webpack,目录中的 webpack.config.js 提供了将本包打包进浏览器/前端应用的参考配置。
九、维护模式下的迁移指引
再次强调 README 中的官方建议:@googleapis/memcache 已进入维护模式。在做技术选型时:
- 已有应用:可以继续使用本文所述 API,无需立即迁移;
- 新应用 / 现代化改造:优先采用
@google-cloud/memcache,其 API 面向资源对象化设计,开发体验和维护状态都更优; - 迁移时两者的资源模型(project/location/instance/node/parameter)概念一致,本文第四节的数据模型表格可作为对照迁移的参考。
十、总结
memcache 服务包为 Node.js 开发者提供了一条轻量、类型安全的路径来管理 GCP 上的 Memcached 实例:通过 google.memcache('v1') 或 @googleapis/memcache 独立包接入,沿 projects.locations.instances 层级完成实例的增删改查,通过 updateParameters + applyParameters 两阶段流程安全下发 Memcached 参数,并借助 operations 子资源轮询长时操作。阅读 src/apis/memcache/README.md 获取服务包概览,深入 v1.ts 查看完整方法与 Schema 定义,即可在已有项目中直接落地使用。