# @cap-js-community/common 中文文档 规范地址：https://npmcn.com/package/%40cap-js-community/common/ 版本：0\.5\.5 npm 元数据更新时间：2026-10-22T08:04:47.415Z 中文译文更新时间：2026-11-09T01:37:02.958Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40cap-js-community/common 原文对照：https://npmcn.com/package/%40cap-js-community/common/?lang=original 项目主页：https://cap.cloud.sap/ 源码仓库：https://github.com/cap-js-community/common ## 关键信息（来自 npm 元数据） - 包体积（解压后）：142 kB，26 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - Node.js 要求：\>=22 - 运行依赖：4 个 - 首次发布：2025-04-09T09:02:06.171Z - 最新版本发布：2026-10-22T08:04:46.999Z - 近 30 天下载量：18591（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：30（近 12 个月 10 个） ## 中文简介 CAP 社区共同节点 ## 安装 ```sh npm install @cap-js-community/common ``` 也可以使用：`pnpm add @cap-js-community/common`、`yarn add @cap-js-community/common`、`bun add @cap-js-community/common` ## README # CAP 社区共同节点 [![npm version](https://img.shields.io/npm/v/@cap-js-community/common)](https://www.npmjs.com/package/@cap-js-community/common) [![monthly downloads](https://img.shields.io/npm/dm/@cap-js-community/common)](https://www.npmjs.com/package/@cap-js-community/common) [![REUSE status](https://api.reuse.software/badge/github.com/cap-js-community/common)](https://api.reuse.software/info/github.com/cap-js-community/common) [![Main CI](https://github.com/cap-js-community/common/actions/workflows/main-ci.yml/badge.svg)](https://github.com/cap-js-community/common/commits/main) ## 开始 - 运行 `npm add @cap-js-community/common` 内 `@sap/cds` 项目 ## 关于此工程 本项目为CDS服务提供共同功能,与 [SAP 云应用编程模型(节点.js)](https://www.npmjs.com/package/@sap/cds)。 。 。 . ## 目录 - **特征 :** - [复制缓存](https://npmcn.com/package/%40cap-js-community/common/#readme-replication-cache) - [移民检查](https://npmcn.com/package/%40cap-js-community/common/#readme-migration-check) - [限制费率](https://npmcn.com/package/%40cap-js-community/common/#readme-rate-limiting) - [Redis 客户端](https://npmcn.com/package/%40cap-js-community/common/#readme-redis-client) - [本地 HTML5 仓库](https://npmcn.com/package/%40cap-js-community/common/#readme-local-html5-repository) - [清洁发展机制构建器](https://npmcn.com/package/%40cap-js-community/common/#readme-cdm-builder) - [支持、反馈、贡献](https://npmcn.com/package/%40cap-js-community/common/#readme-support-feedback-contributing) - [行为守则](https://npmcn.com/package/%40cap-js-community/common/#readme-code-of-conduct) - [许可证发放](https://npmcn.com/package/%40cap-js-community/common/#readme-licensing) ## 复制缓存 复制缓存允许将一个服务(如db服务)缓存到租户-意识到SQLite数据库. 本地复制的SQLite数据库可以通过与原始服务相同的查询查询. ### 使用量 > 复制缓存使用SQLite作为本地数据库用于生产用途. 保证 `@cap-js/sqlite` 被安装为您的项目中的依赖性(而不是 dev 依赖性). ```cds @cds.replicate entity Books { key ID : Integer; title : localized String; descr : localized String; } ``` ### 说明 说明可用于实体级服务复制缓存: - `@cds.replicate: Boolean | Object`: 启用实体的复制缓存 - `@cds.replicate.ttl: Number`: 以毫秒计的缓存条目的时间到寿命( TTL) - `@cds.replicate.auto: Boolean`: 复制自动管理 - `@cds.replicate.preload: Boolean`: 实体预装复制 - `@cds.replicate.group: String`: 复制组名称 - `@cds.replicate.static: Boolean`: 静态复制非租户意识 默认取自CDS环境. ### 选项 可通过 CDS 环境通过 `cds.replicationCache` 节: - `plugin: Boolean`: 通过 CDS 插件激活复制缓存 `db` 服务。 默认是 `true` - `name: String`: 服务名. 默认是 `"db"` - `group: String`: 复制组名. 默认是 `"default"` - `credentials: Object`: SQLite 证书 - `database: String`: 数据库文件. 默认是 `":memory:"` 生产: `"data.sqlite"` - `ttl: Number`: 以毫秒为单位的缓存条目的TTL. 默认是 `1800000` (30分钟) - `check: Number`: 间接以检查大小和棱角. 默认是 `60000` (1分钟) - `stats: Number`: 中间对数统计。 默认是 `300000` (5分钟) - `size: Number`: 以字节表示的最大缓存大小. 默认是 `10485760` (10 MB)和生产中: `104857600` (100甲基溴) - `pipe: Boolean`:复制通过管道流出. `chunks` 未使用。 默认是 `true` - `chunks: Number`: 复制块大小。 默认是 `1000` - `retries: Number`:重复复制失败的复制. 默认是 `3` - `auto: Boolean`:复制是自动管理的。 默认是 `true` - `prune: Boolean`: 复制后直接检查和排出. 默认是 `true` - `validate: Boolean`: 验证复制记录的倒数. 默认是 `true` - `deploy: Boolean`: 部署整个计划,以便查询预测。 默认是 `true` - `preload: Boolean`: 预装所有可复制的实体。 默认是 `false` - `wait: Boolean`: 将读取查询延迟到复制完成. 默认是 `false` - `search: Boolean`: 复制缓存时允许搜索查询. 默认是 `true` - `measure: Boolean`: 测量和比较复制缓存和服务查询执行. 默认是 `false` - `tmpDir: Boolean`: 将复制缓存文件存储在临时目录中. 默认是 `false` - `baseDir: String`: 复制缓存文件的基础目录. 默认是 `"temp"` ### 测试 复制缓存不活动,每一次测试的默认值(`test` 简介). 它可以通过 CDS env 启用 : ```json { "cds": { "replicationCache": { "[test]": { "plugin": true } } } } ``` ## 移民检查 迁移检查可以检查CDS模式中不兼容的更改和 为兼容的更改通过 `cdsmc` 命令行工具. ### 选项 选项可以通过 CDS 环境通过 `cds.migrationCheck` 节: - `baseDir: String`: 指定迁移检查的基准目录。 默认是 `"migration-check"` - `whitelist: Boolean`: 需要为相容的修改维持一个白名单。 默认是 `true` - `checkMtx: Boolean`: 检查中包括 CDS MTXS 持久性 。 默认是 `true` - `keep: Boolean`:更新后保留白名单,否则白名单被清除. 默认是 `false` - `freeze: Boolean`:冻结持久性。 事件兼容的更改不被允许, 默认为 `false` - `label: String`: 标签在时间戳外描述更新的散列文件. 默认是 `""` - `buildPath: String`: 建设的CSN路径. 如果没有具体说明,则取自联合呼吁程序项目类型。 默认是 `null` - `adminHash: String`:指定可识别不相容变化的散列管理器。 默认是 `null` - `adminTracking: Boolean`: 管理员在管理员更改文件中承认的音轨更改。 默认是 `true` ### 使用量 #### 构建生产 NSN 生产CSN在不存在时首次被构建(否则会更新): - 构建 SSN : `cds build --production` - 更新生产 NSN : `cdsmc -u` > 生产CSN MUST被添加到版本控制中. #### 移民检查 移徙检查用于检查发展过程中的不相容变化: - 构建 SSN : `cds build --production` - 检查更改 : `cdsmc` 不相容的变化被检测出并报告为出错. 兼容的更改需要被白列(可以通过选项禁用). ##### 检查 **不兼容的更改 :** - 释放的实体不能被去除(`ReleasedEntityCannotBeRemoved`(中文(简体) ) - 释放实体的赋能状态草案不可更改(`ReleasedEntityDraftEnablementCannotBeChanged`(中文(简体) ) - 释放的元素不能被去除(`ReleasedElementCannotBeRemoved`(中文(简体) ) - 释放元素的密钥不能被更改(`ReleasedElementKeyCannotBeChanged`(中文(简体) ) - 释放元素的管理/未管理状态不能改变(`ReleasedElementManagedUnmanagedCannotBeChanged`(中文(简体) ) - 释放元素的虚拟状态不能更改( Q)`ReleasedElementVirtualCannotBeChanged`(中文(简体) ) - 释放元素的本地化状态不能改变( )`ReleasedElementLocalizationCannotBeChanged`(中文(简体) ) - 释放的元素不能被更改为不可更改( Q)`ReleasedElementNullableCannotBeChanged`(中文(简体) ) - 释放元素的数据类型不能被更改(`ReleasedElementTypeCannotBeChanged`(中文(简体) ) - 释放元素的数据类型不能缩短(`ReleasedElementTypeCannotBeShortened`(中文(简体) ) - 释放元素的规模或精确度不能降低(`ReleasedElementScalePrecisionCannotBeLower`(中文(简体) ) - 释放元素的目标不能改变(`ReleasedElementTargetCannotBeChanged`(中文(简体) ) - 释放元素的本质不能改变(`ReleasedElementCardinalityCannotBeChanged`(中文(简体) ) - 释放元素的状态不能改变(`ReleasedElementOnConditionCannotBeChanged`(中文(简体) ) - 释放元素的密钥条件不能更改(`ReleasedElementKeysConditionCannotBeChanged`(中文(简体) ) - 不允许在同一周期内启用日记模式并更改实体(`ReleasedEntityJournalModeAndEntityChangeIsNotAllowed`(中文(简体) ) - 不允许对已释放实体的索引进行修改(`ReleasedEntityIndexChangeIsNotAllowed`(中文(简体) ) **兼容更改 :** - 对已释放实体索引的修改必须列入白名单(`ReleasedEntityIndexChangeIsNotWhitelisted`(中文(简体) ) - 延长释放的元素的类型需要列入白名单(`ReleasedElementTypeExtensionIsNotWhitelisted`(中文(简体) ) - 扩大已释放元素的规模或精确度需要列入白名单(`ReleasedElementScalePrecisionExtensionIsNotWhitelisted`(中文(简体) ) - 将释放元素的类型更改为相容类型需要白名单(`ReleasedElementTypeChangeIsNotWhitelisted`(中文(简体) ) - 新实体没有列入白名单(`NewEntityIsNotWhitelisted`(中文(简体) ) - 新实体要素没有列入白名单(`NewEntityElementIsNotWhitelisted`(中文(简体) ) - 新实体元素如果不能失效,必须具有默认值(`NewEntityElementNotNullableDefault`(中文(简体) ) - 新实体指数不是白名单(`NewEntityIndexIsNotWhitelisted`(中文(简体) ) #### 更新生产 NSN 当没有发生迁移检查出错时, 生产 NSN 可以更新 : - 构建 SSN : `cds build --production` - 更新生产 NSN : `cdsmc -u` > 生产CSN MUST被添加到版本控制中. ### 白名单 维护白名单扩展文件 `migration-extension-whitelist.json` 对相容更改: - **白名单实体**数字 : ```json { "definitions": { "test.Test": {} } } ``` - **白名单实体元素**数字 : ```json { "definitions": { "test.Test": { "elements": { "value": {} } } } } ``` ### 管理模式 #### 不兼容的更改 接受的不兼容更改可以承认,不再作为错误报告: - 为不兼容的更改获取当前管理散列 : `cdsmc -a` - 在内置管理散列 : `cds.migrationCheck.adminHash` #### 冻结持久性 CDS持久性可以被(暂时)冻结,以防止任何与持久性模型相容的改变(也相容): - 激活/解除巢穴中的持久性冻结 `cds.migrationCheck.freeze` - 冻结/解冻持久性: `cdsmc -u -a` - 文件 `./csn-prod.freeze` 用于表示持久性被冻结 ### 管道 移民检查可以用于管道(例如Pull Request选民的一部分) 确保不引入不兼容的更改: - 构建检查( C) : `cds build --production && cdsmc` - 更新生产 NSN : `cds build --production && cdsmc -u` > 生产CSN MUST被添加到版本控制中. ## 限制费率 限制费率可以限制每个服务和租户的申请数量. ### 使用量 ```cds @cds.rateLimiting service BookshopService { entity Books @readonly as projection on test.Books; } ``` ### 说明 - `@cds.rateLimiting: Boolean`:服务费率限制 - `@cds.rateLimiting.maxConcurrent: Number`: 每项服务和租户同时提出的申请最多 - `@cds.rateLimiting.maxInWindow: Number`: 每项服务和租户在定义窗口中的最大请求数量 - `@cds.rateLimiting.window: Number`: 窗口长度以毫秒计 ### 选项 选项可以通过 CDS 环境通过 `cds.rateLimiting` 节: - `plugin: Boolean`: 速率限制通过CDS插件被激活,用于注释服务. 默认是 `true` - `maxConcurrent: Boolean`: 每项服务和租户同时提出的申请最多。 默认是 `3` - `maxWindow: Boolean`: 每个服务和租户在定义窗口中的最大请求数量。 默认是 `10000` (10秒钟) - `window: Boolean`: 窗口长度以毫秒为单位. 默认是 `3600000` (1小时) - `retry: Boolean`默认为 `5` ### 重写 Redis 选项可以在 CDS 内提供如下: ```json { "cds": { "requires": { "redis-rateLimiting": { "vcap": { "tag": "my-redis" }, "options": {} } } } } ``` 对于共享 redis 配置 Redis 服务名,可以在 CDS env 中提供如下内容: ```json { "cds": { "requires": { "redis-rateLimiting": false, "redis": { "vcap": { "tag": "my-redis" }, "options": {} } } } } ``` ### 测试 费率限制是每一次测试的默认不活动(`test` 简介). 它可以通过 CDS env 启用 : ```json { "cds": { "rateLimiting": { "[test]": { "plugin": true } } } } ``` ## Redis 客户端 提供Redis客户端代理商连接Redis服务. ### 使用量 #### 主要默认单子 ```js const { RedisClient } = require("@cap-js-community/common"); const mainClient = await RedisClient.create().createMainClientAndConnect(options); ``` #### 主要名称为单子 ```js const { RedisClient } = require("@cap-js-community/common"); const mainClient = await RedisClient.create("name").createMainClientAndConnect(options); ``` #### 自定义名称 ```js const { RedisClient } = require("@cap-js-community/common"); const client = await new RedisClient("name").createClientAndConnect(options); ``` ### 选项 选项可以通过 CDS 环境通过 `cds.redis` 节: Redis 选项可以在 CDS 内提供如下: ```json { "cds": { "requires": { "redis": { "vcap": { "tag": "redis-cache" }, "options": {} } } } } ``` 自定义名称的具体Redis选项可以建立如下: ```json { "cds": { "requires": { "redis-customName": { "vcap": { "tag": "redis-cache" }, "options": {} } } } } ``` ```js const { RedisClient } = require("@cap-js-community/common"); const mainClient = await RedisClient.create("customName").createMainClientAndConnect(options); ``` 此外,在创建期间,可以通过下列方式将选项传递给Redis客户端: `options` 参数 : ```js const { RedisClient } = require("@cap-js-community/common"); const mainClient = await RedisClient.create().createMainClientAndConnect(options); ``` 关于Redis的详细情况 `createClient` 配置选项见 [Redis 客户端配置](https://github.com/redis/node-redis/blob/master/docs/client-configuration.md)。 。 。 . ### Redis 哨兵支援系统 Redis 哨兵模式在 `credentials.sentinel_nodes` 并优先于集群模式. ```json { "cds": { "requires": { "redis": { "credentials": { "sentinel_nodes": [ { "host": "sentinel1.example.com", "port": 26379 }, { "host": "sentinel2.example.com", "port": 26379 } ], "master_name": "myprimary" } } } } } ``` 这个 `master_name` 识别雷地斯控制了哨兵监视器 或者,主名可以作为URI碎片在 `credentials.uri` (例如, `redis://host#myprimary`) (中文(简体) ). 若为 `sentinel_nodes[].port` ,默认为 `26379`两者 `host` 财务报告和审定财务报表 `hostname` 用于节点地址. ## 本地 HTML5 仓库 针对包括Approuter组件在内的混合环境开发HTML5应用,需要本地HTML5寄存器来直接测试UI5应用程序的更改而无需部署到远程HTML5寄存器. ### 使用量 - 创建一个 `default-env.json` 内 `approuter` 文件夹,包括来自部署环境的有效 HTML5 寄存器配置 : ```json { "VCAP_SERVICES": { "html5-apps-repo": [ { "credentials": { "uri": "https://html5-apps-repo-rt.cfapps.sap.hana.ondemand.com" } } ] } } ``` - 调用命令 : `local-html5-repo` (简称: `lh5r`(中文(简体) ) 所有应用程序和图书馆都位于 `app` 文件夹并包含一个 `ui5.yaml` 重定向到本地 HTML5 仓库 服务于本地文件系统。 所有其他请求都被代理到远程HTML5寄存器. ## 清洁发展机制构建器 清洁发展机制构建器允许构建一个清洁发展机制文件 `cdm.json` 从应用程序、角色和门户内容: - 建立清洁发展机制: `cdm-build` 生成的清洁发展机制是在 `app/cdm.json`。 。 。 . ### 选项 : - `-f, --force`: 覆盖现有的CDM文件. 默认是 `false` - `-t, --target`: 指定生成的CDM文件的目标路径. 默认是 `app/cdm.json` ## 支持、反馈、贡献 此项目可通过下列方式对特性请求/建议、错误报告等开放: [GitHub 问题](https://github.com/cap-js-community/common/issues)鼓励并始终欢迎各方作出贡献和反馈。 关于如何作出贡献的更多信息,项目结构以及额外贡献信息见我们 [贡献准则](https://npmcn.com/package/%40cap-js-community/common/CONTRIBUTING.md)。 。 。 . ## 行为守则 作为成员、贡献者和领导人,我们保证使参加我们的社区成为每个人不受骚扰的经历。 通过参与这个项目,你同意遵守 [行为守则](https://npmcn.com/package/%40cap-js-community/common/CODE_OF_CONDUCT.md) 在任何时间. ## 许可证发放 版权2025 SAP SE或SAP下属公司和共同出资人。 请看我们的 [自由主义](https://npmcn.com/package/%40cap-js-community/common/LICENSE) 版权和许可证信息。 详细信息,包括第三方组成部分及其许可证/版权信息 [通过REUSE工具](https://api.reuse.software/info/github.com/cap-js-community/common)。 。 。 . ## 常见问题 ### @cap-js-community/common 是什么？ CAP 社区共同节点 ### 如何安装 @cap-js-community/common？ 在项目目录运行 npm install @cap-js-community/common，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cdm、lh5r、cdsmc、cdm-build、migration-check、local-html5-repo，可以用 npx cdm 直接运行。 ### @cap-js-community/common 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @cap-js-community/common 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @cap-js-community/common 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @cap-js-community/common 可以商用吗？ @cap-js-community/common 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @cap-js-community/common 的下载量有多少？ 根据 npm 官方下载统计，@cap-js-community/common 在 2026/10/09 – 2026/11/07 这 30 天内被下载 18,591 次，日均约 620 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @cap-js-community/common 还在维护吗？ 最新版本 0\.5\.5 发布于 2026/10/22（18 天前）；至今共发布 30 个版本，其中过去 12 个月发布了 10 个；首次发布于 2025/04/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。