640 lines
26 KiB
Markdown
640 lines
26 KiB
Markdown
---
|
||
name: portfolio-backend
|
||
description: Parámetros, reglas y estándares de arquitectura backend en C# / .NET 8/9 con Clean Architecture (Domain, Application, Infrastructure, WebApi), CQRS con MediatR, FluentValidation, EF Core MySQL, RBAC para administración y endpoints interactivos de prueba.
|
||
---
|
||
|
||
# Estándar de Arquitectura Backend — Clean Architecture en .NET (Portafolio Interactivo)
|
||
|
||
Este documento define las reglas de arquitectura, flujo de datos por capas, convenciones de código, seguridad y persistencia con MySQL para el backend en **.NET 8/9** del portafolio interactivo.
|
||
|
||
---
|
||
|
||
## 1. Mentalidad de Arquitecto Backend Senior — Reglas de Oro
|
||
|
||
El agente actúa como un **Ingeniero Principal y Arquitecto Backend Senior con 10+ años de experiencia** en desarrollo con .NET y arquitecturas limpias de alto rendimiento.
|
||
|
||
1. **Clean Architecture & Regla de Dependencia**:
|
||
- Las dependencias van estrictamente hacia adentro:
|
||
`WebApi` ──► `Application` ──► `Domain` ◄── `Infrastructure`
|
||
- El núcleo (`Domain`) nunca depende de EF Core, MySQL, MediatR, ASP.NET Core ni librerías externas.
|
||
- La inversión de dependencias permite aislar la lógica de negocio: `Domain` declara los contratos (`IProjectRepository`), e `Infrastructure` los implementa.
|
||
2. **Filosofía Ponytail (Prevención de Sobreingeniería)**:
|
||
- **Prohibido Generic Repository genérico** (`IRepository<T>` con 30 métodos que nadie usa). Diseñar interfaces de repositorio específicas y quirúrgicas para cada raíz de agregado (Aggregate Root).
|
||
- **Prohibido envolver DbContext en un UnitOfWork casero adicional**: `DbContext` de EF Core ya es un *Unit of Work* y *Identity Map* probado en producción.
|
||
- **Prohibido AutoMapper**: En su lugar, proyectar directamente con `.Select()` de LINQ para lecturas, o constructores/métodos estáticos en records para mapeos explícitos, seguros y sin overhead de reflection.
|
||
- **Records posicionales**: Usar `public sealed record ...` para DTOs, Commands y Queries. Cero clases verbosas con getters/setters tradicionales.
|
||
- **Primary Constructors**: Aprovechar la sintaxis moderna de C# 12+ para inyección de dependencias limpia en una sola línea.
|
||
3. **Cero operaciones síncronas en I/O**:
|
||
- Todo acceso a base de datos, hasher o servicios de token es estrictamente asíncrono (`async/await`) recibiendo siempre `CancellationToken`.
|
||
4. **Manejo Centralizado de Excepciones**:
|
||
- Prohibido capturar excepciones dentro de los controladores. Se utiliza `AddProblemDetails()` y `IExceptionHandler` según el estándar **RFC 7807**.
|
||
|
||
---
|
||
|
||
## 2. Límites de Líneas por Archivo y Modularidad Backend
|
||
|
||
Para mantener un balance óptimo entre cohesión y separación de responsabilidades (evitando tanto las *God Classes* monolíticas como la sobre-fragmentación artificial en decenas de micro-archivos), se establecen los siguientes umbrales tolerables:
|
||
|
||
| Tipo de Archivo | Capa / Ubicación | Líneas Ideales | Máximo Tolerable | Acción al Exceder el Límite |
|
||
|---|---|---|---|---|
|
||
| **Controlador REST** | `WebApi/Controllers/` | **50 – 120** | **200** | Prohibido incluir lógica de negocio. Solo validar HTTP, delegar a MediatR (`ISender`) y retornar `ActionResult<T>`. Permite agrupar las rutas CRUD completas de un recurso. |
|
||
| **Command / Query Handler** | `Application/Features/.../` | **40 – 90** | **160** | Principio *One Handler per File*. Si supera 160 líneas, encapsular reglas dentro de la Entidad de Dominio o delegar a subservicios especializados. |
|
||
| **Entidad de Dominio** | `Domain/Entities/` | **60 – 130** | **220** | Contiene propiedades, reglas de negocio y fábrica estática `Create()`. Extraer sub-conceptos a Value Objects si crece. |
|
||
| **DTO / Command / Query** | `Application/.../DTOs/` | **10 – 40** | **80** | Usar `public sealed record` posicionales. Si se agrupan varios DTOs relacionados en un archivo (ej: `ProjectDtos.cs`), el archivo puede alcanzar hasta **120 líneas**. |
|
||
| **Validador FluentValidation**| `Application/.../Validators/` | **25 – 60** | **100** | Encapsular validaciones complejas o reutilizables en métodos de extensión propios. |
|
||
| **Repositorio de Infraestructura** | `Infrastructure/Persistence/` | **50 – 100** | **180** | Implementar los métodos de consulta y persistencia requeridos por el contrato de dominio (`IProjectRepository`). |
|
||
| **Configuración EF Core (Fluent API)** | `Infrastructure/Configurations/` | **30 – 70** | **120** | Una clase por entidad (`IEntityTypeConfiguration<T>`). |
|
||
| **DbContext** | `Infrastructure/Context/` | **40 – 90** | **150** | Registrar los `DbSet<T>` y llamar a `modelBuilder.ApplyConfigurationsFromAssembly(...)`. |
|
||
|
||
### Reglas de Descomposición Modular:
|
||
- **One Handler per File**: Cada caso de uso (Command o Query) y su Handler viven en su propio archivo independiente para facilitar pruebas unitarias y navegación.
|
||
- **División de Controladores**: Un controlador puede manejar cómodamente las operaciones CRUD de una entidad (hasta 150-200 líneas). Solo se divide si mezcla recursos no relacionados o responsabilidades administrativas distintas.
|
||
|
||
---
|
||
|
||
## 3. Mapa de Capas y Responsabilidades
|
||
|
||
```
|
||
backend/src/
|
||
├── Portfolio.Domain/ <- Núcleo del Negocio. Cero dependencias externas.
|
||
│ ├── Entities/ <- Project, Skill, User, Role, InteractiveLog
|
||
│ ├── Enums/ <- ProjectCategory, SkillLevel, UserRole
|
||
│ ├── Exceptions/ <- DomainException, NotFoundException
|
||
│ └── Interfaces/ <- IProjectRepository, IUserRepository, IUnitOfWork (opcional)
|
||
│
|
||
├── Portfolio.Application/ <- Casos de Uso (CQRS). Solo depende de Domain.
|
||
│ ├── Common/
|
||
│ │ ├── Behaviors/ <- ValidationBehavior (MediatR Pipeline)
|
||
│ │ └── Interfaces/ <- IJwtTokenGenerator, IPasswordHasher
|
||
│ ├── Features/ <- Organización vertical por Feature (Vertical Slice inside App)
|
||
│ │ ├── Projects/
|
||
│ │ │ ├── Commands/ <- CreateProjectCommand, UpdateProjectCommand
|
||
│ │ │ ├── Queries/ <- GetProjectsQuery, GetProjectByIdQuery
|
||
│ │ │ ├── DTOs/ <- ProjectResponseDto, CreateProjectRequestDto
|
||
│ │ │ └── Validators/ <- CreateProjectCommandValidator
|
||
│ │ ├── Interactive/ <- Endpoints de prueba para visitantes
|
||
│ │ │ ├── Queries/ <- GetServerTelemetryQuery, PingServerQuery
|
||
│ │ │ └── DTOs/ <- ServerTelemetryDto, PingResponseDto
|
||
│ │ └── Auth/ <- Login, RefreshToken, RBAC
|
||
│ │ ├── Commands/ <- LoginCommand, RefreshTokenCommand
|
||
│ │ ├── DTOs/ <- AuthResponseDto, LoginRequestDto
|
||
│ │ └── Validators/ <- LoginCommandValidator
|
||
│ └── DependencyInjection.cs
|
||
│
|
||
├── Portfolio.Infrastructure/ <- Implementación Técnica. Depende de Application y Domain.
|
||
│ ├── Persistence/
|
||
│ │ ├── Context/ <- PortfolioDbContext (EF Core con MySQL)
|
||
│ │ ├── Configurations/ <- EntityTypeConfigurations (Fluent API)
|
||
│ │ └── Repositories/ <- ProjectRepository, UserRepository
|
||
│ ├── Security/
|
||
│ │ ├── JwtTokenGenerator.cs <- Generación y validación de tokens JWT
|
||
│ │ └── PasswordHasher.cs <- Hasheo de contraseñas (BCrypt / PBKDF2)
|
||
│ └── DependencyInjection.cs
|
||
│
|
||
└── Portfolio.WebApi/ <- Punto de Entrada HTTP. Depende de Application e Infrastructure.
|
||
├── Controllers/ <- ProjectsController, InteractiveController, AuthController
|
||
├── Middleware/ <- GlobalExceptionHandler (ProblemDetails RFC 7807)
|
||
├── Security/ <- HasPermissionAttribute o Authorize policies
|
||
├── Program.cs <- Pipeline HTTP, DI y configuración
|
||
└── appsettings.json
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Flujo de Datos Obligatorio para Endpoints (Data Flow Pipeline)
|
||
|
||
Para mantener total coherencia y evitar sobreingeniería, todo endpoint debe seguir estrictamente este flujo de 7 pasos secuenciales:
|
||
|
||
```
|
||
[1. Request HTTP / DTO]
|
||
│
|
||
▼
|
||
[2. Command / Query (MediatR IRequest<T>)]
|
||
│
|
||
▼
|
||
[3. FluentValidation (Pipeline Behavior)]
|
||
│
|
||
▼
|
||
[4. Handler (IRequestHandler<T, TResponse>)]
|
||
│
|
||
▼
|
||
[5. Dominio & Persistencia]
|
||
├── Si es ESCRITURA: Entidad de Dominio ejecuta regla ──► IRepository.AddAsync() ──► SaveChangesAsync()
|
||
└── Si es LECTURA: DbContext.Set<T>().AsNoTracking().Select(...) ──► Directo a DTO (Sin overhead)
|
||
│
|
||
▼
|
||
[6. Response DTO (Record Inmutable)]
|
||
│
|
||
▼
|
||
[7. Controller Action] (Retorna ActionResult<TResponse> con 200, 201 o 204)
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Implementación Paso a Paso con Código Real
|
||
|
||
### Paso 1: Definir los DTOs (Records Inmutables)
|
||
Los DTOs definen los contratos externos sin exponer la estructura de base de datos.
|
||
|
||
```csharp
|
||
// Application/Features/Projects/DTOs/ProjectDtos.cs
|
||
namespace Portfolio.Application.Features.Projects.DTOs;
|
||
|
||
public sealed record CreateProjectRequestDto(
|
||
string Title,
|
||
string Description,
|
||
string RepositoryUrl,
|
||
string? LiveDemoUrl,
|
||
string[] Technologies,
|
||
bool IsFeatured
|
||
);
|
||
|
||
public sealed record ProjectResponseDto(
|
||
Guid Id,
|
||
string Title,
|
||
string Description,
|
||
string RepositoryUrl,
|
||
string? LiveDemoUrl,
|
||
IReadOnlyList<string> Technologies,
|
||
bool IsFeatured,
|
||
DateTime CreatedAtUtc
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### Paso 2: Command o Query (MediatR `IRequest<T>`)
|
||
Representa la intención del usuario. El Command muta estado; la Query solo consulta.
|
||
|
||
```csharp
|
||
// Application/Features/Projects/Commands/CreateProjectCommand.cs
|
||
using MediatR;
|
||
using Portfolio.Application.Features.Projects.DTOs;
|
||
|
||
namespace Portfolio.Application.Features.Projects.Commands;
|
||
|
||
public sealed record CreateProjectCommand(
|
||
string Title,
|
||
string Description,
|
||
string RepositoryUrl,
|
||
string? LiveDemoUrl,
|
||
string[] Technologies,
|
||
bool IsFeatured
|
||
) : IRequest<ProjectResponseDto>;
|
||
```
|
||
|
||
---
|
||
|
||
### Paso 3: Validación con FluentValidation
|
||
Valida la integridad de los datos antes de que el Handler sea ejecutado.
|
||
|
||
```csharp
|
||
// Application/Features/Projects/Validators/CreateProjectCommandValidator.cs
|
||
using FluentValidation;
|
||
using Portfolio.Application.Features.Projects.Commands;
|
||
|
||
namespace Portfolio.Application.Features.Projects.Validators;
|
||
|
||
public sealed class CreateProjectCommandValidator : AbstractValidator<CreateProjectCommand>
|
||
{
|
||
public CreateProjectCommandValidator()
|
||
{
|
||
RuleFor(x => x.Title)
|
||
.NotEmpty().WithMessage("El título del proyecto es obligatorio.")
|
||
.MaximumLength(150).WithMessage("El título no puede exceder 150 caracteres.");
|
||
|
||
RuleFor(x => x.Description)
|
||
.NotEmpty().WithMessage("La descripción es obligatoria.")
|
||
.MaximumLength(1000).WithMessage("La descripción no puede exceder 1000 caracteres.");
|
||
|
||
RuleFor(x => x.RepositoryUrl)
|
||
.NotEmpty().WithMessage("La URL del repositorio es obligatoria.")
|
||
.Must(uri => Uri.TryCreate(uri, UriKind.Absolute, out _))
|
||
.WithMessage("La URL del repositorio no es válida.");
|
||
|
||
RuleFor(x => x.Technologies)
|
||
.NotEmpty().WithMessage("Debe incluir al menos una tecnología.");
|
||
}
|
||
}
|
||
```
|
||
|
||
#### Pipeline de Validación Automático (ValidationBehavior)
|
||
MediatR ejecuta este pipeline antes del Handler; si la validación falla, lanza `ValidationException` que el `GlobalExceptionHandler` captura retornando HTTP 422:
|
||
|
||
```csharp
|
||
// Application/Common/Behaviors/ValidationBehavior.cs
|
||
using FluentValidation;
|
||
using MediatR;
|
||
|
||
namespace Portfolio.Application.Common.Behaviors;
|
||
|
||
public sealed class ValidationBehavior<TRequest, TResponse>(IEnumerable<IValidator<TRequest>> validators)
|
||
: IPipelineBehavior<TRequest, TResponse>
|
||
where TRequest : IRequest<TResponse>
|
||
{
|
||
public async Task<TResponse> Handle(
|
||
TRequest request,
|
||
RequestHandlerDelegate<TResponse> next,
|
||
CancellationToken cancellationToken)
|
||
{
|
||
if (!validators.Any()) return await next();
|
||
|
||
var context = new ValidationContext<TRequest>(request);
|
||
var validationResults = await Task.WhenAll(
|
||
validators.Select(v => v.ValidateAsync(context, cancellationToken)));
|
||
|
||
var failures = validationResults
|
||
.SelectMany(r => r.Errors)
|
||
.Where(f => f != null)
|
||
.ToList();
|
||
|
||
if (failures.Count != 0)
|
||
throw new ValidationException(failures);
|
||
|
||
return await next();
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Paso 4: Handler (`IRequestHandler<T, TResponse>`)
|
||
Orquesta la lógica de negocio delegando la persistencia a través de la interfaz del repositorio.
|
||
|
||
```csharp
|
||
// Application/Features/Projects/Commands/CreateProjectCommandHandler.cs
|
||
using MediatR;
|
||
using Portfolio.Application.Features.Projects.DTOs;
|
||
using Portfolio.Domain.Entities;
|
||
using Portfolio.Domain.Interfaces;
|
||
|
||
namespace Portfolio.Application.Features.Projects.Commands;
|
||
|
||
public sealed class CreateProjectCommandHandler(IProjectRepository projectRepository)
|
||
: IRequestHandler<CreateProjectCommand, ProjectResponseDto>
|
||
{
|
||
public async Task<ProjectResponseDto> Handle(
|
||
CreateProjectCommand request,
|
||
CancellationToken cancellationToken)
|
||
{
|
||
// Creación y encapsulación en entidad de dominio
|
||
var project = Project.Create(
|
||
request.Title,
|
||
request.Description,
|
||
request.RepositoryUrl,
|
||
request.LiveDemoUrl,
|
||
request.Technologies,
|
||
request.IsFeatured
|
||
);
|
||
|
||
await projectRepository.AddAsync(project, cancellationToken);
|
||
await projectRepository.SaveChangesAsync(cancellationToken);
|
||
|
||
return new ProjectResponseDto(
|
||
project.Id,
|
||
project.Title,
|
||
project.Description,
|
||
project.RepositoryUrl,
|
||
project.LiveDemoUrl,
|
||
project.Technologies,
|
||
project.IsFeatured,
|
||
project.CreatedAtUtc
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### Paso 5: Dominio e Inversión de Persistencia
|
||
|
||
#### A. Entidad de Dominio Pura (Sin EF Core)
|
||
```csharp
|
||
// Domain/Entities/Project.cs
|
||
namespace Portfolio.Domain.Entities;
|
||
|
||
public sealed class Project
|
||
{
|
||
public Guid Id { get; private set; }
|
||
public string Title { get; private set; } = string.Empty;
|
||
public string Description { get; private set; } = string.Empty;
|
||
public string RepositoryUrl { get; private set; } = string.Empty;
|
||
public string? LiveDemoUrl { get; private set; }
|
||
public List<string> Technologies { get; private set; } = [];
|
||
public bool IsFeatured { get; private set; }
|
||
public DateTime CreatedAtUtc { get; private set; }
|
||
|
||
private Project() { } // Constructor privado para EF Core
|
||
|
||
public static Project Create(
|
||
string title,
|
||
string description,
|
||
string repoUrl,
|
||
string? demoUrl,
|
||
string[] technologies,
|
||
bool isFeatured)
|
||
{
|
||
return new Project
|
||
{
|
||
Id = Guid.NewGuid(),
|
||
Title = title.Trim(),
|
||
Description = description.Trim(),
|
||
RepositoryUrl = repoUrl.Trim(),
|
||
LiveDemoUrl = demoUrl?.Trim(),
|
||
Technologies = [..technologies],
|
||
IsFeatured = isFeatured,
|
||
CreatedAtUtc = DateTime.UtcNow
|
||
};
|
||
}
|
||
}
|
||
```
|
||
|
||
#### B. Contrato en Dominio (Puerto)
|
||
```csharp
|
||
// Domain/Interfaces/IProjectRepository.cs
|
||
using Portfolio.Domain.Entities;
|
||
|
||
namespace Portfolio.Domain.Interfaces;
|
||
|
||
public interface IProjectRepository
|
||
{
|
||
Task<Project?> GetByIdAsync(Guid id, CancellationToken cancellationToken);
|
||
Task<IReadOnlyList<Project>> GetAllAsync(CancellationToken cancellationToken);
|
||
Task AddAsync(Project project, CancellationToken cancellationToken);
|
||
void Remove(Project project);
|
||
Task<int> SaveChangesAsync(CancellationToken cancellationToken);
|
||
}
|
||
```
|
||
|
||
#### C. Implementación en Infraestructura (Adaptador EF Core MySQL)
|
||
```csharp
|
||
// Infrastructure/Persistence/Repositories/ProjectRepository.cs
|
||
using Microsoft.EntityFrameworkCore;
|
||
using Portfolio.Domain.Entities;
|
||
using Portfolio.Domain.Interfaces;
|
||
using Portfolio.Infrastructure.Persistence.Context;
|
||
|
||
namespace Portfolio.Infrastructure.Persistence.Repositories;
|
||
|
||
public sealed class ProjectRepository(PortfolioDbContext context) : IProjectRepository
|
||
{
|
||
public async Task<Project?> GetByIdAsync(Guid id, CancellationToken cancellationToken)
|
||
=> await context.Projects.FirstOrDefaultAsync(p => p.Id == id, cancellationToken);
|
||
|
||
public async Task<IReadOnlyList<Project>> GetAllAsync(CancellationToken cancellationToken)
|
||
=> await context.Projects.AsNoTracking().ToListAsync(cancellationToken);
|
||
|
||
public async Task AddAsync(Project project, CancellationToken cancellationToken)
|
||
=> await context.Projects.AddAsync(project, cancellationToken);
|
||
|
||
public void Remove(Project project)
|
||
=> context.Projects.Remove(project);
|
||
|
||
public async Task<int> SaveChangesAsync(CancellationToken cancellationToken)
|
||
=> await context.SaveChangesAsync(cancellationToken);
|
||
}
|
||
```
|
||
|
||
#### D. Contexto EF Core MySQL y Migraciones
|
||
|
||
```csharp
|
||
// Infrastructure/Persistence/Context/PortfolioDbContext.cs
|
||
using Microsoft.EntityFrameworkCore;
|
||
using Portfolio.Domain.Entities;
|
||
|
||
namespace Portfolio.Infrastructure.Persistence.Context;
|
||
|
||
public sealed class PortfolioDbContext(DbContextOptions<PortfolioDbContext> options) : DbContext(options)
|
||
{
|
||
public DbSet<Project> Projects => Set<Project>();
|
||
public DbSet<Skill> Skills => Set<Skill>();
|
||
public DbSet<User> Users => Set<User>();
|
||
public DbSet<RefreshToken> RefreshTokens => Set<RefreshToken>();
|
||
|
||
protected override void OnModelCreating(ModelBuilder modelBuilder)
|
||
{
|
||
modelBuilder.ApplyConfigurationsFromAssembly(typeof(PortfolioDbContext).Assembly);
|
||
base.OnModelCreating(modelBuilder);
|
||
}
|
||
}
|
||
```
|
||
|
||
Registro de Inyección en `Infrastructure/DependencyInjection.cs`:
|
||
```csharp
|
||
public static IServiceCollection AddInfrastructure(this IServiceCollection services, IConfiguration configuration)
|
||
{
|
||
var connectionString = configuration.GetConnectionString("DefaultConnection");
|
||
services.AddDbContext<PortfolioDbContext>(options =>
|
||
options.UseMySql(connectionString, ServerVersion.AutoDetect(connectionString)));
|
||
|
||
services.AddScoped<IProjectRepository, ProjectRepository>();
|
||
return services;
|
||
}
|
||
```
|
||
|
||
Comandos de Migración MySQL:
|
||
```bash
|
||
dotnet ef migrations add InitialCreate --project src/Portfolio.Infrastructure --startup-project src/Portfolio.WebApi
|
||
dotnet ef database update --project src/Portfolio.Infrastructure --startup-project src/Portfolio.WebApi
|
||
```
|
||
|
||
---
|
||
|
||
### Paso 6 & 7: Controlador REST en WebApi
|
||
|
||
```csharp
|
||
// WebApi/Controllers/ProjectsController.cs
|
||
using MediatR;
|
||
using Microsoft.AspNetCore.Authorization;
|
||
using Microsoft.AspNetCore.Mvc;
|
||
using Portfolio.Application.Features.Projects.Commands;
|
||
using Portfolio.Application.Features.Projects.DTOs;
|
||
using Portfolio.Application.Features.Projects.Queries;
|
||
|
||
namespace Portfolio.WebApi.Controllers;
|
||
|
||
[ApiController]
|
||
[Route("api/v1/[controller]")]
|
||
public sealed class ProjectsController(ISender sender) : ControllerBase
|
||
{
|
||
[HttpGet]
|
||
[ProducesResponseType(typeof(IEnumerable<ProjectResponseDto>), StatusCodes.Status200OK)]
|
||
public async Task<ActionResult<IEnumerable<ProjectResponseDto>>> GetAll(
|
||
CancellationToken cancellationToken)
|
||
{
|
||
var result = await sender.Send(new GetProjectsQuery(), cancellationToken);
|
||
return Ok(result);
|
||
}
|
||
|
||
[HttpPost]
|
||
[Authorize(Roles = "Admin")] // Protegido por RBAC para que Bryan gestione sus proyectos
|
||
[ProducesResponseType(typeof(ProjectResponseDto), StatusCodes.Status201Created)]
|
||
[ProducesResponseType(StatusCodes.Status422UnprocessableEntity)]
|
||
public async Task<ActionResult<ProjectResponseDto>> Create(
|
||
[FromBody] CreateProjectRequestDto request,
|
||
CancellationToken cancellationToken)
|
||
{
|
||
var command = new CreateProjectCommand(
|
||
request.Title,
|
||
request.Description,
|
||
request.RepositoryUrl,
|
||
request.LiveDemoUrl,
|
||
request.Technologies,
|
||
request.IsFeatured
|
||
);
|
||
|
||
var created = await sender.Send(command, cancellationToken);
|
||
return CreatedAtAction(nameof(GetAll), new { id = created.Id }, created);
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Endpoints Interactivos Públicos (Live Playground)
|
||
|
||
Para que los visitantes y reclutadores interactúen con el backend sin autenticación pero con rate-limiting nativo para evitar abusos o denegación de servicio:
|
||
|
||
```csharp
|
||
// WebApi/Controllers/InteractiveController.cs
|
||
using MediatR;
|
||
using Microsoft.AspNetCore.Mvc;
|
||
using Microsoft.AspNetCore.RateLimiting;
|
||
using Portfolio.Application.Features.Interactive.DTOs;
|
||
using Portfolio.Application.Features.Interactive.Queries;
|
||
|
||
namespace Portfolio.WebApi.Controllers;
|
||
|
||
[ApiController]
|
||
[Route("api/v1/[controller]")]
|
||
[EnableRateLimiting("interactive-policy")] // Límite nativo de .NET 8/9 (ej. 30 req/min por IP)
|
||
public sealed class InteractiveController(ISender sender) : ControllerBase
|
||
{
|
||
[HttpGet("ping")]
|
||
[ProducesResponseType(typeof(PingResponseDto), StatusCodes.Status200OK)]
|
||
public async Task<ActionResult<PingResponseDto>> Ping(CancellationToken cancellationToken)
|
||
{
|
||
var response = await sender.Send(new PingServerQuery(), cancellationToken);
|
||
return Ok(response);
|
||
}
|
||
|
||
[HttpGet("telemetry")]
|
||
[ProducesResponseType(typeof(ServerTelemetryDto), StatusCodes.Status200OK)]
|
||
public async Task<ActionResult<ServerTelemetryDto>> Telemetry(CancellationToken cancellationToken)
|
||
{
|
||
var response = await sender.Send(new GetServerTelemetryQuery(), cancellationToken);
|
||
return Ok(response);
|
||
}
|
||
}
|
||
```
|
||
|
||
Configuración en `WebApi/Program.cs`:
|
||
```csharp
|
||
builder.Services.AddRateLimiter(options =>
|
||
{
|
||
options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
|
||
options.AddFixedWindowLimiter("interactive-policy", opt =>
|
||
{
|
||
opt.PermitLimit = 30; // Máximo 30 peticiones
|
||
opt.Window = TimeSpan.FromMinutes(1); // por cada minuto
|
||
opt.QueueLimit = 0;
|
||
});
|
||
});
|
||
// En el pipeline:
|
||
app.UseRateLimiter();
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Seguridad y RBAC (Administración para Bryan)
|
||
|
||
1. **Autenticación con JWT**:
|
||
- Tokens con tiempo de expiración corto (15 a 30 minutos).
|
||
- `ClockSkew = TimeSpan.Zero` obligatorio para no permitir ventanas de tokens vencidos.
|
||
2. **Refresh Token Rotation en MySQL**:
|
||
- Cada refresh token se almacena en la tabla `auth_refresh_tokens` con estado `IsRevoked`, `ExpiresAtUtc` y `ReplacedByToken`.
|
||
- Al renovar, el token anterior se revoca inmediatamente y se emite uno nuevo. Si un token revocado intenta usarse, se revoca toda la cadena por sospecha de compromiso.
|
||
|
||
```csharp
|
||
// Domain/Entities/RefreshToken.cs
|
||
namespace Portfolio.Domain.Entities;
|
||
|
||
public sealed class RefreshToken
|
||
{
|
||
public Guid Id { get; private set; }
|
||
public Guid UserId { get; private set; }
|
||
public string TokenHash { get; private set; } = string.Empty;
|
||
public DateTime ExpiresAtUtc { get; private set; }
|
||
public bool IsRevoked { get; private set; }
|
||
public DateTime CreatedAtUtc { get; private set; }
|
||
|
||
public bool IsActive => !IsRevoked && DateTime.UtcNow < ExpiresAtUtc;
|
||
public void Revoke() => IsRevoked = true;
|
||
}
|
||
```
|
||
|
||
3. **RBAC Simple y Efectivo**:
|
||
- Roles en Claim: `Role: Admin`, `Role: Visitor`.
|
||
- Bryan inicia sesión desde el portal o terminal (`POST /api/v1/auth/login`) y recibe los tokens para realizar operaciones de escritura (`POST`, `PUT`, `DELETE`).
|
||
- Los visitantes solo tienen acceso de lectura a los proyectos/skills y a los endpoints públicos de `/api/v1/interactive/*`.
|
||
|
||
---
|
||
|
||
## 8. Manejo Centralizado de Errores — ProblemDetails RFC 7807
|
||
|
||
```csharp
|
||
// WebApi/Middleware/GlobalExceptionHandler.cs
|
||
using Microsoft.AspNetCore.Diagnostics;
|
||
using Microsoft.AspNetCore.Mvc;
|
||
using Portfolio.Domain.Exceptions;
|
||
|
||
namespace Portfolio.WebApi.Middleware;
|
||
|
||
public sealed class GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger) : IExceptionHandler
|
||
{
|
||
public async ValueTask<bool> TryHandleAsync(
|
||
HttpContext httpContext,
|
||
Exception exception,
|
||
CancellationToken cancellationToken)
|
||
{
|
||
logger.LogError(exception, "Excepción capturada: {Message}", exception.Message);
|
||
|
||
var (statusCode, title) = exception switch
|
||
{
|
||
NotFoundException => (StatusCodes.Status404NotFound, "Recurso no encontrado"),
|
||
FluentValidation.ValidationException => (StatusCodes.Status422UnprocessableEntity, "Error de validación"),
|
||
UnauthorizedAccessException => (StatusCodes.Status401Unauthorized, "No autorizado"),
|
||
_ => (StatusCodes.Status500InternalServerError, "Error interno del servidor")
|
||
};
|
||
|
||
var problemDetails = new ProblemDetails
|
||
{
|
||
Status = statusCode,
|
||
Title = title,
|
||
Detail = exception.Message,
|
||
Instance = httpContext.Request.Path
|
||
};
|
||
|
||
httpContext.Response.StatusCode = statusCode;
|
||
await httpContext.Response.WriteAsJsonAsync(problemDetails, cancellationToken);
|
||
return true;
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. Anti-Patrones Prohibidos en Backend
|
||
|
||
| Anti-patrón Prohibido | Solución Obligatoria |
|
||
|---|---|
|
||
| Crear `GenericRepository<T>` con docenas de métodos genéricos | Contratos de repositorio específicos por entidad con los métodos exactos necesarios |
|
||
| Envolver `DbContext` en una clase `UnitOfWork` casera | Usar `PortfolioDbContext` directamente como Unit of Work |
|
||
| Usar AutoMapper con perfiles complejos y mapeo por reflexión | Proyección directa `.Select()` en Queries o mapeo estático con Records |
|
||
| Clases DTO tradicionales con getters/setters y constructores boilerplate | `public sealed record ...` inmutable de C# moderno |
|
||
| Inyección de dependencias clásica con campos privados repetidos | **Primary Constructors** de C# 12+ |
|
||
| Rutas en camelCase o PascalCase en controladores | kebab-case con versionado explícito: `[Route("api/v1/[controller]")]` |
|
||
| `SaveChanges()` síncrono en cualquier punto | Siempre `SaveChangesAsync(cancellationToken)` |
|
||
| Catch de excepciones dentro de acciones del controlador | Delegar al `IExceptionHandler` global con RFC 7807 |
|
||
| Consultas de lectura que cargan entidades con tracking | Usar `.AsNoTracking()` o `.Select()` directo a DTO |
|