Prácticas recomendadas de CGO e Interoperabilidad

Aísle cgo detrás de paquetes pequeños y pruebe en todos los destinos.

Estas reglas mantienen la interop nativa lista para producción: propiedad clara, compilaciones reproducibles y mecanismos de escape cuando se requiere CGO_ENABLED=0.

Cómo usar esta lista

• Aplique en la revisión del diseño antes de agregar import "C" a los paquetes de aplicaciones.
• Marque los elementos durante la revisión de PR para cualquier diferencia que toque unsafe, #cgo o archivos .so de proveedor.
• Ejecute CI tanto con CGO_ENABLED=1 como con CGO_ENABLED=0 cuando el módulo reclame compilaciones portátiles.
• Vincule las violaciones a linters (staticcheck, govulncheck) y excepciones documentadas en ADRs.

A - Límites de paquetes y APIs

• Confinar import "C" a un paquete interno por dependencia nativa. El código de la aplicación solo depende de tipos y errores de Go.
• Exponer funciones de Go estrechas, no tipos C.*, en los límites del módulo. Los llamadores no deben necesitar conocimiento de cgo para compilar.
• Proporcionar fallbacks //go:build !cgo o errores claros cuando cgo sea obligatorio. Las compilaciones de CI y cruzadas deben fallar ruidosamente, no comportarse mal silenciosamente.
• Fijar la versión de los SDK de proveedor en SBOM y README. Registre los nombres de .so, licencias y la matriz de SO/arquitectura compatibles.
• Evitar las funciones init que llaman a C. La inicialización diferida en el primer uso simplifica las pruebas y el orden de inicio.

B - Memoria, punteros y devoluciones de llamada

• Emparejar cada C.CString/C.CBytes con C.free en todas las rutas. Use defer inmediatamente después de que la asignación tenga éxito.
• Documentar la propiedad de los punteros devueltos por C. Copie en Go con C.GoString/C.GoBytes a menos que C retenga la propiedad por contrato.
• Nunca permita que C almacene punteros de Go más allá de una llamada sin fijación y alcanzabilidad. Copie en el heap de C cuando la vida útil se extienda de forma asíncrona.
• Proteger las devoluciones de llamada //export con mutexes o canales. Asuma que C llama desde hilos arbitrarios del SO.
• Use runtime.LockOSThread solo alrededor de la configuración de C local del hilo, no de los manejadores completos. Desbloquee rápidamente para preservar el rendimiento del planificador.

C - Rendimiento y fiabilidad

• Agrupar el trabajo para reducir los cruces de cgo en bucles activos. Perfile runtime.cgocall antes de micro-optimizar el código Go.
• Limitar la entrada concurrente de cgo con semáforos dimensionados a las CPU o a la documentación de la biblioteca. Evitar el crecimiento ilimitado de hilos del SO.
• Mantener las secciones de C cortas; trate el C largo como E/S bloqueante. Tiempos de espera en los límites de Go con contextos cuando sea posible.
• Ejecute código C bajo ASan/Valgrind en los harnesses de prueba nativos. Las pruebas de Go por sí solas no detectan desbordamientos de búfer de C.
• Recupere los pánicos dentro de las funciones //export. Los pánicos no capturados al cruzar el límite FFI abortan el proceso.

D - Compilación, CI y lanzamiento

• Documentar los paquetes CGO_CFLAGS, CGO_LDFLAGS y pkg-config para las imágenes de CI. Las compilaciones reproducibles superan a las rutas exclusivas del portátil.
• Probar las compilaciones de linux/arm64 y darwin al distribuir cgo. La compilación cruzada de cgo necesita bibliotecas y compiladores de destino.
• Distribuir imágenes de contenedor con las capas de libc/SDK requeridas documentadas. Las imágenes scratch necesitan variantes puras de Go o planes musl estáticos.
• Bloquear fusiones en go test ./... con cgo activado y desactivado cuando sea aplicable. Detectar etiquetas de compilación faltantes temprano.
• Prefiera los controladores puros de Go en las bibliotecas consumidas por otros. Los módulos descendentes heredan sus requisitos de cadena de herramientas de cgo.

E - Estrategia y alternativas

• Pruebe golang.org/x/sys y los puertos puros antes de nuevo cgo. Experiencia de consumidor más simple y superficie de ataque más pequeña.
• Elija RPC cuando el aislamiento de fallos o el lanzamiento independiente superen la latencia de microsegundos. Registre la decisión en un ADR.
• Planifique rutas wasm sin cgo para destinos de navegador/WASI. Etiquete los archivos import "C" con !wasm.
• Revise las opciones de interop anualmente a medida que maduran las bibliotecas estándar y los puertos de la comunidad. El cgo de ayer puede ser el Go puro de hoy.
• Mida la latencia de extremo a extremo antes de comprometerse con cgo en proceso. El estilo de integración importa más que los nanosegundos de cruce.

Preguntas frecuentes

Relacionado

• CGO: Cruzando el Límite Go-C - Modelo mental y compensaciones
• Seguridad FFI: Punteros, C.CString y Free - Reglas de propiedad
• Rendimiento de CGO e Interacciones del Planificador - Límites de hilos y latencia
• Guía de Decisiones de Interoperabilidad: CGO vs RPC vs Reescribir - Estrategia antes de la implementación
• Fundamentos de CGO - Ejemplos de inicio ejecutables

Versiones de pila: Esta página fue escrita para Go 1.26.x (predeterminado Green Tea GC, go fix modernizers - verifique el parche en la compilación), chi (última versión - verifique en la compilación), gin (última versión - verifique en la compilación), echo (última versión - verifique en la compilación), google.golang.org/grpc (última versión - verifique en la compilación), sigs.k8s.io/controller-runtime (última versión - verifique en la compilación), kubebuilder (última versión - verifique en la compilación), tinygo (última versión - verifique los objetivos de la placa en la compilación), wazero (última versión - verifique en la compilación) y golangci-lint (última versión - verifique el conjunto de linters en la compilación).