cap-developer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

What I do

我做什么

Provide correct, lean, idiomatic guidance for CAP development — from project setup and CDS modeling through declarative annotations and programmatic event handlers.

This SKILL.md is a router. Each topic lives in its own reference file so it can be loaded and cross-referenced on its own. Read only the file(s) the task needs.

为 CAP 开发提供正确、精简且符合惯用写法的指导——涵盖项目设置和 CDS 建模，一直到声明式注解和编程式事件处理器。

本 SKILL.md 是一个路由器。每个主题都位于各自的参考文件中，因此可以单独加载和交叉引用。只读取任务所需的文件。

Reference map

参考映射

Topic	File	Load when
Domain model + service projections	`references/cds-modeling.md`	Modeling entities/aspects/associations, or exposing them via projections
Declarative annotations (validation, constraints, auth)	`references/declarative.md`	Adding validation, mandatory/readonly/computed values, `@restrict` / `@requires`
Custom event handlers	`references/custom-logic.md`	Only when annotations can't express the rule; before/on/after logic
Sample / seed data	`references/sample-data.md`	Generating test data with the CLI
Node.js runtime specifics	`references/nodejs.md`	The project is a CAP Node.js app
Java runtime specifics	`references/java.md`	The project is a CAP Java app

主题	文件	加载时机
领域模型 + 服务投影	`references/cds-modeling.md`	对实体、切面和关联进行建模，或通过投影公开这些内容时
声明式注解（验证、约束、授权）	`references/declarative.md`	添加验证、必填/只读/计算值、 `@restrict` / `@requires` 时
自定义事件处理器	`references/custom-logic.md`	仅当注解无法表达规则时；在之前/期间/之后逻辑中使用
示例/种子数据	`references/sample-data.md`	使用 CLI 生成测试数据时
Node.js 运行时 specifics	`references/nodejs.md`	项目是 CAP Node.js 应用时
Java 运行时 specifics	`references/java.md`	项目是 CAP Java 应用时

Runtime Choice

运行时选择

When in a new project, use the globally installed

@sap/cds-dk

(cli:

cds

). Defer the language choice until necessary. This choice is only necessary once code is added or the app is deployed.

When only working with cds models, you can simply start with

cds w

without needing to define a runtime.

在新项目中，使用全局安装的

@sap/cds-dk

（CLI：

cds

）。在必要时再决定语言选择。只有在添加代码或部署应用后，才需要做出这一选择。

如果只处理 CDS 模型，可以直接使用

cds w

启动，无需定义运行时。

Documentation source

文档来源

Before guessing at APIs or annotations — and before changing an existing project's model — consult authoritative CAP documentation. Use whichever source is available; never guess URLs or invent APIs:

CAP MCP server (preferred when present). Use it to:
- Search CAP documentation before guessing at APIs or annotations
- Read the effective CDS model of an existing project before adding or changing anything
capire LLM docs (fallback when no MCP server is configured). The official docs expose LLM-friendly entry points — use these instead of ad-hoc web searches:
- ```
https://cap.cloud.sap/docs/llms.txt
```
  — a curated index of every documentation page; start here to locate the right topic.
- ```
https://cap.cloud.sap/docs/llms-full.txt
```
  — the full documentation concatenated into one file, for when you need the complete text.
- ```
https://cap.cloud.sap/docs/sitemap.md
```
  — the semantic sitemap of all pages.
- Any page is available as markdown by appending
```
.md
```
  to its URL (e.g.
```
https://cap.cloud.sap/docs/get-started/bookshop.md
```
  ) or by sending an
```
Accept: text/markdown
```
  header. Follow links from
```
llms.txt
```
  /
```
sitemap.md
```
  to the exact page rather than guessing a path.
- Inspect the effective CDS model without the MCP server via
```
cds compile <path>
```
  (e.g.
```
cds compile srv --to edmx
```
  ).

Never use CAP docs as a Fiori/SAPUI5 reference. They contain useful information about how CAP integrates with Fiori/SAPUI5 but are not a complete reference for those frameworks.

Caveat on release notes and version tables: documentation sourced from release notes or version recommendation tables may be outdated — they reflect what was true at the time of that release, not necessarily today. Always cross-check version-specific claims (e.g. "recommended Node.js version") against live sources like

cds version

npm view

, or the current Getting Started page rather than trusting a snapshot from a past release note.

在猜测 API 或注解之前，以及在更改现有项目的模型之前，请查阅权威的 CAP 文档。使用任何可用的来源；绝不猜测 URL 或虚构 API：

CAP MCP server（存在时优先使用）。 用于：
- 在猜测 API 或注解之前搜索 CAP 文档
- 在添加或更改任何内容之前，读取现有项目的有效 CDS 模型
capire LLM 文档（未配置 MCP server 时的后备方案）。 官方文档提供了适合 LLM 的入口——应使用这些入口，而不是临时进行网络搜索：
- ```
https://cap.cloud.sap/docs/llms.txt
```
  —所有文档页面的精选索引；从这里开始查找正确的主题。
- ```
https://cap.cloud.sap/docs/llms-full.txt
```
  —拼接为一个文件的完整文档，适用于需要完整文本的场景。
- ```
https://cap.cloud.sap/docs/sitemap.md
```
  —所有页面的语义化站点地图。
- 任何页面都可以通过在 URL 后追加
```
.md
```
  转换为 Markdown（例如
```
https://cap.cloud.sap/docs/get-started/bookshop.md
```
  ），或者发送
```
Accept: text/markdown
```
  请求头。应从
```
llms.txt
```
  /
```
sitemap.md
```
  跟踪链接找到确切页面，而不是猜测路径。
- 未配置 MCP server 时，可通过
```
cds compile <path>
```
  （例如
```
cds compile srv --to edmx
```
  ）检查有效的 CDS 模型。

绝不要将 CAP 文档用作 Fiori/SAPUI5 的参考资料。它们包含有关 CAP 如何与 Fiori/SAPUI5 集成的有用信息，但不是这些框架的完整参考资料。

**关于发布说明和版本表的注意事项：**来源于发布说明或版本推荐表的文档可能已经过时—— 它们反映的是发布当时的情况，不一定适用于当前版本。对于与版本相关的说法（例如“推荐的 Node.js 版本”），始终应使用

cds version

、

npm view

或当前的入门页面等实时来源进行交叉核对，而不要依赖过去发布说明中的快照。

Project setup rules

项目设置规则

Start a new project with:

cds init <name>        # creates a subdirectory; omit <name> to init in cwd
cd <name>
cds watch              # start the dev loop (works without a runtime for pure modeling)

When the runtime is known upfront, pass

--java

--nodejs

cds init

(see the runtime-specific reference files for details).

Never run
```
cds add sample
```
— it scaffolds a full demo app into the project.
Use
```
cds add tiny-sample
```
only if the user explicitly wants a minimal starter model.
Use
```
cds add <feature>
```
(e.g.
```
hana
```
,
```
xsuaa
```
,
```
approuter
```
,
```
mta
```
) to add features incrementally and only when needed (e.g. when deployment is requested).

使用以下命令启动新项目：

cds init <name>        # 创建一个子目录；省略 <name> 可在当前目录中初始化
cd <name>
cds watch              # 启动开发循环（纯建模场景无需运行时即可使用）

如果事先已明确运行时，请向

cds init

传递

--java

或

--nodejs

（有关详细信息，请参阅运行时专属的参考文件）。

绝不运行
```
cds add sample
```
——它会在项目中生成完整的演示应用。
仅当用户明确需要最小化的入门模型时，才使用
```
cds add tiny-sample
```
。
使用
```
cds add <feature>
```
（例如
```
hana
```
、
```
xsuaa
```
、
```
approuter
```
、
```
mta
```
）按需逐步添加功能，并且只在确有需要时添加（例如用户要求部署时）。

Working order

工作顺序

Model the domain →
```
references/cds-modeling.md
```
Expose services via projections →
```
references/cds-modeling.md
```
Add constraints declaratively first →
```
references/declarative.md
```
Write handlers only where annotations fall short →
```
references/custom-logic.md
```
(+ the runtime file
```
references/nodejs.md
```
or
```
references/java.md
```
)
Generate sample data →
```
references/sample-data.md
```

对领域进行建模 →
```
references/cds-modeling.md
```
通过投影公开服务 →
```
references/cds-modeling.md
```
优先以声明方式添加约束 →
```
references/declarative.md
```
仅在注解无法满足需求的位置编写处理器 →
```
references/custom-logic.md
```
（以及运行时文件
```
references/nodejs.md
```
或
```
references/java.md
```
）
生成示例数据 →
```
references/sample-data.md
```

Don't

禁止事项

Write handlers for things the generic service provider already handles
Hardcode tenant IDs, system IDs, or credentials anywhere
Put user-facing strings inline — use
```
_i18n/
```
bundles
Run
```
cds add sample
```

Runtime-specific don'ts (e.g.

await

inside

cds.on('served', ...)

in Node) live in the respective reference file.

为通用服务提供程序已经处理的功能编写处理器
在任何位置硬编码租户 ID、系统 ID 或凭据
将面向用户的字符串内联编写——应使用
```
_i18n/
```
bundle
运行
```
cds add sample
```

运行时专属的禁止事项（例如在 Node 中于

cds.on('served', ...)

内使用

await

）位于各自的参考文件中。