mcpField
J
jimmer-orm

jimmer-orm

github.com/coooolfan开发652 次安装5 周前更新
代码仓库

关于 jimmer-orm

面向 Kotlin 和 Java 开发者的 Jimmer ORM 开发 Skill，指导实体定义与查询编写。它强调基于接口的不可变实体，以及支持动态谓词和连接的类型安全 DSL。

主要功能

  1. 01接口式不可变实体指导
  2. 02Kotlin 专用 API 指引
  3. 03类型安全的 SQL DSL 查询
  4. 04动态谓词与表连接
  5. 05关联映射与注解说明
  6. 06实体、DTO 和查询参考

适用场景

  1. 01定义 Jimmer 实体接口
  2. 02映射实体关联和数据库列
  3. 03使用条件谓词构建查询
  4. 04为返回实体的 API 选择投影

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/coooolfan/unirhy --skill jimmer-orm

安装后在 Claude Code 中输入/jimmer-orm确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

assets/
EntityTemplate.kt
references/
dsl-queries.md
dto.md
entity-mapping.md

详细介绍

事实来源

如果当前上下文中指明了 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 配置
    • 检查动态谓词的参数是否正确
    • 确认表连接路径是否正确

评论

支持 Markdown