BRRD.DAC.Standard.Response 1.0.1

BRRD.DAC.Standard.Response

Una biblioteca de respuestas estandarizadas para proyectos DAC en Banreservas.

Descripción General

Esta biblioteca proporciona una forma consistente de estructurar respuestas en sus aplicaciones, incluyendo estados de éxito y error, con soporte integrado para inyección de dependencias.

Características

• Estructura de Respuesta Estandarizada: Formato de respuesta consistente en todas las APIs
• Seguridad de Tipos: Implementación genérica para respuestas fuertemente tipadas
• Soporte para Inyección de Dependencias: Fácil integración con ASP.NET Core DI
• Paginación Integrada: Soporte nativo para respuestas paginadas
• Manejo de Errores: Sistema robusto de gestión de errores con detalles
• Patrón Builder: Constructor fluido para crear respuestas de manera elegante
• Documentación Completa: Documentación XML para soporte de IntelliSense
• Pruebas Unitarias: Cobertura completa de pruebas usando xUnit y FluentAssertions
• Calidad de Código: Incluye analizadores Roslyn y StyleCop para aplicar mejores prácticas

Instalación

Agregue la referencia del paquete a su proyecto:

<PackageReference Include="BRRD.DAC.Standard.Response" Version="1.0.1" />

O usando la CLI de .NET:

dotnet add package BRRD.DAC.Standard.Response

Uso

Uso con Patrón Builder (Recomendado)

El patrón builder ofrece una API fluida y flexible para construir respuestas:

using BRRD.DAC.Standard.Response.Core;
using BRRD.DAC.Standard.Response.Constants;

// Respuesta exitosa simple
var response = StandardResponseBuilder<string>
    .Ok("Datos procesados correctamente")
    .Build();

// Respuesta exitosa con objeto de datos
var bookData = new BookDto
{
    Id = "68b5fd425cdc662b8c393430",
    Title = "The Great Gatsby",
    Author = "F. Scott Fitzgerald",
    Isbn = "978-0-7432-7356-5",
    Price = 15.99m,
    PublishedYear = 1925
};

var response = StandardResponseBuilder<BookDto>
    .Ok(bookData)
    .Build();

// Respuesta de error único
var response = StandardResponseBuilder<object>
    .Error(new ErrorDetail
    {
        Code = "ERR_001",
        Message = "Libro no encontrado"
    })
    .Build();

// Respuesta con objeto complejo (libro con reviews)
var bookWithReviews = new
{
    Title = "1984",
    Author = "George Orwell",
    Status = "available",
    Rating = 4.8,
    Reviews = new
    {
        Comments = new[]
        {
            "Una obra maestra de la literatura distópica.",
            "Lectura obligatoria para entender el presente.",
            "Profundo y perturbador."
        },
        TotalReviews = 1247,
        AverageRating = 4.8
    }
};

var response = StandardResponseBuilder<object>
    .Ok(bookWithReviews)
    .Build();

Uso con Constantes de Mensajes

Utilice los mensajes predefinidos para respuestas comunes:

using BRRD.DAC.Standard.Response.Constants;

// Respuesta OK
var okMessage = ResultMessage.OK; // { code: "ER01", message: "Ok" }

// Error interno
var errorMessage = ResultMessage.INTERNAL_ERROR;

// No encontrado
var notFoundMessage = ResultMessage.NOT_FOUND;

// No autorizado
var unauthorizedMessage = ResultMessage.NOT_AUTHORIZED;

// No autenticado
var unauthenticatedMessage = ResultMessage.NOT_AUTHENTICATED;

Ejemplos de Salida JSON

Respuesta exitosa simple

{
    "meta": {
        "timestamp": "2025-09-01T20:08:34.291Z"
    },
    "data": {
        "id": "68b5fd425cdc662b8c393430",
        "title": "The Great Gatsby",
        "author": "F. Scott Fitzgerald",
        "isbn": "978-0-7432-7356-5",
        "price": 15.99,
        "publishedYear": 1925,
        "genre": "Classic Fiction",
        "publisher": "Scribner",
        "pages": 180,
        "language": "English"
    }
}

Respuesta con objeto complejo

{
    "meta": {
        "timestamp": "2025-10-21T16:54:45.273Z"
    },
    "data": {
        "title": "1984",
        "author": "George Orwell",
        "status": "available",
        "rating": 4.8,
        "reviews": {
            "comments": [
                "Una obra maestra de la literatura distópica.",
                "Lectura obligatoria para entender el presente.",
                "Profundo y perturbador.",
                "Una visión aterradora del futuro."
            ],
            "totalReviews": 1247,
            "averageRating": 4.8,
            "recommendation": {
                "title": "Si te gustó este libro, también te pueden interesar:",
                "suggestedBooks": [
                    {
                        "title": "Brave New World",
                        "author": "Aldous Huxley"
                    },
                    {
                        "title": "Fahrenheit 451",
                        "author": "Ray Bradbury"
                    }
                ]
            }
        }
    }
}

Respuesta con listas y configuración

{
    "meta": {
        "timestamp": "2025-08-12T15:50:48.539Z"
    },
    "data": {
        "title": "Catálogo de Libros",
        "genres": [
            {
                "id": 1,
                "name": "Fiction"
            },
            {
                "id": 2,
                "name": "Non-Fiction"
            },
            {
                "id": 3,
                "name": "Science Fiction"
            }
        ],
        "formats": [
            {
                "id": 1,
                "name": "Paperback"
            },
            {
                "id": 2,
                "name": "Hardcover"
            },
            {
                "id": 3,
                "name": "E-book"
            }
        ],
        "priceRange": {
            "min": 5.99,
            "max": 49.99
        }
    }
}

Respuesta de error

{
    "meta": {
        "timestamp": "2025-11-05T15:30:22.123Z"
    },
    "data": null,
    "errors": [
        {
            "code": "ERR_001",
            "message": "Libro no encontrado",
            "details": "No se encontró un libro con el ISBN proporcionado",
            "field": "isbn",
            "traceId": "abc123-def456"
        }
    ]
}

Respuesta con paginación

{
    "meta": {
        "timestamp": "2025-11-05T15:30:22.123Z",
        "pagination": {
            "currentPage": 1,
            "pageSize": 10,
            "totalItems": 100,
            "totalPages": 10
        }
    },
    "data": [
        {
            "id": 1,
            "title": "To Kill a Mockingbird",
            "author": "Harper Lee"
        },
        {
            "id": 2,
            "title": "Pride and Prejudice",
            "author": "Jane Austen"
        }
    ]
}

Estructura de Respuesta

La clase StandardResponse<T> incluye:

• Meta (Metadata): Metadatos de la respuesta
  • Timestamp (DateTime): Marca de tiempo UTC de la respuesta
  • Pagination (Pagination?): Información de paginación (opcional)
• Data (T?): Los datos de la respuesta
• Errors (ErrorDetail[]?): Lista de errores (si aplica)

Estructura de Error

La clase ErrorDetail incluye:

• Code (string): Código del error
• Message (string): Mensaje descriptivo del error
• Details (string?): Detalles adicionales (opcional)
• Field (string?): Campo relacionado con el error (opcional)
• TraceId (string?): ID de rastreo para debugging (opcional)

Estructura de Paginación

La clase Pagination incluye:

• CurrentPage (int): Página actual
• PageSize (int): Tamaño de página
• TotalItems (int): Total de elementos
• TotalPages (int): Total de páginas

Ejemplos de Uso en APIs

Controlador ASP.NET Core - Ejemplo Simple

[ApiController]
[Route("api/[controller]")]
public class BooksController : ControllerBase
{
    private readonly IBookService _bookService;

    public BooksController(IBookService bookService)
    {
        _bookService = bookService;
    }

    [HttpGet("{id}")]
    public ActionResult<StandardResponse<BookDto>> GetBook(string id)
    {
        try
        {
            var book = _bookService.GetById(id);

            if (book == null)
            {
                var notFoundResponse = StandardResponseBuilder<BookDto>
                    .Error(new ErrorDetail
                    {
                        Code = ResultMessage.NOT_FOUND.Code,
                        Message = $"Libro con ID {id} no encontrado"
                    })
                    .Build();

                return NotFound(notFoundResponse);
            }

            var response = StandardResponseBuilder<BookDto>
                .Ok(book)
                .Build();

            return Ok(response);
        }
        catch (Exception ex)
        {
            var errorResponse = StandardResponseBuilder<BookDto>
                .Error(new ErrorDetail
                {
                    Code = "ERR_BOOK_001",
                    Message = "Error al obtener el libro",
                    Details = ex.Message,
                    TraceId = HttpContext.TraceIdentifier
                })
                .Build();

            return StatusCode(500, errorResponse);
        }
    }

    [HttpPost]
    public ActionResult<StandardResponse<BookDto>> CreateBook(
        [FromBody] CreateBookRequest request)
    {
        try
        {
            var book = _bookService.Create(request);

            var response = StandardResponseBuilder<BookDto>
                .Ok(book)
                .Build();

            return CreatedAtAction(
                nameof(GetBook),
                new { id = book.Id },
                response);
        }
        catch (ValidationException ex)
        {
            var errorResponse = StandardResponseBuilder<BookDto>
                .Errors(ex.Errors.Select(e => new ErrorDetail
                {
                    Code = e.Code,
                    Message = e.Message,
                    Field = e.Field
                }).ToList())
                .Build();

            return BadRequest(errorResponse);
        }
    }
}

Controlador ASP.NET Core - Ejemplo con Paginación

[ApiController]
[Route("api/[controller]")]
public class BooksController : ControllerBase
{
    [HttpGet]
    public ActionResult<StandardResponse<List<BookDto>>> GetBooks(
        [FromQuery] int page = 1,
        [FromQuery] int pageSize = 10)
    {
        var books = _bookService.GetAll(page, pageSize);
        var totalItems = _bookService.GetTotalCount();

        var response = StandardResponseBuilder<List<BookDto>>
            .Ok(books)
            .WithPagination(new Pagination
            {
                CurrentPage = page,
                PageSize = pageSize,
                TotalItems = totalItems,
                TotalPages = (int)Math.Ceiling(totalItems / (double)pageSize)
            })
            .Build();

        return Ok(response);
    }
}

Desarrollo

Compilar el Proyecto

dotnet build

Ejecutar Pruebas

dotnet test

Crear un Paquete NuGet

dotnet pack -c Release

Estructura del Proyecto

BRRD.DAC.Standard.Response/
├─ src/
│  └─ BRRD.DAC.Standard.Response/
│     ├─ Abstractions/       # Interfaces
│     ├─ Core/               # Implementaciones principales
│     ├─ Extensions/         # Extensiones de DI
│     ├─ Constants/          # Mensajes y constantes
│     └─ Properties/         # Información del ensamblado
├─ tests/
│  └─ BRRD.DAC.Standard.Response.Tests/
├─ Directory.Build.props     # Configuración compartida de compilación
└─ .editorconfig            # Reglas de estilo de código

Contribuciones

Por favor siga los estándares de codificación definidos en .editorconfig y asegúrese de que todas las pruebas pasen antes de enviar cambios.

Licencia

BRRD

Versión

1.0.1