Arquitetura Hexagonal na prática: Portas e Adaptadores em um sistema de Matchmaking

HTTP -> Controller -> Porta de Entrada -> Caso de Uso -> Domínio
     -> Porta de Saída -> Adaptador JPA -> Banco
     -> Porta de Saída -> Adaptador de Eventos

package com.henriquemarino.matchmaking.domain.model;
 
import com.henriquemarino.matchmaking.domain.events.DomainEvent;
import com.henriquemarino.matchmaking.domain.events.MatchCreatedEvent;
import com.henriquemarino.matchmaking.domain.events.PlayerJoinedMatchEvent;
import com.henriquemarino.matchmaking.domain.exceptions.InvalidMatchStateException;
import com.henriquemarino.matchmaking.domain.exceptions.MatchFullException;
import com.henriquemarino.matchmaking.domain.exceptions.PlayerAlreadyInMatchException;
 
import java.util.ArrayList;
import java.util.List;
import java.util.Objects;
 
public class Match {
    private final MatchId id;
    private final GameMode gameMode;
    private MatchStatus status;
    private final List<Player> players;
    private final List<DomainEvent> domainEvents = new ArrayList<>();
 
    private Match(MatchId id, GameMode gameMode, MatchStatus status, List<Player> players) {
        this.id = id;
        this.gameMode = gameMode;
        this.status = status;
        this.players = players;
    }
 
    public static Match create(MatchId id, GameMode gameMode) {
        Objects.requireNonNull(id, "MatchId não pode ser nulo");
        Objects.requireNonNull(gameMode, "GameMode não pode ser nulo");
 
        Match match = new Match(id, gameMode, MatchStatus.WAITING_FOR_PLAYERS, new ArrayList<>());
        match.recordEvent(MatchCreatedEvent.of(id, gameMode));
        return match;
    }
 
    public static Match rehydrate(
            MatchId id,
            GameMode gameMode,
            MatchStatus status,
            List<Player> players
    ) {
        return new Match(id, gameMode, status, new ArrayList<>(players));
    }
 
    public void join(Player player) {
        Objects.requireNonNull(player, "Player não pode ser nulo");
 
        if (players.contains(player)) {
            throw new PlayerAlreadyInMatchException(id, player.id());
        }
        if (status == MatchStatus.READY) {
            throw new MatchFullException(id, gameMode.capacity());
        }
        if (status != MatchStatus.WAITING_FOR_PLAYERS) {
            throw new InvalidMatchStateException(id, status, "entrar em");
        }
 
        players.add(player);
        recordEvent(PlayerJoinedMatchEvent.of(id, player.id(), players.size(), gameMode.capacity()));
 
        if (players.size() == gameMode.capacity()) {
            status = MatchStatus.READY;
        }
    }
 
    public List<DomainEvent> pullDomainEvents() {
        List<DomainEvent> pulled = List.copyOf(domainEvents);
        domainEvents.clear();
        return pulled;
    }
 
    private void recordEvent(DomainEvent event) {
        domainEvents.add(event);
    }
}

package com.henriquemarino.matchmaking.ports.outbound;
 
import com.henriquemarino.matchmaking.domain.model.Match;
import com.henriquemarino.matchmaking.domain.model.MatchId;
import java.util.Optional;
 
public interface MatchRepository {
    Match save(Match match);
    Optional<Match> findById(MatchId matchId);
 
    // ... além das consultas de histórico (findFinishedMatches, findFinishedMatchesByPlayer)
}

package com.henriquemarino.matchmaking.application.usecases;
 
import com.henriquemarino.matchmaking.application.commands.JoinMatchCommand;
import com.henriquemarino.matchmaking.domain.exceptions.MatchNotFoundException;
import com.henriquemarino.matchmaking.domain.model.Match;
import com.henriquemarino.matchmaking.domain.model.Player;
import com.henriquemarino.matchmaking.ports.inbound.JoinMatchUseCase;
import com.henriquemarino.matchmaking.ports.outbound.DomainEventPublisher;
import com.henriquemarino.matchmaking.ports.outbound.MatchRepository;
 
public class JoinMatchService implements JoinMatchUseCase {
 
    private final MatchRepository matchRepository;
    private final DomainEventPublisher eventPublisher;
 
    public JoinMatchService(MatchRepository matchRepository, DomainEventPublisher eventPublisher) {
        this.matchRepository = matchRepository;
        this.eventPublisher = eventPublisher;
    }
 
    @Override
    public Match join(JoinMatchCommand command) {
        Match match = matchRepository.findById(command.matchId())
                .orElseThrow(() -> new MatchNotFoundException(command.matchId()));
 
        match.join(Player.join(command.playerId(), command.skillRating()));
 
        Match saved = matchRepository.save(match);
        eventPublisher.publishAll(match.pullDomainEvents());
 
        return saved;
    }
}

public void start(TeamBalancingStrategy balancingStrategy) {
    if (status != MatchStatus.READY) {
        throw new InvalidMatchStateException(id, status, "iniciar");
    }
 
    balancingStrategy.balance(players);
    status = MatchStatus.IN_PROGRESS;
    startedAt = Instant.now();
    recordEvent(MatchStartedEvent.of(id, startedAt));
}

public class SkillBasedTeamBalancingStrategy implements TeamBalancingStrategy {
 
    @Override
    public void balance(List<Player> players) {
        List<Player> ordered = new ArrayList<>(players);
        ordered.sort(Comparator.comparingInt(Player::skillRating).reversed());
 
        int skillOfTeamA = 0;
        int skillOfTeamB = 0;
        int sizeOfTeamA = 0;
        int sizeOfTeamB = 0;
        int halfSize = ordered.size() / 2;
 
        for (Player player : ordered) {
            boolean teamAisFull = sizeOfTeamA == halfSize;
            boolean teamBisFull = sizeOfTeamB == halfSize;
            boolean goToTeamA = !teamAisFull && (teamBisFull || skillOfTeamA <= skillOfTeamB);
 
            if (goToTeamA) {
                player.assignTeam(Team.TEAM_A);
                skillOfTeamA += player.skillRating();
                sizeOfTeamA++;
            } else {
                player.assignTeam(Team.TEAM_B);
                skillOfTeamB += player.skillRating();
                sizeOfTeamB++;
            }
        }
    }
}

package com.henriquemarino.matchmaking.adapters.outbound.persistence;
 
import com.henriquemarino.matchmaking.domain.model.Match;
import com.henriquemarino.matchmaking.ports.outbound.MatchRepository;
import org.springframework.stereotype.Repository;
 
@Repository
public class MatchPersistenceAdapter implements MatchRepository {
 
    private final SpringDataMatchRepository jpaRepository;
    private final MatchPersistenceMapper mapper;
 
    public MatchPersistenceAdapter(SpringDataMatchRepository jpaRepository, MatchPersistenceMapper mapper) {
        this.jpaRepository = jpaRepository;
        this.mapper = mapper;
    }
 
    @Override
    public Match save(Match match) {
        // Converte o modelo puro de domínio para a entidade anotada com JPA
        MatchJpaEntity entity = jpaRepository.findById(match.id().value())
                .map(existing -> {
                    mapper.updateEntity(existing, match);
                    return existing;
                })
                .orElseGet(() -> mapper.toNewEntity(match));
 
        // Salva de fato no banco e converte de volta para o domínio
        return mapper.toDomain(jpaRepository.save(entity));
    }
 
    // ... findById
}

@BeforeEach
void setUp() {
    repository = new InMemoryMatchRepository();
    publisher = new RecordingEventPublisher();
 
    createMatch = new CreateMatchService(new MatchFactory(), repository, publisher);
    joinMatch = new JoinMatchService(repository, publisher);
    startMatch = new StartMatchService(repository, new SkillBasedTeamBalancingStrategy(), publisher);
    finishMatch = new FinishMatchService(repository, publisher);
    getHistory = new GetMatchHistoryService(repository);
}

@Test
void fullLifecycleShouldEndInHistory() {
    Match created = createMatch.create(new CreateMatchCommand(GameMode.SOLO_DUEL));
    MatchId matchId = created.id();
    PlayerId playerOne = PlayerId.newId();
 
    joinMatch.join(new JoinMatchCommand(matchId, playerOne, 100));
    Match ready = joinMatch.join(new JoinMatchCommand(matchId, PlayerId.newId(), 80));
    assertThat(ready.status()).isEqualTo(MatchStatus.READY);
 
    Match started = startMatch.start(new StartMatchCommand(matchId));
    assertThat(started.status()).isEqualTo(MatchStatus.IN_PROGRESS);
    assertThat(started.players()).allMatch(p -> p.team().isPlayable());
 
    Match finished = finishMatch.finish(new FinishMatchCommand(matchId, Team.TEAM_A, "GG"));
    assertThat(finished.status()).isEqualTo(MatchStatus.FINISHED);
 
    assertThat(getHistory.getHistory(GetMatchHistoryQuery.forPlayer(playerOne))).hasSize(1);
}

@Component
public class KafkaDomainEventPublisher implements DomainEventPublisher {
    private final KafkaTemplate<String, Object> kafkaTemplate;
 
    public KafkaDomainEventPublisher(KafkaTemplate<String, Object> kafkaTemplate) {
        this.kafkaTemplate = kafkaTemplate;
    }
 
    @Override
    public void publishAll(List<DomainEvent> events) {
        events.forEach(event -> kafkaTemplate.send("matchmaking-events", event));
    }
}