@cap-js-community/common

中文文档

0.5.5发布于 2026/10/22Apache-2.0TypeScriptCommonJS构建来源已验证近 30 天下载 1.9万

CAP 社区共同节点

文档目录31 节

开始
关于此工程
目录
复制缓存
使用量
说明
选项
测试
移民检查
选项
使用量
白名单
管理模式
管道
限制费率
使用量
说明
选项
重写
测试
Redis 客户端
使用量
选项
Redis 哨兵支援系统
本地 HTML5 仓库
使用量
清洁发展机制构建器
选项 :
支持、反馈、贡献
行为守则
许可证发放

CAP 社区共同节点

开始

运行 npm add @cap-js-community/common 内 @sap/cds 项目

关于此工程

本项目为CDS服务提供共同功能,与 SAP 云应用编程模型(节点.js)。。。 .

复制缓存

复制缓存允许将一个服务(如db服务)缓存到租户-意识到SQLite数据库. 本地复制的SQLite数据库可以通过与原始服务相同的查询查询.

使用量

复制缓存使用SQLite作为本地数据库用于生产用途. 保证 @cap-js/sqlite 被安装为您的项目中的依赖性(而不是 dev 依赖性).

@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 启用 :

{
  "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 对相容更改:

白名单实体数字 :

{
  "definitions": {
    "test.Test": {}
  }
}

白名单实体元素数字 :

{
  "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.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 内提供如下:

{
  "cds": {
    "requires": {
      "redis-rateLimiting": {
        "vcap": {
          "tag": "my-redis"
        },
        "options": {}
      }
    }
  }
}

对于共享 redis 配置 Redis 服务名,可以在 CDS env 中提供如下内容:

{
  "cds": {
    "requires": {
      "redis-rateLimiting": false,
      "redis": {
        "vcap": {
          "tag": "my-redis"
        },
        "options": {}
      }
    }
  }
}

测试

费率限制是每一次测试的默认不活动(test 简介). 它可以通过 CDS env 启用 :

{
  "cds": {
    "rateLimiting": {
      "[test]": {
        "plugin": true
      }
    }
  }
}

Redis 客户端

提供Redis客户端代理商连接Redis服务.

使用量

主要默认单子

const { RedisClient } = require("@cap-js-community/common");
const mainClient = await RedisClient.create().createMainClientAndConnect(options);

主要名称为单子

const { RedisClient } = require("@cap-js-community/common");
const mainClient = await RedisClient.create("name").createMainClientAndConnect(options);

自定义名称

const { RedisClient } = require("@cap-js-community/common");
const client = await new RedisClient("name").createClientAndConnect(options);

选项

选项可以通过 CDS 环境通过 cds.redis 节: Redis 选项可以在 CDS 内提供如下:

{
  "cds": {
    "requires": {
      "redis": {
        "vcap": {
          "tag": "redis-cache"
        },
        "options": {}
      }
    }
  }
}

自定义名称的具体Redis选项可以建立如下:

{
  "cds": {
    "requires": {
      "redis-customName": {
        "vcap": {
          "tag": "redis-cache"
        },
        "options": {}
      }
    }
  }
}

const { RedisClient } = require("@cap-js-community/common");
const mainClient = await RedisClient.create("customName").createMainClientAndConnect(options);

此外,在创建期间,可以通过下列方式将选项传递给Redis客户端: options 参数 :

const { RedisClient } = require("@cap-js-community/common");
const mainClient = await RedisClient.create().createMainClientAndConnect(options);

关于Redis的详细情况 createClient 配置选项见 Redis 客户端配置。。。 .

Redis 哨兵支援系统

Redis 哨兵模式在 credentials.sentinel_nodes 并优先于集群模式.

{
  "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 寄存器配置 :

{
  "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 问题鼓励并始终欢迎各方作出贡献和反馈。关于如何作出贡献的更多信息,项目结构以及额外贡献信息见我们贡献准则。。。 .

行为守则

作为成员、贡献者和领导人,我们保证使参加我们的社区成为每个人不受骚扰的经历。通过参与这个项目,你同意遵守行为守则在任何时间.

许可证发放

版权2025 SAP SE或SAP下属公司和共同出资人。请看我们的自由主义版权和许可证信息。详细信息,包括第三方组成部分及其许可证/版权信息通过REUSE工具。。。 .

版本与发布记录

@cap-js-community/common 共发布 30 个版本，首次发布于 2025/04/09；过去 12 个月发布了 10 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`0.5.5`latest	2026/10/22	18 天前
`0.5.4`	2026/09/25	1 个月前
`0.5.3`	2026/09/22	1 个月前
`0.5.2`	2026/09/21	1 个月前
`0.5.1`	2026/08/04	3 个月前
`0.5.0`	2026/07/03	4 个月前

关于 @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 和提交记录判断。

npm install @cap-js-community/common

pnpmpnpm add @cap-js-community/common
yarnyarn add @cap-js-community/common
bunbun add @cap-js-community/common

命令行npx cdmnpx lh5rnpx cdsmcnpx cdm-build

在你的项目目录中运行此命令。

近 30 天下载

18,591

约 1.9万次日均 620 次

统计周期 2026/10/09 – 2026/11/07
数据来自 npm 官方下载统计，今天更新

最新版本0.5.5发布于 18 天前

开源许可Apache-2.0宽松许可

包体积142 kB26 个文件 · 解压后

运行依赖4 个

模块格式CommonJS

TypeScript自带类型

Node.js>=22

发布版本30 个近 12 个月 10 个

首次发布2025/04/091.6 年前

元数据更新2026/10/22

每一个软件包背后，
都有分享与创造的人。