Reglas de Diseño de API para Bibliotecas de Go
Nomenclatura, devoluciones de errores, contexto como primer parámetro y cambios que rompen la compatibilidad.
//
Busca en todas las páginas de la documentación
Nomenclatura, devoluciones de errores, contexto como primer parámetro y cambios que rompen la compatibilidad.
Referencia densa para autores que publican bibliotecas de Go: escanee antes de exportar nuevos símbolos o etiquetar una versión.
go vet, comprobaciones de API de staticcheck y etiquetas semver.| Regla | Hacer | Evitar | Razón |
|---|---|---|---|
| Nombre del paquete | Corto, minúsculas, sin guiones bajos (httpclient) | common, util, misc | Legibilidad de la ruta de importación |
| Nombre exportado | MixedCaps, sin tartamudeo (user.UserID) | user.UserUserID | Claridad en pkg.go.dev |
| Getter | Name() en lugar de GetName() | Estilo Java Get* en campos simples | Convención de Go |
| Nombre de interfaz | Sufijo -er cuando hay un solo método (Reader) | IReader | Interfaces idiomáticas |
| Acrónimos | Mayúsculas consistentes (HTTP, ID, URL) | Http, Id | Alineación con golint/revive |
| Variables de error | Centinelas exportados con prefijo Err | Estilos mixtos ErrorNotFound | Ergonomía de errors.Is |
| Regla | Hacer | Evitar | Razón |
|---|---|---|---|
| Contexto | func F(ctx context.Context, ...) primero | context en medio de los parámetros | Propagación de cancelación |
| Opciones | Opciones funcionales o struct de configuración | Listas largas de parámetros posicionales | APIs compatibles con versiones futuras |
| Devoluciones | Structs/punteros concretos | Interfaces no exportadas en devoluciones | Claridad del tipo del llamador |
| Parámetros | Interfaces pequeñas en el punto de llamada | Exportar Interface amplias en el paquete productor | Segregación de interfaces |
| Nil | Documentar el comportamiento nil | Pánico en nil sin documentación | Bibliotecas predecibles |
| Tiempo | time.Time / time.Duration en APIs | int64 en bruto sin unidades | Ambigüedad en APIs públicas |
| Regla | Hacer | Evitar | Razón |
|---|---|---|---|
| Errores | Devolver error al final | Pánico para fallos esperados | Control del llamador |
| Envoltorio | fmt.Errorf("op: %w", err) | Cadenas opacas errors.New | Inspección con Is/As |
| Centinelas | var ErrX = errors.New(...) estables | Comparación de cadenas en Error() | Clientes frágiles |
| Registro | Dejar que la aplicación registre | log.Printf de la biblioteca en errores | Acoplamiento de importación |
| Métricas | Hooks/interfaces opcionales | Prometheus codificado | Peso de la dependencia |
| Regla | Hacer | Evitar | Razón |
|---|---|---|---|
| Etiqueta Semver | v1.2.3 en etiquetas de módulo | Etiquetas git ad-hoc | Resolución de go get |
| Cambio que rompe la compatibilidad | Salto mayor / nueva ruta de módulo | Renombrar exportaciones en un parche | Ruptura para el consumidor |
| Obsoleto | // Deprecated: use X + problema | Eliminación silenciosa | Tiempo de migración |
| Experimental | v0 o internal/ hasta que sea estable | v1 con cambios frecuentes | Establecimiento de expectativas |
| go.mod | Directiva go coincide con CI | Desfase entre módulos | Consistencia de la cadena de herramientas |
| Regla | Hacer | Evitar | Razón |
|---|---|---|---|
| Godoc | Frases completas en exportaciones | Comentarios vacíos o con nombre incorrecto | Calidad de pkg.go.dev |
| Ejemplos | Example* en example_test.go | Muestras solo en README | Documentación verificada por compilación |
| Pruebas | package foo_test para vista del consumidor | Solo pruebas de caja blanca | Señal de ergonomía de la API |
| Etiquetas de compilación | Documentar etiquetas de compilación de integración | Sorpresa //go:build en la API principal | go test del consumidor |
// Preferido: devolución concreta, opciones funcionales opcionales
type Client struct { /* ... */ }
type Option func(*Client)
func WithTimeout(d time.Duration) Option { /* ... */ }
func New(opts ...Option) (*Client, error) {
c := &Client{timeout: 30 * time.Second}
for _, o := range opts {
o(c)
}
return c, nil
}// Aceptar interfaces en los límites de integración
func RegisterHandler(mux ServeMux, h Handler) { /* ... */ }| Cambio | Impacto Semver | Ejemplo |
|---|---|---|
| Campo no exportado agregado | Parche | Seguro |
| Nueva función exportada | Menor | func ParseConfig |
| Cambio de firma de función exportada | Mayor | Cambio de tipo de parámetro |
| Eliminar símbolo exportado | Mayor | Eliminar LegacyDial |
| Corrección de comportamiento que rompe llamadores | Mayor o bandera de función | Validación más estricta |
Raramente.
Devuelva tipos concretos a menos que oculte intencionalmente la implementación detrás de un tipo de interfaz pequeño que usted defina.
No.
Acepte ctx de los llamadores; solo main de nivel superior o las pruebas crean raíces.
A menudo un método.
Los consumidores las definen; los productores devuelven structs.
Use valores centinela var ErrFoo.
La inspección estable supera la coincidencia de subcadenas en los mensajes.
Las opciones escalan para bibliotecas con muchos valores predeterminados.
Los structs de configuración funcionan cuando los campos son mayormente requeridos.
Use internal/ hasta que sea estable, o manténgase en etiquetas de módulo v0 con advertencias claras en README.
Póngalos en package foo_test o internal/testutil.
Evite ampliar la superficie semver para ayudantes solo de prueba.
Exporte parámetros de tipo claros con restricciones.
Evite exportar ayudantes excesivamente genéricos que oscurezcan los tipos.
Casi nunca en nombres exportados.
El nombre del paquete ya proporciona contexto (user.New no user.NewUser).
Agregue Deprecated en godoc, mantenga el símbolo, envíe el reemplazo, elimine en la próxima versión mayor.
Las bibliotecas deben usar ctx para cancelación/plazos.
Evite requerir claves de contexto privadas a menos que se documenten como puntos de extensión opcionales.
staticcheck SA1019 (obsoleto), comprobaciones de comentarios exportados (revive) y etiquetas de struct de vet.
Empareje con revisión humana para la forma.
Versiones de Stack: Esta página fue escrita para Go 1.26.x (GC por defecto Green Tea, modernizadores go fix - verificar parche en la compilación), chi (última versión - verificar en la compilación), gin (última versión - verificar en la compilación), echo (última versión - verificar en la compilación), google.golang.org/grpc (última versión - verificar en la compilación), sigs.k8s.io/controller-runtime (última versión - verificar en la compilación), kubebuilder (última versión - verificar en la compilación), tinygo (última versión - verificar objetivos de placa en la compilación), wazero (última versión - verificar en la compilación) y golangci-lint (última versión - verificar conjunto de linters en la compilación).
Revisado por Chris St. John·Última actualización: 16 jul 2026