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
ctxcomo 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.Contexten 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
%wy 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.Isyerrors.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.ErrNoRowses un resultado de dominio, no un fallo. Mapeelo al "no encontrado" del dominio en el borde del repositorio para que el servicio nunca importedatabase/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.