version: "1.0.0" name: spring-mvc-patterns description: Servlet Spring stack patterns — @RestController, MockMvc, HandlerInterceptor, OncePerRequestFilter, JPA, Pageable, RestTemplate/RestClient. Project must use Spring MVC (blocking, 1-thread-per-request). Mutually exclusive with spring-webflux-patterns. triggers: natural: ["servlet endpoint", "rest controller", "mockmvc test", "rest template"] code: ["@RestController", "MockMvc", "HttpServletRequest", "RestTemplate", "RestClient", "OncePerRequestFilter"] applicability: always: false triggers: files_match: ["/*Controller.java", "/*Filter.java", "/*Interceptor.java", "/application*.yml"] code_patterns: ["HttpServletRequest", "HttpServletResponse", "RestTemplate", "RestClient", "OncePerRequestFilter", "HandlerInterceptor", "JpaRepository", "MockMvc"] task_keywords: ["mvc", "servlet", "blocking", "JPA", "RestTemplate", "MockMvc"] related_rules:

• rules/java/api-design.md
• rules/java/security.md

relevance_assessment: | HIGH 90%+: project uses Spring MVC (verified: spring-boot-starter-web on classpath, no spring-boot-starter-webflux) HIGH 80%+: task adds REST endpoint OR uses RestTemplate/RestClient MEDIUM 40-79%: task touches MVC infrastructure (filter, interceptor, MockMvc test) LOW 1-39%: task tangentially related (e.g., DTO that crosses servlet boundary) ZERO: project uses WebFlux (reactive stack); verify in application.yml

Spring MVC Patterns — Servlet Stack

Stack constraint

MVC is blocking, 1 thread per request. NEVER mix with WebFlux. Verify:

• spring-boot-starter-web on classpath (no spring-boot-starter-webflux)
• All I/O OK to block: JDBC/JPA, Jedis, spring-kafka (blocking consumer fine)
• Throughput: moderate (<1k concurrent) — saturates at thread pool

Controller pattern

@RestController
@RequestMapping("/api/v1/orders")
@RequiredArgsConstructor
@Validated
public class OrderController {
    private final CreateOrderUseCase createOrderUseCase;
 
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public OrderResponse createOrder(@Valid @RequestBody CreateOrderRequest request) {
        return createOrderUseCase.execute(request);
    }
 
    @GetMapping
    public Page<OrderDto> list(@PageableDefault(size = 20) Pageable pageable) {
        return orderQueryService.findAll(pageable);
    }
}

Rules: @RequiredArgsConstructor, @Valid on request bodies, return DTOs (never entities), Pageable with @Max(100) size cap.

Filter — OncePerRequestFilter

@Component
public class TracingFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest req, HttpServletResponse resp, FilterChain chain)
        throws ServletException, IOException {
        String requestId = Optional.ofNullable(req.getHeader("X-Request-Id"))
            .orElse(UUID.randomUUID().toString());
        MDC.put("requestId", requestId);
        try {
            chain.doFilter(req, resp);
        } finally {
            MDC.clear();
        }
    }
}

MDC works in MVC (ThreadLocal) — different from WebFlux Reactor Context.

HandlerInterceptor (rate limiting, auth checks)

@Component
@RequiredArgsConstructor
public class RateLimitInterceptor implements HandlerInterceptor {
    private final RateLimiter rateLimiter;
 
    @Override
    public boolean preHandle(HttpServletRequest req, HttpServletResponse resp, Object handler) {
        if (!rateLimiter.tryAcquire(req.getRemoteAddr())) {
            resp.setStatus(429);
            return false;
        }
        return true;
    }
}

Register via WebMvcConfigurer.addInterceptors().

JPA transactions

@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderRepository repo;
 
    @Transactional
    public Order placeOrder(Order order) {
        Order saved = repo.save(order);
        eventPublisher.publish(saved);
        return saved;
    }
 
    @Transactional(readOnly = true)
    public Page<Order> findAll(Pageable pageable) {
        return repo.findAll(pageable);
    }
}

@Transactional(readOnly = true) on query methods — JPA optimization. Always set spring.jpa.open-in-view: false.

Security filter

Servlet security via SecurityFilterChain (NOT SecurityWebFilterChain):

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    return http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/actuator/health").permitAll()
            .anyRequest().authenticated())
        .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()))
        .build();
}

Method security: @EnableMethodSecurity (not @EnableReactiveMethodSecurity).

HTTP client — RestClient (Spring 6.1+) or RestTemplate

@Configuration
public class HttpClientConfig {
    @Bean
    public RestClient userServiceClient(@Value("${user-service.url}") String baseUrl) {
        return RestClient.builder()
            .baseUrl(baseUrl)
            .requestFactory(new SimpleClientHttpRequestFactory() {{
                setConnectTimeout(2000);
                setReadTimeout(5000);
            }})
            .build();
    }
}

Prefer RestClient over RestTemplate in Spring 6.1+. ALWAYS set timeouts.

Testing — MockMvc

@WebMvcTest(OrderController.class)
class OrderControllerTest {
    @Autowired MockMvc mockMvc;
    @MockBean CreateOrderUseCase createOrderUseCase;
 
    @Test
    void shouldCreateOrderWhenValidRequest() throws Exception {
        mockMvc.perform(post("/api/v1/orders")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{\"productId\":\"p1\",\"quantity\":2}"))
            .andExpect(status().isCreated());
    }
}

@WebMvcTest slices context to controller layer. Mock use case.

Anti-patterns

Verification checklist

• [ ] @RequiredArgsConstructor (no @Autowired)
• [ ] @Valid on request bodies
• [ ] DTOs returned (never entities)
• [ ] @Transactional(readOnly = true) on queries
• [ ] spring.jpa.open-in-view: false
• [ ] Pagination capped (@Max(100))
• [ ] HTTP client timeouts configured
• [ ] MockMvc tests cover controllers
• [ ] Graceful shutdown + actuator configured

References

• [references/spring-mvc.md](references/spring-mvc.md) — Full controller patterns, MockMvc, filters, interceptors, pagination
• [references/springboot-production.md](references/springboot-production.md) — Caching, async, rate limiting, Jackson, HikariCP, graceful shutdown
• [references/springboot-3x-features.md](references/springboot-3x-features.md) — Virtual threads (3.2+), @HttpExchange, Observation API

Related

• skills/spring-security — SecurityFilterChain
• skills/database-patterns — JPA repository patterns
• skills/api-design — REST conventions, RFC 7807
• skills/testing-workflow — MockMvc, @WebMvcTest