188 lines
8.2 KiB
Markdown
188 lines
8.2 KiB
Markdown
# 📝 Guía de Convenciones para Nombres de Schemas
|
||
|
||
Esta guía define cómo nombrar los Schemas de **Requests** y **Responses** según el tipo de operación y el contexto (recurso único o colección).
|
||
|
||
---
|
||
|
||
## 1️⃣ Operaciones sobre recurso único
|
||
|
||
**Patrón**
|
||
<Verbo><Entidad><Condición><TipoDeSchema>
|
||
|
||
|
||
- **Verbo**: describe la acción (`Get`, `Delete`, `Update`, `Patch`, `Create`).
|
||
- **Entidad**: en singular (`Product`, `Customer`, `Invoice`).
|
||
- **Condición**: criterio de selección (`ById`, `BySlug`, `ByEmail`).
|
||
- **TipoDeSchema**: origen o propósito (`ParamsSchema`, `CommandSchema`, `QuerySchema`).
|
||
|
||
**Ejemplos ✅**
|
||
- `GetProductByIdParamsSchema`
|
||
- `DeleteCustomerByIdParamsSchema`
|
||
- `UpdateInvoiceByIdCommandSchema`
|
||
|
||
**Ejemplos ❌**
|
||
- `ProductGetByIdParamsSchema` (orden invertido, menos natural).
|
||
- `GetProductsByIdParamsSchema` (plural innecesario en recurso único).
|
||
|
||
**Lectura natural**: *"Esquema de parámetros para obtener un producto por id"*.
|
||
|
||
---
|
||
|
||
## 2️⃣ Operaciones sobre colecciones
|
||
|
||
**Patrón**
|
||
<Entidad>List<Criterio/Filtro><TipoDeSchema>
|
||
|
||
- **Entidad**: en singular (`Product`, `Customer`).
|
||
- **List**: indica conjunto/listado.
|
||
- **Criterio/Filtro**: tipo de filtrado (`Criteria`, `Query`).
|
||
- **TipoDeSchema**: `Schema` o `ResponseSchema` según corresponda.
|
||
|
||
**Ejemplos ✅**
|
||
- `ProductListCriteriaSchema`
|
||
- `CustomerListResponseSchema`
|
||
- `InvoiceListQuerySchema`
|
||
|
||
**Ejemplos ❌**
|
||
- `ListProductCriteriaSchema` (el orden “ListProduct” suena a verbo y no a colección).
|
||
- `ProductsListCriteriaSchema` (plural innecesario en el nombre base).
|
||
|
||
**Lectura natural**: *"Esquema de criterios para una lista de productos"*.
|
||
|
||
---
|
||
|
||
## 3️⃣ Reglas generales
|
||
|
||
1. **Singular siempre** para el nombre base de la entidad.
|
||
2. El **verbo solo** en operaciones sobre un recurso único o mutaciones.
|
||
3. En listados, el **sustantivo principal primero** (`ProductList`, `CustomerList`), nunca `ListProduct`.
|
||
4. Sufijos estándar:
|
||
- `CommandSchema` → body de mutaciones (create/update/patch).
|
||
- `ParamsSchema` → route params (`/:id`).
|
||
- `QuerySchema` → query string no normalizada.
|
||
- `CriteriaSchema` → query normalizada con patrón Criteria.
|
||
- `ResponseSchema` → respuesta de la API.
|
||
5. Mantener **consistencia**: si usas `ProductListCriteriaSchema`, no alternes con `ProductsCriteriaSchema`.
|
||
|
||
---
|
||
|
||
## 4️⃣ Ejemplos positivos y negativos
|
||
|
||
| ✅ Correcto | ❌ Incorrecto | Motivo del error |
|
||
|------------------------------------------|---------------------------------------------|----------------------------------------------|
|
||
| `GetCustomerByIdParamsSchema` | `CustomerGetByIdParamsSchema` | Orden invertido. |
|
||
| `ProductListCriteriaSchema` | `ListProductCriteriaSchema` | Orden “ListProduct” no natural en inglés. |
|
||
| `CustomerListResponseSchema` | `CustomersListResponseSchema` | Plural innecesario. |
|
||
| `DeleteInvoiceByIdParamsSchema` | `DeleteInvoicesByIdParamsSchema` | Plural innecesario en recurso único. |
|
||
| `UpdateProductByIdCommandSchema` | `UpdateProductCommandByIdSchema` | `ById` debe ir antes del tipo de esquema. |
|
||
|
||
---
|
||
|
||
|
||
# Convenciones de nombres para Schemas (Requests y Responses)
|
||
|
||
## Tabla de rutas ↔ Schemas
|
||
|
||
| **Método** | **Ruta** | **Caso de uso** | **Request Schema (validación)** | **Response Schema (DTO)** | **Notas** |
|
||
|-----------:|---------------------|--------------------------------------------------|--------------------------------------------|-------------------------------------------|-----------|
|
||
| GET | `/entities` | Listado con criterios (Criteria normalizado) | `EntityListCriteriaSchema` | `EntityListResponseSchema` | `data: EntitySummary[]`, `pageNumber`, `pageSize`, `totalItems`. |
|
||
| GET | `/entities` | Búsqueda/filtrado por query params “raw” | `SearchEntityQuerySchema` | `EntityListResponseSchema` | Úsalo si **no** aplicas patrón Criteria. |
|
||
| GET | `/entities/:id` | Obtener por ID | `GetEntityByIdParamsSchema` | `EntityDetailResponseSchema` | Si devuelves el recurso “puro”, puedes usar `EntityResourceSchema`. |
|
||
| POST | `/entities` | Crear recurso | `CreateEntityCommandSchema` | `EntityCreatedResponseSchema` **o** `EntityResourceSchema` | Si devuelves 201 + recurso completo, usa `EntityResourceSchema`. |
|
||
| PUT | `/entities/:id` | Reemplazar recurso (idempotente) | `UpdateEntityCommandSchema` + `UpdateEntityByIdParamsSchema` | `EntityResourceSchema` | También válido con PATCH para cambios parciales. |
|
||
| PATCH | `/entities/:id` | Actualizar parcialmente | `PatchEntityCommandSchema` + `UpdateEntityByIdParamsSchema` | `EntityResourceSchema` | Usa un comando separado si el payload difiere del PUT. |
|
||
| DELETE | `/entities/:id` | Eliminar por ID | `DeleteEntityByIdParamsSchema` | — (204 No Content) **o** `EntityDeletedResponseSchema` | 204 recomendado. Si devuelves body, usa `EntityDeletedResponseSchema`. |
|
||
|
||
---
|
||
|
||
## Esquemas reutilizables (Responses)
|
||
|
||
- **Item para listados:**
|
||
`EntitySummarySchema`
|
||
|
||
- **Recurso completo:**
|
||
`EntityResourceSchema`
|
||
|
||
- **Respuestas compuestas:**
|
||
- `EntityListResponseSchema` → `data: EntitySummarySchema[]` + paginación/meta
|
||
- `EntityDetailResponseSchema` → típicamente `EntityResourceSchema`
|
||
- `EntityCreatedResponseSchema` → `{ id, createdAt, ... }` si no devuelves el recurso completo
|
||
- `EntityDeletedResponseSchema` → `{ id, deleted: true }` si no usas 204
|
||
|
||
---
|
||
|
||
## Convenciones de sufijos
|
||
|
||
### Requests
|
||
- `...CommandSchema` → **body** (mutaciones)
|
||
- `...ParamsSchema` → **route params** (`/:id`)
|
||
- `...QuerySchema` → **query string** (`?page=...`)
|
||
- `...CriteriaSchema` → para queries normalizadas con patrón Criteria
|
||
|
||
### Responses
|
||
- `...ListResponseSchema` → listado paginado
|
||
- `...SummarySchema` → item de listado
|
||
- `...DetailResponseSchema` → detalle de recurso
|
||
- `...ResourceSchema` → representación completa del recurso
|
||
- `...CreatedResponseSchema` → recurso recién creado
|
||
- `...DeletedResponseSchema` → confirmación de borrado (si no usas 204)
|
||
|
||
# Ejemplos de nombres de Schemas por entidad
|
||
|
||
## 1. Customers
|
||
|
||
### Requests
|
||
- `CreateCustomerCommandSchema`
|
||
- `UpdateCustomerCommandSchema`
|
||
- `PatchCustomerCommandSchema`
|
||
- `DeleteCustomerByIdParamsSchema`
|
||
- `GetCustomerByIdParamsSchema`
|
||
- `CustomerListCriteriaSchema`
|
||
- `SearchCustomerQuerySchema`
|
||
|
||
### Responses
|
||
- `CustomerSummarySchema`
|
||
- `CustomerResourceSchema`
|
||
- `CustomerListResponseSchema`
|
||
- `CustomerDetailResponseSchema`
|
||
- `CustomerCreatedResponseSchema`
|
||
- `CustomerDeletedResponseSchema`
|
||
|
||
---
|
||
|
||
## 2. Products
|
||
|
||
### Requests
|
||
- `CreateProductCommandSchema`
|
||
- `UpdateProductCommandSchema`
|
||
- `PatchProductCommandSchema`
|
||
- `DeleteProductByIdParamsSchema`
|
||
- `GetProductByIdParamsSchema`
|
||
- `ProductListCriteriaSchema`
|
||
- `SearchProductQuerySchema`
|
||
|
||
### Responses
|
||
- `ProductSummarySchema`
|
||
- `ProductResourceSchema`
|
||
- `ProductListResponseSchema`
|
||
- `ProductDetailResponseSchema`
|
||
- `ProductCreatedResponseSchema`
|
||
- `ProductDeletedResponseSchema`
|
||
|
||
---
|
||
|
||
## Notas
|
||
- Reutilizar esquemas básicos (`EntitySummarySchema`, `EntityResourceSchema`) en respuestas compuestas para cumplir el principio **DRY**.
|
||
- **Sufijos**: mantener siempre los sufijos `CommandSchema`, `ParamsSchema`, `QuerySchema`, `CriteriaSchema`, `ListResponseSchema`, `SummarySchema`, `DetailResponseSchema`, `ResourceSchema`, `CreatedResponseSchema`, `DeletedResponseSchema`.
|
||
- **Pluralización**: usar singular para el nombre de la entidad en los Schemas (ej. `Customer`, `Product`), incluso si la ruta es plural (`/customers`, `/products`).
|
||
- **Carpetas sugeridas**:
|
||
modules/
|
||
<entity>/
|
||
application/
|
||
dto/
|
||
requests/
|
||
responses/
|
||
domain/
|
||
infrastructure/
|
||
api/
|