CommunityProgramación y desarrollogithub.com

sk-go-service

Implementar, extender o depurar un handler, servicio o repositorio en un backend Go, cubriendo propagación de contexto, envoltura de errores, transacciones, alcance multiinquilino y pruebas basadas en tablas.

¿Qué es sk-go-service?

Esta habilidad guía a un agente de IA —como Claude Code, Cursor o Codex— cuando trabaja con un backend Go en capas, típicamente un servicio web con handlers, servicios y repositorios. Está diseñada para mantener corrección bajo concurrencia y multi-tenencia, asegurando que el código producido sea consistente con las convenciones del proyecto existente. La habilidad cubre tareas como propagar el contexto a través de la pila de llamadas, envolver errores con `%w` para preservar la cadena de errores, manejar transacciones de base de datos en la capa correcta (nunca en el repositorio), aplicar filtros de inquilino en cada consulta, gestionar correctamente goroutines con tiempos de vida conocidos, y escribir pruebas de tabla con nombres descriptivos de comportamiento. También incluye pasos de verificación previa como comprobar la versión de Go en `go.mod` y ejecutar `golangci-lint` antes de finalizar. Funciona en cualquier plataforma que pueda ejecutar comandos de terminal (shell) y procesar archivos Go, como Claude Code, Cursor, Codex y Gemini Code Assist, y se activa cuando el usuario pide agregar un endpoint, modificar una consulta de repositorio, o diagnosticar un panic, fuga de recursos o test inestable en un servicio Go.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-go-service

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

Trabajo con servicios Go

Convenciones que mantienen un servicio Go en capas correcto bajo concurrencia y multi-tenencia. Lea primero el paquete circundante —un patrón local que se aplica de manera consistente prevalece sobre cualquier cosa aquí.

Antes de escribir código

Verifique la cadena de herramientas. go.mod determina qué características de la biblioteca estándar y del lenguaje están disponibles, y los servicios en el mismo espacio de trabajo a menudo se basan en diferentes versiones. Una captura de variable de bucle es un error real por debajo de Go 1.22 y no es un problema por encima; errors.Join, slices y maps requieren 1.21. Lea la versión en lugar de asumir la más reciente.

Luego encuentre la capa que posee la decisión que está a punto de cambiar. Los handlers traducen el transporte al dominio y nada más. Los servicios toman la decisión. Los repositorios realizan la consulta. Una validación agregada en el handler es invisible para todos los demás llamadores del servicio.

Contexto

El contexto pertenece a la solicitud y muere con ella.

  • Pase ctx como primer parámetro, hasta la llamada a la base de datos. Una función que no recibe contexto no puede cancelarse y no puede llevar un plazo.
  • Nunca almacene un context.Context en un campo de estructura.
  • Nunca entregue un contexto de solicitud a una goroutine que sobreviva al handler. El trabajo en segundo plano independiente necesita su propio contexto con su propio tiempo de espera, y los valores que necesita deben copiarse explícitamente antes de que el handler retorne.
  • Lo mismo aplica a cualquier manejador derivado de la solicitud —una transacción, una conexión, un accesor de base de datos con alcance de solicitud. Usar uno después de que el handler retorna es un use-after-free con un mensaje de error más amigable.

Errores

  • Envuelva con %w y agregue lo que el llamador no puede saber ya: el identificador, la operación. fmt.Errorf("cargar orden %d: %w", id, err). No prefije con el nombre de la función; una pila de estos se lee como ruido.
  • Compare con errors.Is y errors.As. Un == directo se rompe en el momento en que alguien envuelve.
  • Traduzca a un estado de transporte exactamente en un lugar, en el límite del handler. Un repositorio que devuelve un código HTTP ha filtrado dos capas.
  • sql.ErrNoRows es un resultado de dominio, no un fallo. Mapeelo al "no encontrado" del dominio en el borde del repositorio para que el servicio nunca importe database/sql.
  • Nunca descarte un error para satisfacer al compilador. Si es genuinamente ignorable, asígnelo a _ con un comentario que explique por qué.

Transacciones

Abra la transacción en la capa que posee el invariante —generalmente el servicio, nunca el repositorio, porque un repositorio que abre su propia transacción no puede ser compuesto en una más grande. Pase el manejador de la transacción hacia abajo.

Confirme y revierta en cada ruta, incluido el pánico. El rollback después de un commit exitoso debe ser inofensivo; eso es lo que hace seguro defer tx.Rollback().

No haga E/S dentro de una transacción que no necesite ser atómica con ella. Una llamada HTTP a un proveedor de pago dentro de una transacción abierta mantiene bloqueos de base de datos durante la duración de la interrupción de otra persona.

Multi-inquilino

Si el servicio es multi-inquilino, el identificador del inquilino se aplica en el código, no en la base de datos. Cada consulta del repositorio —lectura y escritura— lleva el predicado del inquilino. Una consulta que filtra solo por clave primaria devolverá felizmente la fila de otro inquilino. Derive el identificador del accesor de contexto de solicitud que el código base ya usa, y verifique cuál accesor es correcto: un servicio que actúa en nombre de un subinquilino generalmente tiene dos, y el obvio a menudo es el incorrecto.

Goroutines

Cada goroutine necesita una vida conocida y un propietario conocido. Antes de escribir go, responda: quién espera por ella, cómo se detiene, y dónde va su error. Una goroutine cuyo error se descarta es una falla silenciosa.

Use errgroup cuando el llamador espera. Use un sync.WaitGroup explícito más un canal de errores recolectado cuando no encaja. Un go f() simple en el manejo de solicitudes es casi siempre un defecto.

Pruebas

Basadas en tablas, un t.Run por caso, nombrado por el comportamiento en lugar de la entrada. Cada caso indica su entrada, su expectativa, y nada más; la configuración compartida por cada caso pertenece arriba de la tabla.

Siempre pase un tiempo de espera al ejecutarlas:

go test -count=1 -timeout 60s ./...

-count=1 elimina la caché de resultados, que de otro modo informa un pase para código que acaba de cambiar. El tiempo de espera importa más de lo que parece: una prueba bloqueada sin tiempo de espera consume memoria hasta que la máquina se detiene.

Pruebe el comportamiento exportado del paquete. Una prueba que accede a internos no exportados bloquea la implementación y falla en cada refactor honesto.

Cuando una prueba es inestable, está reportando una carrera real la mayoría de las veces. Ejecútela bajo -race antes de concluir lo contrario, y nunca la arregle agregando un sleep.

Antes de dar por terminado

Ejecute la prueba más estrecha que cubra el cambio, luego amplíe si un contrato compartido se movió. Ejecute golangci-lint run en el servicio en lugar de un objetivo make que pueda tragar el código de salida. Reporte los fallos con su salida en lugar de debilitar la prueba.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

Skills relacionados