Spring Boot

com.acme.shop
├── order/
│   ├── OrderController.java       // @RestController — web edge
│   ├── OrderService.java          // @Service — @Transactional unit of work
│   ├── OrderRepository.java       // extends JpaRepository<Order, Long>
│   ├── Order.java                 // @Entity (jakarta.persistence)
│   └── dto/CreateOrderRequest.java, OrderResponse.java   // records, never entities
├── config/AppProperties.java      // @ConfigurationProperties record
├── security/SecurityConfig.java   // SecurityFilterChain bean
└── ShopApplication.java           // @SpringBootApplication

@RestController
@RequestMapping("/api/users")
class UserController {
    private final UserService users;
    UserController(UserService users) { this.users = users; }   // constructor injection

    @PostMapping(version = "1")                                  // Boot 4 API versioning
    ResponseEntity<UserResponse> create(@Valid @RequestBody CreateUserRequest req) {
        UserResponse body = users.create(req);
        URI location = URI.create("/api/users/" + body.id());
        return ResponseEntity.created(location).body(body);     // 201 + Location
    }
}

record CreateUserRequest(@NotBlank String name, @Email String email) {}
record UserResponse(Long id, String name, String email) {}

@RestControllerAdvice
class ApiExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    ResponseEntity<ApiError> onInvalid(MethodArgumentNotValidException e) {
        var details = e.getBindingResult().getFieldErrors().stream()
            .map(f -> f.getField() + ": " + f.getDefaultMessage()).toList();
        return ResponseEntity.badRequest().body(new ApiError("validation_failed", "Invalid request", details));
    }
}
record ApiError(String code, String message, List<String> details) {}

// Bad: leaks columns; lazy fields blow up in the serializer after the tx closes.
@GetMapping("/{id}") User get(@PathVariable Long id) { return repo.findById(id).orElseThrow(); }
// Good: map to a DTO inside the transactional service.
@GetMapping("/{id}") UserResponse get(@PathVariable Long id) { return users.get(id); }

@Service
class UserService {
    private final UserRepository repo;
    private final PasswordEncoder encoder;
    UserService(UserRepository repo, PasswordEncoder encoder) { this.repo = repo; this.encoder = encoder; }

    @Transactional
    UserResponse create(CreateUserRequest req) {
        var user = repo.save(new User(req.name(), req.email(), encoder.encode(req.rawPassword())));
        return new UserResponse(user.getId(), user.getName(), user.getEmail());
    }

    @Transactional(readOnly = true)
    UserResponse get(Long id) {
        return repo.findById(id).map(this::toResponse).orElseThrow(() -> new NotFoundException(id));
    }
}

// Bad: not testable with `new`, hides missing beans until runtime, allows final-less mutation.
@Autowired private UserRepository repo;
// Good:
private final UserRepository repo;
UserService(UserRepository repo) { this.repo = repo; }

import jakarta.persistence.*;

@Entity @Table(name = "users")
class User {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id;
    private String name;
    @Column(unique = true) private String email;
    @OneToMany(mappedBy = "user") private List<Order> orders = new ArrayList<>();
    // getters; protected no-arg ctor for Hibernate
}

interface UserRepository extends JpaRepository<User, Long> {
    Optional<User> findByEmail(String email);                       // derived query
    Page<User> findByNameContaining(String q, Pageable page);       // paginated

    @Query("select u from User u join fetch u.orders where u.id = :id")
    Optional<User> findWithOrders(@Param("id") Long id);            // fetch join kills N+1
}

# application.yml — no secrets committed here; import them at boot.
spring:
  config:
    import: "optional:configtree:/run/secrets/"   # mount real secrets at runtime
  datasource:
    url: ${DB_URL}
    username: ${DB_USER}
    password: ${DB_PASSWORD}
app:
  invite-ttl: 24h
  max-orders-per-day: 50
---
spring:
  config:
    activate:
      on-profile: dev
app:
  max-orders-per-day: 5

@ConfigurationProperties(prefix = "app")
record AppProperties(Duration inviteTtl, int maxOrdersPerDay) {}   // typed, validated at startup
// register once: @EnableConfigurationProperties(AppProperties.class) on a @Configuration

@Configuration
@EnableMethodSecurity                                            // enables @PreAuthorize
class SecurityConfig {
    @Bean
    SecurityFilterChain api(HttpSecurity http) throws Exception {
        http
          .csrf(csrf -> csrf.disable())                          // OK: stateless token API, no cookies
          .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
          .authorizeHttpRequests(auth -> auth
              .requestMatchers(HttpMethod.POST, "/api/users").permitAll()
              .requestMatchers("/api/admin/**").hasRole("ADMIN")
              .anyRequest().authenticated())
          .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()));
        return http.build();
    }

    @Bean PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); }
}

@WebMvcTest(UserController.class)
class UserControllerTest {
    @Autowired MockMvc mvc;
    @MockitoBean UserService users;                              // not @MockBean

    @Test void rejectsBlankName() throws Exception {
        mvc.perform(post("/api/users").contentType(MediaType.APPLICATION_JSON)
                .content("{\"name\":\"\",\"email\":\"a@b.co\"}"))
           .andExpect(status().isBadRequest());
    }
}

@TestConfiguration(proxyBeanMethods = false)
class ContainersConfig {
    @Bean @ServiceConnection
    PostgreSQLContainer<?> postgres() { return new PostgreSQLContainer<>("postgres:17"); }
}