Stack Java Spring — InfoWhere

Template de stack para projetos Java
Última atualização: 25/01/2026
Nível de experiência: ⭐⭐⭐⭐⭐ Expert

1. Visão Geral

Stack principal para projetos enterprise, APIs robustas e sistemas de clientes.

2. Versões

3. Dependências Core

3.1 Spring Ecosystem

<!-- Core -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- Security + OAuth2 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

<!-- Data -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

<!-- Validation -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

3.2 Database

<!-- PostgreSQL -->
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

<!-- Liquibase (migrations) -->
<dependency>
    <groupId>org.liquibase</groupId>
    <artifactId>liquibase-core</artifactId>
</dependency>

3.3 Documentação API

<!-- OpenAPI / Swagger -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

3.4 Utilitários

<!-- Lombok -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>

<!-- MapStruct (DTO mapping) -->
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.5.5.Final</version>
</dependency>

4. Testes

<!-- JUnit 5 + Spring Test -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

<!-- Testcontainers -->
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>postgresql</artifactId>
    <scope>test</scope>
</dependency>

<!-- Security Test -->
<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-test</artifactId>
    <scope>test</scope>
</dependency>

Cobertura mínima: 80-85%

5. Autenticação / Autorização

Configuração típica

@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    return http
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/api/public/**").permitAll()
            .requestMatchers("/api/admin/**").hasRole("ADMIN")
            .anyRequest().authenticated()
        )
        .oauth2ResourceServer(oauth2 -> oauth2
            .jwt(Customizer.withDefaults())
        )
        .build();
}

6. Database

Convenções

• Tabelas: snake_case plural (users, invoices)
• Colunas: snake_case (created_at, user_id)
• Índices: idx_{table}_{column}
• Foreign Keys: fk_{table}_{ref_table}

7. Estrutura do Projeto

src/main/java/com/infowhere/{projeto}/
├── config/                 # Configurações Spring
│   ├── SecurityConfig.java
│   ├── OpenApiConfig.java
│   └── ...
├── controller/             # REST Controllers
│   └── api/
│       └── v1/
├── service/                # Business logic
├── repository/             # Spring Data repos
├── domain/                 # Entities
│   ├── entity/
│   └── dto/
├── mapper/                 # MapStruct mappers
├── exception/              # Custom exceptions
│   └── handler/            # Global exception handler
└── util/                   # Utilitários

src/main/resources/
├── application.yml
├── application-dev.yml
├── application-prod.yml
└── db/
    └── changelog/          # Liquibase migrations
        └── db.changelog-master.xml

src/test/java/
├── integration/            # Testes de integração
├── unit/                   # Testes unitários
└── fixtures/               # Test data

8. Padrões e Convenções

8.1 API REST

• Versionamento: /api/v1/
• Formato: JSON
• Naming: kebab-case para URLs (/api/v1/user-profiles)
• Métodos: GET, POST, PUT, PATCH, DELETE
• Status codes: 200, 201, 204, 400, 401, 403, 404, 500

8.2 DTOs

• Request: *Request (ex: CreateUserRequest)
• Response: *Response (ex: UserResponse)
• Nunca expor entities diretamente

8.3 Exceptions

// Custom exception
public class ResourceNotFoundException extends RuntimeException { }

// Global handler
@RestControllerAdvice
public class GlobalExceptionHandler { }

8.4 Logs

• Framework: SLF4J + Logback
• Formato: JSON em produção
• Níveis: ERROR, WARN, INFO, DEBUG

9. Infraestrutura

Dockerfile típico

FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

10. O que NÃO usar

11. Checklist de Novo Projeto

• Criar projeto no Spring Initializr
• Configurar application.yml com profiles
• Configurar SecurityConfig com Keycloak
• Configurar Liquibase
• Criar estrutura de pastas
• Configurar OpenAPI/Swagger
• Configurar GlobalExceptionHandler
• Criar Dockerfile
• Criar docker-compose.yml para dev
• Configurar testes com Testcontainers
• Criar README.md com instruções

12. Links de Referência

• Spring Boot Docs
• Spring Security Docs
• Keycloak Docs
• Liquibase Docs

Nota: Este template é a base. Cada projeto pode ter ajustes específicos documentados no technical_context.md do projeto.