Skip to content

Commit a90be2e

Browse files
henry-hubhenry-hub
authored
feat: add ihub-catalog semantic layer with 39 components across 13 domains (#1476)
- taxonomy.json: 13-domain classification system with journey mapping - domains/*.json: per-domain component entries with ai_context - catalog.json: merged catalog for AI one-shot loading - scripts/merge_catalog.py: domain → catalog.json merge tool - scripts/validate_catalog.py: toml ↔ catalog consistency checker - libs.versions.toml: domain section comments + domain bundles - Fix warm-flow gradle_ref to match actual toml aliases
1 parent 94fac35 commit a90be2e

18 files changed

Lines changed: 4187 additions & 17 deletions

‎gradle/ihub-catalog/catalog.json‎

Lines changed: 1947 additions & 0 deletions
Large diffs are not rendered by default.

‎gradle/ihub-catalog/domains/data.json‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
[
2+
{
3+
"id": "data-orm-mybatis-plus",
4+
"name": "MyBatis-Plus",
5+
"name_en": "MyBatis-Plus",
6+
"domain": "data",
7+
"subdomain": "orm",
8+
"stage": [
9+
"code"
10+
],
11+
"type": "platform-bom",
12+
"description": "MyBatis 增强工具包，提供通用 CRUD、分页、条件构造器等开箱即用的 ORM 能力",
13+
"use_case": "首选 ORM 方案。数据层开发时的默认选择，通过 BOM 统一管理 MyBatis-Plus 族版本",
14+
"ai_context": "## 集成模式\n通过 BOM 引入版本管理。使用 mybatis-plus-boot-starter 自动配置集成。\n\n## 配置要点\n- mybatis-plus.mapper-locations: Mapper XML 文件位置\n- mybatis-plus.type-aliases-package: 实体类别名包\n- mybatis-plus.global-config.db-config.id-type: 主键策略\n- 分页插件需显式配置 MybatisPlusInterceptor\n\n## 约束与限制\n- 基于 MyBatis，SQL 能力完整但需要理解 MyBatis 体系\n- 复杂多表查询建议使用 MyBatis XML 而非注解\n- 自动生成代码需谨慎审查\n\n## 常见陷阱\n- 忘记配置分页插件导致分页失效\n- 逻辑删除字段未配置 @TableLogic\n- 乐观锁字段未配置 @Version\n- 实体类与数据库字段类型不匹配（特别是日期类型）",
15+
"alternatives": [
16+
"data-orm-easy-query"
17+
],
18+
"maven": {
19+
"group": "com.baomidou",
20+
"artifact": "mybatis-plus-bom"
21+
},
22+
"version_ref": null,
23+
"gradle_ref": "mybatis-plus-bom",
24+
"dependencies": [],
25+
"starter_available": true,
26+
"tags": [
27+
"orm",
28+
"mybatis",
29+
"mybatis-plus",
30+
"crud",
31+
"bom"
32+
],
33+
"status": "stable",
34+
"since_version": "0.1.0",
35+
"deprecated_since": null,
36+
"migration_guide": null,
37+
"related_plugins": [
38+
"pub.ihub.plugin.ihub-boot"
39+
],
40+
"doc_url": "https://baomidou.com",
41+
"source_url": null,
42+
"ihub_layer": "L2"
43+
},
44+
{
45+
"id": "data-orm-mybatis-plus-ext",
46+
"name": "MyBatis-Plus-Ext",
47+
"name_en": "MyBatis-Plus Extensions",
48+
"domain": "data",
49+
"subdomain": "orm",
50+
"stage": [
51+
"code"
52+
],
53+
"type": "third-party-reference",
54+
"description": "MyBatis-Plus 扩展包，提供自动建表、数据绑定、多数据源注解等高级功能",
55+
"use_case": "在 MyBatis-Plus 基础上需要自动建表（Actable）、关联数据自动绑定（Bind）、动态条件注解时使用",
56+
"ai_context": "## 集成模式\n在 mybatis-plus-bom 基础上叠加。各模块按需引入：\n- mpe-annotation: 基础注解\n- mpe-autotable-*: 自动建表\n- mpe-bind: 关联数据绑定\n- mpe-datasource: 多数据源注解\n- mpe-condition: 动态条件注解\n- mpe-spring-boot3-starter: Spring Boot 3.x 自动配置\n\n## 配置要点\n- 自动建表功能需在开发环境谨慎使用\n- 数据绑定可能产生 N+1 查询\n- 多数据源与 dynamic-datasource 配合使用\n\n## 约束与限制\n- 必须与 MyBatis-Plus 配合使用\n- 自动建表不建议在生产环境启用\n- Bind 注解会产生额外 SQL 查询\n\n## 常见陷阱\n- 生产环境忘记关闭自动建表导致数据库结构意外变更\n- Bind 注解导致 N+1 查询问题\n- 多数据源配置混淆",
57+
"alternatives": [],
58+
"maven": {
59+
"group": "org.dromara.mpe",
60+
"artifact": "mybatis-plus-ext-annotation"
61+
},
62+
"version_ref": "mpe",
63+
"gradle_ref": [
64+
"mpe-annotation",
65+
"mpe-autotable-annotation",
66+
"mpe-autotable-core",
67+
"mpe-actable-core",
68+
"mpe-bind",
69+
"mpe-condition",
70+
"mpe-datasource",
71+
"mpe-processor",
72+
"mpe-spring-boot-starter",
73+
"mpe-spring-boot3-starter"
74+
],
75+
"dependencies": [
76+
{
77+
"component_id": "data-orm-mybatis-plus",
78+
"required": true,
79+
"scope": "implementation",
80+
"reason": "MyBatis-Plus-Ext 是 MyBatis-Plus 的扩展"
81+
}
82+
],
83+
"starter_available": true,
84+
"tags": [
85+
"orm",
86+
"mybatis-plus",
87+
"extension",
88+
"auto-table",
89+
"data-bind"
90+
],
91+
"status": "stable",
92+
"since_version": "0.1.0",
93+
"deprecated_since": null,
94+
"migration_guide": null,
95+
"related_plugins": [
96+
"pub.ihub.plugin.ihub-boot"
97+
],
98+
"doc_url": "https://mybatis-plus-ext.duanshu.com",
99+
"source_url": null,
100+
"ihub_layer": "L3"
101+
},
102+
{
103+
"id": "data-orm-easy-query",
104+
"name": "Easy-Query",
105+
"name_en": "Easy-Query",
106+
"domain": "data",
107+
"subdomain": "orm",
108+
"stage": [
109+
"code"
110+
],
111+
"type": "third-party-reference",
112+
"description": "强类型 SQL DSL 框架，提供编译期安全的 SQL 构建、自动建表、多表查询等能力",
113+
"use_case": "MyBatis-Plus 的替代方案。需要强类型安全、编译期 SQL 校验、Lambda 风格查询时选择。适合喜欢 JPA 风格但需要 SQL 控制力的场景",
114+
"ai_context": "## 集成模式\n通过 BOM 引入，使用 eq-sql-springboot-starter 自动配置。支持 Java 和 Kotlin。\n\n## 配置要点\n- easy-query.enable: 是否启用\n- easy-query.default-track: 是否默认追踪实体变更\n- easy-query.logic-delete-strategy: 逻辑删除策略\n- 支持 MySQL、PostgreSQL、SQL Server 等主流数据库\n\n## 约束与限制\n- 与 MyBatis-Plus 互斥，不要同时使用两种 ORM\n- 部分复杂 SQL（如递归 CTE）可能不如 MyBatis XML 直观\n- 团队需要学习 DSL 风格查询语法\n\n## 常见陷阱\n- 同时引入 MyBatis-Plus 和 Easy-Query 导致配置冲突\n- 未配置 dialect 导致 SQL 生成错误\n- 实体追踪（tracking）开启后忘记调用 saveChanges 导致数据丢失",
115+
"alternatives": [
116+
"data-orm-mybatis-plus"
117+
],
118+
"maven": {
119+
"group": "com.easy-query",
120+
"artifact": "sql-core"
121+
},
122+
"version_ref": "easy-query",
123+
"gradle_ref": [
124+
"eq-sql-core",
125+
"eq-sql-springboot-starter",
126+
"eq-sql-api4j",
127+
"eq-sql-api-proxy",
128+
"eq-sql-cache",
129+
"eq-sql-mysql",
130+
"eq-sql-processor",
131+
"eq-sql-ksp-processor",
132+
"eq-sql-kt-springboot-starter",
133+
"eq-all"
134+
],
135+
"dependencies": [],
136+
"starter_available": true,
137+
"tags": [
138+
"orm",
139+
"sql",
140+
"dsl",
141+
"lambda",
142+
"type-safe"
143+
],
144+
"status": "stable",
145+
"since_version": "0.1.0",
146+
"deprecated_since": null,
147+
"migration_guide": null,
148+
"related_plugins": [
149+
"pub.ihub.plugin.ihub-boot"
150+
],
151+
"doc_url": "https://easy-query.com",
152+
"source_url": null,
153+
"ihub_layer": "L2"
154+
},
155+
{
156+
"id": "data-datasource-dynamic",
157+
"name": "Dynamic-Datasource",
158+
"name_en": "Dynamic Datasource",
159+
"domain": "data",
160+
"subdomain": "datasource",
161+
"stage": [
162+
"code",
163+
"adapt"
164+
],
165+
"type": "third-party-reference",
166+
"description": "动态数据源切换框架，支持运行时多数据源切换、读写分离、负载均衡",
167+
"use_case": "需要多数据源管理（主从分离、多租户分库、读写分离）时使用。通过 @DS 注解实现数据源切换",
168+
"ai_context": "## 集成模式\n通过 starter 自动配置。使用 @DS 注解标记类或方法的数据源。\n\n## 配置要点\n- spring.datasource.dynamic.primary: 默认数据源\n- spring.datasource.dynamic.datasource.<name>: 配置多个数据源\n- @DS(\"slave\")：方法级数据源切换\n- 支持 seata 分布式事务集成\n\n## 约束与限制\n- 不支持嵌套数据源切换（内层 @DS 会被外层覆盖）\n- 事务内切换数据源需要特殊处理\n- 多数据源的事务管理需要额外配置\n\n## 常见陷阱\n- 事务内 @DS 切换不生效\n- 忘记配置 primary 导致默认数据源未定义\n- 多数据源的 DDL 初始化脚本路径混淆",
169+
"alternatives": [],
170+
"maven": {
171+
"group": "com.baomidou",
172+
"artifact": "dynamic-datasource-spring-boot3-starter"
173+
},
174+
"version_ref": null,
175+
"gradle_ref": "dynamic-datasource",
176+
"dependencies": [],
177+
"starter_available": true,
178+
"tags": [
179+
"datasource",
180+
"dynamic",
181+
"read-write-split",
182+
"multi-tenant"
183+
],
184+
"status": "stable",
185+
"since_version": "0.1.0",
186+
"deprecated_since": null,
187+
"migration_guide": null,
188+
"related_plugins": [
189+
"pub.ihub.plugin.ihub-boot"
190+
],
191+
"doc_url": "https://dynamic-datasource.com",
192+
"source_url": null,
193+
"ihub_layer": "L2"
194+
}
195+
]

‎gradle/ihub-catalog/domains/ddd.json‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
[
2+
{
3+
"id": "ddd-architecture-jmolecules",
4+
"name": "jMolecules",
5+
"name_en": "jMolecules",
6+
"domain": "ddd",
7+
"subdomain": "architecture",
8+
"stage": [
9+
"ideate",
10+
"code",
11+
"qa"
12+
],
13+
"type": "platform-bom",
14+
"description": "DDD 架构约束框架，通过注解声明领域概念（Entity、ValueObject、AggregateRoot 等）并自动生成架构验证规则",
15+
"use_case": "实施领域驱动设计时使用。通过注解标记领域概念，配合 ArchUnit 规则自动验证架构约束，防止架构腐化",
16+
"ai_context": "## 集成模式\n通过 BOM 引入版本管理。核心模块：\n- jmolecules-ddd: DDD 基础注解（@Entity, @ValueObject, @AggregateRoot, @Repository）\n- jmolecules-events: 领域事件支持\n- jmolecules-cqrs-architecture: CQRS 架构约束\n- jmolecules-layered-architecture: 分层架构约束\n- jmolecules-onion-architecture: 洋葱架构约束\n\n集成模块：\n- jmolecules-spring: Spring 自动配置\n- jmolecules-jpa: JPA 映射支持\n- jmolecules-jackson: Jackson 序列化支持\n- jmolecules-archunit: ArchUnit 规则自动生成\n\n## 配置要点\n- 架构约束通过 ArchUnit 测试验证\n- 需要显式引入对应的 architecture 模块来启用特定架构风格\n- Spring 集成模块提供自动配置\n\n## 约束与限制\n- 注解本身不提供运行时行为，需要配合集成模块\n- ArchUnit 规则在测试阶段验证，不阻止编译\n- 团队需要理解 DDD 概念才能正确使用注解\n\n## 常见陷阱\n- 混淆 @Entity（jMolecules DDD 概念）与 @Entity（JPA）\n- 忘记添加架构约束模块导致没有强制检查\n- 在错误的分层中使用领域概念（如 Service 层直接操作 Entity）",
17+
"alternatives": [
18+
"ddd-modularity-spring-modulith"
19+
],
20+
"maven": {
21+
"group": "org.jmolecules",
22+
"artifact": "jmolecules-bom"
23+
},
24+
"version_ref": null,
25+
"gradle_ref": [
26+
"jmolecules-bom",
27+
"jmolecules-ddd",
28+
"jmolecules-events",
29+
"jmolecules-cqrs",
30+
"jmolecules-layered",
31+
"jmolecules-onion",
32+
"jmolecules-spring",
33+
"jmolecules-jpa",
34+
"jmolecules-jackson",
35+
"jmolecules-archunit"
36+
],
37+
"dependencies": [],
38+
"starter_available": false,
39+
"tags": [
40+
"ddd",
41+
"architecture",
42+
"jpa",
43+
"archunit",
44+
"cqrs",
45+
"bom"
46+
],
47+
"status": "stable",
48+
"since_version": "0.1.0",
49+
"deprecated_since": null,
50+
"migration_guide": null,
51+
"related_plugins": [
52+
"pub.ihub.plugin.ihub-boot"
53+
],
54+
"doc_url": "https://github.com/xmolecules/jmolecules",
55+
"source_url": null,
56+
"ihub_layer": "L2"
57+
},
58+
{
59+
"id": "ddd-modularity-spring-modulith",
60+
"name": "Spring Modulith",
61+
"name_en": "Spring Modulith",
62+
"domain": "ddd",
63+
"subdomain": "modularity",
64+
"stage": [
65+
"ideate",
66+
"code",
67+
"qa"
68+
],
69+
"type": "platform-bom",
70+
"description": "Spring 官方模块化工具包，提供模块定义、模块间依赖验证、模块集成测试、事件发布与文档化能力",
71+
"use_case": "构建模块化单体应用时使用。通过 Spring Modulith 定义模块边界，验证模块依赖，生成模块文档。可与 jMolecules 配合使用",
72+
"ai_context": "## 集成模式\n通过 BOM 引入，使用 @ApplicationModuleListener 处理模块间事件，ArchUnit 规则验证模块边界。\n\n## 配置要点\n- @ApplicationModuleListener: 跨模块事件监听\n- spring.modulith.events.externalization.enabled: 是否启用事件外化\n- ModuleTestExecution: 模块集成测试运行器\n- Documenter: 生成模块关系图\n\n## 约束与限制\n- 仅适用于 Spring Boot 3.x+/4.x\n- 模块通信通过事件机制，不适合高频同步调用\n- 模块测试需要特殊的测试运行器\n\n## 常见陷阱\n- 模块间直接注入 Service（应该通过事件通信）\n- 忘记配置 ArchUnit 规则导致模块边界不被强制\n- 将 @ApplicationModuleListener 方法写在错误的事务边界中",
73+
"alternatives": [
74+
"ddd-architecture-jmolecules"
75+
],
76+
"maven": {
77+
"group": "org.springframework.modulith",
78+
"artifact": "spring-modulith-bom"
79+
},
80+
"version_ref": null,
81+
"gradle_ref": "spring-modulith-bom",
82+
"dependencies": [
83+
{
84+
"component_id": "infra-platform-spring-boot",
85+
"required": true,
86+
"scope": "implementation",
87+
"reason": "Spring Modulith 是 Spring 生态的子项目"
88+
}
89+
],
90+
"starter_available": false,
91+
"tags": [
92+
"spring",
93+
"modulith",
94+
"modularity",
95+
"ddd",
96+
"archunit",
97+
"bom"
98+
],
99+
"status": "stable",
100+
"since_version": "1.0.0",
101+
"deprecated_since": null,
102+
"migration_guide": null,
103+
"related_plugins": [
104+
"pub.ihub.plugin.ihub-boot"
105+
],
106+
"doc_url": "https://docs.spring.io/spring-modulith/",
107+
"source_url": null,
108+
"ihub_layer": "L2"
109+
}
110+
]

0 commit comments

Comments
 (0)