Desarrollo de Servicios – Estándares de Codificación¶

Guías globales aplicables a todos los servicios y lenguajes.

Configuración de ambiente¶

Principios¶

Nunca usar valores hardcodeados para configuraciones.
Siempre usar variables de entorno.
Nunca incluir secretos en el código ni en control de versiones.

Flujo de variables¶

.env (desarrollo local - NO en git)
    ↓
Ambiente de ejecución (Dev, Staging, Prod)
    ↓
Aplicación lee variables
    ↓
Módulo config centralizado
    ↓
Servicios usan ConfigService (u equivalente)

Cada servicio: - Tiene su propio env.example documentando solo lo que usa. - Usa un módulo de configuración centralizado (ej. src/config/configuration.ts en NestJS).

El dev-env: - Centraliza todas las variables en config/env.example. - Copia a .env en make init.

Nunca crear .env.production, .env.test, etc.; las variables reales vienen del ambiente.

Nomenclatura y convenciones¶

Variables y constantes¶

Nombres en castellano con significado claro (nombreUsuario, fechaCreacion, estadoActivo).
Constantes en SCREAMING_SNAKE_CASE (TIEMPO_ESPERA_MAXIMO, PUERTO_SERVIDOR).

Funciones¶

Verbo + sustantivo en castellano (obtenerUsuario, crearProducto, validarEmail).

Clases/Tipos¶

PascalCase (UsuarioServicio, RespuestaAPI, EstadoProducto).

Gestión de errores y códigos HTTP¶

Códigos estándar¶

2xx éxito (200, 201, 204).
4xx error del cliente (400, 401, 403, 404, 409, 422, 429).
5xx error del servidor (500, 502, 503).

Respuesta de error recomendada¶

{
  "exito": false,
  "codigo": "CODIGO_ERROR",
  "mensaje": "Descripción legible del error",
  "detalles": {
    "campo": ["Validación específica"]
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "id_solicitud": "req-12345-abcde"
}

Categorías de errores (ejemplos)¶

Validación: PARAMETROS_INVALIDOS, FORMATO_INCORRECTO, RANGO_INVALIDO.
Autenticación: NO_AUTENTICADO, TOKEN_EXPIRADO, TOKEN_INVALIDO.
Autorización: ACCESO_DENEGADO, PERMISOS_INSUFICIENTES.
Recurso: RECURSO_NO_EXISTE, USUARIO_NO_ENCONTRADO.
Negocio: RECURSO_DUPLICADO, ESTADO_INVALIDO, STOCK_INSUFICIENTE.
Servidor: ERROR_INTERNO, SERVICIO_EXTERNO_ERROR, TIMEOUT_EXTERNO.

Transacciones en conectables¶

Principio¶

Cada vez que se accede a un conectable (BD, API externa, etc.) se debe usar transacciones: o se aplican todas las operaciones o ninguna.

Patrón general¶

abrir transacción
try:
  operación 1
  operación 2
  confirmar
catch error:
  revertir
  registrar error
  lanzar excepción adecuada
finally:
  cerrar conexión

Ejemplo (NestJS/TypeORM) reducido:

async crearUsuarioConPerfil(dto: CreateUsuarioDto) {
  const queryRunner = this.dataSource.createQueryRunner();
  await queryRunner.connect();
  await queryRunner.startTransaction();
  try {
    const usuario = await queryRunner.manager.save(Usuario, dto);
    const perfil = await queryRunner.manager.save(Perfil, { usuarioId: usuario.id });
    await queryRunner.commitTransaction();
    return { usuario, perfil };
  } catch (error) {
    await queryRunner.rollbackTransaction();
    throw error;
  } finally {
    await queryRunner.release();
  }
}

Validación y seguridad¶

Validar datos de entrada en los límites (Controllers/Resolvers).
Usar DTOs y validación declarativa (ej. class-validator).
Registrar errores con logs estructurados (nivel, contexto, correlación).
Jamás loguear secretos o datos sensibles en texto plano.