---
title: "SharedFlow em Kotlin: O que É e Como Funciona | Kotlin Brasil"
url: "https://kotlin.dev.br/glossario/sharedflow/"
markdown_url: "https://kotlin.dev.br/glossario/sharedflow.MD"
description: "O que é SharedFlow em Kotlin, com exemplos: MutableSharedFlow, replay, buffer, extraBufferCapacity, diferença para StateFlow e Channel, e uso com ViewModel."
date: "2026-11-21"
author: "Karina Melo"
---

# SharedFlow em Kotlin: O que É e Como Funciona | Kotlin Brasil

O que é SharedFlow em Kotlin, com exemplos: MutableSharedFlow, replay, buffer, extraBufferCapacity, diferença para StateFlow e Channel, e uso com ViewModel.


## O que é SharedFlow em Kotlin?

**Resposta rápida:** `SharedFlow` é um [Flow](/glossario/flow/) **quente** de *broadcast* da biblioteca `kotlinx.coroutines`. Vários coletores compartilham as mesmas emissões. Ele **não exige um valor atual** (diferente do [StateFlow](/glossario/stateflow/)) e é o padrão idiomático para **eventos one-shot**: snackbar, navegação, analytics, alertas de domínio e fan-out em backends Kotlin.

Pense no `SharedFlow` como um alto-falante no corredor: quem estiver ouvindo agora escuta o aviso. Quem chegou tarde só ouve o que ainda estiver no “replay” configurado — e, se o replay for zero, o aviso já passou. Não é placar permanente; é **mensagem**.

| Característica | SharedFlow |
|---|---|
| Tipo de fluxo | Quente (hot), broadcast |
| Valor atual obrigatório | Não |
| Replay | Configurável (`replay`) |
| Buffer extra | `extraBufferCapacity` |
| Deduplicação por `equals` | Não (emite mesmo valor repetido) |
| Caso de uso típico | Eventos de UI, fan-out, notificações |

### Sintaxe básica

```kotlin
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.SharedFlow
import kotlinx.coroutines.flow.asSharedFlow

sealed interface EventoUi {
    data class MostrarSnackbar(val texto: String) : EventoUi
    data class Navegar(val rota: String) : EventoUi
}

class PedidoViewModel {
    private val _eventos = MutableSharedFlow<EventoUi>(
        replay = 0,
        extraBufferCapacity = 1,
    )
    val eventos: SharedFlow<EventoUi> = _eventos.asSharedFlow()

    suspend fun confirmarPedido() {
        // ... regra de negócio ...
        _eventos.emit(EventoUi.MostrarSnackbar("Pedido confirmado"))
        _eventos.emit(EventoUi.Navegar("pedido/sucesso"))
    }
}
```

A superfície pública expõe apenas `SharedFlow` (somente leitura). A emissão fica no `MutableSharedFlow` privado — o mesmo padrão de encapsulamento do StateFlow.

### Replay, buffer e overflow

`MutableSharedFlow` tem três knobs que mudam o comportamento sob carga:

```kotlin
val eventos = MutableSharedFlow<String>(
    replay = 1,                 // novos coletores recebem o último evento
    extraBufferCapacity = 16,   // folga além do replay
    onBufferOverflow = BufferOverflow.DROP_OLDEST,
)
```

| Parâmetro | Efeito prático |
|---|---|
| `replay` | Quantos valores recentes um assinante novo recebe na hora |
| `extraBufferCapacity` | Slots extras para absorver produtores mais rápidos que consumidores |
| `onBufferOverflow` | O que fazer quando a capacidade estoura: suspender, dropar o mais antigo ou dropar o mais novo |

Capacidade total em memória ≈ `replay + extraBufferCapacity`. Com `replay = 0` e `extraBufferCapacity = 0`, `emit` **suspende** até existir um coletor pronto — útil quando você não quer perder o evento, perigoso se ninguém estiver ouvindo.

```kotlin
import kotlinx.coroutines.channels.BufferOverflow
import kotlinx.coroutines.flow.MutableSharedFlow

val telemetria = MutableSharedFlow<String>(
    replay = 0,
    extraBufferCapacity = 64,
    onBufferOverflow = BufferOverflow.DROP_OLDEST,
)

// tryEmit nunca suspende: retorna false se não couber
val aceito = telemetria.tryEmit("fps=58")
```

- Prefira `emit` (suspend) para eventos de negócio que não podem sumir sem backpressure consciente.
- Prefira `tryEmit` para telemetria/alta frequência, aceitando perda sob pressão.
- `DROP_OLDEST` mantém o sinal mais recente; `DROP_LATEST` preserva o histórico já enfileirado; `SUSPEND` aplica backpressure no produtor.

### Coletar o SharedFlow

```kotlin
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.flow.collect

suspend fun observarEventos(eventos: SharedFlow<EventoUi>) = coroutineScope {
    launch {
        eventos.collect { evento ->
            when (evento) {
                is EventoUi.MostrarSnackbar -> println(evento.texto)
                is EventoUi.Navegar -> println("ir para ${evento.rota}")
            }
        }
    }
}
```

No Jetpack Compose / Android, colete em um escopo ligado ao ciclo de vida para não processar navegação com a tela morta:

```kotlin
@Composable
fun PedidoScreen(viewModel: PedidoViewModel) {
    val context = LocalContext.current

    LaunchedEffect(Unit) {
        viewModel.eventos.collect { evento ->
            when (evento) {
                is EventoUi.MostrarSnackbar -> {
                    // mostrar snackbar
                }
                is EventoUi.Navegar -> {
                    // navegar uma única vez
                }
            }
        }
    }
}
```

Se a arquitetura da tela ainda está em construção, o [guia de MVVM com Kotlin](/guias/guia-arquitetura-mvvm-kotlin/) e o [tutorial de Flow](/tutoriais/kotlin-flow-tutorial/) mostram onde encaixar `SharedFlow` ao lado do estado.

### SharedFlow vs StateFlow vs Flow frio vs Channel

| Necessidade | Escolha | Motivo |
|---|---|---|
| Estado atual sempre disponível (UI, sessão) | [StateFlow](/glossario/stateflow/) | tem `value`, exige inicial, deduplica iguais |
| Eventos one-shot para um ou mais ouvintes | `SharedFlow` | broadcast configurável; não exige estado atual |
| Pipeline sob demanda (rede, disco, transformação) | [Flow](/glossario/flow/) frio | cada collect reinicia o trabalho |
| Comunicação ponto a ponto entre coroutines | [Channel](/glossario/channel/) | fila com capacidade e backpressure explícitos |
| Broadcast com histórico curto | `SharedFlow(replay = N)` | reenvia os últimos N eventos a novos coletores |

```kotlin
class CheckoutViewModel {
    private val _uiState = MutableStateFlow(CheckoutUiState())
    val uiState: StateFlow<CheckoutUiState> = _uiState.asStateFlow()

    private val _eventos = MutableSharedFlow<EventoUi>()
    val eventos: SharedFlow<EventoUi> = _eventos.asSharedFlow()

    suspend fun pagar() {
        _uiState.update { it.copy(carregando = true) }
        // ... gateway ...
        _uiState.update { it.copy(carregando = false, pago = true) }
        _eventos.emit(EventoUi.MostrarSnackbar("Pagamento aprovado"))
    }
}
```

Regra prática: **o que a tela precisa redesenhar** → `StateFlow`. **o que deve acontecer uma vez** → `SharedFlow` (ou `Channel` se for 1:1). Colocar snackbar dentro do `StateFlow` é a receita clássica de toast duplicado após rotação.

### Por que SharedFlow não deduplica?

Diferente do StateFlow, emitir o mesmo conteúdo duas vezes **notifica** os coletores de novo. Isso é desejável para eventos:

```kotlin
data class Alerta(val texto: String)

val alertas = MutableSharedFlow<Alerta>()

alertas.emit(Alerta("Sem conexão"))
alertas.emit(Alerta("Sem conexão")) // segundo coletor/ouvinte também vê
```

Se você precisa “estado atual + histórico de mudanças iguais”, não force o SharedFlow: modele um `StateFlow` para o estado e um `SharedFlow` separado para o efeito.

### Concorrência, escopo e vários coletores

`MutableSharedFlow` é seguro para emissão concorrente. Cada coletor ativo recebe as emissões (respeitando buffer/replay). Cancelar um coletor não cancela os outros.

```kotlin
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.launch

class AuditoriaService {
    private val escopo = CoroutineScope(SupervisorJob() + Dispatchers.Default)
    private val _eventos = MutableSharedFlow<String>(extraBufferCapacity = 32)
    val eventos: SharedFlow<String> = _eventos.asSharedFlow()

    fun registrar(acao: String) {
        escopo.launch {
            _eventos.emit(acao)
        }
    }
}
```

Combine com [coroutines](/glossario/coroutine/), [launch](/glossario/launch/) e [dispatchers](/glossario/dispatcher/): o SharedFlow distribui o sinal; a coroutine decide *quando* emitir.

### Operadores e `shareIn`

Qualquer `Flow` frio pode virar um SharedFlow compartilhado com `shareIn` — o espelho de `stateIn` para streams sem “valor atual” obrigatório:

```kotlin
import kotlinx.coroutines.flow.SharingStarted
import kotlinx.coroutines.flow.map
import kotlinx.coroutines.flow.shareIn

class CotacoesRepository(
    private val escopo: CoroutineScope,
    private val fonte: Flow<Double>,
) {
    val ticks: SharedFlow<Double> = fonte
        .map { preco -> preco }
        .shareIn(
            scope = escopo,
            started = SharingStarted.WhileSubscribed(5_000),
            replay = 1,
        )
}
```

`WhileSubscribed` evita manter o upstream ligado quando ninguém escuta. `replay = 1` entrega o último tick a quem chegar atrasado, sem transformar o fluxo em StateFlow.

### SharedFlow no backend Kotlin

Em serviços JVM o mesmo tipo resolve fan-out: invalidação de cache, progresso de job para vários clientes SSE/WebSocket, alarmes de circuit breaker ou eventos de domínio internos.

```kotlin
class HubProgresso {
    private val _progresso = MutableSharedFlow<Int>(
        replay = 1,
        extraBufferCapacity = 8,
    )
    val progresso: SharedFlow<Int> = _progresso.asSharedFlow()

    suspend fun publicar(percentual: Int) {
        require(percentual in 0..100)
        _progresso.emit(percentual)
    }
}
```

Novos assinantes com `replay = 1` já sabem o percentual mais recente; quem já estava conectado continua recebendo atualizações. Para a stack completa de APIs e mensageria, veja o [guia de Kotlin para backend](/guias/kotlin-para-backend/).

### Erros comuns

- **Usar SharedFlow no lugar de estado de tela.** Sem `value`, a UI não tem um snapshot estável para redesenhar após rotação. Estado → `StateFlow`; efeito → `SharedFlow`.
- **Expor `MutableSharedFlow` publicamente.** Outras camadas passam a emitir eventos arbitrários. Publique `SharedFlow` via `asSharedFlow()`.
- **`replay > 0` em eventos de navegação.** Um coletor atrasado pode “navegar de novo” para uma rota antiga. Para one-shot de UI, comece com `replay = 0`.
- **Capacidade zero sem coletor.** `emit` suspende para sempre se ninguém coleta e não há buffer — deadlock silencioso em testes e em `init {}` de ViewModel.
- **Assumir que `tryEmit` sempre funciona.** Com buffer cheio e overflow `SUSPEND`/sem folga, retorna `false`. Trate o retorno ou use `emit`.
- **Esperar deduplicação automática.** Valores iguais *são* reemitidos. Se isso for problema, filtre no coletor ou modele IDs únicos.
- **Coletar sem Lifecycle no Android.** Um `collect` solto pode processar snackbar/navegação com a Activity destruída. Amarre ao escopo da UI.

### Boas práticas

- Separe **estado** (`StateFlow`) de **efeito** (`SharedFlow`) no mesmo ViewModel/serviço.
- Modele eventos como `sealed interface`/`sealed class` — o glossário de [sealed class](/glossario/sealed-class/) e o `when` exaustivo evitam `else` esquecidos.
- Escolha `replay` conscientemente: `0` para one-shot de UI; `1` quando o último sinal ainda importa (status, último tick).
- Dimensionne `extraBufferCapacity` pelo pior burst esperado, não por “número mágico”.
- Em testes, use Turbine ou `runTest` com coleta controlada — o post [Testando Flow, StateFlow e Turbine](/blog/testando-flow-stateflow-turbine-kotlin-2026/) cobre o setup; o mesmo padrão vale para SharedFlow.
- Documente a política de overflow: perda silenciosa em telemetria é aceitável; em pagamento, quase nunca.

### Perguntas frequentes

**SharedFlow substitui Channel?** Não totalmente. Channel brilha em filas 1:1 com backpressure de produtor/consumidor. SharedFlow brilha em broadcast. Dá para adaptar um ao outro, mas a API certa comunica a intenção.

**Preciso de `distinctUntilChanged`?** Só se a sua regra de negócio pedir. SharedFlow não filtra iguais. Depois de um `map`/`filter`, você continua com um Flow intermediário até fechar de novo com `shareIn` se quiser compartilhar.

**Qual a diferença para `Channel.BUFFERED`?** Channel entrega cada elemento a **um** recebedor (a menos que você faça fan-out manual). SharedFlow entrega a **todos** os coletores ativos.

**Posso ter SharedFlow de Unit?** Sim (`MutableSharedFlow<Unit>()`), mas um `sealed interface` com tipos nomeados documenta melhor a intenção e escala quando o evento ganha payload.

**SharedFlow tem `value`?** Não. Se você se pega querendo ler “o evento atual”, provavelmente precisa de StateFlow — ou de `replayCache` apenas para inspecionar o histórico de replay em depuracao, não como API de UI.

### Próximos passos

- [StateFlow em Kotlin](/glossario/stateflow/) — o par natural para estado atual observável
- [Flow em Kotlin](/glossario/flow/) — streams frios, operators e builders
- [Channel em Kotlin](/glossario/channel/) — filas ponto a ponto entre coroutines
- [Guia completo de Kotlin Flow](/guias/kotlin-flow-guia/) — shareIn, stateIn e padrões de produção
- [Tutorial de Flow](/tutoriais/kotlin-flow-tutorial/) — prática guiada com exemplos progressivos
- [Arquitetura MVVM com Kotlin](/guias/guia-arquitetura-mvvm-kotlin/) — onde encaixar estado e eventos
- [Testando Flow e StateFlow com Turbine](/blog/testando-flow-stateflow-turbine-kotlin-2026/) — testes determinísticos de coleta

### Termos relacionados

- [StateFlow](/glossario/stateflow/) — fluxo quente com valor atual para estado de UI e sessão
- [Flow](/glossario/flow/) — streams assíncronos frios dos quais SharedFlow compartilha a API de coleta
- [Channel](/glossario/channel/) — comunicação ponto a ponto com capacidade explícita
- [Coroutine](/glossario/coroutine/) — unidade de concorrência que emite e coleta eventos
- [Emit](/glossario/emit/) — operação de emitir valores em builders e fluxos mutáveis
- [ViewModel](/glossario/viewmodel/) — dono típico do MutableSharedFlow na camada de apresentação
- [Sealed Class](/glossario/sealed-class/) — hierarquia restrita ideal para modelar eventos de UI
