企业官网建设流程全解析

• 后端

本文以 src/apis/networksecurity/README.md 为核心骨架，结合该模块在 google-api-nodejs-client 仓库中的实际源码（v1.ts、v1beta1.ts、index.ts、package.json）与 Discovery 文档（discovery/networksecurity-v1.json），系统讲解@googleapis/networksecurity的安装方式、支持状态、资源 API 结构、认证方式与常见调用模式。读完本文，你将能够独立完成该包的安装、初始化、鉴权，并掌握 Address Groups、TLS 策略、安全配置等核心资源的调用方法，同时理解为何官方建议新项目优先考虑@google-cloud/network-security而非本模块。

一、模块定位与支持状态（Support status）

networksecurity是 Network Security API 的官方 Node.js 客户端封装，位于仓库的 src/apis/networksecurity 目录下，其底层服务域名为https://networksecurity.googleapis.com/（见 discovery/networksecurity-v1.json 中的baseUrl）。

根据模块自带的 README，该库当前处于维护模式（maintenance mode）：

• 它仍会持续发布，供已有存量应用的开发者继续使用；
• 官方明确不建议新项目使用本模块；
• 如果你正在构建新应用，或对旧应用做现代化改造，请改用@google-cloud/network-security库。官方认为后者更快、更易用、维护更好。

从仓库的实际代码看，这一判断有充分的依据：本模块的v1.ts与v1beta1.ts是由 Discovery 文档自动生成的代码（两个文件头部均标注THIS FILE IS AUTO-GENERATED），每个方法都通过googleapis-common的createAPIRequest走统一的通用请求管线；而@google-cloud/network-security是 Google Cloud 的专用客户端库，拥有更贴近领域模型的 API 设计与更积极的维护节奏。因此，决策建议：

• 新项目 → 使用@google-cloud/network-security；
• 存量项目迁移成本高、或需要在统一googleapis全家桶中管理 API → 可继续使用本模块。

二、安装与版本信息

2.1 安装命令

模块 README 给出的标准安装命令为：

$ npm install @googleapis/networksecurity

该包也可通过主仓库的googleapis统一入口使用（见下文“快速上手”）。从 package.json 可以看到当前版本为21.1.0，其关键元数据如下：

• main：build/index.js，types：build/index.d.ts，包同时提供 CommonJS 与 TypeScript 类型定义；
• engines.node：>=22.0.0（即要求 Node.js 22 或更高版本，这一要求在 CHANGELOG.md 中被标记为破坏性变更引入）；
• dependencies：仅依赖googleapis-common ^9.0.0（负责认证、请求管线等公共基础设施）；
• license：Apache-2.0。

2.2 版本演进与破坏性变更

从 CHANGELOG.md 可追踪该模块的演进脉络：

• 21.1.0（2026-10）：API 例行更新；
• 21.0.0（2026-09）：破坏性变更，将最低 Node 版本提升至 22；
• 20.0.0（2026-09）：破坏性变更，同样提升最低 Node 版本至 22。

这意味着升级到 v21 及以上的用户需要确保运行环境满足 Node 22+ 的硬性要求，否则包将无法正常工作。

三、快速上手：初始化与认证

模块的 index.ts 定义了三种使用入口：

1. 工厂函数networksecurity(version)：按版本字符串（'v1'/'v1beta1'）返回对应的Networksecurity客户端实例；
2. 选项对象networksecurity(options)：传入{version, auth, ...}类型的Options后返回实例；
3. 统一入口：通过主包googleapis的google.networksecurity('v1')获取实例（该用法在 v1.ts 的类注释中给出了示例）。

同时index.ts还导出了auth（AuthPlus实例）、networksecurity_v1、networksecurity_v1beta1以及googleapis-common的各类公共类型（GlobalOptions、MethodOptions、BodyResponseCallback等），方便 TypeScript 用户做类型推导与自定义请求配置。

3.1 最小可用示例（v1）

以下代码来自 v1.ts 中资源方法的标准@example注释，展示了完整的初始化、鉴权与调用链路：

const {google} = require('googleapis'); const networksecurity = google.networksecurity('v1'); async function main() { // 使用 Application Default Credentials（ADC）认证 const auth = new google.auth.GoogleAuth({ // 作用域可指定为数组，或单个以空格分隔的字符串 scopes: ['https://www.googleapis.com/auth/cloud-platform'], }); // 获取 auth client，并将其绑定到后续所有调用 const authClient = await auth.getClient(); google.options({auth: authClient}); // 发起 API 调用（此处为获取 location 信息） const res = await networksecurity.projects.locations.get({ name: 'projects/my-project/locations/my-location', }); console.log(res.data); } main().catch(e => { console.error(e); throw e; });

3.2 认证方式与作用域

该 API 只暴露一个 OAuth 2.0 作用域（见 discovery/networksecurity-v1.json 的auth.oauth2.scopes）：

也就是说，所有方法都要求cloud-platform级别的授权。官方推荐的本地开发认证流程为：

$ gcloud auth application-default login

（该步骤同样出现在 v1.ts 各方法的示例注释中。）除 ADC 外，v1.ts的StandardParameters还支持OAuth2Client、JWT（服务账号）、Compute（GCE 元数据）、UserRefreshClient、BaseExternalAccountClient、API Key 等多种凭证类型，你可以按场景选择。

四、资源 API 全貌：从源码结构理解调用层级

4.1 顶层资源：organizations 与 projects

在 v1.ts 中，Networksecurity类的构造函数实例化了两个顶层资源：

• organizations→Resource$Organizations（v1.ts）
• projects→Resource$Projects（v1.ts）

两者都挂载了locations子资源。organizations适用于企业组织级（organizations/{org}/locations/{location}/...）的资源配置；projects适用于项目级（projects/{project}/locations/{location}/...）的资源配置。

4.2 locations 下的子资源清单（v1）

从 v1.ts 中Resource$Projects$Locations的字段列表可见，Network Security API v1 在 locations 下提供了 22 类资源：

提示：v1beta1版本（v1beta1.ts）除以上资源外还额外提供ratelimitPolicies（限流策略），若你需要限流能力，可选用google.networksecurity('v1beta1')。

每个资源类都遵循统一的“驼峰命名 + 同名方法”模式，例如addressGroups对应Addressgroups类中的addItems、cloneItems、create、delete、get、list、patch、removeItems等方法（见 v1.ts 起）。

五、核心资源实战：Address Groups（地址组）

Schema$AddressGroup（v1.ts）定义了地址组资源的结构，其字段包括：

5.1 创建地址组

以下完整示例来自 v1.ts 的create方法注释，可直接复制运行：

const res = await networksecurity.projects.locations.addressGroups.create({ // 必填。要创建的 AddressGroup 资源的短名称。 // 长度 1-63 个字符，仅允许字母、数字、连字符和下划线，且不能以数字开头。例如 "authz_policy"。 addressGroupId: 'my-address-group', // 必填。AddressGroup 的父资源，格式为 projects/{project}/locations/{location} parent: 'projects/my-project/locations/my-location', // 可选。请求 ID，用于幂等重试（有效 UUID，不支持全零 UUID） requestId: '3d1d5f0e-9b6a-4c1e-8f2a-000000000000', requestBody: { name: 'projects/my-project/locations/my-location/addressGroups/my-address-group', type: 'IPv4', capacity: 100, items: ['198.51.100.1', '198.51.100.2'], description: '生产环境防火墙白名单地址组', }, }); console.log(res.data);

注意create属于长时运行操作（LRO）：从 v1.ts 的类型签名可见，其返回类型为Schema$Operation，而非直接的AddressGroup。你需要轮询返回的Operation.name来确认创建完成。

5.2 向地址组增删条目

• 增加条目：addressGroups.addItems，请求体字段为items（必填的待添加条目列表）与requestId（可选，用于幂等重试），见 v1.ts；
• 删除条目：addressGroups.removeItems，请求体同样包含items与requestId（对应Schema$RemoveAddressGroupItemsRequest，见 v1.ts）。

两者都需要传入完整资源路径addressGroup参数（格式projects/{project}/locations/{location}/addressGroups/{addressGroup}），且同为 LRO 操作。

5.3 查询与更新

• get：按name读取单个地址组；
• list：按parent分页列出地址组（支持pageSize、pageToken、filter、orderBy等标准查询参数）；
• patch：局部更新，配合updateMask指定要修改的字段；
• delete：删除地址组。

六、长时运行操作（LRO）与 Operation 结构

Network Security API 的创建、更新、删除类方法大多返回Schema$Operation（v1.ts），其关键字段为：

对应的operations资源（v1.ts）提供三个方法：

• get：查询操作状态；
• cancel：取消进行中的操作（请求体可为空对象{}）；
• delete：删除已完成的操作记录。

一个典型的长操作轮询模式：

const op = await networksecurity.projects.locations.addressGroups.create({...}); // 轮询直到 done === true let result = await networksecurity.projects.locations.operations.get({ name: op.data.name, }); while (!result.data.done) { await new Promise(r => setTimeout(r, 5000)); result = await networksecurity.projects.locations.operations.get({ name: op.data.name, }); } console.log(result.data.response);

七、其他重要资源一览

• AuthorizationPolicy（授权策略）：定义服务如何授权入站连接，action取值为ALLOW或DENY（见 v1.ts）。该资源本身不改变配置，需挂载到目标 HTTPS 代理或端点配置选择器后生效。
• SecurityProfile / SecurityProfileGroup（安全配置）：通过securityProfiles.create与securityProfiles.list（见 v1.ts）管理安全配置文件，可组合 TLS 检查、威胁防护等能力；组织级资源位于organizations.locations.securityProfiles。
• ClientTlsPolicy / ServerTlsPolicy（客户端/服务端 TLS 策略）：管理双向 TLS（mTLS）相关的客户端与服务器证书策略，serverTlsPolicies.create/list见 v1.ts。
• FirewallEndpoint 系列：防火墙端点及其与 VPC 的关联（firewallEndpoints、firewallEndpointAssociations），支持在组织级与项目级创建与管理。
• UrlLists：URL 列表资源，供防火墙/安全策略引用。
• DnsThreatDetectors：DNS 威胁检测器，提供get、list、patch等方法。

这些资源在代码中均表现为projects.locations.<resource>.<method>(params)的调用形式，方法参数的类型（Params$...）与方法返回类型（Schema$...）都由生成器在 v1.ts 与 v1beta1.ts 中给出，TypeScript 用户可获得完整的 IDE 提示与编译期校验。

八、项目规范：License、贡献与问题反馈

按模块 README 的约定，本库遵循以下项目规范：

• License：Apache 2.0，完整许可证文本见仓库根目录的 LICENSE。模块自身也通过package.json的license: "Apache-2.0"字段声明；
• 贡献：欢迎提交 Pull Request，官方建议先开一个 Issue 讨论再动手；详细规范见 CONTRIBUTING.md；
• 问题反馈：开发相关问题可到 StackOverflow 的google-api-nodejs-client标签下提问；发现 bug 请通过 Issues 提交，并提供可复现的示例；
• 代码规范：模块内置gts fix（自动修复）与gts check（静态检查）脚本，使用 Google TypeScript Style；可通过npm run compile（tsc -p .）本地编译，npm run webpack打包浏览器可用版本。

九、总结

@googleapis/networksecurity是 Network Security API 的官方维护模式客户端，适合已有存量应用继续使用；它通过 index.ts 暴露v1与v1beta1两个版本，覆盖地址组、授权策略、TLS 策略、安全配置、防火墙端点等丰富的网络安全管理能力。若你正开始一个新项目，请优先评估官方推荐的@google-cloud/network-security库；若你维护既有代码或希望与googleapis全家桶统一集成，本模块仍是一个可靠的选择——只需注意其 Node.js 22+ 的运行环境要求，并掌握本文所述的 ADC 认证、资源层级调用与 LRO 轮询模式即可。

• 后端