Mejores Prácticas para Clientes Tipados
25 prácticas para clientes Solana completamente tipados y basados en IDL.
-
Trata la IDL como contrato de API: Cada cambio en cuentas y argumentos es una revisión de cambio disruptivo (Conceptos Básicos de Clientes Tipados).
-
Regenera en CI: Falla cuando
clients/generateddifiere después deanchor build+ Codama. -
Fija el renderizador de Codama con el kit 7.0.0: Las versiones principales del renderizador siguen los diseños de los codecs.
-
Nunca edites archivos generados: Envuelve las extensiones en módulos escritos a mano.
-
Confirma la IDL o un artefacto de compilación verificable: El soporte debe poder reproducir la generación del cliente.
-
Nombra los resultados de múltiples programas: Evita colisiones de nombres de exportación.
-
Usa las utilidades
fetch*: Combina RPC + decodificación para reducir errores (Obtención y Decodificación de Cuentas). -
Simula lotes de instrucciones: Detecta errores de restricciones antes del modal de la billetera.
-
Mapea errores del programa: Muestra los códigos de error de la IDL en la copia de la UI.
-
bigintparau64: Coincide con los tipos Borsh en cadena en TypeScript. -
Coordina el despliegue + frontend: Envía las actualizaciones del cliente con las actualizaciones del programa.
-
IDs de programa específicas del entorno:
devnet≠mainneten archivos.env. -
Documenta el hash de la IDL en los lanzamientos: Entrada de registro de cambios por cada cambio de interfaz.
-
Prefiere Codama sobre codecs manuales: El costo de mantenimiento es menor a largo plazo.
-
gillpara el arranque,kitpara casos extremos: Entiende ambas capas (gill). -
El servidor lee tipado: Las rutas de Next.js importan decodificadores sin billeteras.
-
El cliente escribe tipado: La billetera firma solo las instrucciones generadas.
-
Prueba fixtures de decodificación: Instantáneas de bytes de cuenta en pruebas unitarias.
-
Evita
getProgramAccountsen la UI de mainnet: Usa un indexador o RPC filtrado. -
Alineación con Anchor 0.32.1: IDL del crate
anchor-langcoincidente. -
No
web3.jsen la ruta generada: Modelo de Dirección Única a través dekit. -
Carga diferida de IDLs grandes: Divide los programas para reducir el tamaño del paquete.
-
Envuelve errores de RPC: Traduce 429 y timeouts para los usuarios.
-
Audita cuentas CPI en la IDL: Los clientes deben incluir las cuentas restantes cuando sea necesario.
-
Educa al equipo sobre los comandos de codegen:
CONTRIBUTING.mdlista los pasos exactos.
Preguntas Frecuentes
¿Cliente TS de Anchor todavía?
Manten el legado; el código nuevo usa la salida del kit Codama.
¿Generados confirmados?
Sí, con verificación de deriva en CI, o regenera solo en CI si el artefacto de IDL está almacenado.
¿IDL nativa no-Anchor?
Codama soporta esquemas de IDL JSON compatibles.
Relacionado
- Codama - herramienta de generación de código
- Mejores Prácticas de @solana/kit - capa RPC
- Generando Clientes TS - flujo de trabajo
Versiones de la Pila: 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.