Hilt: el grafo que verifica el compilador

La diferencia entre un error que ves al compilar y uno que ves al abrir la pantalla no es de comodidad: es de coste, y la distancia entre ambos crece de forma exponencial con el tamaño del equipo y con el tiempo que transcurre hasta que alguien ejecuta ese camino concreto de la aplicación. Hilt existe porque alguien tomó en serio esa aritmética y decidió pagar por adelantado: en vez de resolver el grafo cuando se pide un objeto, lo resuelve mientras se compila, generando el código de ensamblaje y comprobando que cada arista tiene destino. El precio es un procesador de anotaciones en la construcción, una sintaxis más ceremoniosa y errores de compilación que a veces cuesta leer. La contrapartida es una garantía muy fuerte y muy concreta: si el proyecto compila, no existe ninguna dependencia sin proveer, ni ninguna que viva más de lo que debe.

Qué significa verificar el grafo al compilar

Hilt no es un contenedor que busca objetos en un registro: es un generador de código. Durante la compilación recorre las anotaciones, construye el grafo dirigido de tipos y comprueba tres propiedades antes de emitir una sola clase.

Merece la pena detenerse en la tercera comprobación, porque es la menos apreciada y la que más problemas evita. Una fuga de memoria por ámbito es un fallo que no se manifiesta como excepción, sino como consumo creciente y ralentización progresiva, y su diagnóstico exige herramientas y paciencia. Que un procesador de anotaciones lo convierta en un error rojo con nombre de tipo es un cambio de categoría en la dificultad del problema.

Proveer y vincular

Hay dos formas de decirle a Hilt cómo obtener un tipo, y confundirlas es el error más común de quien empieza. Se usa @Provides cuando el objeto se construye con código —típicamente porque pertenece a una librería ajena y no se pueden anotar sus constructores— y @Binds cuando lo único que hace falta es declarar que cierta implementación cumple cierta interfaz.

@Module
@InstallIn(SingletonComponent::class)
object RedModule {

    @Provides
    @Singleton
    fun proveerCliente(): OkHttpClient = OkHttpClient.Builder().build()

    @Provides
    @Singleton
    fun proveerApi(cliente: OkHttpClient): PerfilApi =
        Retrofit.Builder()
            .baseUrl("https://api.example.com")
            .client(cliente)
            .build()
            .create(PerfilApi::class.java)
}

@Module
@InstallIn(SingletonComponent::class)
abstract class RepositorioModule {

    // Binds no construye nada: solo declara que esta clase cumple el contrato
    @Binds
    abstract fun vincularRepositorio(impl: RepositorioHttp): RepositorioPerfil
}

class RepositorioHttp @Inject constructor(
    private val api: PerfilApi,
) : RepositorioPerfil {
    override suspend fun obtener(): Perfil = api.perfil().aDominio()
}

La asimetría tiene una razón técnica que conviene entender. @Binds es abstracto y no genera cuerpo alguno: el procesador se limita a anotar en el grafo que una arista apunta a otra, con lo que el código generado es estrictamente menor y la compilación algo más rápida. @Provides sí genera una fábrica completa. La regla práctica es minimalista: usa @Binds siempre que puedas, @Provides solo cuando debas.

Componentes y ámbitos

Un componente es un contenedor de objetos con un ciclo de vida asociado, y la jerarquía entre componentes determina qué puede ver qué. Un componente hijo alcanza todo lo que provee su padre; el padre no ve nada del hijo. Esa asimetría es exactamente la que hace imposible que un objeto de vida larga capture uno de vida corta.

flowchart TD
S[SingletonComponent vive con la aplicacion] --> A[ActivityRetainedComponent sobrevive a la rotacion]
A --> V[ViewModelComponent muere con el ViewModel]
A --> AC[ActivityComponent muere con la Activity]
AC --> F[FragmentComponent]
AC --> VW[ViewComponent]
style S fill:#89b4fa,color:#11111b
style A fill:#a6e3a1,color:#11111b
style V fill:#f9e2af,color:#11111b

Cada componente tiene su anotación de ámbito: @Singleton para el de aplicación, @ActivityRetainedScoped para el que sobrevive a los cambios de configuración, @ViewModelScoped para el que acompaña al ViewModel y @ActivityScoped para el que muere con la pantalla. Un objeto sin anotación de ámbito no es un error: significa que se crea uno nuevo en cada petición, que suele ser lo correcto para objetos baratos y sin estado.

La decisión de ámbito no es de rendimiento sino de corrección, y se resuelve con una única pregunta: ¿este objeto debe ser el mismo para todos los que lo pidan dentro de una misma vida? Una caché en memoria compartida sí; un mapeador sin estado no. Marcar @Singleton por si acaso convierte cualquier estado accidental en estado global, y el estado global es la fuente de la clase de fallos más difícil de reproducir que existe: la que depende del orden en que el usuario visitó las pantallas.

El ViewModel dentro del grafo

El punto donde todo se junta es la anotación que conecta el contenedor MVI con el grafo sin que ninguna pantalla sepa construir nada.

@HiltViewModel
class PerfilViewModel @Inject constructor(
    private val repositorio: RepositorioPerfil,
    private val estadoGuardado: SavedStateHandle,
) : ViewModel(), ContainerHost<PerfilState, PerfilEfecto> {

    override val container = container<PerfilState, PerfilEfecto>(PerfilState())

    fun cargar() = intent {
        reduce { state.copy(cargando = true) }
        val perfil = repositorio.obtener()
        reduce { state.copy(cargando = false, perfil = perfil) }
    }
}

@AndroidEntryPoint
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent { PantallaPerfil(viewModel = hiltViewModel()) }
    }
}

Lo que @HiltViewModel genera es una fábrica de ViewModel registrada en el grafo, de modo que la llamada a hiltViewModel en Compose no construye el objeto: lo pide. El detalle que suele pasar inadvertido es SavedStateHandle, que Hilt provee automáticamente dentro del ViewModelComponent sin que haya que declarar nada, y que llega con los argumentos de navegación ya dentro. Eso permite que el contenedor lea el identificador de la entidad que debe cargar sin recibirlo por un método aparte, y por tanto sin un estado intermedio inválido entre la construcción y la primera intención.