Skip to content
EmersondllPublic

About

Enterprise-grade refactoring and standardization guidelines for Java 26 and Spring Boot 4.0.7 microservices.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

java-spec

Enterprise standards for Java 17 or newer and Spring Boot 3 or 4, on Maven or Gradle. Maintainer: Emerson Lima — https://github.com/Emersondll

This package tells a person or a coding agent how to write, review, and change a Spring Boot service. It does not generate a sample product. It does not add a class, a dependency, or a pattern that the repository does not already use and that the task does not ask for.

Quarkus, Micronaut, and Jakarta EE application servers are out of scope. Optional stacks (WebFlux, Batch, Spring Integration, Kafka, Redis, Liquibase, Keycloak, Helm, a second CI system) are documented for a service that already has them, or for a task that asks for them.

How to read it

  1. SKILL.md is the contract: conduct, rules, the router, and precedence.
  2. references/01-versions.md is the only place for Java, Spring Boot, starter, JaCoCo, SpotBugs, and image-major numbers. A version written in another file is a token to fill from that matrix.
  3. Open one topic file for the task. Do not load the whole tree.
  4. When two files disagree, follow SKILL.md for behavior and references/01-versions.md for versions. references/workflows/practices.md does not override a numbered reference.

The short map is references/00-index.md. The one-page rules are references/02-rules.md. Conduct is references/03-conduct.md.

Layout

java-spec/
├── SKILL.md                 contract and router
├── README.md                this file
├── scripts/
│   └── audit_java.py        mechanical checks (tree-sitter)
└── references/
    ├── 00-index.md … 39-refactor-checklist.md
    └── workflows/           procedures, not extra rules

Numbers are unique. There is no 01b, 06b, or 20c. The two digits are the file id. The slug is the subject. Workflows stay in workflows/ so a procedure is not confused with a topic of the same name (17-openapi.md is the contract shape; workflows/generate-openapi.md is how to write the file).

What each file decides

Start

File Subject
SKILL.md Rules, router, precedence
references/00-index.md File list
references/01-versions.md Java 17+, Boot 3 and Boot 4, starters, tool floors
references/02-rules.md One-page rules
references/03-conduct.md How to work: no unused type, no new pattern, JavaDoc, OpenAPI from real mappings

Workflows

File Subject
references/workflows/generate-openapi.md Write openapi.yaml from the controllers. JavaDoc in the same change
references/workflows/rest.md Resource URLs, verbs, status codes
references/workflows/run-tests.md Unit, slice, integration, end-to-end, coverage, mutation
references/workflows/refactor.md Change structure without changing behavior
references/workflows/write-docs.md README, JavaDoc, runbooks
references/workflows/practices.md Design choices that lose to a numbered reference

Service shape

File Subject
references/04-architecture.md Packages, layering, API version in the path
references/05-hexagonal.md Ports and adapters, only when the project is already hexagonal
references/06-quality.md Style, null-safety, Lombok, Checkstyle, SpotBugs, Sonar
references/07-java.md Records, sealed types, pattern matching, JavaDoc
references/15-imports.md Import order. No wildcards
references/16-annotations.md Spring stereotypes
references/39-refactor-checklist.md Tick list used with the refactor workflow

HTTP

File Subject
references/17-openapi.md Shape of the OpenAPI document. Not a catalog of endpoints
references/19-errors.md One RFC 9457 body (ErrorResponse, application/problem+json)
references/21-pagination.md List contract
references/28-idempotency.md Idempotency-Key on unsafe creates
references/13-sync-async.md A result the caller needs now stays synchronous. Later work is a message

Data and configuration

File Subject
references/22-mongodb.md MongoDB indexes and Mongock
references/23-jpa.md JPA indexes and Flyway
references/24-profiles.md dev, test, and prod profiles
references/33-data.md PostgreSQL, MySQL, JDBC, Redis, Liquibase, isolation, locking, deadlocks

A new service uses YAML. A repository that already uses application.properties keeps that file. The same key is not defined in both.

Build

File Subject
references/25-maven.md Single-module pom.xml, Surefire, Failsafe, JaCoCo
references/26-gradle.md Kotlin or Groovy DSL, catalog, cache, locking, test suites
references/27-maven-advanced.md Multi-module reactor, Enforcer, reproducible build, PMD

Keep the build tool the repository already has. Do not mix Maven and Gradle. The gate is ./mvnw verify or ./gradlew check.

Messaging and resilience

File Subject
references/20-rabbitmq.md Exchanges, queues, publisher confirms, DLQ, choreography
references/34-messaging.md Outbox relay, inbox, ack and nack, ordering, Kafka, redrive
references/14-circuit-breaker.md Timeouts, Resilience4j, fallback

RabbitMQ and Kafka are not interchangeable. Use the broker already on the classpath.

Security and operations

File Subject
references/18-security.md Gateway token, IDOR, secrets, log redaction
references/35-identity.md OAuth2, OpenID Connect, JWT, Keycloak, injection
references/32-logging.md No personal data in logs, trace id, AppConstants
references/10-observability.md SLF4J, Micrometer, Prometheus, tracing
references/12-otel.md OpenTelemetry compose stack
references/09-performance.md N+1, cache, query shape
references/11-docker.md Multi-stage image and Compose
references/31-cicd.md GitHub Actions, secrets, Kubernetes, Trivy
references/38-platform.md WebFlux, Batch, Integration, Helm, GitLab, Jenkins, Azure, pools, GC
references/30-git.md Branches, Conventional Commits, pull requests
references/29-docs.md What belongs in the README and what belongs in OpenAPI
references/36-scenarios.md New service, upgrades, outages, duplicates, rollback, offline build
references/08-testing.md Pyramid, JaCoCo floors, Testcontainers, PIT
references/37-more-tests.md WireMock, REST Assured, Pact, ArchUnit, jqwik, load, resilience

Script

scripts/audit_java.py <project-dir> checks mechanical rules (field injection, wildcards, method length, missing JavaDoc, mixed YAML and properties, and others). It needs tree-sitter and tree-sitter-java. Exit code 0 is clean. It does not replace ./mvnw verify or ./gradlew check.

Scope in one pass

In scope: Java 17+, Spring Boot 3 and 4, Spring MVC, Spring Security, Spring Data, Spring Cloud as a BOM, validation, Actuator, AMQP, Kafka when the service uses it, Integration and Batch when the service uses them, Maven, Gradle, PostgreSQL, MySQL, MongoDB, Redis as a cache, RabbitMQ, Docker, Testcontainers, quality tools, and observability.

Out of scope: a second error body, an embedded database standing in for production, a frozen patch copied from an example, and a framework that is not Spring Boot.

About

Enterprise-grade refactoring and standardization guidelines for Java 26 and Spring Boot 4.0.7 microservices.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages