{"id":46893950,"title":"Show HN: Replacing NotNull and Preconditions with fluent Java assertions","points":1,"user":"symplice","time":1770251129,"time_ago":"14 hours ago","type":"link","content":"

Some time ago, I was tasked with maintaining a Java app built using the Clean architecture. In theory, the domain was supposed to remain agnostic, but in reality, every entity was either:

Sprinkled with Jakarta annotations (framework leakage)\nFilled with Guava’s Preconditions.checkArgument() calls (intrusive dependencies)\nCluttered with manual null checks like if (x == null) (inconsistent and untested)

The painful part? A constructor like this (anonymized):

`public Invoice(String customerEmail, BigDecimal amount, List<Item> items, LocalDate dueDate) {\n this.customerEmail = Preconditions.checkNotNull(customerEmail, "email required");\n Preconditions.checkArgument(customerEmail.contains("@"), "bad email");\n Preconditions.checkArgument(customerEmail.length() < 100, "email too long");

    this.amount = Preconditions.checkNotNull(amount);\n    Preconditions.checkArgument(amount.compareTo(BigDecimal.ZERO) > 0, "amount positive");\n    // ...

\n}`

What I tried first:

I removed Jakarta Bean Validation and Apache Commons Validate because they impose strong framework coupling and generate verbose dependencies or generic exceptions, violating domain independence. Bean Validation 3.0 with records improves the situation but is still annotation-based, making it hard to compose for complex business rules.

Constraints I set for myself:

If I were to introduce a dependency into our domain layer, it had to:\nHave no transitive dependencies (single JAR, only java.base)\nThrow typed exceptions (not IllegalArgumentException)\nSupport fluent chaining without hurting readability\nAllow custom predicates without falling into lambda hell

What I built

    `public Invoice(String email, BigDecimal amount, List<Item> items, LocalDate dueDate) {\n    this.email = Assert.field("email", email)\n                       .notBlank()\n                       .email()\n                       .maxLength(100)\n                       .value();\n                       \n    this.amount = Assert.field("amount", amount)\n                        .positive()\n                        .value();\n    // ...

\n}`

Why this matters

The exception hierarchy: Instead of IllegalArgumentException: bad email, you get EmailFormatInvalidException with structured fields (fieldName, invalidValue, constraint). Our monitoring now distinguishes between "user sent garbage" (400) and "developer logic error" (500) automatically.

Composable rules:

    `Assert.field("iban", iban)\n          .notBlank()\n          .satisfies(this::isValidIBANChecksum, "Checksum failed");`\n

\nThe trade-offs (being honest)

Not for Hibernate users: If you're all-in on Jakarta and love @NotNull on your JPA entities, this adds nothing. This is for the "ports and adapters" crowd.\nVerbosity vs. annotations: Yes, it's more lines than @Email @NotNull. But those lines are explicit, testable, and framework-agnostic.

No AOP magic: You can't just slap this on a method parameter and expect auto-validation. This is imperative, intentional, constructor-level defense.

The bigger picture

I've come to believe that validation libraries fall into two categories:\nFramework validation (Jakarta, Spring): Great for binding/HTTP layer, terrible for domain purity.\nUtility validation (Guava, Apache): Great for reuse, terrible for expressiveness and exception granularity.\nThere's a missing middle: Domain-native validation that reads like business rules and fails like typed domain events.

Discussion

For those doing DDD or Clean Architecture in Java - how do you handle input validation without contaminating your entities? Do you accept Jakarta annotations in your domain layer? Write defensive code manually? Or have you found another approach?

Also curious: would typed exceptions (e.g., NumberValueTooLowException vs IllegalArgumentException) actually help your production debugging, or is it over-engineering?

https://github.com/Sympol/pure-assert","url":"item?id=46893950","comments":[{"id":46894437,"level":0,"user":"pestatije","time":1770255010,"time_ago":"13 hours ago","content":"

Another middle-way to go is define your own domain preconditions, then map those to whichever agent your using at compile- and run- times","comments":[]}],"comments_count":1}