Padrões de Código Java

Padrões para código Java (17+) legível e de fácil manutenção em serviços Spring Boot e Quarkus.

Quando Usar

• Escrevendo ou revisando código Java em projetos Spring Boot ou Quarkus
• Aplicando convenções de nomenclatura, imutabilidade ou tratamento de exceções
• Trabalhando com records, sealed classes ou pattern matching (Java 17+)
• Revisando o uso de Optional, streams ou generics
• Estruturando pacotes e layout do projeto
• [QUARKUS]: Trabalhando com escopos CDI, entidades Panache ou pipelines reativos

Como Funciona

Detecção de Framework

Antes de aplicar os padrões, determine o framework a partir do arquivo de build:

• Arquivo de build contém quarkus → aplique convenções [QUARKUS]
• Arquivo de build contém spring-boot → aplique convenções [SPRING]
• Nenhum detectado → aplique apenas convenções compartilhadas

Princípios Fundamentais

• Prefira clareza à esperteza
• Imutável por padrão; minimize o estado mutável compartilhado
• Falhe rapidamente com exceções significativas
• Nomenclatura e estrutura de pacotes consistentes
• [QUARKUS]: Prefira processamento em tempo de compilação em vez de em tempo de execução; evite reflexão em tempo de execução sempre que possível

Exemplos

As seções abaixo mostram exemplos concretos de Spring Boot, Quarkus e Java compartilhados para nomenclatura, imutabilidade, injeção de dependência, código reativo, exceções, layout de projeto, logging, configuração e testes.

Nomenclatura

// PASS: Classes/Records: PascalCase
public class MarketService {}
public record Money(BigDecimal amount, Currency currency) {}

// PASS: Methods/fields: camelCase
private final MarketRepository marketRepository;
public Market findBySlug(String slug) {}

// PASS: Constants: UPPER_SNAKE_CASE
private static final int MAX_PAGE_SIZE = 100;

// PASS: [QUARKUS] JAX-RS resources named as *Resource, not *Controller
public class MarketResource {}

// PASS: [SPRING] REST controllers named as *Controller
public class MarketController {}

Imutabilidade

// PASS: Favor records and final fields
public record MarketDto(Long id, String name, MarketStatus status) {}

public class Market {
  private final Long id;
  private final String name;
  // getters only, no setters
}

// PASS: [QUARKUS] Panache active-record entities use public fields (Quarkus convention)
@Entity
public class Market extends PanacheEntity {
  public String name;
  public MarketStatus status;
  // Panache generates accessors at build time; public fields are idiomatic here
}

// PASS: [QUARKUS] Panache MongoDB entities
@MongoEntity(collection = "markets")
public class Market extends PanacheMongoEntity {
  public String name;
  public MarketStatus status;
}

Uso de Optional

// PASS: Return Optional from find* methods
// [SPRING]
Optional<Market> market = marketRepository.findBySlug(slug);

// [QUARKUS] Panache
Optional<Market> market = Market.find("slug", slug).firstResultOptional();

// PASS: Map/flatMap instead of get()
return market
    .map(MarketResponse::from)
    .orElseThrow(() -> new EntityNotFoundException("Market not found"));

Melhores Práticas de Streams

// PASS: Use streams for transformations, keep pipelines short
List<String> names = markets.stream()
    .map(Market::name)
    .filter(Objects::nonNull)
    .toList();

// FAIL: Avoid complex nested streams; prefer loops for clarity

Injeção de Dependência

// PASS: [SPRING] Constructor injection (preferred over @Autowired on fields)
@Service
public class MarketService {
  private final MarketRepository marketRepository;

  public MarketService(MarketRepository marketRepository) {
    this.marketRepository = marketRepository;
  }
}

// PASS: [QUARKUS] Constructor injection
@ApplicationScoped
public class MarketService {
  private final MarketRepository marketRepository;

  @Inject
  public MarketService(MarketRepository marketRepository) {
    this.marketRepository = marketRepository;
  }
}

// PASS: [QUARKUS] Package-private field injection (acceptable in Quarkus — avoids proxy issues)
@ApplicationScoped
public class MarketService {
  @Inject
  MarketRepository marketRepository;
}

// FAIL: [SPRING] Field injection with @Autowired
@Autowired
private MarketRepository marketRepository; // use constructor injection

// FAIL: [QUARKUS] @Singleton when interception or lazy init is needed
@Singleton // non-proxyable — use @ApplicationScoped instead
public class MarketService {}

Padrões Reativos [QUARKUS]

// APROVADO: Retorna Uni/Multi de endpoints reativos
@GET
@Path("/{slug}")

…