# Jimmer Orm

> Jimmer ORM 开发助手，帮助编写实体映射代码和 DSL 查询语句。适用于：(1) 定义或修改 Jimmer 实体（使用 @Entity 注解的 interface）；(2) 编写 Jimmer DSL 查询代码；(3) 配置实体关联关系（@ManyToOne, @OneToMany, @ManyToMany）；(4) 使用动态谓词、动态表连接或隐式子查询；(5) 编辑包含 Jimmer 相关代码的 Java/Kotlin 文件。

- Skill: `coooolfan/jimmer-orm` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add coooolfan/jimmer-orm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/coooolfan/jimmer-orm/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: coooolfan (https://skillmd.com/u/coooolfan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/coooolfan/jimmer-orm

---


## 事实源

如果当前上下文中指名了 Jimmer 项目的源码的本地路径，应当以源码实现作为基准。如果有其他情况需要查阅 Jimmer 的具体实现，其代码仓库为 `https://github.com/babyfish-ct/jimmer`

## 核心概念

### 实体定义特点

- 使用 **interface** 定义实体，而非 class
- 实体是**动态对象**和**不可变对象**
- 只有 getter，没有 setter
- 由 KSP (Kotlin) 或 AnnotationProcessor (Java) 编译时生成实现
- 属性未设置 ≠ 属性为 null

### DSL 查询特点

- 强类型 SQL DSL，提供编译时安全保证
- 动态谓词：根据参数决定是否添加 SQL 条件
- 动态表连接：未使用的连接自动忽略，冲突连接自动合并
- 隐式子查询：基于集合关联创建子查询，自动生成父子关联条件

## 语言选择

Jimmer 为 Kotlin 提供了特化的 API 风格

- **实体映射：** 参考 `references/entity-mapping.md`
- **DSL 查询：** 参考 `references/dsl-queries.md`
- **实体模板：** 参考 `assets/EntityTemplate.kt`

## 关键注解速查

- `@Entity` - 标记实体类型
- `@MappedSuperclass` - 标记映射父接口，复用公共字段
- `@Embeddable` - 标记嵌入值对象
- `@Id` - 标记主键
- `@GeneratedValue` - 主键生成策略
- `@Key` - 业务键
- `@ManyToOne` / `@OneToMany` / `@ManyToMany` / `@OneToOne` - 关联映射
- `@ManyToManyView` - 通过中间实体暴露多对多视图
- `@IdView` - 关联 id 视图
- `@JoinColumn` - 自定义外键列名
- `@JoinTable` - 自定义中间表
- `@Column` - 自定义列名（仅用于非关联字段）
- `@Table` - 自定义表名
- `@Version` - 乐观锁版本字段
- `@LogicalDeleted` - 逻辑删除字段
- `@Formula` / `@Transient` - 计算属性
- `?` (Kotlin) - 标记可空属性

## 命名约定

- 实体名 → 表名：`BookStore` → `BOOK_STORE`
- 属性名 → 列名：`firstName` → `FIRST_NAME`
- 多对一外键：`store` → `STORE_ID`

## 工作流程

1. **定义实体时：**
   - 使用 interface 而非 class
   - 根据项目语言参考对应的实体模板和映射文档
   - 中间表有排序、时间、来源等业务字段时，定义中间实体并用 `@ManyToManyView` 暴露只读多对多视图
   - 需要直接按外键查询或写入 input 时，优先为关联补充 `@IdView`
   - 参考 `assets/EntityTemplate.kt` 和 `references/entity-mapping.md`
   - 参考 `references/dto.md` 完成 DTO 定义

2. **编写查询时：**
   - 优先使用动态谓词（Kotlin: `` `ilike?` ``/`` `between?` ``/`` `valueIn?` ``）
   - 使用动态表连接处理单值关联查询
   - 使用隐式子查询处理集合关联，避免集合 JOIN 导致结果重复和分页失效
   - API 返回实体时使用 fetcher/DTO 控制投影，不要依赖默认序列化形状
   - 根据项目语言参考对应的 DSL 查询文档
   - 参考 `references/dsl-queries.md`

3. **遇到问题时：**
   - 检查实体是否使用 interface 定义
   - 检查关联映射的 `mappedBy` 配置
   - 检查动态谓词的参数是否正确
   - 确认表连接路径是否正确