Enums de Errores Personalizados
Los enums de errores personalizados traducen fallos de negocio a códigos estables u32. Anchor los publica en el IDL; los programas nativos deberían distribuir JSON equivalente para los clientes de @solana/kit 7.0.0.
Receta
#[repr(u32)]
pub enum VaultError {
InsufficientFunds = 6000,
SlippageExceeded = 6001,
}Cuándo usar esto:
- Al construir dApps orientadas al usuario que muestran errores específicos.
- Para soportar mensajes de error i18n fuera de la cadena.
- Al auditar modos de fallo.
Ejemplo Funcional
#[error_code]
pub enum Error {
#[msg("Fondos insuficientes")]
InsufficientFunds,
#[msg("Deslizamiento excedido")]
SlippageExceeded,
}Lo que esto demuestra:
- El atributo de Anchor genera códigos + IDL.
- Las cadenas
Msgson pistas fuera de la cadena. - El ordenamiento estable es importante.
Análisis Profundo
Rangos de Códigos
- Anchor: 6000+
- Nativo: elegir un rango no utilizado por programa
Exportación IDL
Los clientes decodifican el nombre + código.
Notas de Rust
return Err(Error::InsufficientFunds.into());Trampas
- Reordenar enum - Cambia los códigos - rompe el cliente. Solución: Añadir solo al final.
- Códigos duplicados entre programas - Confusión en logs en transacciones multi-CPI. Solución: Nombrar en la UI por ID de programa.
- Filtrar pistas de explotación en
msg- Las cadenasmsgdetalladas son públicas. Solución: Texto genérico para el usuario fuera de la cadena. - Demasiado granular - Cientos de códigos difíciles de mantener. Solución: Agrupar lógicamente.
- No publicar IDL - Los clientes muestran error desconocido. Solución: Publicar artefacto IDL en CI.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
Solo ProgramError incorporado | Programas internos | UX |
| Errores de cadena | No en cadena | N/A |
| Eventos para fallos | Herramienta incorrecta | Usar errores |
Preguntas Frecuentes
¿Atributo `msg` de Anchor?
Metadatos para IDL.
¿IDL Nativo?
Escribir a mano o con Codama.
¿i18n?
Mapear código a idioma fuera de la cadena.
¿Simulación?
Devuelve el mismo código personalizado.
¿Error en CPI?
Puede ver el código del llamador en los logs.
¿Máximo `u32`?
Límite práctico menor.
¿`thiserror`?
Alojar pruebas de configuración.
¿Fuzz?
Todas las ramas devuelven Err, no panic.
¿6000 reservado?
Convención de Anchor.
¿Múltiples programas?
Tupla de ID de programa + código.
¿Versión IDL?
Etiquetar lanzamientos.
¿Decodificador de Kit?
Ayudantes de @solana/kit 7.0.0.
Relacionado
- Manejo de Errores en Cadena - Patrones
- Decodificación de Errores Fuera de Cadena - Clientes
- Código de Error y
require!- Errores de Anchor
Versiones de Stack: Esta página fue escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, y LiteSVM 0.6.x.