Proxy
Sustituto · Intermediario
Proporciona un sustituto de otro objeto para controlar el acceso a él: carga perezosa, permisos, caché o acceso remoto.
“Necesito controlar el acceso a un objeto: carga perezosa, permisos o caché.”
workEl caso real
El sistema de una red de clínicas muestra la historia clínica de cada paciente: datos, diagnósticos y estudios de imagen que pesan cientos de megas en un almacenamiento externo. Hay dos reglas: solo el médico tratante puede ver la historia, y las imágenes no deben descargarse hasta que alguien las abra.
warningEl problema sin el patrón
El repositorio descarga todo al cargar al paciente, aunque el médico solo mire los datos generales. Y la verificación de permisos está copiada en cada controlador: basta que un endpoint nuevo la olvide para exponer datos sensibles.
check_circleCómo lo resuelve el patrón
Un ProxyHistoriaClinica implementa la misma interfaz que la historia real. Comprueba los permisos antes de cada acceso (proxy de protección) y no descarga las imágenes hasta que se piden (proxy virtual). El resto del sistema no distingue el proxy del objeto real.
schemaDiagrama de clases
Diagrama interactivo: puedes acercar, mover el lienzo y pasar el cursor sobre cada clase para ver su detalle.
codeEl código, antes y después
// Repetido en cada controlador
if (!usuario.esMedicoTratante(pacienteId)) throw new AccesoDenegado();
const historia = await repo.cargarCompleta(pacienteId); // descarga también las imágenes
return historia.diagnosticos();interface HistoriaClinica {
diagnosticos(): Diagnostico[];
imagenes(): Promise<Imagen[]>;
}
class ProxyHistoriaClinica implements HistoriaClinica {
private cache?: Imagen[];
constructor(private real: HistoriaClinicaReal, private usuario: Usuario) {}
diagnosticos() {
this.verificarAcceso();
return this.real.diagnosticos();
}
async imagenes() {
this.verificarAcceso();
return (this.cache ??= await this.real.imagenes()); // carga perezosa
}
private verificarAcceso() {
if (!this.usuario.esMedicoTratante(this.real.pacienteId)) throw new AccesoDenegado();
}
}Ejemplos en TypeScript, simplificados para mostrar la idea: los tipos auxiliares (Pedido, Cliente…) se omiten.
thumb_upCuándo usarlo
- ✓Proxy virtual: el objeto es costoso de crear o cargar y no siempre se usa.
- ✓Proxy de protección: el acceso depende de los permisos de quien lo pide.
- ✓Proxy remoto, de caché o de registro: el objeto vive en otro servicio, sus respuestas se pueden reutilizar o quieres dejar constancia de cada llamada.
- ✓Referencia inteligente: liberar un objeto costoso cuando ya nadie lo está usando.
do_not_disturb_onCuándo no usarlo
- ✕El objeto es barato y no necesita ningún control: el proxy solo añade una capa.
- ✕La latencia es crítica y cada indirección cuenta.
memoryPrincipios en juego
- •Responsabilidad única: el control de acceso y la carga perezosa salen del objeto real.
- •Abierto/Cerrado: añades controles sin modificar la clase real ni a sus clientes.
hubPatrones relacionados
- •Decorator: misma forma, pero el decorador añade comportamiento que elige el cliente y el proxy controla el acceso.
- •Adapter: ofrece una interfaz distinta; Proxy ofrece la misma.
- •Facade: también se coloca delante de algo, pero para simplificar un subsistema completo.
quizPon a prueba lo que leíste
Dos preguntas al azar sobre este patrón. Cada vez que las cambias salen otras.
code_blocksProxy en tu lenguaje
El mismo caso, implementado completo y de forma idiomática. Se puede copiar y ejecutar.
LO IDIOMÁTICO EN TYPESCRIPT: El proxy es una clase que implementa la misma interfaz que el objeto real; ??= resuelve la carga perezosa en una línea. JavaScript también ofrece el objeto nativo Proxy, útil para interceptar cualquier propiedad de forma genérica, pero una clase explícita es más clara y tipada.
interface Usuario { id: string; pacientesAsignados: string[] }
interface Imagen { nombre: string; megas: number }
export interface HistoriaClinica {
readonly pacienteId: string;
diagnosticos(): string[];
imagenes(): Promise<Imagen[]>;
}
class HistoriaClinicaReal implements HistoriaClinica {
constructor(readonly pacienteId: string) {}
diagnosticos(): string[] {
return ['Hipertensión controlada'];
}
async imagenes(): Promise<Imagen[]> {
console.log(' (descargando estudios del almacenamiento...)');
return [{ nombre: 'resonancia-2026-10.dcm', megas: 340 }];
}
}
export class ProxyHistoriaClinica implements HistoriaClinica {
#imagenes?: Imagen[];
constructor(private readonly real: HistoriaClinica, private readonly usuario: Usuario) {}
get pacienteId(): string {
return this.real.pacienteId;
}
diagnosticos(): string[] {
this.#verificarAcceso();
return this.real.diagnosticos();
}
async imagenes(): Promise<Imagen[]> {
this.#verificarAcceso();
return (this.#imagenes ??= await this.real.imagenes()); // solo se descarga la primera vez
}
#verificarAcceso(): void {
if (!this.usuario.pacientesAsignados.includes(this.real.pacienteId)) {
throw new Error(`Acceso denegado a la historia ${this.real.pacienteId}`);
}
}
}
// ── Uso ──
const medica: Usuario = { id: 'dra-rios', pacientesAsignados: ['P-77'] };
const historia: HistoriaClinica = new ProxyHistoriaClinica(new HistoriaClinicaReal('P-77'), medica);
console.log(historia.diagnosticos()); // no descarga imágenes
console.log((await historia.imagenes()).length); // descarga
console.log((await historia.imagenes()).length); // reutiliza lo ya cargado
const ajena = new ProxyHistoriaClinica(new HistoriaClinicaReal('P-90'), medica);
try {
ajena.diagnosticos();
} catch (error) {
console.log((error as Error).message); // Acceso denegado a la historia P-90
}LO IDIOMÁTICO EN C# / .NET: El proxy implementa la misma interfaz y usa Lazy<T> para crear la historia real solo en el primer acceso. Un acceso sin permiso lanza UnauthorizedAccessException. (.NET también ofrece DispatchProxy para crear proxies dinámicos, útil para registro o métricas genéricas.)
var medica = new Usuario("dra-rios", ["P-77"]);
IHistoriaClinica historia = new ProxyHistoriaClinica("P-77", medica);
Console.WriteLine("Proxy creado: todavía no se cargó nada");
Console.WriteLine(string.Join(", ", historia.Diagnosticos())); // carga la historia la primera vez
Console.WriteLine(historia.Imagenes().Count); // ya está cargada
try
{
new ProxyHistoriaClinica("P-90", medica).Diagnosticos();
}
catch (UnauthorizedAccessException error)
{
Console.WriteLine(error.Message); // Acceso denegado a la historia P-90
}
public record Usuario(string Id, IReadOnlyList<string> PacientesAsignados);
public interface IHistoriaClinica
{
IReadOnlyList<string> Diagnosticos();
IReadOnlyList<string> Imagenes();
}
public class HistoriaClinica : IHistoriaClinica
{
public HistoriaClinica(string pacienteId) =>
Console.WriteLine($" (cargando la historia {pacienteId} y sus estudios...)");
public IReadOnlyList<string> Diagnosticos() => ["Hipertensión controlada"];
public IReadOnlyList<string> Imagenes() => ["resonancia-2026-10.dcm"];
}
public class ProxyHistoriaClinica : IHistoriaClinica
{
private readonly string _pacienteId;
private readonly Usuario _usuario;
private readonly Lazy<HistoriaClinica> _real;
public ProxyHistoriaClinica(string pacienteId, Usuario usuario)
{
_pacienteId = pacienteId;
_usuario = usuario;
_real = new Lazy<HistoriaClinica>(() => new HistoriaClinica(pacienteId)); // aún no se crea
}
public IReadOnlyList<string> Diagnosticos() => Real.Diagnosticos();
public IReadOnlyList<string> Imagenes() => Real.Imagenes();
private HistoriaClinica Real => _usuario.PacientesAsignados.Contains(_pacienteId)
? _real.Value
: throw new UnauthorizedAccessException($"Acceso denegado a la historia {_pacienteId}");
}LO IDIOMÁTICO EN JAVA: El proxy implementa la misma interfaz que la historia real y la crea solo en el primer acceso. Un acceso sin permiso lanza una excepción propia. (Java también trae java.lang.reflect.Proxy para crear proxies dinámicos, que es lo que usan Spring y Hibernate por debajo.)
void main() {
var medica = new Usuario("dra-rios", Set.of("P-77"));
HistoriaClinica historia = new ProxyHistoriaClinica("P-77", medica);
IO.println("Proxy creado: todavía no se cargó nada");
IO.println(historia.diagnosticos()); // carga la historia la primera vez
IO.println(historia.imagenes().size()); // ya está cargada
try {
new ProxyHistoriaClinica("P-90", medica).diagnosticos();
} catch (AccesoDenegado error) {
IO.println(error.getMessage()); // Acceso denegado a la historia P-90
}
}
record Usuario(String id, Set<String> pacientesAsignados) {}
class AccesoDenegado extends RuntimeException {
@Serial private static final long serialVersionUID = 1L;
AccesoDenegado(String mensaje) { super(mensaje); }
}
interface HistoriaClinica {
List<String> diagnosticos();
List<String> imagenes();
}
class HistoriaClinicaReal implements HistoriaClinica {
HistoriaClinicaReal(String pacienteId) {
IO.println(" (cargando la historia " + pacienteId + " y sus estudios...)");
}
@Override public List<String> diagnosticos() { return List.of("Hipertensión controlada"); }
@Override public List<String> imagenes() { return List.of("resonancia-2026-10.dcm"); }
}
class ProxyHistoriaClinica implements HistoriaClinica {
private final String pacienteId;
private final Usuario usuario;
private HistoriaClinicaReal real; // se crea en el primer acceso
ProxyHistoriaClinica(String pacienteId, Usuario usuario) {
this.pacienteId = pacienteId;
this.usuario = usuario;
}
@Override public List<String> diagnosticos() { return real().diagnosticos(); }
@Override public List<String> imagenes() { return real().imagenes(); }
private HistoriaClinicaReal real() {
if (!usuario.pacientesAsignados().contains(pacienteId)) {
throw new AccesoDenegado("Acceso denegado a la historia " + pacienteId);
}
if (real == null) real = new HistoriaClinicaReal(pacienteId);
return real;
}
}LO IDIOMÁTICO EN JAVASCRIPT: JavaScript trae el patrón incorporado: el objeto nativo Proxy intercepta cualquier acceso a las propiedades de otro objeto. Aquí el get verifica permisos (proxy de protección) y crea la historia real solo la primera vez que se usa (proxy virtual), sin escribir un método por cada operación.
class HistoriaClinica {
constructor(pacienteId) {
console.log(` (cargando la historia ${pacienteId} y sus estudios...)`);
this.pacienteId = pacienteId;
}
diagnosticos() { return ['Hipertensión controlada']; }
imagenes() { return [{ nombre: 'resonancia-2026-10.dcm', megas: 340 }]; }
}
/**
* @param {string} pacienteId
* @param {{ id: string, pacientesAsignados: string[] }} usuario
* @returns {HistoriaClinica} para quien lo usa, es una historia clínica normal
*/
export function crearHistoriaProtegida(pacienteId, usuario) {
let real; // se crea al primer uso
return /** @type {HistoriaClinica} */ (new Proxy({}, {
get(_objetivo, propiedad) {
if (!usuario.pacientesAsignados.includes(pacienteId)) {
throw new Error(`Acceso denegado a la historia ${pacienteId}`);
}
real ??= new HistoriaClinica(pacienteId);
const valor = real[propiedad];
return typeof valor === 'function' ? valor.bind(real) : valor;
},
}));
}
// ── Uso ──
const medica = { id: 'dra-rios', pacientesAsignados: ['P-77'] };
const historia = crearHistoriaProtegida('P-77', medica);
console.log('Proxy creado: todavía no se cargó nada');
console.log(historia.diagnosticos()); // carga la historia la primera vez
console.log(historia.imagenes().length); // ya está cargada
const ajena = crearHistoriaProtegida('P-90', medica);
try {
ajena.diagnosticos();
} catch (error) {
console.log(error.message); // Acceso denegado a la historia P-90
}LO IDIOMÁTICO EN PYTHON: __getattr__ se llama cuando un atributo no existe en el proxy, así que se puede reenviar todo al objeto real sin escribir un método por operación. functools.cached_property crea el objeto real solo la primera vez que se necesita (proxy virtual).
from dataclasses import dataclass
from functools import cached_property
from typing import Any
class HistoriaClinica:
def __init__(self, paciente_id: str) -> None:
print(f" (cargando la historia {paciente_id} y sus estudios...)")
self.paciente_id = paciente_id
def diagnosticos(self) -> list[str]:
return ["Hipertensión controlada"]
def imagenes(self) -> list[str]:
return ["resonancia-2026-10.dcm"]
@dataclass(frozen=True)
class Usuario:
id: str
pacientes_asignados: tuple[str, ...]
class ProxyHistoriaClinica:
def __init__(self, paciente_id: str, usuario: Usuario) -> None:
self._paciente_id = paciente_id
self._usuario = usuario
@cached_property
def _real(self) -> HistoriaClinica: # se crea al primer uso
return HistoriaClinica(self._paciente_id)
def __getattr__(self, nombre: str) -> Any:
if self._paciente_id not in self._usuario.pacientes_asignados:
raise PermissionError(f"Acceso denegado a la historia {self._paciente_id}")
return getattr(self._real, nombre)
if __name__ == "__main__":
medica = Usuario("dra-rios", ("P-77",))
historia = ProxyHistoriaClinica("P-77", medica)
print("Proxy creado: todavía no se cargó nada")
print(historia.diagnosticos()) # carga la historia la primera vez
print(len(historia.imagenes())) # ya está cargada
ajena = ProxyHistoriaClinica("P-90", medica)
try:
ajena.diagnosticos()
except PermissionError as error:
print(error) # Acceso denegado a la historia P-90LO IDIOMÁTICO EN GO: El proxy cumple la misma interfaz que la historia real. sync.OnceValues (Go 1.21) carga el objeto real una sola vez y es seguro con goroutines. Los permisos se comprueban antes de cada acceso y un acceso denegado se devuelve como error.
package main
import (
"errors"
"fmt"
"slices"
"sync"
)
type HistoriaClinica interface {
Diagnosticos() ([]string, error)
Imagenes() ([]string, error)
}
type historiaReal struct{ pacienteID string }
func cargarHistoria(pacienteID string) (*historiaReal, error) {
fmt.Printf(" (cargando la historia %s y sus estudios...)\n", pacienteID)
return &historiaReal{pacienteID}, nil
}
func (h *historiaReal) Diagnosticos() ([]string, error) {
return []string{"Hipertensión controlada"}, nil
}
func (h *historiaReal) Imagenes() ([]string, error) {
return []string{"resonancia-2026-10.dcm"}, nil
}
var ErrAccesoDenegado = errors.New("acceso denegado")
type Usuario struct {
ID string
PacientesAsignados []string
}
type ProxyHistoria struct {
pacienteID string
usuario Usuario
real func() (*historiaReal, error) // se ejecuta una sola vez
}
func NuevoProxyHistoria(pacienteID string, usuario Usuario) *ProxyHistoria {
return &ProxyHistoria{
pacienteID: pacienteID,
usuario: usuario,
real: sync.OnceValues(func() (*historiaReal, error) { return cargarHistoria(pacienteID) }),
}
}
func (p *ProxyHistoria) acceder() (*historiaReal, error) {
if !slices.Contains(p.usuario.PacientesAsignados, p.pacienteID) {
return nil, fmt.Errorf("%w a la historia %s", ErrAccesoDenegado, p.pacienteID)
}
return p.real()
}
func (p *ProxyHistoria) Diagnosticos() ([]string, error) {
h, err := p.acceder()
if err != nil {
return nil, err
}
return h.Diagnosticos()
}
func (p *ProxyHistoria) Imagenes() ([]string, error) {
h, err := p.acceder()
if err != nil {
return nil, err
}
return h.Imagenes()
}
func main() {
medica := Usuario{"dra-rios", []string{"P-77"}}
var historia HistoriaClinica = NuevoProxyHistoria("P-77", medica)
fmt.Println("Proxy creado: todavía no se cargó nada")
fmt.Println(historia.Diagnosticos()) // carga la historia la primera vez
fmt.Println(historia.Imagenes()) // ya está cargada
_, err := NuevoProxyHistoria("P-90", medica).Diagnosticos()
fmt.Println(err, errors.Is(err, ErrAccesoDenegado)) // acceso denegado a la historia P-90 true
}LO IDIOMÁTICO EN RUST: El proxy implementa el mismo trait que la historia real. std::cell::OnceCell guarda el objeto real y lo crea solo en el primer acceso, y un acceso denegado se devuelve como Err, sin excepciones. El operador ? propaga ese error en una línea.
use std::cell::OnceCell;
trait HistoriaClinica {
fn diagnosticos(&self) -> Result<Vec<String>, String>;
fn imagenes(&self) -> Result<Vec<String>, String>;
}
struct HistoriaReal;
impl HistoriaReal {
fn cargar(paciente_id: &str) -> Self {
println!(" (cargando la historia {paciente_id} y sus estudios...)");
HistoriaReal
}
}
impl HistoriaClinica for HistoriaReal {
fn diagnosticos(&self) -> Result<Vec<String>, String> {
Ok(vec!["Hipertensión controlada".to_string()])
}
fn imagenes(&self) -> Result<Vec<String>, String> {
Ok(vec!["resonancia-2026-10.dcm".to_string()])
}
}
struct Usuario {
pacientes_asignados: Vec<String>,
}
struct ProxyHistoria<'a> {
paciente_id: String,
usuario: &'a Usuario,
real: OnceCell<HistoriaReal>, // vacío hasta el primer acceso
}
impl ProxyHistoria<'_> {
fn acceder(&self) -> Result<&HistoriaReal, String> {
if !self.usuario.pacientes_asignados.contains(&self.paciente_id) {
return Err(format!(
"acceso denegado a la historia {}",
self.paciente_id
));
}
Ok(self
.real
.get_or_init(|| HistoriaReal::cargar(&self.paciente_id)))
}
}
impl HistoriaClinica for ProxyHistoria<'_> {
fn diagnosticos(&self) -> Result<Vec<String>, String> {
self.acceder()?.diagnosticos()
}
fn imagenes(&self) -> Result<Vec<String>, String> {
self.acceder()?.imagenes()
}
}
fn nuevo_proxy<'a>(paciente_id: &str, usuario: &'a Usuario) -> ProxyHistoria<'a> {
ProxyHistoria {
paciente_id: paciente_id.to_string(),
usuario,
real: OnceCell::new(),
}
}
fn main() {
let medica = Usuario {
pacientes_asignados: vec!["P-77".to_string()],
};
let proxy = nuevo_proxy("P-77", &medica);
let historia: &dyn HistoriaClinica = &proxy;
println!("Proxy creado: todavía no se cargó nada");
println!("{:?}", historia.diagnosticos()); // carga la historia la primera vez
println!("{:?}", historia.imagenes()); // ya está cargada
println!("{:?}", nuevo_proxy("P-90", &medica).diagnosticos()); // Err("acceso denegado a la historia P-90")
}LO IDIOMÁTICO EN PHP: El proxy implementa la misma interfaz y crea la historia real en el primer acceso con ??=. PHP también ofrece alternativas: el método mágico __call para reenviar cualquier método, y desde PHP 8.4 los "lazy objects" nativos (ReflectionClass::newLazyProxy), que usan los ORM como Doctrine.
<?php
declare(strict_types=1);
interface HistoriaClinica
{
/** @return list<string> */
public function diagnosticos(): array;
/** @return list<string> */
public function imagenes(): array;
}
final class HistoriaClinicaReal implements HistoriaClinica
{
public function __construct(string $pacienteId)
{
echo " (cargando la historia {$pacienteId} y sus estudios...)\n";
}
public function diagnosticos(): array { return ['Hipertensión controlada']; }
public function imagenes(): array { return ['resonancia-2026-10.dcm']; }
}
final readonly class Usuario
{
/** @param list<string> $pacientesAsignados */
public function __construct(public string $id, public array $pacientesAsignados) {}
}
final class ProxyHistoriaClinica implements HistoriaClinica
{
private ?HistoriaClinicaReal $real = null; // se crea en el primer acceso
public function __construct(private readonly string $pacienteId, private readonly Usuario $usuario) {}
public function diagnosticos(): array { return $this->real()->diagnosticos(); }
public function imagenes(): array { return $this->real()->imagenes(); }
private function real(): HistoriaClinicaReal
{
if (!in_array($this->pacienteId, $this->usuario->pacientesAsignados, true)) {
throw new DomainException("Acceso denegado a la historia {$this->pacienteId}");
}
return $this->real ??= new HistoriaClinicaReal($this->pacienteId);
}
}
$medica = new Usuario('dra-rios', ['P-77']);
$historia = new ProxyHistoriaClinica('P-77', $medica);
echo "Proxy creado: todavía no se cargó nada\n";
echo implode(', ', $historia->diagnosticos()), "\n"; // carga la historia la primera vez
echo count($historia->imagenes()), "\n"; // ya está cargada
try {
(new ProxyHistoriaClinica('P-90', $medica))->diagnosticos();
} catch (DomainException $error) {
echo $error->getMessage(), "\n"; // Acceso denegado a la historia P-90
}