¿Por qué cambiar tu código te sale tan caro? SOLID y Clean Architecture en Laravel 13 y Vue 3

He visto envejecer proyectos de las dos maneras posibles. En unos, cada funcionalidad nueva cuesta un poco más que la anterior; llega un día en que nadie quiere tocar el módulo de facturación y proponer "cambiemos la librería de HTTP" suena a broma pesada. En otros, el código aguanta el cambio sin dramas: pruebas una pieza por separado, y pasar de una base de datos a otra (o de un framework de UI a otro) es reescribir un adaptador y poco más. Lo que separa a unos de otros casi nunca es el talento del equipo ni el stack que eligieron. Es cómo está ordenado el código por dentro. Y esa parte ya está resuelta desde hace décadas; solo hay que conocerla.

En este artículo repaso dos ideas que se apoyan la una en la otra —SOLID y la arquitectura limpia— desde quién las escribió y por qué, hasta el código del día a día. Con una vuelta de tuerca que no se ve tan seguido: voy a aplicar la misma arquitectura en los dos extremos de una app, una API en Laravel 13 y un frontend en Vue 3 (Composition API, Vuetify, Pinia, CASL y Vite). La idea es que compruebes que el principio es el mismo aunque cambie el lenguaje.

De dónde viene todo esto

Vale la pena saber de dónde salió todo esto, aunque sea para quitarle el aire de moda pasajera. Nada de esto se inventó ayer: es lo que fue quedando después de que mucha gente tropezara con los mismos problemas durante medio siglo.

SOLID: cinco principios con nombre y apellido

En el año 2000, Robert C. Martin —"Uncle Bob"— publicó un artículo llamado Design Principles and Design Patterns donde reunía cinco principios de diseño orientado a objetos que había ido formulando (y tomando prestados) durante los noventa. El artículo, ojo, no usaba la palabra "SOLID": fue Michael Feathers quien, hacia 2004, se dio cuenta de que reordenando las iniciales salía un acrónimo fácil de recordar. De ahí viene la palabra que hoy usamos sin pensarlo.

Antes de ir una por una, la foto de conjunto. Son cinco reglas distintas, pero todas empujan hacia el mismo sitio:

Y aquí va cada una con su historia —quién la escribió y cuándo—:

Arquitectura limpia: ordenar las dependencias

Si DIP dice "depende de abstracciones", la arquitectura limpia responde a la pregunta natural: ¿en qué dirección deben apuntar todas las dependencias de mi sistema? La respondió Robert C. Martin en un artículo de 2012 —The Clean Architecture— que luego expandió en su libro homónimo de 2017.

Pero Martin fue explícito en que no inventaba nada: su diagrama era la síntesis de varias ideas anteriores que decían lo mismo con distinta forma. Vale la pena conocer el linaje, porque cada una aporta un matiz:

De todas ellas, Martin extrajo una sola regla, la que hace que todo funcione. La llamó la Regla de la Dependencia, y en el artículo de 2012 la enunció así de simple: las dependencias del código fuente solo pueden apuntar hacia adentro.

Conviene detenerse aquí, porque en esa frase está casi todo. El círculo de afuera son los detalles volátiles: el framework, la base de datos, la web, todo lo que cambias cada pocos años. El de adentro son las políticas estables: las reglas de tu negocio, que casi no se mueven. La regla dice que los detalles conocen a las políticas, y nunca al revés. Tu entidad Invoice no sabe que existe Laravel; tu caso de uso CreateInvoice no tiene idea de si los datos llegan por HTTP, por una cola o por una prueba. Y esa ignorancia es justo lo que te deja las manos libres para cambiar lo de afuera.

Una API Laravel 13 con arquitectura limpia

Bajemos al código. La idea es organizar la app en capas que respeten la Regla de la Dependencia. Laravel 13 trae un esqueleto slim —su app/ viene casi vacío—, así que estas carpetas las creas tú; no son magia del framework, son una convención que hace visible la arquitectura.

app/
├── Domain/                       # el corazón: NO importa nada de Laravel
│   └── Invoices/
│       ├── Invoice.php           # entidad (reglas de negocio)
│       ├── Money.php             # objeto de valor (inmutable)
│       ├── InvoiceId.php         # objeto de valor
│       └── InvoiceRepository.php # CONTRATO (interface) — el puerto
│
├── Application/                  # casos de uso: la lógica de TU app
│   └── Invoices/
│       ├── CreateInvoice.php     # la acción, orquesta el dominio
│       └── NewInvoiceData.php    # DTO de entrada
│
├── Infrastructure/               # detalles: implementaciones concretas
│   └── Invoices/
│       ├── EloquentInvoiceRepository.php   # implementa el contrato
│       └── InvoiceModel.php                # el modelo Eloquent
│
├── Http/                         # adaptadores de entrada (la web)
│   ├── Controllers/StoreInvoiceController.php   # fino: recibe y responde
│   ├── Requests/StoreInvoiceRequest.php         # validación
│   ├── Resources/InvoiceResource.php            # forma del JSON de salida
│   └── Policies/InvoicePolicy.php               # autorización
│
└── Providers/
    └── DomainServiceProvider.php  # enlaza interfaces -> implementaciones

Recorramos las piezas de adentro hacia afuera, que es como manda la regla.

El dominio: reglas puras, sin framework

En el centro viven las entidades y los objetos de valor: PHP plano, sin heredar de Model, sin saber que Laravel existe. Un objeto de valor como Money es pequeño, inmutable y encapsula una regla —el dinero no se representa con float, se guarda en céntimos para no perder precisión—:

// app/Domain/Invoices/Money.php
namespace App\Domain\Invoices;

final readonly class Money
{
    public function __construct(
        public int $cents,
        public string $currency = 'PEN',
    ) {
        if ($cents < 0) {
            throw new \InvalidArgumentException('El monto no puede ser negativo.');
        }
    }

    public static function fromDecimal(string $amount, string $currency = 'PEN'): self
    {
        return new self((int) round(((float) $amount) * 100), $currency);
    }

    public function toDecimal(): string
    {
        return number_format($this->cents / 100, 2, '.', '');
    }
}

Junto a las entidades vive el contrato del repositorio: una interfaz que declara qué necesitas hacer con las facturas, sin decir cómo. Este es el puerto de la arquitectura hexagonal, y la clave de todo el diseño:

// app/Domain/Invoices/InvoiceRepository.php
namespace App\Domain\Invoices;

interface InvoiceRepository
{
    public function save(Invoice $invoice): void;

    public function findById(InvoiceId $id): ?Invoice;
}

El caso de uso: orquestar sin ensuciarse

La capa de aplicación contiene los casos de uso —lo que tu app hace—. CreateInvoice recibe datos ya validados (un DTO), construye la entidad y la manda guardar a través de la interfaz. No sabe que detrás hay Eloquent:

// app/Application/Invoices/CreateInvoice.php
namespace App\Application\Invoices;

use App\Domain\Invoices\{Invoice, Money, InvoiceRepository};

final readonly class CreateInvoice
{
    // DIP: depende de la ABSTRACCIÓN, no de la implementación concreta.
    public function __construct(private InvoiceRepository $invoices) {}

    public function handle(NewInvoiceData $data): Invoice
    {
        $invoice = Invoice::issue(
            client: $data->client,
            total: Money::fromDecimal($data->amount, $data->currency),
        );

        $this->invoices->save($invoice);

        return $invoice;
    }
}

Ese constructor es el corazón del asunto. CreateInvoice pide un InvoiceRepository —la interfaz— y Laravel se lo entrega resuelto. En una prueba unitaria le pasas un doble en memoria; en producción, el que habla con PostgreSQL. El caso de uso ni se entera, y por eso se prueba en milisegundos sin tocar la base de datos.

La infraestructura: el detalle intercambiable

Aquí, y solo aquí, aparece Eloquent. EloquentInvoiceRepository implementa el contrato del dominio y traduce entre tu entidad pura y el modelo de la base de datos:

// app/Infrastructure/Invoices/EloquentInvoiceRepository.php
namespace App\Infrastructure\Invoices;

use App\Domain\Invoices\{Invoice, InvoiceId, InvoiceRepository};

final class EloquentInvoiceRepository implements InvoiceRepository
{
    public function save(Invoice $invoice): void
    {
        InvoiceModel::updateOrCreate(
            ['id' => $invoice->id()->value],
            ['client' => $invoice->client(), 'cents' => $invoice->total()->cents],
        );
    }

    public function findById(InvoiceId $id): ?Invoice
    {
        return InvoiceModel::find($id->value)?->toDomain();
    }
}

El puente entre el mundo abstracto y el concreto lo tiende el contenedor de servicios de Laravel, en un service provider. Esta única línea es la que hace realidad la Inversión de Dependencias:

// app/Providers/DomainServiceProvider.php
public function register(): void
{
    $this->app->bind(
        \App\Domain\Invoices\InvoiceRepository::class,       // cuando alguien pida esto...
        \App\Infrastructure\Invoices\EloquentInvoiceRepository::class, // ...dale esto.
    );
}

Este diagrama es, en una imagen, por qué DIP se llama inversión: la flecha que en un diseño ingenuo iría de CreateInvoice a EloquentInvoiceRepository (alto nivel dependiendo del bajo nivel) queda invertida —ambos apuntan a la interfaz en el medio—. Cambiar PostgreSQL por una API externa, por Redis o por un doble de prueba es escribir una clase nueva y cambiar un bind. Nada más se mueve.

El adaptador de entrada: un controlador que casi no piensa

Con el dominio y el caso de uso resolviendo lo difícil, el controlador queda anémico —y eso es una virtud, no un defecto—. Recibe la petición ya validada por el Form Request, comprueba permisos con la Policy, delega en el caso de uso y devuelve un Resource:

// app/Http/Controllers/StoreInvoiceController.php
final class StoreInvoiceController
{
    public function __construct(private CreateInvoice $createInvoice) {}

    public function __invoke(StoreInvoiceRequest $request): JsonResponse
    {
        $this->authorize('create', Invoice::class);   // -> InvoicePolicy

        $invoice = $this->createInvoice->handle(
            NewInvoiceData::fromRequest($request),
        );

        return InvoiceResource::make($invoice)
            ->response()
            ->setStatusCode(201);
    }
}

Cada clase que tocamos hace una sola cosa (SRP): el Form Request valida, la Policy autoriza, el Resource da forma al JSON, el caso de uso orquesta, el repositorio persiste. Si mañana cambia la regla de validación, sabes exactamente qué archivo abrir —y solo ese—.

El mismo plano, ahora en Vue 3

Y aquí viene lo que casi nadie se molesta en hacer, que es justo donde está el mayor rédito: la arquitectura limpia no es solo cosa del backend. Un frontend moderno arrastra los mismos problemas (lógica de negocio enredada con la UI, componentes que saben demasiado y que no hay por dónde probar) y le sirve la misma cura. Vamos a armar el lado Vue 3 con la misma forma que la API.

La organización que mejor funciona en Vue es por funcionalidad (feature-based), no por tipo de archivo. Cada feature es una rebanada vertical con sus propias capas:

src/
├── features/
│   └── invoices/
│       ├── domain/
│       │   ├── invoice.ts            # tipos/entidades (sin Vue)
│       │   └── invoice.gateway.ts    # PUERTO: interface del acceso a datos
│       ├── application/
│       │   └── useCreateInvoice.ts   # caso de uso (composable)
│       ├── infrastructure/
│       │   └── invoice.api.ts        # implementa el puerto con HTTP
│       ├── stores/
│       │   └── invoices.store.ts     # estado (Pinia)
│       └── components/
│           └── InvoiceForm.vue       # UI (Vuetify) — el borde
├── shared/
│   └── auth/ability.ts               # abilities de CASL (autorización)
└── main.ts                           # arranque: Vue + Vuetify + Pinia + router

El dominio y el puerto: TypeScript puro

Igual que en Laravel, el centro no sabe que Vue existe. Son tipos y una interfaz —el puerto—:

// features/invoices/domain/invoice.ts
export interface Invoice {
  id: string
  client: string
  amount: string     // decimal como string, para no perder precisión
  currency: string
}

export interface NewInvoice {
  client: string
  amount: string
  currency: string
}

// features/invoices/domain/invoice.gateway.ts
import type { Invoice, NewInvoice } from './invoice'

// El PUERTO: qué necesitamos, no cómo. El caso de uso dependerá de esto.
export interface InvoiceGateway {
  create(data: NewInvoice): Promise<Invoice>
  list(): Promise<Invoice[]>
}

La infraestructura: el adaptador HTTP

El adaptador concreto implementa el puerto usando la librería HTTP que sea. Aquí es el único lugar donde aparece Axios; si mañana migras a fetch, a ky o a WebSockets, cambias esta clase y nada más:

// features/invoices/infrastructure/invoice.api.ts
import axios from 'axios'
import type { InvoiceGateway } from '../domain/invoice.gateway'
import type { Invoice, NewInvoice } from '../domain/invoice'

export class InvoiceApi implements InvoiceGateway {
  async create(data: NewInvoice): Promise<Invoice> {
    const { data: json } = await axios.post('/api/invoices', data)
    return json.data          // el InvoiceResource de Laravel, ya tipado
  }

  async list(): Promise<Invoice[]> {
    const { data: json } = await axios.get('/api/invoices')
    return json.data
  }
}

El caso de uso: un composable que orquesta

En Vue, el equivalente natural a un caso de uso es un composable. useCreateInvoice recibe el gateway (el puerto), maneja el estado reactivo de la operación —cargando, error, resultado— y expone una acción. No conoce Axios ni a Vuetify: solo el puerto y el store.

// features/invoices/application/useCreateInvoice.ts
import { ref } from 'vue'
import type { InvoiceGateway } from '../domain/invoice.gateway'
import type { NewInvoice } from '../domain/invoice'
import { useInvoicesStore } from '../stores/invoices.store'

// DIP: recibe la abstracción por parámetro, no la crea adentro.
export function useCreateInvoice(gateway: InvoiceGateway) {
  const store = useInvoicesStore()
  const loading = ref(false)
  const error = ref<string | null>(null)

  async function submit(data: NewInvoice) {
    loading.value = true
    error.value = null
    try {
      const invoice = await gateway.create(data)
      store.add(invoice)               // actualiza el estado global
      return invoice
    } catch (e) {
      error.value = 'No se pudo crear la factura.'
      throw e
    } finally {
      loading.value = false
    }
  }

  return { submit, loading, error }
}

El estado: Pinia como adaptador

Pinia —el store oficial de Vue, sucesor de Vuex— es un adaptador más: guarda el estado de la aplicación y lo ofrece reactivo a la UI. Con la Composition API se lee como un composable:

// features/invoices/stores/invoices.store.ts
import { defineStore } from 'pinia'
import { ref } from 'vue'
import type { Invoice } from '../domain/invoice'

export const useInvoicesStore = defineStore('invoices', () => {
  const items = ref<Invoice[]>([])
  const add = (invoice: Invoice) => items.value.unshift(invoice)
  return { items, add }
})

El borde: un componente Vuetify que solo muestra

Finalmente, el componente. Con Vuetify para la UI y la Composition API (<script setup>), su trabajo es mínimo: recoger datos, llamar al caso de uso y reaccionar. Toda la lógica difícil ya está resuelta en las capas de adentro, así que el componente es delgado y legible:

<!-- features/invoices/components/InvoiceForm.vue -->
<script setup lang="ts">
import { reactive } from 'vue'
import { useCreateInvoice } from '../application/useCreateInvoice'
import { InvoiceApi } from '../infrastructure/invoice.api'

// se inyecta el adaptador concreto; el composable solo ve el puerto
const { submit, loading, error } = useCreateInvoice(new InvoiceApi())

const form = reactive({ client: '', amount: '', currency: 'PEN' })
</script>

<template>
  <v-form @submit.prevent="submit(form)">
    <v-text-field v-model="form.client" label="Cliente" />
    <v-text-field v-model="form.amount" label="Monto" type="number" />
    <v-alert v-if="error" type="error" :text="error" />
    <v-btn type="submit" :loading="loading" color="primary">
      Crear factura
    </v-btn>
  </v-form>
</template>

La sorpresa: el espejo full-stack

Y aquí las dos mitades encajan. Cuando pones el frontend y el backend uno al lado del otro, salta a la vista: son la misma arquitectura reflejada en un espejo. Framework afuera, dominio adentro, a los dos lados. Y en medio, una sola frontera: un contrato tipado.

Ese reflejo se nota, sobre todo, en la autorización. En el backend, Laravel decide quién puede qué con Policies. En el frontend, CASL (una librería de autorización isomórfica de Sergii Stotskyi) hace lo mismo con abilities. Y como los dos hablan de las mismas acciones y los mismos sujetos, puedes definir las reglas una vez y reflejarlas a los dos lados:

// app/Http/Policies/InvoicePolicy.php
final class InvoicePolicy
{
    public function create(User $user): bool
    {
        return $user->hasPermission('invoices.create');
    }

    public function delete(User $user, Invoice $invoice): bool
    {
        // solo el dueño o un admin
        return $user->id === $invoice->ownerId
            || $user->hasRole('admin');
    }
}

// shared/auth/ability.ts
import { AbilityBuilder, createMongoAbility } from '@casl/ability'

export function defineAbilitiesFor(user: User) {
  const { can, build } = new AbilityBuilder(createMongoAbility)

  if (user.permissions.includes('invoices.create')) {
    can('create', 'Invoice')
  }
  can('delete', 'Invoice', { ownerId: user.id })
  if (user.roles.includes('admin')) can('delete', 'Invoice')

  return build()
}

<v-btn v-if="$can('create', 'Invoice')" @click="open">
  Nueva factura
</v-btn>

Para cerrar el círculo, sigamos una petición de punta a punta y veamos cómo cruza las dos arquitecturas en espejo:

Fíjate en la simetría: la petición sale del dominio de Vue (donde CASL ya dijo "sí, muéstralo"), cruza la frontera HTTP como un JSON tipado, y entra al dominio de Laravel (donde la Policy dice "sí, permítelo"). Dos comprobaciones de la misma regla, cada una en su lado, cada una con su propósito. Cuando tu equipo de frontend y tu equipo de backend comparten este mapa mental, dejan de hablar idiomas distintos: hablan de casos de uso, entidades y puertos, y esas palabras significan lo mismo en .ts y en .php.

El costo de hacerlo de más (y de menos)

No quiero venderte esto sin la letra pequeña, porque la tiene. Hay dos formas de equivocarse, y las dos duelen.

Acertar es cuestión de criterio, no de reglas fijas. Un par de guías que a mí me sirven:

Cierre

Ninguna de estas dos ideas salió de un aula ni de un comité de arquitectos. Son lo que la industria fue respondiendo, a golpes, a una sola pregunta: ¿cómo hago que el cambio siga saliendo barato dentro de tres años? Y la respuesta cabe en una frase que Barbara Liskov, Bertrand Meyer y Robert C. Martin fueron escribiendo por partes a lo largo de treinta años: pon las reglas del negocio en el centro, empuja los detalles al borde y haz que las dependencias siempre apunten hacia adentro.

Lo demás es aplicar esa idea con cabeza. En Laravel 13 toma la forma de dominio, casos de uso, repositorios e inyección de dependencias. En Vue 3, la de features, composables, puertos y Pinia. Y cuando los pones uno frente al otro, ves que estabas construyendo la misma cosa dos veces, en espejo: CASL y las Policies acaban siendo la misma regla, mirándose desde los dos lados del cristal. Esa coherencia —que un equipo hable un mismo idioma de dominio del .vue al .php— es lo que de verdad hace que un sistema envejezca bien.

Fuentes