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

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.