google-api-nodejs-client 中的 memcache 服务包:用 Node.js 管理 Google Cloud Memorystore for Memcached 实例

原创2026-10-14 19:26:401,890 阅读
文章标签:后端

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;
});

运行前需要完成两件事(源码每个方法示例都重复强调的预处理步骤):

  1. 在 Google Cloud Console 启用 API:memcache.googleapis.com;
  2. 通过 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 定义,即可在已有项目中直接落地使用。

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