La capa de datos: repositorios, fuentes y modelos por capa

Si hay una pieza de la arquitectura recomendada que se aplica mal de forma sistemática, es el repositorio. La versión degradada aparece en casi todos los proyectos y es fácil de reconocer: una clase con el sufijo correcto cuyos métodos se corresponden uno a uno con los del cliente de red, cada uno reenviando la llamada y traduciendo el resultado. Esa clase no es una fuente de verdad ni una frontera ni una abstracción; es una capa de reenvío que añade un archivo y no elimina ninguna dependencia, porque quien la usa sigue estando acoplado a la forma del servidor, solo que con un intermediario por medio. El repositorio de verdad se define por otra cosa: es el único sitio del sistema que sabe responder qué es cierto sobre un tipo de dato, y esa responsabilidad implica decidir entre fuentes, resolver conflictos y sostener una respuesta cuando ninguna fuente está disponible.

El repositorio manda sobre un tipo de dato

La guía oficial recomienda un repositorio por cada tipo de dato relevante de la aplicación, y esa formulación es más exigente de lo que parece. No dice un repositorio por servicio remoto, ni por pantalla, ni por tabla: dice por tipo de dato del negocio. Un ArticuloRepository es el dueño del concepto artículo, y todo lo que la aplicación necesite saber o hacer con artículos pasa por él, vengan los datos de donde vengan y sean cuantas sean las fuentes implicadas.

Esa formulación tiene una consecuencia inmediata que sorprende a mucha gente: el número de repositorios de una aplicación no guarda ninguna relación con el número de rutas de su servidor. Un solo repositorio puede consumir seis rutas, y seis rutas de un mismo recurso pueden colapsar en tres métodos si el negocio no distingue entre ellas. Cuando la correspondencia sale uno a uno de forma sistemática, la capa no se diseñó: se transcribió.

De ahí se sigue lo que realmente distingue a un repositorio de un reenviador. El repositorio toma decisiones. Decide si un dato en caché sigue siendo válido, decide qué fuente consultar primero, decide qué hacer cuando la red contradice al disco, decide si una escritura se confirma antes o después de llegar al servidor. Cada una de esas decisiones es una regla del negocio, no una operación técnica, y su lugar natural es exactamente aquí.

class ArticuloRepositoryImpl(
    private val local: ArticuloLocalDataSource,
    private val remota: ArticuloRemoteDataSource,
) : ArticuloRepository {

    override fun observar(id: ArticuloId): Flow<Articulo> =
        local.observar(id).map { entidad -> entidad.aDominio() }

    override suspend fun refrescar(id: ArticuloId): Result<Unit> = runCatching {
        val respuesta = remota.obtener(id)
        local.guardar(respuesta.aEntidad())     // la verdad se escribe en un solo sitio
    }
}

Fíjate en la asimetría del contrato: se observa de un sitio y se refresca desde otro, pero lo que sale hacia arriba tiene un único origen. Esa es la fuente única de verdad, y es lo que garantiza que dos pantallas que muestran el mismo artículo no puedan discrepar. Si cada una hubiera pedido su copia al servidor, la coherencia dependería del azar de los tiempos de respuesta.

La fuente única no tiene por qué ser el disco en todos los casos. Para datos que no merecen persistirse puede ser una caché en memoria dentro del propio repositorio, y para datos que la aplicación no posee puede ser directamente el servidor. Lo que la propiedad exige no es una tecnología concreta sino que exista exactamente un lugar capaz de responder, y que todo lo demás sea una vista de ese lugar.

Otra consecuencia que ordena mucho el diseño es que un repositorio debería ser único en el proceso para su tipo de dato. Dos instancias del mismo repositorio con cachés separadas son dos verdades con el mismo nombre, y el fallo que producen aparece meses después en forma de pantallas que discrepan sin motivo aparente. Por eso su ciclo de vida pertenece al ámbito de la aplicación y no al de una pantalla, y por eso conviene desconfiar de cualquier lugar donde se construya uno a mano.

Fuentes: una por origen y ciegas entre sí

Una fuente de datos encapsula exactamente un origen: la base local, el servicio remoto, el almacén de preferencias, el sistema de archivos, un sensor. Su trabajo consiste en traducir entre el lenguaje de ese medio y algo utilizable, y ahí termina. No orquesta, no decide, no combina.

La regla de que las fuentes no se conocen entre sí es la que más se incumple y la que más caro se paga. En cuanto la fuente remota escribe en la local, la lógica de coordinación queda repartida entre dos clases que además dependen la una de la otra, y la pregunta de qué ocurre cuando falla la escritura después de una respuesta correcta deja de tener un único sitio donde responderse. Toda la orquestación pertenece al repositorio, sin excepciones que valgan la pena.

flowchart TD
A[ViewModel] --> B[ArticuloRepository]
B --> C[Fuente local con base de datos]
B --> D[Fuente remota con cliente de red]
B --> E[Fuente de preferencias]
C -.no se conocen.- D
style B fill:#a6e3a1,color:#11111b

Conviene también resistirse a la simetría automática. Nada obliga a que cada repositorio tenga exactamente una fuente local y una remota: hay datos que solo viven en el dispositivo, como las preferencias de visualización, y datos que no tiene sentido guardar, como el resultado de una búsqueda libre. Crear una fuente vacía para cumplir con el patrón es exactamente el mismo error que crear un caso de uso que no hace nada, y se paga en el mismo tipo de moneda.

Hay un segundo motivo para esta separación que solo se aprecia al probar. Una fuente con un único origen se sustituye por una implementación en memoria en cuatro líneas, y con eso el repositorio entero, que es donde está la lógica interesante, se prueba sin dispositivo, sin servidor de mentira y sin base de datos real. Cuando la orquestación vive dentro de las fuentes, esa prueba deja de ser posible y el equipo acaba probando la lógica de negocio a través de la interfaz, que es el sitio más caro y más frágil para hacerlo.

Un modelo por capa y las traducciones que lo sostienen

La disciplina más cuestionada de esta capa es también la que más protege: cada capa tiene sus propios tipos, y en las fronteras hay traducción. La fuente remota trabaja con tipos de transporte, con sus anotaciones de serialización y sus campos opcionales porque el servidor los puede omitir. La fuente local trabaja con entidades, con sus anotaciones de persistencia, sus claves primarias y sus índices. El repositorio expone modelos de dominio, que no tienen ninguna anotación porque no pertenecen a ninguna tecnología.

@Serializable
data class ArticuloDto(val id: String, val nombre: String?, val precio_centimos: Long?)

@Entity(tableName = "articulos")
data class ArticuloEntity(@PrimaryKey val id: String, val nombre: String, val precioCentimos: Long)

data class Articulo(val id: ArticuloId, val nombre: String, val precio: Dinero)

La objeción habitual es que son tres declaraciones casi idénticas y dos funciones de conversión para el mismo concepto, y la objeción es correcta el primer día. Lo que compensa aparece después, y conviene enumerarlo porque es concreto. La opcionalidad se resuelve una sola vez, en la traducción, en lugar de propagarse por toda la aplicación en forma de comprobaciones defensivas. El identificador deja de ser una cadena que se puede confundir con cualquier otra cadena y pasa a ser un tipo que el compilador vigila. El importe deja de ser un número entero cuya unidad hay que recordar. Y cuando el servidor renombre un campo, el cambio se detiene en la función de conversión, que es exactamente donde debería detenerse.

Ese último punto merece medirse. En un proyecto con modelo compartido, un renombrado en el servidor produce errores de compilación repartidos por pantallas, ViewModel y pruebas. En un proyecto con modelos por capa, produce un error en una función de veinte líneas. La diferencia es el radio de daño, y el radio de daño es lo que determina si un cambio pequeño se puede hacer un jueves por la tarde.

El sitio donde ocurre la traducción también importa y suele elegirse por descuido. Debe ocurrir en la frontera, es decir, en el repositorio o inmediatamente dentro de cada fuente, y nunca en la capa superior. Una función de conversión invocada desde un ViewModel significa que el tipo ajeno ya cruzó la frontera y que la traducción llegó tarde; el compilador no lo señalará, porque compila igual de bien, pero el acoplamiento ya está hecho.

internal fun ArticuloDto.aEntidad() = ArticuloEntity(
    id = id,
    nombre = nombre.orEmpty(),                 // la opcionalidad muere aqui
    precioCentimos = precio_centimos ?: 0L,
)

Que esas funciones sean internal y vivan junto al tipo que traducen es una convención pequeña con un efecto grande: impide que alguien las use desde fuera para colar el tipo ajeno un nivel más arriba, y mantiene la conversión al lado del código que hay que cambiar cuando el contrato cambie.

Dicho esto, la disciplina admite grados y aplicarla sin criterio también tiene coste. Una aplicación pequeña, con un servidor que controla el mismo equipo y un dominio que no es más que lo que el servidor dicta, puede compartir modelo entre la fuente remota y el repositorio sin drama. Lo que casi nunca sale bien es lo contrario: dejar que la entidad de persistencia, con sus restricciones de forma impuestas por la base de datos, sea el modelo que ve la pantalla, porque entonces cualquier migración de esquema se convierte en un cambio de interfaz.

Los errores forman parte del contrato

La última decisión de diseño de esta capa es la que más se posterga: qué ocurre cuando algo falla. Dejar que las excepciones suban es la opción por defecto y tiene un defecto grave, y es que la excepción viaja con el vocabulario de su origen. Un fallo de resolución de nombres, un tiempo de espera agotado, una violación de restricción de unicidad. Ninguno de esos conceptos pertenece a la pantalla, y sin embargo la pantalla acabará capturándolos porque alguien tiene que decidir qué se le dice al usuario.

El repositorio, que ya es la frontera del origen de los datos, debe serlo también del vocabulario de los fallos. Lo que sale hacia arriba son resultados que la capa superior sabe interpretar sin saber nada del medio.

sealed interface ErrorDeDatos {
    data object SinConexion : ErrorDeDatos
    data object NoEncontrado : ErrorDeDatos
    data class Rechazado(val motivo: String) : ErrorDeDatos
    data object Inesperado : ErrorDeDatos
}

Ese tipo cerrado tiene además una virtud que las excepciones no pueden ofrecer: obliga a que alguien decida. Una excepción se puede ignorar sin que nada avise, y de hecho se ignora por omisión hasta que alguien la ve en producción; una rama sin cubrir en una expresión exhaustiva no compila. La diferencia entre ambos regímenes es la diferencia entre confiar en la disciplina del equipo y confiar en el compilador.

Hay una distinción que conviene hacer explícita porque ordena todo lo demás. Los fallos esperados forman parte del dominio: que no haya conexión, que el recurso no exista, que el servidor rechace la operación. Son situaciones previstas y merecen un tipo en el contrato. Los fallos inesperados, en cambio, son errores de programación disfrazados y no deberían modelarse como casos: deben registrarse, notificarse y colapsar en un único caso genérico, porque enumerar sus variantes solo consigue que la pantalla tenga que manejar situaciones que nadie sabe explicar en lenguaje humano.