Skip to content

a-pavithraa/springboot-skills-marketplace / plugins/springboot-architecture/skills/code-reviewer

code-reviewer

Unverified

Use when asked to review, check or diagnose Spring Boot code: a pull request, diff, module or file before it merges; a slow endpoint or query (N+1, unbounded reads, JPA and Hibernate performance); security, JSpecify null-safety, architecture boundaries or Boot 4 migration risks in existing code; or whether the tests would catch real bugs, proving each finding by running it. Not for Kotlin-only code, non-Spring frameworks, or generic review advice without code context.

references/jspecify-null-safety.md

View on GitHub
# JSpecify Null-Safety (Spring Boot 4 / Spring Framework 7)

## Table of Contents

1. [Purpose](#purpose)
2. [Important: Optional for Applications](#important-optional-for-applications)
3. [Core Rules](#core-rules)
4. [Annotation Placement (Type-Use)](#annotation-placement-type-use)
5. [Migration from org.springframework.lang](#migration-from-orgspringframeworklang)
6. [NullAway (Build-Time Checking)](#nullaway-build-time-checking)
7. [Tooling Guidance](#tooling-guidance)
8. [Official Documentation](#official-documentation)

---

## Purpose

Use JSpecify annotations to make nullability explicit in Spring applications and libraries. Spring Framework 7 and the Spring Boot 4 portfolio expose null-safe APIs with JSpecify; application code should align with those contracts and avoid deprecated Spring null-safety annotations.

## Important: Optional for Applications

**JSpecify is OPTIONAL for application code.** While Spring Boot 4 and Spring Framework 7 internally use JSpecify annotations, applications can:

1. **Adopt JSpecify** (recommended for new projects) - Full type-safety with modern tooling
2. **Keep using Spring's `org.springframework.lang` annotations** (acceptable during transition) - Will work but are deprecated
3. **Use no null-safety annotations** (not recommended but supported) - No compile-time null checking

**When to use JSpecify:**
- New Spring Boot 4 projects
- Projects wanting modern IDE/tooling support
- Libraries that need to interoperate with Spring's null-safe APIs

**When Spring's annotations are acceptable:**
- Existing Spring Boot 3 applications migrating gradually
- Teams not yet ready for type-use annotation syntax
- Legacy codebases with extensive Spring annotation usage

## Core Rules

- **Default non-null** via `@NullMarked` in `package-info.java`.
- **Explicit nullable** with `@Nullable` at the type-use site.
- **Avoid deprecated Spring annotations** from `org.springframework.lang` (`@Nullable`, `@NonNull`, `@NonNullApi`, `@NonNullFields`).
- **Copy nullability annotations on overrides** (JSpecify annotations are not inherited).

## Annotation Placement (Type-Use)

JSpecify annotations are `TYPE_USE`, so place them directly before the type.

```java
// field
private @Nullable String fileEncoding;

// parameter + return type
public @Nullable String buildMessage(@Nullable String message) { ... }
```

### Arrays and Varargs

Type-use syntax matters:

```java
@Nullable Object[] array;          // elements nullable, array non-null
Object @Nullable [] array;         // elements non-null, array nullable
@Nullable Object @Nullable [] arr; // both nullable
```

### Generics

```java
List<String>            // non-null elements
List<@Nullable String>  // nullable elements
```

### Nested and Fully-Qualified Types

Type-use annotations appear after the last dot:

```java
Cache.@Nullable ValueWrapper
jakarta.validation.@Nullable Validator
```

## Migration from org.springframework.lang

Spring’s legacy null-safety annotations are deprecated in Spring Framework 7 in favor of JSpecify. JSpecify is type-use only, so array/varargs declarations must be updated to preserve semantics (for example, `@Nullable Object[]` becomes `Object @Nullable []`).

Place annotations next to the type instead of at the far left:

```java
// before (legacy style)
@Nullable private String field;
@Nullable public String method();

// after (JSpecify style)
private @Nullable String field;
public @Nullable String method();
```

## NullAway (Build-Time Checking)

If the goal is application-wide null-safety, use NullAway:

- Recommended: `NullAway:OnlyNullMarked=true` (checks only `@NullMarked` packages)
- Optional: `NullAway:CustomContractAnnotations=org.springframework.lang.Contract`
- Optional (second step): `NullAway:JSpecifyMode=true` for full JSpecify semantics

## Tooling Guidance

- IDEs can surface nullability issues when JSpecify annotations are present.
- NullAway JSpecify mode requires a recent javac (Spring docs mention JDK 22+). Spring Boot 4 guidance recommends Java 25, or a recent JDK 21.0.8+ with `-XDaddTypeAnnotationsToSymbol=true` if Java 25 is not possible.
- If you must keep a Java 17 baseline, use a Java 25 toolchain with `--release 17`.

---

## Official Documentation

- [JSpecify Reference Documentation](https://jspecify.dev/)
- [JSpecify User Guide](https://jspecify.dev/docs/user-guide)
- [Spring Framework Null-Safety](https://docs.spring.io/spring-framework/reference/core/null-safety.html)
- [NullAway - Uber's Null-Safety Tool](https://github.com/uber/NullAway)
- [JSpecify GitHub Repository](https://github.com/jspecify/jspecify)
- [Spring Boot 4 Migration Guide](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide)
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall