Skip to content

Big-Dao/demo-annotations-spring

BranchesTags

Repository files navigation

demo-annotations-spring

Spring Boot 3.5 + Java 25 — an annotation, pattern, and platform showcase wrapped around a real inventory mini-ERP. English below · 中文 further down. Spring Boot 3.5 + Java 25 注解、模式与平台一站式示例，外加一个完整的库存 ERP 沙盒。

tests java spring--boot

English

What's in here

  • 18 production patterns — REST, WebFlux, GraphQL, RSocket, Batch, Quartz, JDBC, JPA, R2DBC, MongoDB, Redis sessions, RabbitMQ, Kafka, WebSocket/STOMP, AOP, Caching, Rate Limiting, Resilience4j.
  • 30+ interactive labs under /labs/* — each ships with a concept card (problem → solution → pitfalls), live UI, and unit tests.
  • A real inventory ERP at /inventory-demo/ — items, tags, documents, dashboards.
  • Guided Tour at /tour/ — 15 ordered stops covering the highlights in ≈ 10 minutes.
  • Showcase deployment — multi-stage Containerfile + bash scripts/deploy-showcase.sh puts the app behind /actuator/health in under a minute.

Requirements

Tool Version
JDK 25 (Temurin / OpenJDK)
Container engine Podman 4+ (or Docker 24+; set ENGINE=docker)
Maven bundled wrapper (./mvnw)

Quick start (60 seconds)

git clone https://github.com/Big-Dao/demo-annotations-spring.git
cd demo-annotations-spring
bash scripts/bootstrap.sh           # check Java 25, warm Maven cache
./mvnw spring-boot:run              # H2 + default profile

Open the Guided Tour for the recommended walkthrough.

Showcase deployment

bash scripts/deploy-showcase.sh     # build image, start container, wait for /actuator/health
# … then visit http://localhost:8080/tour/
bash scripts/deploy-showcase.sh down

Profiles

Profile Purpose
(none) H2 in-memory, all light demos
dev H2 console, GraphiQL, Spring Boot Admin
postgres PostgreSQL + Flyway (podman compose up -d postgres)
redis Spring Session in Redis
rabbitmq / kafka / mongo Their respective brokers/stores
secure JWT auth, method security
otel OpenTelemetry / OTLP exporter (pair with -P!brave,otel)
json-logs Structured Logback JSON output
prod Hardened defaults, requires explicit secrets

Optional containers

podman compose up -d postgres redis rabbitmq kafka mongodb zipkin
podman compose --profile observability up -d   # Prometheus + Grafana + Loki + Tempo

Key URLs

  • / — Inventory demo home
  • /tour/ — Guided Tour (start here)
  • /learn/ — Learning Path & module catalog
  • /health-dashboard/ — Profiles, modules, test snapshot
  • /swagger-ui/index.html — REST API explorer
  • /actuator/health — Liveness probe (returns UP when ready)
  • /labs/observability/ — Observability stack walkthrough
  • /labs/deployment/ — Deployment artefact checklist

Testing

./mvnw test                                  # full suite
./mvnw test -Dtest=TourControllerTest        # one class
./mvnw -Pspotless apply                      # format

Coverage report is generated to target/site/jacoco/ and served at http://localhost:8080/jacoco/ while the app is running.

Project structure

src/main/java/com/example/demoannotations/
├── domain/      JPA entities (BaseEntity, InventoryItem, Person …)
├── repo/        Spring Data interfaces
├── service/     Business logic (@Transactional, @Cacheable, @Async …)
├── web/         REST controllers, page controllers, response wrapping
├── webflux/     Reactive endpoints, functional routes, SSE
├── graphql/     @QueryMapping / @MutationMapping
├── messaging/   RabbitMQ + Kafka + Spring Integration
├── batch/       Spring Batch jobs
├── security/    JWT filter, method security, login flow
├── labs/        30+ self-contained labs (each with a concept card)
├── tour/        Guided Tour curator
└── project/     Module catalog, descriptors

Documentation

License

Educational sample. Use, modify, and extend freely.

中文

项目简介

本仓库是围绕一个真实库存 ERP 沙盒构建的 Spring Boot 3.5 + Java 25 注解与模式示例集，包含：

  • 18 种生产级模式 —— REST、WebFlux、GraphQL、RSocket、Batch、Quartz、JDBC、JPA、R2DBC、MongoDB、Redis 会话、RabbitMQ、Kafka、WebSocket/STOMP、AOP、缓存、限流、Resilience4j。
  • 30+ 个交互实验位于 /labs/*，每个实验都配有「概念卡片」（问题 → 方案 → 陷阱）、可视化 UI 与单元测试。
  • 库存 ERP 沙盒位于 /inventory-demo/，涵盖物料、标签、单据、仪表盘。
  • 导览模式位于 /tour/，15 个有序站点，约 10 分钟看完核心特性。
  • 一键展示部署 —— 多阶段 Containerfile + bash scripts/deploy-showcase.sh，60 秒内启动并通过 /actuator/health 健康检查。

环境要求

工具 版本
JDK 21（Temurin / OpenJDK）
容器引擎 Podman 4+（或 Docker 24+，设置 ENGINE=docker）
Maven 内置 wrapper（./mvnw）

快速开始（60 秒）

git clone https://github.com/Big-Dao/demo-annotations-spring.git
cd demo-annotations-spring
bash scripts/bootstrap.sh           # 检查 Java 25、预热 Maven 缓存
./mvnw spring-boot:run              # H2 + 默认 profile

启动后请打开 导览模式，按推荐路径游览。

展示部署

bash scripts/deploy-showcase.sh     # 构建镜像、启动容器、等待 /actuator/health
# 然后访问 http://localhost:8080/tour/
bash scripts/deploy-showcase.sh down

Spring Profile 一览

Profile 作用
(空) H2 内存库，所有轻量演示
dev 启用 H2 Console、GraphiQL、Spring Boot Admin
postgres PostgreSQL + Flyway（podman compose up -d postgres）
redis 通过 Redis 持久化 HttpSession
rabbitmq / kafka / mongo 启用对应消息或存储
secure 启用 JWT 鉴权与方法安全
otel 切换为 OpenTelemetry / OTLP（搭配 -P!brave,otel）
json-logs Logback 结构化 JSON 输出
prod 生产硬化配置，需要显式密钥

可选服务容器

podman compose up -d postgres redis rabbitmq kafka mongodb zipkin
podman compose --profile observability up -d   # Prometheus + Grafana + Loki + Tempo

核心入口

  • / —— 库存沙盒首页
  • /tour/ —— 导览模式（推荐起点）
  • /learn/ —— 学习路径与模块目录
  • /health-dashboard/ —— Profile / 模块 / 测试统计
  • /swagger-ui/index.html —— REST API 浏览器
  • /actuator/health —— 健康端点（就绪后返回 UP）
  • /labs/observability/ —— 可观测性栈实验
  • /labs/deployment/ —— 部署产物清单

测试

./mvnw test                                  # 全量测试
./mvnw test -Dtest=TourControllerTest        # 单个类
./mvnw -Pspotless apply                      # 代码格式化

JaCoCo 覆盖率报告生成到 target/site/jacoco/，应用运行时可通过 http://localhost:8080/jacoco/ 查看。

目录速览

src/main/java/com/example/demoannotations/
├── domain/      JPA 实体（BaseEntity、InventoryItem、Person …）
├── repo/        Spring Data 接口
├── service/     业务逻辑（@Transactional、@Cacheable、@Async …）
├── web/         REST 控制器、页面控制器、响应包装
├── webflux/     响应式端点、函数式路由、SSE
├── graphql/     @QueryMapping / @MutationMapping
├── messaging/   RabbitMQ + Kafka + Spring Integration
├── batch/       Spring Batch 作业
├── security/    JWT 过滤器、方法安全、登录流程
├── labs/        30+ 个独立实验（每个含概念卡片）
├── tour/        导览模式编排
└── project/     模块目录、描述符

进阶文档

协议

教学示例，欢迎自由使用、修改与扩展。

🌍 世界一流优化（World-Class Hardening）

本仓库已按"世界一流"标准做了系统化加固，可作为生产级 Spring Boot 项目模板参考。

架构概览

flowchart LR
  Client -->|HTTP/2 + gzip| Tomcat
  Tomcat --> SecurityFilters[JWT / Headers / CSP]
  SecurityFilters --> DispatcherServlet
  DispatcherServlet --> Controllers
  Controllers --> Services
  Services --> JPA & RestClient & WebClient & Kafka & Rabbit
  JPA --> H2[(H2/PostgreSQL)]
  Services -. metrics .-> Micrometer --> Prometheus --> Grafana
  Services -. traces  .-> OTel --> Tempo --> Grafana
  Services -. logs    .-> JSON --> Loki --> Grafana
Loading

Profile 矩阵

Profile 用途 依赖服务
(默认) H2 内存库 无
postgres PostgreSQL 持久层 postgres
redis 分布式 Session redis
rabbitmq / kafka 消息总线 rabbit / kafka
mongo 文档存储 mongodb
secure JWT 鉴权链路 无
datasource 多数据源读写分离 无
prod 生产配置（强密钥、压缩、HTTP/2） 视情况组合

质量门 / CI

维度 门禁
单元测试 Surefire（260+ 用例）
集成测试 Failsafe + Testcontainers (*IT.java)
覆盖率 JaCoCo line ≥ 60 % / branch ≥ 35 %
静态分析（可选） ./mvnw -P quality-strict verify（SpotBugs，待 ASM 9.8 支持 Java 25）
架构守护 ArchUnit（受 ASM 影响临时禁用，规则保留）
安全 CodeQL · Trivy（fs + image）· gitleaks · Dependabot
供应链 CycloneDX SBOM（bom.xml/json）

安全头（默认启用）

HSTS · CSP · X-Content-Type-Options · Referrer-Policy · Permissions-Policy · frameOptions=sameOrigin。 CSP 包含 'unsafe-inline' 以兼容 17 个 demo 页面，生产前请按需收紧并迁移至 nonce-based CSP。

性能与可观测性

  • HTTP/2 (h2c) + 响应压缩（≥1KB）。

  • Tomcat 线程上限 / accept queue 显式调优。

  • JVM 默认 ZGC + MaxRAMPercentage=75 + OOM heap dump（见 Containerfile）。

  • 虚拟线程默认开启（spring.threads.virtual.enabled=true）。

  • HTTP 请求直方图 + p50/p95/p99，按 URI 维度。

  • 一键启动可观测性栈：

    podman compose -f compose.observability.yaml up -d
# Grafana :3000  Prometheus :9090  Tempo :3200  Loki :3100  OTel :4318

部署

  • Containerfile：Java 25 + 多阶段 + Layered Jar + 非 root + tini。
  • K8s 清单：deploy/k8s/ 含 Deployment / HPA / PDB / NetworkPolicy / ServiceMonitor。
  • Helm chart：deploy/helm/demo-annotations-spring/，helm install demo ./deploy/helm/demo-annotations-spring。
  • GraalVM native：./mvnw -P native -DskipTests native:compile（部分依赖需补 hints）。

Release 自动化

  • Conventional Commits + Release Drafter（PR 标签自动归类、自动 bump 版本）。
  • CI 在打 tag 时构建并推送镜像至 GHCR，附带 SBOM。

性能基线

./mvnw spring-boot:run &
./scripts/perf-baseline.sh   # 输出至 scripts/perf-baseline.txt

About

Spring Boot annotation demo project - showcasing Spring annotations, testing patterns, and best practices

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages