spring-data-jdbc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Detection guard

检测防护

Before applying any rule from this skill, confirm the target file imports from

org.springframework.data.relational.core.mapping

org.springframework.data.annotation

. If you see

jakarta.persistence.*

imports, stop and switch to the

spring-data-jpa

skill — the two stacks are not interchangeable and patterns from JPA (

HibernateProxy

@ManyToOne

@OneToMany

@JoinColumn

FetchType

) do not apply here.

在应用本技能的任何规则之前，请确认目标文件导入了

org.springframework.data.relational.core.mapping

org.springframework.data.annotation

中的内容。如果发现

jakarta.persistence.*

导入，请停止操作并切换到

spring-data-jpa

技能——这两个技术栈不可互换，JPA的模式（

HibernateProxy

、

@ManyToOne

、

@OneToMany

、

@JoinColumn

、

FetchType

）不适用于此处。

Harness compatibility

运行时兼容性

This skill is designed to work across multiple agent runtimes (Claude Code, Codex, OpenCode). Two harness-specific primitives are referenced by name in this skill; treat them as preferred-but-optional and degrade gracefully:

AskUserQuestion
(Claude Code structured prompt with multiple-choice options). When the runtime supports it, use it for Step 1.4 of every conventions file — the JSON examples in those files map to the tool's expected payload. When the runtime does not support it (Codex, OpenCode, plain CLI), ask exactly the same questions inline in the conversation: render each question as a short paragraph followed by a numbered or bulleted list of options, mark the recommended option with
```
(Recommended)
```
, and accept either the option label or its number in the user's reply. The decision tree is identical; only the rendering changes.
"Memory" — Claude Code's persistent file-based auto-memory. References like "check memory for previously saved conventions" mean: if you have access to Claude Code's auto-memory, look there first. In Codex/OpenCode (and any runtime without persistent memory), substitute "scan earlier turns of this conversation" — if conventions were resolved in the same session, reuse them; if the session is fresh, just run Step 1 from scratch.

Do not refuse a task because one of these primitives is missing. Substitute the inline equivalent and announce the substitution once at the start of the task ("AskUserQuestion not available in this runtime — asking inline" / "no persistent memory in this runtime — detecting conventions from scratch").

本技能设计为可在多个Agent运行时（Claude Code、Codex、OpenCode）中工作。本技能中提及了两个特定于运行时的原语；请将它们视为首选但可选的方案，并优雅地降级处理：

AskUserQuestion
（带有多选选项的Claude Code结构化提示）。当运行时支持该功能时，在每个约定文件的步骤1.4中使用它——这些文件中的JSON示例与工具预期的负载格式匹配。当运行时不支持该功能时（Codex、OpenCode、纯CLI环境），请在对话中直接提出完全相同的问题：将每个问题渲染为简短段落，后跟编号或项目符号列表形式的选项，用
```
(Recommended)
```
标记推荐选项，并接受用户回复中的选项标签或编号。决策树完全相同；仅渲染方式不同。
"Memory"——Claude Code的持久化文件自动记忆功能。诸如"检查内存中之前保存的约定"之类的表述意味着：如果可以访问Claude Code的自动记忆功能，请优先查看此处。在Codex/OpenCode（以及任何没有持久化记忆的运行时）中，替换为"扫描本次对话的早期回合"——如果在同一会话中已解析过约定，请复用它们；如果会话是全新的，则从头开始执行步骤1。

不要因为缺少其中一个原语而拒绝任务。替换为对应的内联等效方案，并在任务开始时宣布一次替换（例如"当前运行时不支持AskUserQuestion——将直接提问" / "当前运行时无持久化记忆——从头检测约定"）。

Preflight: Spring MCP

预检：Spring MCP

This skill is part of the Spring Agent Toolkit and is designed to work with the Spring MCP server (provided by the Amplicode IntelliJ plugin). Before doing anything else, check your tool list for any Spring MCP tool — they are exposed under the

amplicode

MCP server (e.g.

get_jdbc_entity_details

list_all_domain_entities

list_entity_repositories

); harnesses that flatten MCP tools into the tool list use the

mcp__amplicode__

prefix on the same names.

If at least one Amplicode tool is available — MCP is connected. Proceed with the skill below.
If none are available — stop and invoke the amplicode-install
skill (bundled with the Spring Agent Toolkit). It installs the Amplicode plugin and walks the user through the «Настроить Spring Agent» welcome-screen button + MCP-client restart. After it completes, the MCP tools become available — resume this skill.
If
```
amplicode-install
```
is not registered in your skill list or the user declines to install (e.g. they are running in a harness without MCP support such as a CI sandbox), continue with the file-read fallbacks described in the next section so the task is not blocked.

本技能是Spring Agent Toolkit的一部分，设计用于与Spring MCP服务器（由Amplicode IntelliJ插件提供）配合使用。在执行任何操作之前，请检查工具列表中是否有任何Spring MCP工具——它们在

amplicode

MCP服务器下暴露（例如

get_jdbc_entity_details

、

list_all_domain_entities

、

list_entity_repositories

）；将MCP工具展平到工具列表中的运行时会在相同名称前添加

mcp__amplicode__

前缀。

如果至少有一个Amplicode工具可用——MCP已连接。继续执行以下技能内容。
如果没有可用的Amplicode工具——停止操作并调用**
```
amplicode-install
```
**技能（与Spring Agent Toolkit捆绑提供）。它会安装Amplicode插件并引导用户完成«Настроить Spring Agent»欢迎屏幕按钮 + MCP客户端重启的流程。完成后，MCP工具将可用——恢复执行本技能。
如果
```
amplicode-install
```
未在技能列表中注册或者用户拒绝安装（例如他们在不支持MCP的环境中运行，如CI沙箱），请继续使用下一节中描述的文件读取降级方案，以免任务受阻。

MCP availability and fallbacks

MCP可用性与降级方案

This skill prefers the Spring MCP tools (

get_jdbc_entity_details

list_all_domain_entities

list_entity_repositories

) because they return resolved, project-wide answers in one call. If the Spring MCP server is unreachable (connection error, tool not registered, harness without MCP support) and the user has chosen not to install the plugin via the Preflight above, do not refuse the task — fall back to direct file reads / grep:

This project is Kotlin-first (Kotlin 2.2.20 primary, Java for some modules) — every fallback grep must hit both

*.kt

and

*.java

. Do not pass

-t java

rg

; either omit the type filter or use

-t kotlin -t java

Instead of
```
list_all_domain_entities
```
— grep the project for
```
org.springframework.data.relational.core.mapping.Table
```
imports (or
```
@Table
```
annotations whose import resolves there) to enumerate JDBC entities. Works the same in
```
.java
```
and
```
.kt
```
.
Instead of
```
list_entity_repositories
```
— grep for the repository-declaration keyword (
```
extends
```
in Java,
```
:
```
in Kotlin; Kotlin may omit the space before the colon, so use
```
\s*
```
). Spell out every base interface explicitly rather than relying on optional prefixes —
```
(List)?(...|...)
```
parses ambiguously to a human reader:
```
(extends|:)\s*(ListCrudRepository|CrudRepository|ListPagingAndSortingRepository|PagingAndSortingRepository)\b
```
Instead of
```
get_jdbc_entity_details
```
— see the "Without
```
get_jdbc_entity_details
```
" subsection in
```
references/aggregate-rules-impl.md
```
. The manual procedure there yields the same
```
idField.type
```
/
```
aggregateRootFqn
```
/
```
aggregates
```
/
```
referencedBy
```
information by reading source files (both Java and Kotlin).

State once at the start of the task that you are operating in fallback mode and why (e.g. "Spring MCP not reachable — using file-read fallback"). Do not silently switch.

本技能优先使用Spring MCP工具（

get_jdbc_entity_details

、

list_all_domain_entities

、

list_entity_repositories

），因为它们可以通过一次调用返回已解析的项目级答案。如果Spring MCP服务器无法访问（连接错误、工具未注册、运行时不支持MCP）且用户已选择不通过上述预检步骤安装插件，请不要拒绝任务——降级为直接读取文件/ grep：

本项目是Kotlin优先（主要使用Kotlin 2.2.20，部分模块使用Java）——每次降级grep必须同时覆盖

*.kt

和

*.java

文件。不要给

rg

传递

-t java

参数；要么省略类型过滤器，要么使用

-t kotlin -t java

。

替代
```
list_all_domain_entities
```
——在项目中grep查找
```
org.springframework.data.relational.core.mapping.Table
```
导入（或导入指向该包的
```
@Table
```
注解）以枚举JDBC实体。此方法在
```
.java
```
和
```
.kt
```
文件中效果相同。
替代
```
list_entity_repositories
```
——grep查找仓库声明关键字（Java中为
```
extends
```
，Kotlin中为
```
:
```
；Kotlin可能省略冒号前的空格，因此使用
```
\s*
```
）。明确列出每个基础接口，不要依赖可选前缀——
```
(List)?(...|...)
```
对人类读者来说解析存在歧义：
```
(extends|:)\s*(ListCrudRepository|CrudRepository|ListPagingAndSortingRepository|PagingAndSortingRepository)\b
```
替代
```
get_jdbc_entity_details
```
——请参阅
```
references/aggregate-rules-impl.md
```
中的"Without
```
get_jdbc_entity_details
```
"小节。其中的手动流程通过读取源文件（Java和Kotlin均可）生成相同的
```
idField.type
```
/
```
aggregateRootFqn
```
/
```
aggregates
```
/
```
referencedBy
```
信息。

在任务开始时声明一次当前处于降级模式及原因（例如"Spring MCP无法访问——使用文件读取降级方案"）。不要静默切换模式。

Working with JDBC Entities

处理JDBC实体

When the task involves creating or modifying a Spring Data JDBC entity:

If entity conventions have not been detected yet in this conversation — check memory for previously saved conventions first (or earlier conversation turns in runtimes without persistent memory — see "Harness compatibility"). If found, reuse them. Otherwise read
```
references/entity-conventions.md
```
and follow all substeps there to detect project conventions.
Read
```
references/entity-rules-impl.md
```
and follow the rules there when writing or modifying the entity.
If the entities involve any relationship between each other or to existing entities — a collection field, a reference field, an FK column, or a relationship described in the user's request ("X belongs to Y", "Y has many X") — also read
```
references/aggregate-rules-impl.md
```
before deciding the shape of any link. The entity rules cover field syntax; the aggregate rules decide which relationship shapes are legal and in which direction the link may be held. Skipping this step is how illegal shapes (raw FK to a member of another aggregate, references to non-roots) get generated.

Tool-vs-source policy — when you are going to edit the entity, read the source file directly.

get_jdbc_entity_details

is documented as a read-only analysis tool and explicitly says "you plan to modify the entity class afterward — read the file directly instead." Use the MCP tool only for cross-aggregate context that is not visible from one file:

The target's role in its aggregate (
```
aggregateRootFqn
```
).
Other aggregates pointing here (
```
referencedBy
```
).
The id type of a different aggregate you need to link to via
```
AggregateReference<Other, IdType>
```
(when reading
```
Other
```
's source is overkill).

For everything in the file you are editing — id type, current fields, current

@MappedCollection

@Embedded

declarations — read the file.

当任务涉及创建或修改Spring Data JDBC实体时：

如果本次对话中尚未检测到实体约定——请先检查内存中之前保存的约定（或在无持久化记忆的运行时中检查对话早期回合——请参阅"运行时兼容性"）。如果找到，请复用它们。否则，请阅读
```
references/entity-conventions.md
```
并遵循其中的所有子步骤来检测项目约定。
阅读
```
references/entity-rules-impl.md
```
并在编写或修改实体时遵循其中的规则。
如果实体涉及彼此之间或与现有实体的任何关系——集合字段、引用字段、FK列或用户请求中描述的关系（"X属于Y"、"Y拥有多个X"）——在决定任何链接的形式之前，还需阅读
```
references/aggregate-rules-impl.md
```
。实体规则涵盖字段语法；聚合规则决定哪些关系形式是合法的，以及链接可以保留在哪个方向。跳过此步骤会导致生成非法形式（指向另一个聚合成员的原始FK、引用非根实体）。

工具与源文件的使用策略——当你要编辑实体时，请直接读取源文件。

get_jdbc_entity_details

被记录为只读分析工具，明确说明"如果你计划稍后修改实体类——请直接读取文件"。仅在需要从单个文件中看不到的跨聚合上下文时使用MCP工具：

目标实体在其聚合中的角色（
```
aggregateRootFqn
```
）。
指向此处的其他聚合（
```
referencedBy
```
）。
需要通过
```
AggregateReference<Other, IdType>
```
链接到的另一个聚合的ID类型（当读取
```
Other
```
的源文件过于繁琐时）。

对于你正在编辑的文件中的所有内容——ID类型、当前字段、当前

@MappedCollection

@Embedded

声明——请直接读取文件。

Reviewing JDBC Patterns

评审JDBC模式

When the user asks to review JDBC patterns, conventions, or code quality in the project:

Detect current conventions by following
```
references/entity-conventions.md
```
(steps 1.1–1.5).
Compare the detected conventions against the best practices defined in
```
references/entity-rules-impl.md
```
. For each deviation, output a recommendation in the format:

undefined

当用户要求评审项目中的JDBC模式、约定或代码质量时：

遵循
```
references/entity-conventions.md
```
（步骤1.1–1.5）检测当前约定。
将检测到的约定与
```
references/entity-rules-impl.md
```
中定义的最佳实践进行比较。对于每个偏差，按以下格式输出建议：

undefined

JDBC Review

JDBC评审

[Convention or pattern name]

Current: <what the project does>
Recommended: <what the best practice says>
Reason: <why this matters>


If no deviations are found — state that the project follows best practices.

---

[约定或模式名称]

当前实现：<项目当前的做法>
推荐方案：<最佳实践要求的做法>
原因：<为何此点重要>


如果未发现偏差——声明项目遵循最佳实践。

---

Working with JDBC Repositories

处理JDBC仓库

When the task involves adding or modifying a Spring Data JDBC repository:

If repository conventions have not been detected yet in this conversation — check memory (or earlier conversation turns — see "Harness compatibility") first. Otherwise read
```
references/repository-conventions.md
```
and follow all substeps there.
Read
```
references/repository-rules-impl.md
```
and follow the rules there.

Before creating a new repository, call

list_entity_repositories

with

entityFqn = <target>

to confirm no repository already exists for this entity, and call

get_jdbc_entity_details

for the target — a repository may only be created for an aggregate root (

aggregateRootFqn == null

). Note that

list_entity_repositories

has no JDBC filter; filter results manually if you called it without

entityFqn

当任务涉及添加或修改Spring Data JDBC仓库时：

如果本次对话中尚未检测到仓库约定——请先检查内存（或对话早期回合——请参阅"运行时兼容性"）。否则，请阅读
```
references/repository-conventions.md
```
并遵循其中的所有子步骤。
阅读
```
references/repository-rules-impl.md
```
并遵循其中的规则。

在创建新仓库之前，调用

list_entity_repositories

并传入

entityFqn = <目标实体>

以确认该实体尚未存在仓库，并调用目标实体的

get_jdbc_entity_details

——仅可为聚合根（

aggregateRootFqn == null

）创建仓库。注意

list_entity_repositories

没有JDBC过滤器；如果未传入

entityFqn

调用该工具，请手动过滤结果。

Working with Aggregates

处理聚合

When the task involves aggregate boundaries — adding

AggregateReference

fields, converting an owned

@MappedCollection

into a cross-aggregate link, splitting an aggregate, creating any relationship (including one-to-many, many-to-many) between entities, or answering "who references X?" / "what's inside aggregate Y?":

MANDATORY: Read
```
references/aggregate-rules-impl.md
```
first and scan it for rules that apply to your specific relationship type. Do not proceed with entity modifications until you have confirmed which rule applies.
If aggregate conventions have not been detected yet in this conversation — check memory (or earlier conversation turns — see "Harness compatibility") first. Otherwise read
```
references/aggregate-conventions.md
```
and follow all substeps there.
Only after reading both reference files — proceed with entity modifications. Follow the rules there exactly.

The MCP tool

get_jdbc_entity_details

is the source of truth for aggregate membership. Its response carries

aggregateRootFqn

(null if this entity is itself a root),

aggregates

(owned children, recursive — only populated for roots), and

referencedBy

(other aggregates linking here via

AggregateReference

). Read these before making any aggregate-boundary decision.

当任务涉及聚合边界——添加

AggregateReference

字段、将所属的

@MappedCollection

转换为跨聚合链接、拆分聚合、创建实体之间的任何关系（包括一对多、多对多）或回答"谁引用了X？" / "聚合Y包含什么？"时：

强制要求： 首先阅读
```
references/aggregate-rules-impl.md
```
并扫描适用于你特定关系类型的规则。在确认适用的规则之前，请勿进行实体修改。
如果本次对话中尚未检测到聚合约定——请先检查内存（或对话早期回合——请参阅"运行时兼容性"）。否则，请阅读
```
references/aggregate-conventions.md
```
并遵循其中的所有子步骤。
仅在阅读完两个参考文件之后——再进行实体修改。严格遵循其中的规则。

MCP工具

get_jdbc_entity_details

是聚合成员关系的权威来源。其响应包含

aggregateRootFqn

（如果该实体本身是根，则为null）、

aggregates

（所属子实体，递归——仅为根实体填充）和

referencedBy

（通过

AggregateReference

链接到此处的其他聚合）。在做出任何聚合边界决策之前，请读取这些信息。

Critical: One-to-many and many-to-many relationships

关键：一对多和多对多关系

Any one-to-many or many-to-many relationship between different aggregates requires a link entity. This is non-negotiable. Before implementing such a relationship:

Verify from
```
get_jdbc_entity_details
```
(or by reading the entities) that both participants are aggregate roots or check their aggregate membership.
If they are in different aggregates, you must create an intermediate link entity — do not use direct
```
@MappedCollection
```
pointing at another root.
Read the specific rule in
```
references/aggregate-rules-impl.md
```
— section "Rule: One-to-many between two aggregates goes through a link entity" or "Rule: Many-to-many between two aggregates goes through a link entity".
Follow the link-entity pattern exactly as documented: holding side owns link collection via
```
@MappedCollection
```
; each link entity carries
```
AggregateReference<Target, IdType>
```
to the target root.

**不同聚合之间的任何一对多或多对多关系都需要一个链接实体。**这是不可协商的。在实现此类关系之前：

通过
```
get_jdbc_entity_details
```
（或读取实体）验证双方是否为聚合根，或检查它们的聚合成员关系。
如果它们属于不同的聚合，你必须创建一个中间链接实体——不要使用直接指向另一个根实体的
```
@MappedCollection
```
。
阅读
```
references/aggregate-rules-impl.md
```
中的特定规则——"规则：两个聚合之间的一对多关系需通过链接实体实现"或"规则：两个聚合之间的多对多关系需通过链接实体实现"。
严格按照文档中的链接实体模式实现：持有方通过
```
@MappedCollection
```
拥有链接集合；每个链接实体携带指向目标根实体的
```
AggregateReference<Target, IdType>
```
。