# JavaNexus

**Repository Path**: solidify-the-foundation/java-nexus

## Basic Information

- **Project Name**: JavaNexus
- **Description**: java的项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-08-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JavaNexus

JavaNexus 是一个面向 JDK 21 的微型企业级任务执行平台。它不是 Spring Boot CRUD
示例，而是一座用于验证 DDD、并发治理、JVM 运行时和韧性设计的可运行实验场。

当前版本 `0.1.0-SNAPSHOT` 已交付两条纵向切片：第一条完成任务生命周期与有界虚拟线程执行，
第二条加入 PostgreSQL 聚合仓储和 Transactional Outbox，使业务状态与待发布领域事件在同一事务中
提交，并能在发布进程中断后恢复投递。

## 已实现能力

- 纯 Java 的 `Job` 聚合：`ACCEPTED → RUNNING → 终态`，非法迁移立即失败。
- 两种真实持久化 adapter：原子内存仓储用于快速实验，PostgreSQL 用于生产形态验证。
- Transactional Outbox：事务内追加、租约认领、`SKIP LOCKED` 多实例竞争、重试和死信。
- 有界虚拟线程编排器：容量背压、任务键去重、超时、中断、取消和优雅关闭。
- Spring Boot REST 适配器、参数校验、统一错误响应和 Actuator 探针。
- JDK Unified Logging GC Pause 分析器：统计总暂停、最大值、P50/P95/P99。
- JUnit、ArchUnit、JaCoCo 和 JMH 基线；架构测试守护核心层依赖方向。
- ADR、JVM 调优清单、容器构建和分阶段演进路线。

## 架构

```mermaid
flowchart LR
    Client["REST Client"] --> App["nexus-app<br/>application orchestration"]
    App --> Core["nexus-core<br/>Job aggregate + ports"]
    App --> Infra["nexus-infra<br/>virtual threads + adapters"]
    Infra --> Core
    Infra --> Postgres[("PostgreSQL<br/>jobs + outbox_events")]
    Relay["Outbox relay<br/>at-least-once"] --> Postgres
    Relay --> Broker["Publisher adapter<br/>logging / future Kafka"]
    App --> Runtime["nexus-runtime<br/>GC analysis"]
    Tests["nexus-tests<br/>ArchUnit + JMH"] --> Core
    Tests --> Infra
    Tests --> Runtime
```

依赖只向内：`nexus-core` 不依赖 Spring，也不知道持久化和线程模型。并发模块的外部接口只有
`submit/cancel/snapshot`，调用方无需理解许可释放、定时器与中断竞态。

## 快速启动

要求 JDK 21 与 Maven 3.9+。

```bash
mvn clean verify
mvn -pl nexus-app -am spring-boot:run
```

提交一个 200 ms 的模拟作业：

```bash
curl -i http://localhost:8080/api/v1/jobs \
  -H 'Content-Type: application/json' \
  -d '{
    "name":"invoice-rebuild",
    "payload":"tenant-42",
    "timeoutMillis":2000,
    "simulatedDurationMillis":200,
    "fail":false
  }'
```

响应中的 `Location` 可用于查询和取消：

```bash
curl http://localhost:8080/api/v1/jobs/<job-id>
curl -X DELETE http://localhost:8080/api/v1/jobs/<job-id>
curl http://localhost:8080/actuator/health
```

默认 profile 使用内存 adapter。要运行 PostgreSQL + Outbox 的完整链路：

```bash
docker compose up -d postgres
mvn -pl nexus-app -am spring-boot:run -Dspring-boot.run.profiles=postgres
```

Flyway 会创建 `jobs` 与 `outbox_events`。relay 每次以短事务认领一批事件；发布成功后确认，失败则按
配置延迟重试，达到最大次数后写入死信状态。交付语义是 **at-least-once**：将来接 Kafka 时必须把
`OutboxMessage.id` 作为消息键，并在消费者侧建立幂等记录。

## JVM 实验

生成包含 GC、安全点和文件轮转信息的日志：

```bash
java -Xms256m -Xmx256m -XX:+UseG1GC \
  -Xlog:gc*,safepoint:file=gc.log:time,uptime,level,tags:filecount=5,filesize=20m \
  -jar nexus-app/target/nexus-app-0.1.0-SNAPSHOT.jar
```

分析 Pause 分布：

```bash
mvn -pl nexus-runtime -am package
java -cp nexus-runtime/target/nexus-runtime-0.1.0-SNAPSHOT.jar \
  io.javanexus.runtime.gc.GcLogCli gc.log
```

运行虚拟线程与平台线程的阻塞负载基准：

```bash
mvn -pl nexus-tests -am test-compile
mvn -pl nexus-tests -Dexec.mainClass=org.openjdk.jmh.Main \
  org.codehaus.mojo:exec-maven-plugin:3.5.0:java
```

基准结果必须连同 CPU、内存、JDK 构建号和 JVM 参数一起保存，禁止只提交一个孤立数字。

## 模块地图

| 模块 | 当前职责 | 下一适配器/实验 |
|---|---|---|
| `nexus-core` | 聚合、值对象、领域事件、持久化接口 | DAG 规约、幂等提交键 |
| `nexus-infra` | 虚拟线程编排、双仓储 adapter、Transactional Outbox relay | Kafka、消费者幂等、Redis |
| `nexus-runtime` | GC Pause 日志分析 | Instrumentation Agent、JFR 事件读取 |
| `nexus-app` | REST、应用编排、配置和健康检查 | OpenTelemetry、Resilience4j |
| `nexus-tests` | 架构规则与 JMH | Testcontainers、故障注入、容量模型 |

完整路线见 [docs/ROADMAP.md](docs/ROADMAP.md)，设计理由见 [docs/adr](docs/adr)，调优实验模板见
[docs/JVM_TUNING_CHECKLIST.md](docs/JVM_TUNING_CHECKLIST.md)。

## 设计纪律

1. 每个生产能力必须有失败路径测试，不能只测 Happy Path。
2. 每次性能结论必须包含基线、变量、数据、代价和最终选择。
3. 新基础设施先通过核心层接口接入，禁止把 Spring/JPA/Kafka 类型泄漏进领域模型。
4. 只有出现第二个真实实现或测试替身时才增加新的可替换接口，避免过度抽象。
5. Outbox publisher 只能承诺至少一次；消费者必须用事件 ID 去重，禁止把“正常情况下只发一次”当保证。