CommunityProgramación y desarrollogithub.com

Backend Silk: estándares compartidos de backend

Estándares de ingeniería compartidos para proyectos backend y API en Python (Flask, FastAPI, Django, FastMCP) y Node.js (Express). Cubre estructura de proyecto, capas de rutas, helpers y servicios, reglas de código basado en clases, manejo de errores y códigos de estado, casos extremos, logging, configuración .env, autenticación y propiedad de datos, comunicación entre repositorios, higiene de Git y pruebas.

¿Qué es Backend Silk: estándares compartidos de backend?

Backend Silk define un conjunto de principios y estándares compartidos para construir backends de producción en Python y Node.js. Su objetivo principal es evitar dos fallos comunes: estructura incorrecta (lógica en la capa equivocada, archivos innecesarios) y sobre-ingeniería (abstracciones prematuras). También previene un tercer fallo silencioso: cambios o refactorizaciones que eliminan comportamiento existente sin darse cuenta. El skill organiza el código en capas claras: rutas (routes), ayudantes (helpers), servicios (services) y utilidades (utils), con reglas estrictas de direccionalidad (las rutas llaman a helpers, los helpers llaman a servicios, nunca al revés). También impone normas como usar clases para helpers y servicios, mantener funciones de ~40–50 líneas, validar esquemas Pydantic una sola vez, y evitar código muerto. Además, proporciona guías detalladas para logging, configuración segura con .env, manejo de errores con códigos de estado HTTP correctos, y comunicación entre repositorios. Soporta múltiples frameworks (Flask, FastAPI, Django, FastMCP, Express) y se complementa con skills "spider" específicos para cada framework.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VivekShevale/eight-eye/tree/HEAD/skills/backend/backend-silk

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace Backend Silk: estándares compartidos de backend?

Actúa como un ingeniero senior de backend en Python que escribe código simple y de producción. Los dos fallos que este skill existe para prevenir son estructura incorrecta (lógica en la capa equivocada, archivos que nadie necesita) y sobre-ingeniería (abstracciones antes de tener una app funcionando). Un tercer fallo, más silencioso, es igual de costoso: un cambio o refactorización que elimina silenciosamente un comportamiento que solía funcionar.

Skills complementarios

Nomenclatura: los skills *-spider construyen un tipo específico de proyecto; los skills *-silk son los estándares compartidos que cada spider teje. Este skill contiene los principios compartidos por todos los backends. Carga también los complementos correspondientes:

SituaciónUsar también
Proyecto Flask / FastAPI / Djangoflask-spider / fastapi-spider / django-spider
Proyecto Node.js / Expressnode-spider (las reglas aquí aplican; los ejemplos de código son Python)
Servidor MCP o cliente MCPmcp-spider
PostgreSQL, MySQL, SQLite (SQLAlchemy, Django ORM)sql-silk
MongoDBmongodb-silk
LLM, embeddings, vector store, RAGrag-spider

Los skills de framework deciden la mecánica del framework; este skill decide los principios. Si parecen conflictivos, sigue el skill de framework para la sintaxis y este skill para la estructura.

Antes de modificar código

  1. Lee el código real primero. Revisa la estructura de carpetas, modelos, configuración y el archivo que estás a punto de modificar. Nunca adivines un nombre de campo, firma de función, nombre de archivo o ruta de importación; léelo. (Una date adivinada en lugar de la real expense_date rompió esquema, helper y respuesta de una sola vez.) Cuando no estés seguro de cómo funciona una librería instalada, consulta su API real en lugar de asumir.
  2. Decide las rutas primero. Para una funcionalidad, enumera cada endpoint (método, ruta, request, response, códigos de estado, autenticación) antes de implementar.
  3. El alcance proviene del requisito. Construye lo que la declaración del problema necesita. Endpoints extra, analíticas, caché, limitación de tasa, re-ranking, seguimiento de costos, endpoints de descarga/búsqueda que nadie pidió: menciónalos en una línea como "posible más adelante", no los construyas.
  4. Preserva el comportamiento funcional. Al reescribir una función, enumera lo que hace ahora (filtros, paginación, validación, logging, campos de respuesta) y asegúrate de que la nueva versión todavía lo haga todo.

Capas

rutas -> ayudantes -> servicios -> base de datos / sistemas externos
            |            |
         utilidades  utilidades
CarpetaPoseeNo debe contener
routes/ (blueprints de Flask, routers de FastAPI, views.py + urls.py de Django, tools/ de MCP)URL, método, dependencia/decorador de autenticación, código de estado, modelo de respuesta, una llamada a un helperLógica de negocio, consultas, código de validación, try/except, logging
helpers/Lógica de negocio para una funcionalidad, como un controlador: validación más allá del esquema, comprobaciones de propiedad, consultas y filtros específicos de la funcionalidad, orquestación de servicios, mapeo de fallos esperados a errores HTTP, construcción de la respuestaAbrir/cerrar sesiones de BD, commit/rollback, crear clientes LLM o SDK
services/Un sistema externo o pieza de infraestructura cada uno: conexión a BD y CRUD genérico (db_service.py), LLM, embeddings, vector store, PDF, email, API de otro repositorioReglas de negocio específicas de la funcionalidad, conocimiento HTTP (HTTPException, códigos de estado), llamadas a helpers
utils/Código basado en clases reutilizado por varios módulos: LogUtils, ErrorHandlers, AuthUtils, convertidores purosCódigo usado por una sola funcionalidad, llamadas a APIs externas
schemas/Modelos de request/response de Pydantic (Django: serializers.py)Modelos de BD
models/Modelos de persistenciaLógica de negocio
prompts/Plantillas de prompts como código (solo cuando se usa un LLM)Prompts en .env
config.pyUn objeto de configuración cargado desde .envLógica

Reglas que se derivan de la tabla:

  • La dirección es unidireccional. Las rutas llaman a helpers, los helpers llaman a servicios. Un servicio nunca llama a un helper; una utilidad nunca llama a un helper.
  • División de base de datos. El helper construye consultas de funcionalidad (filtros, búsqueda, propiedad); el servicio de BD las ejecuta y posee la conexión, sesión, commit y rollback. Detalles en sql-silk / mongodb-silk. Con Django, el ORM es la capa de BD, por lo que no hay db_service.
  • Sin capas de paso directo. Si un helper solo reenvía a un servicio, elimina el helper y llama al servicio. Cada archivo debe ganarse su lugar.
  • Utils vs helpers. Usado en muchos lugares → utils/. Usado por una funcionalidad → el helper de esa funcionalidad.
  • Crea carpetas y archivos cuando aparezca una necesidad real, no por adelantado. Una función nunca justifica una nueva carpeta (errors/, exceptions.py, core/); agrégala a la clase existente que corresponda.
  • Nomenclatura: <dominio>_routes.py (que contiene <dominio>_router, o <dominio>_bp en Flask), <dominio>_helper.py → XHelper, <dominio>_service.py → XService, <dominio>_schema.py, <dominio>_utils.py → XUtils, <nombre>_prompt.py → NOMBRE_PROMPT. El nombre de una clase siempre coincide con su carpeta (una class ExpenseService dentro de helpers/ es incorrecto).

Roles completos de carpetas y árboles iniciales: references/architecture.md.

Reglas de código

  1. Módulos basados en clases. Los helpers, servicios y utilidades son clases. Usa @staticmethod/@classmethod para código sin estado e instancias solo cuando la clase contenga una dependencia (por ejemplo, una sesión o cliente inyectado). Los archivos de rutas y urls.py de Django se mantienen a nivel de módulo. No fuerces herencia, clases base abstractas o interfaces sin dos implementaciones reales.
  2. Las funciones se mantienen alrededor de 40–50 líneas. Divide una función larga en métodos significativos de la misma clase (por ejemplo, list_expenses → parse_filter_parameters + apply_expense_filters), no en fragmentos arbitrarios.
  3. Ningún nombre de función que comience con _. Ninguna función definida dentro de otra función. Registra manejadores con llamadas explícitas como app.add_exception_handler(...) en lugar de funciones decoradas anidadas.
  4. Todas las importaciones al principio del archivo, agrupadas stdlib → terceros → app.*. Corrige importaciones circulares moviendo el código al módulo correcto, no importando dentro de funciones. La única excepción aceptada son las importaciones de blueprints de Flask dentro de create_app().
  5. Usa librerías establecidas en lugar de lógica escrita a mano: password-validator, email-validator/EmailStr, PyJWT, bcrypt, cargadores y divisores de LangChain, httpx.
  6. Valida una sola vez. Si el esquema de Pydantic ya impone una regla, no la vuelvas a comprobar en el helper.
  7. No calcules lo mismo dos veces en una solicitud, y falla rápido. Realiza comprobaciones baratas antes que las costosas (comprobación de email duplicado antes del hash bcrypt).
  8. Sin configuración hardcodeada: URLs, nombres de modelo, límites, top_k, temperatura y secretos provienen de config.py.
  9. Sin código muerto: funciones no utilizadas, importaciones no utilizadas, archivos placeholder vacíos y restos de startapp se eliminan.
  10. Type hints y un docstring de una línea en cada clase y método público. Comentarios solo donde la razón no sea obvia.
  11. Nunca tragues excepciones. Captura excepciones específicas donde puedas actuar sobre ellas; deja que el resto llegue al manejador global.

Verificación de sobre-ingeniería

Antes de agregar un archivo, clase, capa, dependencia o patrón, pregúntate: ¿el requisito actual lo necesita, y ya existe algo que lo haga? Todo esto se construyó y luego se eliminó:

  • pydantic-settings o frameworks de validación antes de que la app se ejecute (una dataclass congelada de configuración es suficiente)
  • un nuevo módulo o clase de excepción para un solo error
  • helpers que solo llaman a un servicio
  • pares de claves RS256 entre dos servicios que posees (un secreto compartido HS256 es suficiente)
  • valores derivados almacenados (total_tokens cuando existen input + output)
  • dos colecciones o tablas cuando una con una lista incrustada funciona
  • prompts largos y descripciones largas de herramientas

Cuando varios diseños funcionen, elige el más simple que siga siendo seguro para producción.

Esquemas de solicitud y respuesta (resumen)

  • Cada endpoint valida su cuerpo y parámetros de consulta con un esquema de solicitud que rechaza campos desconocidos y campos propiedad del servidor; el código posterior a la validación usa solo el objeto validado.
  • Cada respuesta exitosa se construye a partir de un esquema de respuesta: el recurso en sí (XResponse), una lista {"items", "page", "page_size", "total", "total_pages"}, o un esquema de resultado de acción (TokenResponse). Sin envoltorio, sin literales de objeto ensamblados en el manejador.
  • Los códigos de estado indican éxito y fracaso: 200 lectura/actualización, 201 creación, 204 eliminación sin cuerpo, errores con ErrorResponse. Nunca un fracaso con 200.

Contrato completo y dónde viven los esquemas por framework: references/api-design.md.

Errores (resumen)

  • Cada respuesta de error tiene una forma, desde assets/common_schema.py: {"status": "error", "message": "...", "details": [{"field": "...", "message": "..."}]} (details solo cuando hay errores de campo)
  • Los servicios lanzan excepciones simples o de librería; los helpers lanzan errores HTTP para casos esperados; una clase ErrorHandlers en utils/error_handlers.py mapea errores de dependencia y captura todo lo demás como 500.
  • Códigos de estado: 400 entrada incorrecta, 401 no autenticado, 404 faltante o registro de otro usuario, 409 duplicado, 413 demasiado grande, 422 validación de esquema, 424 dependencia propia caída (base de datos, vector store), 429 límite de tasa upstream, 502 upstream devolvió un error, 503 otro servicio inalcanzable, 504 timeout upstream, 500 inesperado. Nunca 200 para un fracaso.
  • Los usuarios ven un mensaje corto y seguro, nunca un traceback, host, cadena de conexión o clave.

Lista de verificación de casos extremos y patrones de manejador: references/errors-and-edge-cases.md. Llamadas entre repositorios: references/cross-repo-communication.md.

Logging (resumen)

Una clase LogUtils (assets/log_utils.py) configurada una vez al inicio desde LOG_LEVEL y LOG_TO_FILE en .env; cada otro módulo solo hace logger = LogUtils.get_logger(__name__). Formato %(asctime)s | %(levelname)s | %(name)s | %(message)s, mensajes como Evento | clave=valor, sin secretos ni datos personales, cada fracaso registrado una vez. Detalles: references/logging.md.

Configuración y seguridad (resumen)

  • config.py con una dataclass congelada cargada desde .env (assets/config.py); .env.example confirmado con placeholders y comentarios (assets/env.example), .env nunca confirmado (assets/gitignore).
  • Contraseñas: política de password-validator solo en el registro, hashing bcrypt/werkzeug, mensaje genérico "Email o contraseña inválidos." en el inicio de sesión.
  • JWT: secreto de .env, id de usuario tomado solo del token verificado, nunca del cuerpo de la solicitud.
  • Cada consulta está limitada al usuario actual; los registros de otros usuarios devuelven 404.

Detalles: references/security.md. Convenciones de API (métodos, paginación, filtrado, parámetros de búsqueda): references/api-design.md.

Git y pruebas (resumen)

  • Nunca confirmado: .env, claves, credenciales, subidas, datos vectoriales, bases de datos locales, logs, entornos virtuales, informes generados. Las migraciones se confirman con el cambio de modelo que las produjo.
  • Los mensajes de commit siguen Conventional Commits (feat:, fix:, refactor:, chore:, test:, docs:, perf:), un asunto por commit, un commit por repositorio.
  • Las pruebas cubren caminos críticos: autenticación, propiedad entre usuarios, validación, respuestas de error, fallos de dependencia (simulados). Los servicios externos (LLMs, otros repos) se simulan.
  • Evaluaciones (golden datasets, scripts de evaluación, informes) solo existen cuando se solicitan explícitamente; ver rag-spider / mcp-spider.

Detalles: references/git-and-testing.md.

Lista de verificación de código

  • Capas respetadas; ningún archivo de paso directo; nombres de clases coinciden con carpetas
  • Sin funciones con guión bajo al inicio o anidadas; importaciones al principio; funciones ≤ ~50 líneas
  • Comportamiento existente preservado (filtros, paginación, validación, campos de respuesta)
  • Cada endpoint tiene un esquema de solicitud y un esquema de respuesta; sin objetos de respuesta ad-hoc
  • Casos extremos de references/errors-and-edge-cases.md manejados con códigos de estado correctos
  • Nuevas configuraciones en config.py y .env.example; nada hardcodeado; sin secretos en código o logs
  • Logging agregado donde corresponde, en el nivel correcto
  • Sin importaciones no utilizadas ni código muerto dejado atrás

Archivos de referencia (leer solo cuando sea necesario)

ArchivoLeer cuando
references/architecture.mdCrear un proyecto, agregar una carpeta de funcionalidad, no estar seguro de dónde pertenece el código
references/errors-and-edge-cases.mdEscribir endpoints, manejadores de errores, o revisar caminos de fallo
references/cross-repo-communication.mdUn servicio llama a otro repositorio, servidor MCP, o API externa
references/logging.mdConfigurar o revisar logging
references/security.mdAutenticación, contraseñas, JWT, subidas, secretos, CORS
references/api-design.mdDiseñar endpoints, esquemas de solicitud/respuesta, paginación, filtros, búsqueda
references/git-and-testing.mdCommits, descripciones de PR, qué nunca se confirma, pruebas, enfoque de depuración

Archivos de activos (copiar al proyecto y adaptar)

Copia las plantillas de forma selectiva: conserva solo las partes que este proyecto usa ahora (secciones de .gitignore, claves de .env.example, campos de configuración). Las líneas sobrantes para funcionalidades que el proyecto no tiene son basura y confunden al próximo lector.

ArchivoSe convierte en
assets/log_utils.pyapp/utils/log_utils.py
assets/common_schema.pyapp/schemas/common_schema.py
assets/config.pyapp/config.py
assets/env.example.env.example
assets/gitignore.gitignore (la sección "Siempre" más solo las secciones marcadas que apliquen)

Skills relacionados