web-spring-boot-starter

The web-spring-boot-starter project delivers an opinionated web layer for Spring Boot 3.5.x applications. It groups reusable context components, auto-configuration, and a consumable starter so teams can enable unified API behaviour with one dependency.

Table of Contents

• Modules
• Features
• Quick Start
• Sample Response
• Configuration Hints
• Authentication Integration
• Internationalisation
• Requirements
• Build & Test
• Versioning & Release
• Project Links
• License

Modules

• web-spring-boot-context — shared building blocks such as the ApiResponse model (now carrying traceId), global exception handling, trace propagation helpers, and request logging filters.

• web-spring-boot-autoconfigure — conditional beans, configuration properties, and metadata that wire the context components into a servlet web application.

• web-spring-boot-starter — starter POM that exposes the auto-configuration alongside Spring Web dependencies for consumers.

Features

• Consistent JSON envelope through ApiResponse<T> exposing code, message, data, and the active traceId.

• GlobalExceptionHandler returning structured errors for validation, business, and generic failures.

• Optional response wrapping via ResponseBodyAdvice, toggled with web.starter.response.enabled.

• Trace propagation filter that reads or generates X-Trace-Id, stores it in MDC, and surfaces it in every response body.

• Request logging filter with configurable header dumps and payload truncation.

• Internationalised message lookup based on Accept-Language, plus a MessageResolver helper.

• Sensible Jackson defaults (ISO-8601 dates, optional long-to-string serialisation) and configurable CORS policy.

• Optional @LoginRequired annotation with a pluggable LoginRequirementEvaluator to integrate project-specific authentication.

Quick Start

Add the starter to your Spring Boot application:

<dependency>
  <groupId>com.childrengreens</groupId>
  <artifactId>web-spring-boot-starter</artifactId>
  <version>0.0.1</version>
</dependency>

With the starter on the classpath your existing controllers can continue returning domain objects or DTOs. The ResponseWrappingAdvice supplied by the context module will automatically wrap non ApiResponse payloads when web.starter.response.enabled=true, attach the current traceId, and keep ResponseEntity/String responses untouched.

Sample Response

A minimal controller can stay focused on domain data:

@RestController
class StatusController {

    @GetMapping("/status")
    StatusPayload status() {
        return new StatusPayload("UP");
    }

    record StatusPayload(String state) { }
}

When response wrapping is enabled the HTTP payload becomes:

{
  "code": "0",
  "message": "OK",
  "data": {
    "state": "UP"
  },
  "traceId": "a8ad0b6ee5c84fab"
}

If the controller throws an exception handled by GlobalExceptionHandler, the structure remains identical:

{
  "code": "BUSINESS_ERROR",
  "message": "Login required",
  "data": null,
  "traceId": "a8ad0b6ee5c84fab"
}

Configuration Hints

The starter provides rich metadata so IDEs offer auto-completion for all web.starter.* properties. A full reference is available in Web Starter Properties Guide. Common tweaks:

web.starter.trace.enabled=true
web.starter.trace.header-name=X-Trace-Id
web.starter.response.enabled=true
web.starter.response.wrap-on-null-body=false
web.starter.logging.include-headers=true
web.starter.logging.max-payload-size=16KB
web.starter.jackson.write-long-as-string=true
web.starter.cors.allowed-origins=https://example.com

Authentication Integration

Annotate handlers with @LoginRequired and supply a LoginRequirementEvaluator bean that performs project-specific checks.

@LoginRequired(scope = "admin")
@GetMapping("/admin/metrics")
String adminOnlyEndpoint() {
    return "top-secret";
}

@Bean
LoginRequirementEvaluator loginRequirementEvaluator(UserSessionService sessions) {
    return (request, handler, scope) -> {
        if (!sessions.isAuthenticated(scope)) {
            throw new UnauthorizedException("Not logged in");
        }
    };
}

The interceptor is only registered when web.starter.auth.enabled=true and an evaluator bean is present.

Internationalisation

Enable i18n support by configuring message bundles:

web.starter.i18n.enabled=true
web.starter.i18n.base-names=classpath:i18n/messages
web.starter.i18n.default-locale=zh_CN

The starter exposes a MessageResolver abstraction that honours the current request Locale, enabling re-usable message lookup from services or controllers.

Requirements

• JDK 17+

• Maven 3.9+

• Spring Boot 3.5.x

Build & Test

# Format license headers, compile all modules, and run tests
mvn clean install

# Focus on auto-configuration tests only
mvn -pl web-spring-boot-autoconfigure test

# Faster local iteration while developing
mvn -T 1C clean install -DskipTests=true

Versioning & Release

• The root pom.xml keeps the project version in the revision property. Bump releases with mvn versions:set -DnewVersion=x.y.z (run in the project root) so every module stays aligned.

• During local builds the canonical POM still contains ${revision}; flatten-maven-plugin (wired in the default lifecycle) resolves it to a literal version before artifacts are installed or deployed.

• To publish to Maven Central, ensure your ~/.m2/settings.xml defines credentials for the ossrh server, then run:

mvn -Prelease deploy

The `release` profile signs artifacts and attaches sources/javadoc jars as required by Central.

Project Links

• Home: https://github.com/ChildrenGreens/web-spring-boot-starter

• Issues: https://github.com/ChildrenGreens/web-spring-boot-starter/issues

License

Apache License 2.0. See LICENSE.txt in the project root.