用途：帮助将 SAP CAP 项目迁移到 CDS 9 / @sap/cds 9（2025 年 5 月发布），并列出弃用 API、破坏性变更、新解析器、@sap/xssec v4 升级、@cap-js 系列替换等要点。参考资料指向 CAP 官方发布说明。
版本要求：package.json 中 engines.node 需 >=20，依赖 @sap/cds 与 @sap/cds-dk 均为 ^9。@sap/cds 7 及以下自 2025 年 5 月起 EOL，CDS CLI 命令对 cds < 8 会报错。
主要步骤：
- 升级包：npm install @sap/cds@latest @sap/cds-dk@latest，npm install @sap/xssec@latest（须 v4+）。
- 升级 @sap/xssec v4，移除旧的 xssec_compat 兼容标志，确保依赖为 ^4。
- 切换到 @cap-js 数据库服务：@sap/cds-hana → @cap-js/hana，@sap/cds-sqlite → @cap-js/sqlite（或 Node 22.5+ 原生 SQLite），@sap/cds-pg → @cap-js/postgres，并更新 cds.requires.db.kind。
- 启用新 CDS 解析器：package.json 中设置 cds.cdsc.newParser 为 true。新解析器对语法更严格，注解表达式须用括号包裹（如 @restrict: [{ where: (buyer = $user) }]），安全注解拼写错误由警告变为错误。
- 切换新协议适配器，移除 odata.compat 等兼容标志。
- 将旧 MTX 迁移到 @sap/cds-mtxs，卸载 @sap/cds-mtx 并安装 @sap/cds-mtxs，即由 @sap/cds-mtxs 自动激活多租户。
- 更新弃用 API：cds.User.tokenInfo→authInfo；draftProtection.enabled 移到 cds.security.authorization 下；@attachments.disable_facet→@UI.Hidden；Java 数组式 @protocols→@odata service；ctz containerize→cds up --to k8s；listOf/streamOf→list/stream，result.single(Class)→result.single()。
- 唯一约束处理：CDS 9 不再假定冲突列，也不再自动抛 ENTITY_ALREADY_EXISTS，原始数据库错误直接传播，需显式捕获处理。
- 更新 ESLint：安装最新 @sap/eslint-plugin-cds（v4 需 ESLint 9 或 10）并使用 flat config，含 JS 处理检查（2025 年 8 月新增）用于发现 SQL 注入风险。
迁移后检查：cds --version；cds compile srv/ --to json；npm test；npx eslint srv/ db/。
常见错误：跳过 xssec v4 导致生产认证失效；升级前未用新解析器测试；长期保留兼容标志（CDS 9 已移除）；忘记更新 devDependencies 中的 @cap-js/sqlite；未处理 ENTITY_ALREADY_EXISTS 假设移除。
CDS 10 已于 2026 年 6 月发布，如需迁移可参考专门的 cds10-migration，可用 @sap/cds-dk 10.x 的 cds upgrade 工具检查破坏性变更。官方参考见 cap.cloud.sap/docs/releases/2025/may25 与 /migration/cds10。