Prácticas recomendadas para errores y registros
Equilibre la observabilidad con la disciplina de la Unidad de Costo (CU): códigos de error estables para clientes, registros controlados para ingenieros, eventos estructurados para indexadores.
Cómo usar esta lista
- Publique IDL/errors.json en cada lanzamiento.
- Simule las rutas de fallo principales en CI.
- Controle con funciones los registros detallados.
A - Errores
- Devuelva
ProgramError- nunca entre en pánico ante entradas controladas por el usuario. Códigos de fallo limpios. - Mantenga estables los códigos de error personalizados; solo agregue nuevas variantes. Compatibilidad con el cliente.
- Publique tablas de errores legibles por máquina con la versión del programa. Precisión de decodificación.
- Mapee los errores de CPI deliberadamente cuando la experiencia del usuario necesite mensajes específicos del programa. Responsabilidad clara.
- Pruebe unitariamente cada rama de error. Cobertura para modos de fallo.
B - Registros
- Controle
msg!detrás de funciones en compilaciones de lanzamiento. Control de CU. - Nunca registre secretos, semillas o datos privados del usuario. Cadena pública.
- Use tokens de registro con prefijo para grep (
MYAPP:step). Eficiencia de operaciones. - Evite registros dentro de bucles y cadenas de CPI. Multiplicación de CU.
- Prefiera eventos para la observabilidad dirigida al indexador. Canalizaciones estructuradas.
C - Operaciones
- Simule antes de enviar en dApps; muestre errores decodificados. Ahorro en experiencia de usuario y soporte.
- Archive IDL + JSON de errores por hash de despliegue. Viaje en el tiempo para incidentes.
- Agregue pruebas LiteSVM que afirmen códigos de error específicos. Seguridad contra regresiones.
- Documente el playbook de depuración para el equipo de soporte. Resolución más rápida.
- Elimine los registros de depuración temporales antes de la etiqueta de mainnet. Costo y ruido.
Preguntas frecuentes
¿Errores vs eventos?
Los errores fallan; los eventos observan principalmente las rutas de éxito.
¿Anchor es suficiente?
Aún controle los registros y publique IDL.
¿Registros Pinocchio?
Mismos costos de syscall.
¿i18n?
Mapee códigos fuera de la cadena.
¿Monitorización?
Indexe eventos, no registros de spam sin procesar.
¿Presupuesto de CU?
Los registros afectan el aterrizaje en ix ajustados.
¿Programa inmutable?
Tabla de errores congelada - planifique códigos.
¿Surfpool?
Depuración por defecto.
¿Kit 7.0.0?
Estándar de decodificación del cliente.
¿Seguridad?
Los errores pueden filtrar pistas - texto genérico para el usuario.
¿Cumplimiento?
Sin PII en los registros.
¿CI?
Falle en nuevas rutas de pánico.
Relacionado
- Conceptos básicos de manejo de errores - Introducción
- Registros con msg! - Registros conscientes de CU
- Código de error y require! - Pila 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.