Evite que los errores aumenten con este nuevo marco

La gestión de errores en Go es sencilla y flexible, ¡pero no tiene estructura! Se supone que es simple, ¿no? Solo hay que devolver un error , envuelto en un mensaje, y seguir adelante. Bueno, esa simplicidad rápidamente se vuelve caótica a medida que nuestra base de código crece con más paquetes, más desarrolladores y más "soluciones rápidas" que permanecen allí para siempre. Con el tiempo, los registros se llenan de "no se pudo hacer esto" y "no se esperaba eso", y nadie sabe si es culpa del usuario, del servidor, un código con errores o simplemente una desalineación de las estrellas. Los errores se crean con mensajes inconsistentes. Cada paquete tiene su propio conjunto de estilos, constantes o tipos de error personalizados. Los códigos de error se agregan de manera arbitraria. ¡No hay una manera sencilla de saber qué errores pueden devolverse de qué función sin investigar su implementación! Por eso, acepté el desafío de crear un nuevo marco de trabajo de errores. Decidimos optar por un sistema estructurado y centralizado que utilice códigos de espacio de nombres para que los errores sean significativos, rastreables y, lo más importante, ¡nos brinden tranquilidad! Esta es la historia de cómo empezamos con un enfoque de gestión de errores simple, nos frustramos muchísimo a medida que los problemas crecían y finalmente creamos nuestro propio marco de trabajo de errores. Las decisiones de diseño, cómo se implementó, las lecciones aprendidas y por qué transformó nuestro enfoque de gestión de errores. ¡Espero que también te sirva de ideas! Los errores de Go son solo valores Go tiene una forma sencilla de manejar los errores: los errores son simplemente valores. Un error es simplemente un valor que implementa la interfaz con un único método . En lugar de lanzar una excepción e interrumpir el flujo de ejecución actual, las funciones de Go devuelven un valor junto con otros resultados. El invocador puede decidir cómo manejarlo: verificar su valor para tomar una decisión, envolver con nuevos mensajes y contexto, o simplemente devolver el error, dejando la lógica de manejo para los invocadores principales. error Error() string error Podemos convertir cualquier tipo en un si le añadimos el método . Esta flexibilidad permite que cada paquete defina su propia estrategia de gestión de errores y elija la que mejor se adapte a sus necesidades. Esto también se integra bien con la filosofía de componibilidad de Go, lo que facilita la inclusión, la ampliación o la personalización de errores según sea necesario. error Error() string Cada paquete necesita lidiar con los errores. La práctica habitual es devolver un valor de error que implementa la interfaz y permite que el emisor decida qué hacer a continuación. A continuación, se muestra un ejemplo típico: error func loadCredentials() (Credentials, error) { data, err := os.ReadFile("cred.json") if errors.Is(err, os.ErrNotExist) { return nil, fmt.Errorf("file not found: %w", err) } if err != nil { return nil, fmt.Errorf("failed to read file: %w", err) } cred, err := verifyCredentials(cred); if err != nil { return nil, fmt.Errorf("invalid credentials: %w", err) } return cred, nil } Go proporciona un puñado de utilidades para trabajar con errores: y para generar errores simples. Creación de errores: errors.New() fmt.Errorf() envuelva los errores con contexto adicional utilizando y el verbo . Envoltura de errores: fmt.Errorf() %w fusiona varios errores en uno solo. Combinación de errores: errors.Join() hace coincidir un error con un valor específico, hace coincidir un error con un tipo específico y recupera el error subyacente. Comprobación y gestión de errores: errors.Is() errors.As() errors.Unwrap() En la práctica, solemos ver estos patrones: Devolver errores simples con o . Uso de paquetes estándar: errors.New() fmt.Errorf() por ejemplo, y definen variables de error reutilizables. Exportación de constantes o variables: go-redis gorm.io las bibliotecas como crean tipos de error especializados, a menudo con códigos asociados para contexto adicional. Tipos de error personalizados: lib/pq grpc/status.Error utiliza un enfoque basado en interfaz para definir tipos de error con varias implementaciones. Interfaces de error con implementaciones: aws-sdk-go como , que define múltiples interfaces para clasificar y gestionar errores. O múltiples interfaces: errdefs de Docker Comenzamos con un enfoque común En los primeros días, al igual que muchos desarrolladores de Go, seguimos las prácticas comunes de Go y mantuvimos el manejo de errores al mínimo, pero funcional. Funcionó bastante bien durante un par de años. Incluya stacktrace usando , un paquete popular en ese momento. pkg/errors Exportar constantes o variables para errores específicos del paquete. Utilice para comprobar errores específicos. errors.Is() Envuelva los errores con nuevos mensajes y contexto. Para los errores de API, definimos tipos de error y códigos con enumeración Protobuf. Incluyendo seguimiento de pila con pkg/errors Usamos , un paquete de manejo de errores popular en ese momento, para incluir stacktrace en nuestros errores. Esto fue particularmente útil para la depuración, ya que nos permitió rastrear el origen de los errores en diferentes partes de la aplicación. pkg/errors Para crear, encapsular y propagar errores con StackTrace, implementamos funciones como , y . Aquí hay un ejemplo de nuestra implementación inicial: Newf() NewValuef() Wrapf() type xError struct { msg message, stack: callers(), } func Newf(msg string, args ...any) error { return &xError{ msg: fmt.Sprintf(msg, args...), stack: callers(), // 👈 stacktrace } } func NewValuef(msg string, args ...any) error { return fmt.Errorf(msg, args...) // 👈 no stacktrace } func Wrapf(err error, msg string, args ...any) error { if err == nil { return nil } stack := getStack(err) if stack == nil { stack = callers() } return &xError{ msg: fmt.Sprintf(msg, args...), stack: stack, } } Exportación de variables de error Cada paquete de nuestra base de código definió sus propias variables de error, a menudo con estilos inconsistentes. package database var ErrNotFound = errors.NewValue("record not found") var ErrMultipleFound = errors.NewValue("multiple records found") var ErrTimeout = errors.NewValue("request timeout") package profile var ErrUserNotFound = errors.NewValue("user not found") var ErrBusinessNotFound = errors.NewValue("business not found") var ErrContextCancel = errors.NewValue("context canceled") y envoltura con contexto adicional Comprobación de errores con errors.Is() res, err := repo.QueryUser(ctx, req) switch { case err == nil: // continue case errors.Is(database.NotFound): return nil, errors.Wrapf(ErrUserNotFound, "user not found (id=%v)", req.UserID) default: return nil, errors.Wrapf(ctx, "failed to query user (id=%v)", req.UserID) } Esto ayudó a propagar errores con más detalles, pero a menudo resultó en verbosidad, duplicación y menos claridad en los registros: internal server error: failed to query user: user not found (id=52a0a433-3922-48bd-a7ac-35dd8972dfe5): record not found: not found Definición de errores externos con Protobuf Para las API externas, adoptamos un modelo de error basado en Protobuf inspirado en la : Graph API de Meta message Error { string message = 1; ErrorType type = 2; ErrorCode code = 3; string user_title = 4; string user_message = 5; string trace_id = 6; map details = 7; } enum ErrorType { ERROR_TYPE_UNSPECIFIED = 1; ERROR_TYPE_AUTHENTICATION = 2; ERROR_TYPE_INVALID_REQUEST = 3; ERROR_TYPE_RATE_LIMIT = 4; ERROR_TYPE_BUSINESS_LIMIT = 5; ERROR_TYPE_WEBHOOK_DELIVERY = 6; } enum ErrorCode { ERROR_CODE_UNSPECIFIED = 1 [(error_type = UNSPECIFIED)]; ERROR_CODE_UNAUTHENTICATED = 2 [(error_type = AUTHENTICATION)]; ERROR_CODE_CAMPAIGN_NOT_FOUND = 3 [(error_type = NOT_FOUND)]; ERROR_CODE_META_CHOSE_NOT_TO_DELIVER = 4 /* ... */; ERROR_CODE_MESSAGE_WABA_TEMPLATE_CAN_ONLY_EDIT_ONCE_IN_24_HOURS = 5; } Este enfoque ayudó a estructurar los errores, pero con el tiempo se agregaron tipos y códigos de error sin un plan claro, lo que generó inconsistencias y duplicaciones. Y los problemas crecieron con el tiempo. Se declararon errores en todas partes. Cada paquete definía sus propias constantes de error sin un sistema centralizado. Las constantes y los mensajes estaban dispersos en el código base, lo que hacía que no quedara claro qué errores podría devolver una función: ¿es o o ambos? gorm.ErrRecordNotFound user.ErrNotFound El error aleatorio de envoltura generó registros inconsistentes y arbitrarios Muchas funciones envolvieron errores con mensajes arbitrarios e inconsistentes sin declarar sus propios tipos de error. Los registros eran extensos, redundantes y difíciles de buscar o monitorear. Los mensajes de error eran genéricos y, a menudo, no explicaban qué había salido mal ni cómo había sucedido. Además, eran frágiles y propensos a cambios inadvertidos. unexpected gorm error: failed to find business channel: error received when invoking API: unexpected: context canceled La falta de estandarización condujo a un manejo inadecuado de los errores Cada paquete manejaba los errores de forma diferente, lo que hacía difícil saber si una función devolvía, envolvía o transformaba errores. A menudo se perdía el contexto a medida que se propagaban los errores. Las capas superiores recibieron vagos sin causas raíz claras. errores internos del servidor 500 No existe categorización que haga imposible el seguimiento Los errores no se clasificaron por gravedad o comportamiento: un error puede ser un comportamiento normal cuando el usuario cierra la pestaña del navegador, pero es importante si la solicitud se cancela porque esa consulta es aleatoriamente lenta. context.Canceled Los problemas importantes quedaron enterrados bajo registros ruidosos, lo que hizo que fuera difícil identificarlos. Sin categorización, era imposible monitorear eficazmente la frecuencia, la gravedad o el impacto de los errores. Es hora de centralizar la gestión de errores De vuelta a la mesa de dibujo Para abordar los desafíos crecientes, decidimos construir una mejor estrategia de error en torno a la idea central de . códigos de error centralizados y estructurados Los errores se declaran en todas partes → Centralice la declaración de errores en un solo lugar para una mejor organización y trazabilidad. Registros inconsistentes y arbitrarios → Códigos de error estructurados con formato claro y consistente. Manejo inadecuado de errores → tipo de con un conjunto integral de ayudantes. Estandarice la creación y verificación de errores en el nuevo Error Sin categorización → Clasifique los códigos de error con etiquetas para un monitoreo efectivo a través de registros y métricas. Decisiones de diseño Todos los códigos de error se definen en un lugar centralizado con estructura de espacio de nombres. Utilice espacios de nombres para crear códigos de error claros, significativos y ampliables. Ejemplo: para "Usuario no encontrado". PRFL.USR.NOT_FOUND para "Documento de flujo no encontrado". FLD.NOT_FOUND Ambos pueden compartir un código base subyacente , que significa "Registro no encontrado en PostgreSQL". DEPS.PG.NOT_FOUND . Cada capa de servicio o biblioteca solo debe devolver sus propios códigos de espacio de nombres Cada capa de servicio, repositorio o biblioteca declara su propio conjunto de códigos de error. Cuando una capa recibe un error de una dependencia, debe envolverlo con su propio código de espacio de nombres antes de devolverlo. Por ejemplo: cuando se recibe un error de una dependencia, el paquete "database" debe encapsularlo como . Luego, el servicio "profile/user" debe encapsularlo nuevamente como . gorm.ErrRecordNotFound DEPS.PG.NOT_FOUND PRFL.USR.NOT_FOUND . Todos los errores deben implementar la interfaz Error Esto crea un límite claro entre los errores de bibliotecas de terceros ( ) y nuestros internos. error Error Esto también ayuda al progreso de la migración, a separar entre paquetes migrados y aquellos que aún no se han migrado. Un error puede contener uno o varios errores, que juntos forman un árbol. [FLD.INVALID_ARGUMENT] invalid argument → [TPL.INVALID_PARAMS] invalid input params 1. [TPL.PARAM.EMPTY] name can not be empty 2. [TPL.PARAM.MALFORM] invalid format for param[2] Siempre requiere context.Context . Puede adjuntar contexto al error. Muchas veces vimos registros con errores independientes sin contexto, sin y no tenemos idea de dónde provienen. trace_id Se pueden adjuntar claves/valores adicionales a los errores, que se pueden usar en registros o en la monitorización. Cuando se envían errores a través del límite del servicio, solo se expone el código de error de nivel superior. Las personas que llaman no necesitan ver los detalles de implementación interna de ese servicio. Para errores externos, siga utilizando el ErrorCode y ErrorType de Protobuf actuales. Esto garantiza la compatibilidad con versiones anteriores, por lo que nuestros clientes no necesitan reescribir su código. Asigna automáticamente códigos de error de espacio de nombres a códigos Protobuf, códigos de estado HTTP y etiquetas. Los ingenieros definen la asignación en el lugar centralizado, y el marco asignará cada código de error al Protobuf , , estado gRPC, estado HTTP y etiquetas para registro/métricas correspondientes. ErrorCode ErrorType Esto garantiza la coherencia y reduce la duplicación. El marco de error del espacio de nombres Paquetes básicos y tipos Hay algunos paquetes básicos que forman la base de nuestro nuevo marco de manejo de errores. connectly.ai/go/pkgs/ : el paquete principal que define el tipo y los códigos. errors Error : para enviar errores al front-end o a la API externa. errors/api : Paquete auxiliar destinado a ser utilizado con dot import. errors/E : Utilidades de prueba para trabajar con errores de espacio de nombres. testing Error y Code La interfaz es una extensión de la interfaz estándar, con métodos adicionales para devolver un . Un se implementa como . Error error Code Code uint16 package errors // import "connectly.ai/go/pkgs/errors" type Error interface { error Code() Code } type Code struct { code uint16 } type CodeI interface { CodeDesc() CodeDesc } type GroupI interface { /* ... */ } type CodeDesc struct { /* ... */ } exporta todos los códigos de error y tipos comunes El paquete errors/E package E // import "connectly.ai/go/pkgs/errors/E" import "connectly.ai/go/pkgs/errors" type Error = errors.Error var ( DEPS = errors.DEPS PRFL = errors.PRFL ) func MapError(ctx context.Context, err error) errors.Mapper { /* ... */ } func IsErrorCode(err error, codes ...errors.CodeI) { /* ... */ } func IsErrorGroup(err error, groups ...errors.GroupI) { /* ... */ } Ejemplo de uso Códigos de error de ejemplo: // dependencies → postgres DEPS.PG.NOT_FOUND DEPS.PG.UNEXPECTED // sdk → hash SDK.HASH.UNEXPECTED // profile → user PRFL.USR.NOT_FOUND PFRL.USR.UNKNOWN // profile → user → repository PRFL.USR.REPO.NOT_FOUND PRFL.USR.REPO.UNKNOWN // profile → auth PRFL.AUTH.UNAUTHENTICATED PRFL.AUTH.UNKNOWN PRFL.AUTH.UNEXPECTED de paquetes: database package database // import "connectly.ai/go/pkgs/database" import "gorm.io/gorm" import . "connectly.ai/go/pkgs/errors/E" type DB struct { gorm: gorm.DB } func (d *DB) Exec(ctx context.Context, sql string, params ...any) *DB { tx := d.gorm.WithContext(ctx).Exec(sql, params...) return wrapTx(tx) } func (x *DB) Error(msgArgs ...any) Error { return wrapError(tx.Error()) // 👈 convert gorm error to 'Error' } func (x *DB) SingleRowError(msgArgs ...any) Error { if err := x.Error(); err != nil { return err } switch { case x.RowsAffected == 1: return nil case x.RowsAffected == 0: return DEPS.PG.NOT_FOUND.CallerSkip(1). New(x.Context(), formatMsgArgs(msgArgs)) default: return DEPS.PG.UNEXPECTED.CallerSkip(1). New(x.Context(), formatMsgArgs(msgArgs)) } } Paquete : pb/services/profile package profile // import "connectly.ai/pb/services/profile" // these types are generated from services/profile.proto type QueryUserRequest struct { BusinessId string UserId string } type LoginRequest struct { Username string Password string } del paquete: service/profile package profile import uuid "github.com/google/uuid" import . "connectly.ai/go/pkgs/errors/E" import l "connectly.ai/go/pkgs/logging/l" import profilepb "connectly.ai/pb/services/profile" // repository requests type QueryUserByUsernameRequest struct { Username string } // repository layer → query user func (r *UserRepository) QueryUserByUsernameAuth( ctx context.Context, req *QueryUserByUsernameRequest, ) (*User, Error) { if req.Username == "" { return PRFL.USR.REPO.INVALID_ARGUMENT.New(ctx, "empty request") } var user User sqlQuery := `SELECT * FROM "user" WHERE username = ? LIMIT 1` tx := r.db.Exec(ctx, sqlQuery, req.Username).Scan(&user) err := tx.SingleRowError() switch { case err == nil: return &user, nil case IsErrorCode(DEPS.PG.NOT_FOUND): return PRFL.USR.REPO.USER_NOT_FOUND. With(l.String("username", req.Username)) Wrap(ctx, "user not found") default: return PRFL.USR.REPO.UNKNOWN. Wrap(ctx, "failed to query user") } } // user service layer → query user func (u *UserService) QueryUser( ctx context.Context, req *profilepb.QueryUserRequest, ) (*profilepb.QueryUserResponse, Error) { // ... rr := QueryUserByUsernameRequest{ Username: req.Username } err := u.repo.QueryUserByUsername(ctx, rr) if err != nil { return nil, MapError(ctx, err). Map(PRFL.USR.REPO.NOT_FOUND, PRFL.USR.NOT_FOUND, "the user %q cannot be found", req.UserName, api.UserTitle("User Not Found"), api.UserMsg("The requested user id %q can not be found", req.UserId)). KeepGroup(PRFL.USR). Default(PRFL.USR.UNKNOWN, "failed to query user") } // ... return resp, nil } // auth service layer → login user func (a *AuthService) Login( ctx context.Context, req *profilepb.LoginRequest, ) (*profilepb.LoginResponse, *profilepb.LoginResponse, Error) { vl := PRFL.AUTH.INVALID_ARGUMENT.WithMsg("invalid request") vl.Vl(req.Username != "", "no username", api.Detail("username is required")) vl.Vl(req.Password != "", "no password", api.Detail("password is required")) if err := vl.ToError(ctx); err != nil { return err } hashpwd, err := hash.Hash(req.Password) if err != nil { return PRFL.AUTH.UNEXPECTED.Wrap(ctx, err, "failed to calc hash") } usrReq := profilepb.QueryUserByUsernameRequest{/*...*/} usrRes, err := a.userServiceClient.QueryUserByUsername(ctx, usrReq) if err != nil { return nil, MapError(ctx, err). Map(PRFL.USR.NOT_FOUND, PRFL.AUTH.UNAUTHENTICATED, "unauthenticated"). Default(PRFL.AUTH.UNKNOWN, "failed to query by username") } // ... } Bueno, hay muchas funciones y conceptos nuevos en el código anterior. Veámoslos paso a paso. Creando y envolviendo errores usando dot import Primero, importe el paquete errors/E Esto le permitirá utilizar directamente tipos comunes como en lugar de y acceder a códigos mediante en lugar de . Error errors.Error PRFL.USR.NOT_FOUND errors.PRFL.USR.NOT_FOUND import . "connectly.ai/go/pkgs/errors/E" Crea nuevos errores usando CODE.New() Supongamos que recibe una solicitud no válida, puede crear un nuevo error de la siguiente manera: err := PRFL.USR.INVALID_ARGUMENT.New(ctx, "invalid request") es un . PRFL.USR.INVALID_ARGUMENT Code Un expone métodos como o para crear un nuevo error. Code New() Wrap() La función recibe como primer argumento, seguido del mensaje y argumentos opcionales. New() context.Context Imprimelo con : fmt.Print(err) [PRFL.USR.INVALID_ARGUMENT] invalid request o con para ver más detalles: fmt.Printf("%+v") [PRFL.USR.INVALID_ARGUMENT] invalid request connectly.ai/go/services/profile.(*UserService).QueryUser /usr/i/src/go/services/profile/user.go:1234 connectly.ai/go/services/profile.(*UserRepository).QueryUser /usr/i/src/go/services/profile/repo/user.go:2341 Envuelva un error dentro de un nuevo error usando CODE.Wrap() dbErr := DEPS.PG.NOT_FOUND.Wrap(ctx, gorm.ErrRecordNotFound, "not found") usrErr := PRFL.USR.NOT_FOUND.Wrap(ctx, dbErr, "user not found") producirá esta salida con : fmt.Print(usrErr) [PRFL.USR.NOT_FOUND] user not found → [DEPS.PG.NOT_FOUND] not found → record not found o con fmt.Printf("%+v", usrErr) [PRFL.USR.NOT_FOUND] user not found → [DEPS.PG.NOT_FOUND] not found → record not found connectly.ai/go/services/profile.(*UserService).QueryUser /usr/i/src/go/services/profile/user.go:1234 El seguimiento de la pila procederá del más interno. Si está escribiendo una función auxiliar, puede utilizar para omitir fotogramas: Error CallerSkip(skip) func mapUserError(ctx context.Context, err error) Error { switch { case IsErrorCode(err, DEPS.PG.NOT_FOUND): return PRFL.USR.NOT_FOUND.CallerSkip(1).Wrap(ctx, err, "...") default: return PRFL.USR.UNKNOWN.CallerSkip(1).Wrap(ctx, err, "...") } } Añadiendo contexto a los errores Agregar contexto a un error usando With() Puede agregar pares clave/valor adicionales a los errores mediante . .With(l.String(...)) es un paquete auxiliar para exportar funciones de sugar para el registro. logging/l devuelve una y devuelve . l.String("flag", flag) Tag{String: flag} l.UUID("user_id, userID) Tag{Stringer: userID} import l "connectly.ai/go/pkgs/logging/l" usrErr := PRFL.USR.NOT_FOUND. With(l.UUID("user_id", req.UserID), l.String("flag", flag)). Wrap(ctx, dbErr, "user not found") Las etiquetas se pueden generar con : fmt.Printf("%+v", usrErr) [PRFL.USR.NOT_FOUND] user not found {"user_id": "81febc07-5c06-4e01-8f9d-995bdc2e0a9a", "flag": "ABRW"} → [DEPS.PG.NOT_FOUND] not found {"a number": 42} → record not found , o : Agregue contexto a los errores directamente dentro de New() Wrap() MapError() Aprovechando la función y su familia, y otras funciones similares pueden detectar etiquetas de forma inteligente entre los argumentos de formato. No es necesario introducir funciones diferentes. l.String() New() err := INF.HEALTH.NOT_READY.New(ctx, "service %q is not ready (retried %v times)", req.ServiceName, l.String("flag", flag) countRetries, l.Number("count", countRetries), ) salida: [INF.HEALTH.NOT_READY] service "magic" is not ready (retried 2 times) {"flag": "ABRW", "count": 2} Diferentes tipos: , , Error0 VlError ApiError Actualmente, existen 3 tipos que implementan las interfaces . Puedes agregar más tipos si es necesario. Cada uno puede tener una estructura diferente, con métodos personalizados para necesidades específicas. Error es una extensión de Error la interfaz error estándar de Go type Error interface { error Code() Message() Fields() []tags.Field StackTrace() stacktrace.StackTrace _base() *base // a private method } Contiene un método privado para garantizar que no implementemos por accidente nuevos tipos fuera del paquete . Es posible que eliminemos (o no) esa restricción en el futuro cuando experimentemos con más patrones de uso. Error errors estándar y utilizamos la afirmación de tipo? ¿Por qué no usamos simplemente la interfaz error Porque queremos separar los errores de terceros de nuestros errores internos. Todas las capas y paquetes de nuestros códigos internos deben devolver siempre . De esta forma, podemos saber con seguridad cuándo tenemos que convertir los errores de terceros y cuándo solo tenemos que ocuparnos de nuestros códigos de error internos. Error También crea un límite entre los paquetes migrados y los que aún no se han migrado. No, ese futuro aún no ha llegado. Puede que llegue algún día, pero por ahora, todavía tenemos que migrar nuestros paquetes uno por uno. Volviendo a la realidad, no podemos simplemente declarar un nuevo tipo, agitar una varita mágica, susurrar un mensaje y, luego, ¡todos los millones de líneas de código se convierten mágicamente y funcionan sin problemas y sin errores! de hechizo es el tipo de predeterminado Error0 Error . Este contiene una y un suberror opcional. Puedes usar para devolver una estructura concreta en lugar de una interfaz , pero debes . La mayoría de los códigos de error producirán un valor Error0 base NewX() *Error0 Error tener cuidado type Error0 struct { base err error } var errA: Error = DEPS.PG.NOT_FOUND.New (ctx, "not found") var errB: *Error0 = DEPS.PG.NOT_FOUND.NewX(ctx, "not found") es la estructura común compartida por todas las implementaciones , para proporcionar una funcionalidad común: , , , y más. base Error Code() Message() StackTrace() Fields() type base struct { code Code msg string kv []tags.Field stack stacktrace.StackTrace } VlError es para errores de validación Puede contener múltiples suberrores y proporcionar métodos útiles para trabajar con ayudantes de validación. type VlError struct { base errs []error } Puedes crear un similar a otro : VlError Error err := PRFL.USR.INVALID_ARGUMENT.New(ctx, "invalid request") O bien crea un , agrégale errores y luego conviértelo en un : VlBuilder VlError userID, err0 := parseUUID(req.UserId) err1 := validatePassword(req.Password) vl := PRFL.USR.INVALID_ARGUMENT.WithMsg("invalid request") vl.Add(err0, err1) vlErr := vl.ToError(ctx) E incluya pares clave/valor como de costumbre: vl := PRFL.USR.INVALID_ARGUMENT. With(l.Bool("testingenv", true)). WithMsg("invalid request") userID, err0 := parseUUID(req.UserId) err1 := validatePassword(req.Password) vl.Add(err0, err1) vlErr := vl.ToError(ctx, l.String("user_id", req.UserId)) El uso de generará el siguiente resultado: fmt.Printf("%+v", vlErr) [PRFL.USR.INVALID_ARGUMENT] invalid request {"testingenv": true, "user_id": "A1234567890"} ApiError es un adaptador para migrar errores de API Anteriormente, usábamos una estructura independiente para devolver errores de API al front-end y a los clientes externos. Incluye como como . api.Error ErrorType ErrorCode se mencionó anteriormente package api import errorpb "connectly.ai/pb/models/error" // Deprecated type Error struct { pbType errorpb.ErrorType pbCode errorpb.ErrorCode cause error msg string usrMsg string usrTitle string // ... } Este tipo ya no se utiliza. En su lugar, declararemos todas las asignaciones ( , , código gRPC, código HTTP) en un lugar centralizado y las convertiremos en los límites correspondientes. Hablaré sobre la declaración de código en . ErrorType ErrorCode la siguiente sección Para realizar la migración al nuevo marco de errores de espacio de nombres, agregamos . Cada se convierte en un código . un espacio de nombres temporal ZZZ.API_TODO ErrorCode ZZZ.API_TODO ZZZ.API_TODO.UNEXPECTED ZZZ.API_TODO.INVALID_REQUEST ZZZ.API_TODO.USERNAME_ ZZZ.API_TODO.META_CHOSE_NOT_TO_DELIVER ZZZ.API_TODO.MESSAGE_WABA_TEMPLATE_CAN_ONLY_EDIT_ONCE_IN_24_HOURS Y se crea como adaptador. Todas las funciones que antes devolvían se cambiaron para que devuelvan (implementado por ). ApiError *api.Error Error *ApiError package api import . "connectly.ai/go/pkgs/errors/E" // previous func FailPreconditionf(err error, msg string, args ...any) *Error { return &Error{ pbType: ERROR_TYPE_FAILED_PRECONDITION, pbCode: ERROR_CODE_MESSAGE_WABA_TEMPLATE_CAN_ONLY_EDIT_ONCE_IN_24_HOURS, cause: err, msg: fmt.Sprintf(msg, args...) } } // current: this is deprecated, and serves and an adapter func FailPreconditionf(err error, msg string, args ...any) *Error { ctx := context.TODO() return ZZZ.API_TODO.MESSAGE_WABA_TEMPLATE_CAN_ONLY_EDIT_ONCE_IN_24_HOURS. CallerSkip(1). // correct the stacktrace by 1 frame Wrap(ctx, err, msg, args...) } Una vez realizada toda la migración, el uso anterior: wabaErr := verifyWabaTemplateStatus(tpl) apiErr := api.FailPreconditionf(wabaErr, "template cannot be edited"). WithErrorCode(ERROR_CODE_MESSAGE_WABA_TEMPLATE_CAN_ONLY_EDIT_ONCE_IN_24_HOURS). WithUserMsg("According to WhatsApp, the message template can be only edited once in 24 hours. Consider creating a new message template instead."). ErrorOrNil() Debería convertirse en: CPG.TPL.EDIT_ONCE_IN_24_HOURS.Wrap( wabaErr, "template cannot be edited", api.UserMsg("According to WhatsApp, the message template can be only edited once in 24 hours. Consider creating a new message template instead.")) Tenga en cuenta que el se deriva implícitamente del código del espacio de nombres interno. No es necesario asignarlo explícitamente cada vez. Pero, ¿cómo declarar la relación entre los códigos? Se explicará en la siguiente sección. ErrorCode Declaración de nuevos códigos de error En este punto, ya sabes cómo crear nuevos errores a partir de códigos existentes. Es hora de explicar qué son los códigos y cómo agregar uno nuevo. valor Un Code se implementa como un uint16 , que tiene una presentación de cadena correspondiente. type Code struct { code: uint16 } fmt.Printf("%q", DEPS.PG.NOT_FOUND) // "DEPS.PG.NOT_FOUND" Para almacenar esas cadenas, hay una matriz de todos disponibles: CodeDesc const MaxCode = 321 // 👈 this value is generated var allCodes [MaxCode]CodeDesc type CodeDesc { c int // 42 code string // DEPS.PG.NOT_FOUND api APICodeDesc } type APICodeDesc { ErrorType errorpb.ErrorType ErrorCode errorpb.ErrorCode HttpCode int DefMessage string UserMessage string UserTitle string } Así es como se declaran los códigos: var DEPS deps // dependencies var PRFL prfl // profile var FLD fld // flow document type deps struct { PG pg // postgres RD rd // redis } // tag:postgres type pg struct { NOT_FOUND Code0 // record not found CONFLICT Code0 // record already exist MALFORM_SQL Code0 } // tag:profile type PRFL struct { REPO prfl_repo USR usr AUTH auth } // tag:profile type prfl_repo struct { NOT_FOUND Code0 // internal error code INVALID_ARGUMENT VlCode // internal error code } // tag:usr type usr struct { NOT_FOUND Code0 `api-code:"USER_NOT_FOUND"` INVALID_ARGUMENT VlCode `api-code:"INVALID_ARGUMENT"` DISABlED_ACCOUNT Code0 `api-code:"DISABLED_ACCOUNT"` } // tag:auth type auth struct { UNAUTHENTICATED Code0 `api-code:"UNAUTHENTICATED"` PERMISSION_DENIED Code0 `api-code:"PERMISSION_DENIED"` } Después de declarar nuevos códigos, debes el script de generación: ejecutar run gen-errors El código generado se verá así: // Code generated by error-codes. DO NOT EDIT. func init() { // ... PRFL.AUTH.UNAUTHENTICATED = Code0{Code{code: 143}} PRFL.AUTH.PERMISSION_DENIED = Code0{Code{code: 144}} // ... allCodes[143] = CodeDesc{ c: 143, code: "PRFL.AUTH.UNAUTHENTICATED", tags: []string{"auth", "profile"}, api: APICodeDesc{ ErrorType: ERROR_TYPE_UNAUTHENTICATED, ErrorCode: ERROR_CODE_UNAUTHENTICATED, HTTPCode: 401, DefMessage: "Unauthenticated error", UserMessage: "You are not authenticated.", UserTitle: "Unauthenticated error", })) } tipo correspondiente Cada Error tiene un tipo Code ¿Alguna vez se preguntó cómo crea un y crea un ? Es porque utilizan diferentes tipos de código. PRFL.USR.NOT_FOUND.New() *Error0 PRFL.USR.INVALID_ARGUMENTS.New() *VlError Y cada tipo devuelve un tipo diferente, cada uno puede tener sus propios métodos adicionales: Code Error type Code0 struct { Code } type VlCode struct { Code } func (c Code0) New(/*...*/) Error { return &Error0{/*...*/} } func (c VlCode) New(/*...*/) Error { return &VlError{/*...*/} } // extra methods on VlCode to create VlBuilder func (c VlCode) WithMsg(msg string, args ...any) *VlBuilder {/*...*/} type VlBuilder struct { code VlCode msg string args []any } func (b *VlBuilder) ToError(/*...*/) Error { return &VlError{Code: code, /*...*/ } } Utilice api-code para marcar los códigos disponibles para API externas El código de error del espacio de nombres debe usarse internamente. Para que un código esté disponible para su devolución en una API HTTP externa, debe marcarlo con . El valor es el correspondiente. api-code errorpb.ErrorCode Si un código de error no está marcado con , es un código interno y se mostrará como un genérico. api-code Internal Server Error Tenga en cuenta que es un código externo, mientras que es un código interno. PRFL.USR.NOT_FOUND PRFL.USR.REPO.NOT_FOUND Declare la asignación entre ErrorCode , ErrorType y códigos gRPC/HTTP en protobuf usando la opción de enumeración: // error/type.proto ERROR_TYPE_PERMISSION_DENIED = 707 [(error_type_detail_option) = { type: "PermissionDeniedError", grpc_code: PERMISSION_DENIED, http_code: 403, // Forbidden message: "permission denied", user_title: "Permission denied", user_message: "The caller does not have permission to execute the specified operation.", }]; // error/code.proto ERROR_CODE_DISABlED_ACCOUNT = 70020 [(error_code_detail_option) = { error_type: ERROR_TYPE_DISABlED_ACCOUNT, grpc_code: PERMISSION_DENIED, http_code: 403, // Forbidden message: "account is disabled", user_title: "Account is disabled", user_message: "Your account is disabled. Please contact support for more information.", }]; Códigos y UNEXPECTED UNKNOWN Cada capa suele tener dos códigos genéricos y . Tienen propósitos ligeramente diferentes: UNEXPECTED UNKNOWN El código se utiliza para errores que nunca deberían ocurrir. UNEXPECTED El código se utiliza para errores que no se manejan explícitamente. UNKNOWN Asignación de errores a código nuevo Al recibir un error devuelto por una función, debe manejarlo: convertir los errores de terceros en errores de espacio de nombres internos y asignar códigos de error de capas internas a capas externas. Convertir errores de terceros en errores de espacio de nombres internos La forma en que se gestionan los errores depende de lo que devuelve el paquete de terceros y de lo que necesita la aplicación. Por ejemplo, al gestionar errores de base de datos o de API externa: switch { case errors.Is(err, sql.ErrNoRows): // map a database "no rows" error to an internal "not found" error return nil, PRFL.USR.NOT_FOUND.Wrap(ctx, err, "user not found") case errors.Is(err, context.DeadlineExceeded): // map a context deadline exceeded error to a timeout error return nil, PRFL.USR.TIMEOUT.Wrap(ctx, err, "query timeout") default: // wrap any other error as unknown return nil, PRFL.USR.UNKNOWN.Wrap(ctx, err, "unexpected error") } Uso de ayudantes para errores de espacios de nombres internos : Comprueba si el error contiene alguno de los códigos especificados. IsErrorCode(err, CODES...) : Devuelve verdadero si el error pertenece al grupo de entrada. IsErrorGroup(err, GROUP) Patrón de uso típico: user, err := queryUser(ctx, userReq) switch { case err == nil: // continue case IsErrorCode(PRL.USR.REPO.NOT_FOUND): // check for specific error code and convert to external code // and return as HTTP 400 Not Found return nil, PRFL.USR.NOT_FOUND.Wrap(ctx, err, "user not found") case IsGroup(PRL.USR): // errors belong to the PRFL.USR group are returned as is return nil, err default: return nil, PRL.USR.UNKNOWN.Wrap(ctx, err, "failed to query user") } MapError() para escribir código de mapeo más fácilmente: Dado que la asignación de códigos de error es un patrón común, existe un asistente para agilizar la escritura del código. El código anterior se puede reescribir de la siguiente manera: MapError() user, err := queryUser(ctx, userReq) if err != nil { return nil, MapError(ctx, err). Map(PRL.USR.REPO.NOT_FOUND, PRFL.USR.NOT_FOUND, "user not found"). KeepGroup(PRF.USR). Default(PRL.USR.UNKNOWN, "failed to query user") } Puede formatear argumentos y agregar pares clave/valor como de costumbre: return nil, MapError(ctx, err). Map(PRL.USR.REPO.NOT_FOUND, PRFL.USR.NOT_FOUND, "user %v not found", username, l.String("flag", flag)). KeepGroup(PRF.USR). Default(PRL.USR.UNKNOWN, "failed to query user", l.Any("retries", retryCount)) Prueba con espacio de nombres s Error Las pruebas son fundamentales para cualquier base de código seria. El marco proporciona ayudantes especializados como para que escribir y confirmar condiciones de error en las pruebas sea más fácil y expresivo. ΩxError() // 👉 return true if the error contains the message ΩxError(err).Contains("not found") // 👉 return true if the error does not contain the message ΩxError(err).NOT().Contains("not found") Hay muchos más métodos y también puedes encadenarlos: ΩxError(err). MatchCode(DEPS.PG.NOT_FOUND). // match any code in top or wrapped errors TopErrorMatchCode(PRFL.TPL.NOT_FOUND) // only match code from the top error MatchAPICode(API_CODE.WABA_TEMPLATE_NOTE_FOUND). // match errorpb.ErrorCode MatchExact("exact message to match") ? ¿Por qué utilizar métodos en lugar de Ω(err).To(testing.MatchCode()) Porque los métodos son más fáciles de descubrir. Cuando te enfrentas a docenas de funciones como , es difícil saber cuáles funcionarán con s y cuáles no. Con los métodos, puedes simplemente escribir un punto , y tu IDE mostrará una lista de todos los métodos disponibles diseñados específicamente para confirmar s. testing.MatchValues() Error . Error Migración El marco de trabajo es solo la mitad de la historia. ¿Escribir el código? Esa es la parte fácil. El verdadero desafío comienza cuando hay que incorporarlo a una base de código masiva y viva donde docenas de ingenieros están implementando cambios a diario, los clientes esperan que todo funcione perfectamente y el sistema simplemente no puede dejar de funcionar. La migración conlleva responsabilidad. Se trata de minuciosamente fragmentos de código, realizar cambios minúsculos a la vez, romper un montón de pruebas en el proceso. Luego, inspeccionarlos y corregirlos manualmente uno por uno, fusionarlos en la rama principal, implementarlos en producción, observar los registros y las alertas. Repetirlo una y otra vez... dividir Aquí hay algunos consejos para la migración que aprendimos a lo largo del camino: comience reemplazando los patrones antiguos con el nuevo marco. Corrija los problemas de compilación que surjan de este proceso. Comience con la búsqueda y reemplazo: Por ejemplo, reemplace todos en este paquete con . error Error type ProfileController interface { LoginUser(req *LoginRequest) (*LoginResponse, error) QueryUser(req *QueryUserRequest) (*QueryUserResponse, error) } El nuevo código se verá así: import . "connectly.ai/go/pkgs/errors" type ProfileController interface { LoginUser(req *LoginRequest) (*LoginResponse, Error) QueryUser(req *QueryUserRequest) (*QueryUserResponse, Error) } comience con los paquetes de nivel más bajo y avance hacia arriba. De esta manera, puede asegurarse de que los paquetes de nivel inferior se migren por completo antes de pasar a los de nivel superior. Migrar un paquete a la vez: si faltan pruebas en partes del código base, agréguelas. Si no está seguro de los cambios, agregue más pruebas. Son útiles para asegurarse de que los cambios no afecten la funcionalidad existente. Agregue pruebas unitarias faltantes: considere cambiar las funciones relacionadas a DEPRECATED y luego agregue nuevas funciones con el nuevo tipo . Si su paquete depende de llamar a paquetes de nivel superior: Error Supongamos que está migrando el paquete de base de datos, que tiene el método : Transaction() package database func (db *DB) Transaction(ctx context.Context, fn func(tx *gorm.DB) error) error { return db.gorm.Transaction(func(tx *gorm.DB) error { return fn(tx) }) } Y se utiliza en el paquete de servicio de usuario: err = s.DB(ctx).Transaction(func(tx *database.DB) error { user, usrErr := s.repo.CreateUser(ctx, tx, user) if usrErr != nil { return usrErr } } Dado que primero está migrando el paquete , dejando el y docenas de otros paquetes como están. La llamada aún devuelve el tipo de anterior, mientras que el método debe devolver el nuevo tipo . Puede cambiar el método a y agregar un nuevo método : database user s.repo.CreateUser() error Transaction() Error Transaction() DEPRECATED TransactionV2() package database // DEPRECATED: use TransactionV2 instead func (db *DB) Transaction_DEPRECATED(ctx context.Context, fn func(tx *gorm.DB) error) error { return db.gorm.Transaction(func(tx *gorm.DB) error { return fn(tx) }) } func (db *DB) TransactionV2(ctx context.Context, fn func(tx *gorm.DB) error) Error { err := db.gorm.Transaction(func(tx *gorm.DB) error { return fn(tx) }) return adaptToErrorV2(err) } : cuando encuentre un error que no se ajuste a los existentes, agregue un nuevo código. Esto le ayudará a crear un conjunto completo de códigos de error a lo largo del tiempo. Los códigos de otros paquetes siempre están disponibles como referencias. Agregue nuevos códigos de error a medida que avanza Conclusión Al principio, el manejo de errores en Go puede parecer simple: basta con devolver un y continuar. Pero a medida que nuestra base de código fue creciendo, esa simplicidad se convirtió en una maraña de registros imprecisos, manejo inconsistente y sesiones de depuración interminables. error Al dar un paso atrás y repensar cómo manejamos los errores, hemos creado un sistema que funciona para nosotros, no en nuestra contra. Los códigos de espacio de nombres centralizados y estructurados nos brindan claridad, mientras que las herramientas para mapear, encapsular y probar errores nos hacen la vida más fácil. En lugar de nadar en un mar de registros, ahora tenemos errores significativos y rastreables que nos indican qué está mal y dónde buscar. Este marco no solo sirve para hacer que nuestro código sea más limpio, sino para ahorrar tiempo, reducir la frustración y ayudarnos a prepararnos para lo desconocido. Es solo el comienzo de un viaje (aún estamos descubriendo más patrones), pero el resultado es un sistema que, de alguna manera, puede brindar tranquilidad en cuanto al manejo de errores. ¡Con suerte, también puede generar algunas ideas para tus proyectos! 😊 Autor Soy Oliver Nguyen. Soy un desarrollador de software que trabaja principalmente con Go y JavaScript. Disfruto aprendiendo y viendo una mejor versión de mí mismo cada día. Ocasionalmente desarrollo nuevos proyectos de código abierto. Comparto conocimientos y pensamientos durante mi recorrido. La publicación también está publicada en y 👋 blog.connectly.ai olivernguyen.io