# jfoundry

**Repository Path**: huahill/jfoundry

## Basic Information

- **Project Name**: jfoundry
- **Description**: jfoundry is a practical DDD framework for Java, built on jMolecules and designed for Hexagonal Architecture and Onion Architecture. | jfoundry 是一个面向 Java 的可落地 DDD 开发框架，基于 jMolecules 构建，适用于六边形架构和洋葱架构。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-19
- **Last Updated**: 2026-10-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# jfoundry

中文 | [English](README.md)

---

`jfoundry` 是一个面向 Java 的可落地 DDD 开发框架，基于 jMolecules 构建，适用于 Hexagonal Architecture（六边形架构）和 Onion Architecture（洋葱架构）。

它让业务项目能将领域建模、架构边界和可靠集成落实为代码。核心定义 DDD 概念、架构语义、应用层契约、领域事件、持久化 SPI 和消息 SPI，不依赖特定运行时框架。Spring、Quarkus 与 Helidon 通过平级运行时集成模块装配同一套核心能力。

JFoundry 不是完整的业务应用框架，也不要求应用引入全部模块。它是一个可组合的能力平台：应用按需选择 DDD、持久化、消息、可靠集成和运行时能力，而具体框架适配器始终位于运行时无关核心之外。

## 为什么是 jfoundry

很多 DDD 项目会在实现中失去原有边界：领域代码引入框架或 ORM API，事务归属不清，Repository 演变为通用查询接口，外部事件也无法可靠投递。`jfoundry` 提供：

- 基于 jMolecules 的 DDD、Hexagonal、Onion 和 CQRS 语义。
- 领域、应用、基础设施与运行时集成之间明确的依赖方向。
- 将架构约束变为可执行测试的 ArchUnit 规则。
- 用于持久化、消息传输、可靠消息、事务和运行时装配的可选生产能力。

## 架构

领域模型不依赖 Spring、ORM、HTTP、消息代理或数据库客户端。应用层契约编排用例并定义能力 SPI；基础设施实现技术适配器；运行时集成负责装配。

```text
运行时集成
  -> 应用层 / 基础设施适配器
       -> 应用层契约
            -> 领域
```

依赖方向始终指向内层。因此运行时集成位于核心之外，而不是每个应用的必需依赖。

领域事件与 Outbox 是相互独立的能力：进程内领域事件派发不需要 Outbox，通用 Outbox 也不需要领域事件。
只有在需要可靠地将领域事件外部化时，应用才选择显式的领域事件 Outbox 组合；可选的持久化桥接层负责保持聚合事件自动收集的便利性，
同时避免通用持久化与领域事件耦合。

在仓库结构中，`jfoundry-core/` 归集运行时无关模块，`jfoundry-runtime/` 归集 Spring、Quarkus 和 Helidon 集成，`jfoundry-boms/` 提供依赖管理。这些目录是源码分组，不是 Maven 聚合模块。模块数量反映了“能力”和“运行时或实现”两个独立维度，并不意味着应用需要依赖整个仓库。

![jfoundry 模块架构](docs/i18n/assets/jfoundry-module-architecture.svg)

## AI 辅助架构工作流

[`domain-architecture-skills`](https://github.com/xfoundries/domain-architecture-skills) 是
JFoundry 在设计期的配套插件。用户无需预先选择架构风格：`$domain-architecture-workflow` 会从需求出发完成领域建模，
再依据已确认的业务需求、外部边界和项目约束判断是否需要完整架构风格；需要时，由工作流在
[Hexagonal 与 Onion](docs/i18n/zh/framework/architecture-styles.md) 之间作出选择，随后才将决策映射为 JFoundry 模块和
ArchUnit 规则。CQRS 仍是按需使用的局部模式。

仅当项目选择 JFoundry 后，插件才进入框架落地。它需要独立安装，不是运行时依赖。

与 JFoundry 配合使用的验证证据和边界见[采用就绪度与已验证范围](docs/i18n/zh/integration/adoption-readiness.md)。

### 查看端到端示例

可直接查看 [jfoundry 费用报销审批 Demo](https://github.com/xfoundries/jfoundry-expense-approval-demo)。
这是一个端到端参考项目：它以刻意简化的业务领域验证完整的架构和集成链路，并持续维护 Hexagonal
与 Onion Simple 两个变体。

```text
需求 -> 领域建模 -> 架构决策 -> 可选的 jfoundry 落地 -> 实施交接
```

## 能力概览

| 范畴 | 能力 |
|------|------|
| 领域建模 | 聚合、值对象、领域事件、Repository 契约和领域异常 |
| 架构 | Hexagonal 和 Onion 语义，以及 ArchUnit 规则 |
| 应用层 | 应用服务、事务边界、CQRS 和领域事件编排 |
| 持久化 | 聚合持久化契约，以及 MyBatis-Plus 和 JPA 实现 |
| Web | 面向 Spring MVC、Quarkus REST 和 Helidon MP JAX-RS 的 RFC 9457 Problem Details 与安全 HTTP 诊断日志，以及 Spring 和 MicroProfile REST Client 日志 |
| 消息传输 | 运行时无关的出站传输契约，以及显式选择的 Kafka、RabbitMQ、RocketMQ 适配器 |
| 可靠消息 | Transactional Outbox、Inbox 幂等、消息和序列化 SPI |
| 运行时集成 | Spring Framework 与 Spring Boot 装配；Quarkus 与 Helidon 的 CDI/Jakarta Transactions、JPA 与 Outbox/Inbox 装配 |

## 能力组合

JFoundry 的能力可以独立选择。一个典型应用通常只选择适合自己的路径，而不是引入整个项目：

| 需求 | 典型组合 |
|------|----------|
| DDD 建模与架构约束 | 领域与架构能力 |
| 进程内领域事件 | 领域事件能力，不要求 Outbox |
| 通用可靠消息 | Outbox 或 Inbox 能力，再选择存储、传输和序列化适配器 |
| 领域事件可靠外部化 | 领域事件 + Outbox 组合；需要自动收集聚合事件时，再添加可选的持久化桥接层 |
| 聚合持久化 | 持久化契约，以及 JPA 或 MyBatis-Plus 实现 |
| 运行时装配 | 对应的 Spring、Quarkus 或 Helidon 集成 |

这种组合方式保持了默认接入的轻量，同时允许应用在明确选择后获得面向生产的可靠集成能力。

## 选择路径

- **选择能力**：先从[能力目录](docs/i18n/zh/capabilities/index.md)开始，将业务需求映射到受支持运行时的依赖入口。
- **架构与建模**：从[接入指南](docs/i18n/zh/integration/getting-started.md)开始，选择[架构风格](docs/i18n/zh/framework/architecture-styles.md)，并阅读[建模约定](docs/i18n/zh/modeling/index.md)。
- **聚合持久化**：先阅读[聚合持久化](docs/i18n/zh/capabilities/aggregate-persistence.md)，再选择适合项目的平级实现：[MyBatis-Plus](docs/i18n/zh/implementations/mybatis-plus.md) 或 [JPA](docs/i18n/zh/implementations/jpa.md)。
- **Web**：先阅读[Web](docs/i18n/zh/capabilities/web.md)，再选择 RFC 9457 Problem Details 或运行时专属的 HTTP 服务端与 REST Client 诊断日志。
- **消息传输**：通过[消息传输](docs/i18n/zh/capabilities/message-delivery.md)选择直接使用的 Kafka、RabbitMQ、RocketMQ 或应用自有传输适配器。
- **Spring Boot + MyBatis-Plus（常用组合）**：先完成 [Spring Boot 运行时装配](docs/i18n/zh/implementations/spring-boot.md)，再接入 [MyBatis-Plus](docs/i18n/zh/implementations/mybatis-plus.md) 聚合持久化；这是一条常见接入路径，不改变 JPA 的同等支持地位。
- **可靠消息**：先阅读[可靠消息](docs/i18n/zh/capabilities/reliable-messaging.md)，再从对应的 [MyBatis-Plus](docs/i18n/zh/implementations/mybatis-plus.md) 或 [JPA](docs/i18n/zh/implementations/jpa.md) 指南中选择其存储实现。
- **Spring Boot**：通过 [Spring Boot 运行时装配](docs/i18n/zh/implementations/spring-boot.md) 使用启动器与条件化自动配置组装已选择的能力；其属性、条件与 Bean 优先级见 [Spring Boot 自动配置参考](docs/i18n/zh/reference/spring-boot-autoconfiguration.md)。
- **Quarkus**：通过 [Quarkus 运行时集成](docs/i18n/zh/implementations/quarkus.md) 使用显式扩展组合接入 CDI 事务、Problem Details 与 HTTP 日志、领域事件分发、基于 JPA 的可靠消息、Kafka 与 RabbitMQ 投递并验证原生镜像。
- **Helidon MP**：通过 [Helidon MP 运行时集成](docs/i18n/zh/implementations/helidon.md) 显式组合 CDI/JTA、JPA、Outbox/Inbox、Kafka 与 RabbitMQ 投递、Problem Details 与 HTTP 日志。其原生镜像当前验证 CDI/Web；Helidon Narayana JTA 的原生执行仍是上游实验性能力。

## 最小接入

所有应用都引入运行时无关 BOM，再只添加应用需要的启动器与能力实现。Spring Boot、Quarkus 与 Helidon 应用还要额外引入各自的运行时 BOM；运行时 BOM 只管理平台生态版本，不能替代 JFoundry BOM。

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.github.xfoundries</groupId>
            <artifactId>jfoundry-dependencies</artifactId>
            <version>${jfoundry.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

## 领域模型示例

```java
// Money.java
import org.jfoundry.domain.valueobject.ValueObject;

import java.math.BigDecimal;

public record Money(BigDecimal amount, String currency) implements ValueObject {
}
```

```java
// OrderId.java
import org.jmolecules.ddd.types.Identifier;

public record OrderId(String value) implements Identifier {
}
```

```java
// Order.java
import org.jfoundry.domain.entity.agg.BaseAggregateRoot;

public final class Order extends BaseAggregateRoot<Order, OrderId> {

    private Money total;

    public Order(OrderId id, Money total) {
        super(id);
        this.total = total;
    }

    public void changeTotal(Money total) {
        this.total = total;
    }
}
```

## 文档

### 快速开始

- [接入指南](docs/i18n/zh/integration/getting-started.md)
- [采用就绪度与已验证范围](docs/i18n/zh/integration/adoption-readiness.md)
- [发布支持策略](docs/release/support-policy.md)
- [供应链安全](docs/release/supply-chain-security.md)
- [`domain-architecture-skills`](https://github.com/xfoundries/domain-architecture-skills)

### 能力

- [能力目录](docs/i18n/zh/capabilities/index.md)
- [聚合持久化](docs/i18n/zh/capabilities/aggregate-persistence.md)
- [Web](docs/i18n/zh/capabilities/web.md)
- [消息传输](docs/i18n/zh/capabilities/message-delivery.md)
- [可靠消息：Outbox 与 Inbox](docs/i18n/zh/capabilities/reliable-messaging.md)
- [应用事务](docs/i18n/zh/capabilities/application-transactions.md)
- [分布式锁](docs/i18n/zh/capabilities/distributed-locks.md)

### 持久化实现

- [MyBatis-Plus](docs/i18n/zh/implementations/mybatis-plus.md)
- [JPA](docs/i18n/zh/implementations/jpa.md)

### 运行时集成

- [Spring Boot 运行时装配](docs/i18n/zh/implementations/spring-boot.md)
- [Quarkus 运行时集成](docs/i18n/zh/implementations/quarkus.md)
- [Helidon MP 运行时集成](docs/i18n/zh/implementations/helidon.md)

### 框架语义

- [架构风格指南](docs/i18n/zh/framework/architecture-styles.md)
- [ArchUnit 架构规则](docs/i18n/zh/framework/archunit-rules.md)
- [框架边界设计](docs/i18n/zh/framework/framework-boundaries.md)

### 建模

- [建模](docs/i18n/zh/modeling/index.md)
- [值对象规范](docs/i18n/zh/modeling/value-object.md)
- [领域事件](docs/i18n/zh/modeling/domain-event.md)
- [Repository 与读侧契约迁移指南](docs/i18n/zh/modeling/repository-vs-read-contracts.md)

### 发布与兼容

- [兼容性矩阵](docs/release/compatibility.md)
- [发布到 Maven Central](docs/release/maven-central.md)
- [原生镜像验证状态](docs/i18n/zh/integration/adoption-readiness.md)：应结合[兼容性矩阵](docs/release/compatibility.md)查看已按运行时与能力划定的验证证据，不能据此推定所有组件均受支持。

完整文档结构见[中文文档索引](docs/i18n/zh/index.md)。

## 构建

```bash
./mvnw validate
./mvnw test
./mvnw clean install
```

## 许可证

[Apache License 2.0](LICENSE)