Uno de los objetivos clave que tuvimos al construir el primer grupo de SDK fue permitir a los desarrolladores cambiar rápidamente entre lenguajes de programación sin tener que adaptarse a un diseño completamente diferente. Este documento tiene la intención de guiar a los desarrolladores para enviar SDK basados en Bitxor que comparten el mismo diseño para lograr la interoperabilidad.
Infraestructura
Este paquete incluye el cliente de API y los objetos de transferencia de datos (DTO) generados. Las solicitudes HTTP se realizan siguiendo el patrón de Repositorio, y devuelven modelos inmutables del dominio Bitxor a través del patrón Observable.
Modelos
Los modelos de dominio de Bitxor son inmutables por definición, lo que significa que el desarrollador no puede cambiar sus atributos. En su lugar, los desarrolladores deben crear nuevas transacciones y enviarlas a la cadena de bloques a través de TransactionHTTP.
Servicios
Operaciones comunes que requieren combinar múltiples solicitudes de la API REST.
Contratos estandarizados: Garantizar la interoperabilidad y armonización de los modelos de datos.
Acoplamiento flexible: Reducir el grado de acoplamiento de los componentes.
Abstracción: Aumentar la consistencia a largo plazo de la interoperabilidad y permitir que los componentes subyacentes evolucionen de forma independiente.
Reutilización: Permitir la interoperabilidad de alto nivel entre módulos y consumidores potenciales de componentes.
Sin estado: Aumentar la disponibilidad y escalabilidad de los componentes permitiéndoles interoperar con más frecuencia y de forma más confiable.
Componibilidad: Para que los componentes sean efectivamente componibles, deben ser interoperables.
El Bitxor SDK utiliza intensamente la biblioteca ReactiveX.
Los beneficios de usar un enfoque reactivo son:
Funcional: Los desarrolladores pueden evitar programas complejos con estado utilizando funciones de entrada/salida limpias sobre flujos observables.
Menos es más: Los operadores de ReactiveX a menudo reducen lo que antes era un desafío elaborado en unas pocas líneas de código.
Manejo de errores asincrónico: El try/catch tradicional es débil para el manejo de errores en cálculos asíncronos, pero ReactiveX ofrece a los desarrolladores las herramientas adecuadas para manejar los errores.
Concurrencia: Los observables y los planificadores en ReactiveX permiten al programador abstraer los problemas de subprocesamiento, sincronización y concurrencia de bajo nivel.
Frontend: Manipulación de eventos de interfaz de usuario y respuestas de API en la web utilizando RxJS.
Backend: Aprovechamiento de la asincronía de ReactiveX, permitiendo.
Si es nuevo en la programación reactiva, lo alentamos a que comience con la guía en línea Learn RxJS.
Revisa la documentación técnica para familiarizarte con las Bitxor características integradas.
Configura el Bitxor entorno local a través de Docker.
Consulta la referencia de la API y juega con el conjunto de puntos finales ofrecidos.
Familiarízate con el SDK actual a través de ejemplos de código y la CLI.
Únete a nuestro Discord para hacer preguntas relacionadas con Bitxor.
Asegúrate de que nadie esté trabajando actualmente en el SDK que deseas crear. Verifica la lista de repositorios y comenta tus intenciones en el canal #sig-api.
Reclama el SDK haciendo un “fork�?de este repositorio <https://help.github.com/en/articles/creating-a-pull-request/>`_ y agrega una nueva entrada a la lista de repositorios.
Puedes basar tu trabajo en el SDK de TypeScript. La versión de TypeScript es la primera que recibe las últimas actualizaciones. Verifica regularmente el registro de cambios para asegurarte de no perderte ninguna actualización de código.
Crea un nuevo repositorio, preferiblemente en GitHub, con:
El README con las instrucciones para instalar el SDK.
Las pautas para contribuyentes para ayudar a otros a saber cómo pueden ayudarte.
¡Un proyecto con una buena cobertura de pruebas es más probable que sea utilizado y confiado por los desarrolladores!
Recomendamos encarecidamente hacer Desarrollo Guiado por Pruebas (Test-Driven Development) o pruebas unitarias (pruebas al final). Si necesitas inspiración, siéntete libre de adaptar directamente las mismas pruebas que hemos realizado.
Ejemplo de archivo de configuración travis.yml aquí.
Ejemplo de pruebas unitarias.
Ejemplo de pruebas de extremo a extremo.
Una vez que hayas escrito algunas pruebas, configura un sistema de Integración Continua (CI) para ejecutar automáticamente el conjunto de pruebas y el linter de código. Utilizamos travis-ci, pero siéntete libre de utilizar el que mejor se adapte a tus necesidades.
Además, nos esforzamos por mantener nuestros código con una cobertura de pruebas unitarias del 80% o superior. Utilizamos coveralls para supervisar la cobertura de pruebas.
El OpenAPI Generator maneja la generación de API y DTO. Es compatible con varios idiomas y, con suerte, el suyo está en la lista.
Estos son los pasos que seguimos para generar los DTO de Typescript (objetos de transferencia de datos):
Descargue la última especificación Bitxor OpenAPI de las versiones de GitHub.
Instale la CLI del generador de OpenApi.
npm install @openapitools/[email protected] -g
Genere los DTO para el lenguaje de programación seleccionado.
openapi-generator generate -i ./openapi3.yml -g typescript-node -o ./bitxor-ts-sdk/ && rm -R bitxor-ts-sdk/test
La lib generada normalmente se publica en un repositorio central (por ejemplo, maven, npm). Los SDK dependen de esas bibliotecas como cualquier otra dependencia de terceros. Para automatizar el despliegue de los paquetes, incluido el generador para el lenguaje de programación seleccionado en el proyecto bitxor-openapi-generator.
Descarte las clases de cliente generadas e impleméntelas usando el patrón Repository que devuelve Observables <https://en.wikipedia.org/wiki/Observer_pattern> `_ de `ReactiveX.
Note
El SDK para TypeScript actualmente elige la plantilla typescript-node del OpenAPI Generator, pero también hay otras plantillas disponibles para adaptarse a otros propósitos. El SDK ha interconectado todos los repositorios Http para que se puedan aplicar diferentes implementaciones.
Ejemplo de repositorios e implementaciones:
Consulte la lista completa de repositorios e implementaciones.
Los repositorios devuelven modelos en lugar de DTO. Deberá codificar los modelos antes de finalizar el envoltorio de la API.
De forma predeterminada, los modelos son inmutables y tienen como objetivo ocultar la complejidad, como la conversión de tipos o la relación entre objetos.
Ejemplo de implementación de modelos:
See the complete list of models.
Encontrará en las implementaciones diferentes invariantes para garantizar que el objeto esté bien construido y se publique una API más agradable.
Particular decisions we considered:
UInt64 apoyo: mientras Java supports big numbers, por ejemplo, JavaScript no lo hace. El SDK de JavaScript tiene una clase personalizada para manejar el uint64 types. Si su idioma es compatible con uint64, use esa implementación en su lugar.
Conversiones de API: a veces, los datos devueltos por API están comprimidos. Es posible que deba convertir esos tipos para el usuario.
Namespace id: en el momento de la creación, agrega el nombre de la cadena, pero cuando recibe el espacio de nombres de la red, viene formateado como uint64 id. Un punto final específico devuelve el nombre cadena del espacio de nombres.
La biblioteca catbuffer-schemas define el protocolo para serializar y deserializar Bitxor entidades.
En combinación con el proyecto de generadores catbuffer, los desarrolladores pueden generar clases constructoras para un conjunto determinado de lenguajes de programación. Por ejemplo, el Bitxor SDK utiliza el código generado para operar con las entidades en forma binaria.
Note
Si no hay un generador para el lenguaje de programación seleccionado, deberá desarrollarlo primero. Puede basar su trabajo en el generador para TypeScript.
Si hay un generador, siga los siguientes pasos para generar los constructores para todas las entidades existentes:
Clone el repositorio catbuffer-generators de forma recursiva.
git clone --recursive [email protected]:bitxor/catbuffer-generators.git
Instale los requisitos del paquete.
pip install -r requirements.txt
Clone el repositorio catbuffer-schemas dentro de la carpeta catbuffer-generators.
Genere código para todos los esquemas ejecutando el siguiente comando en el directorio catbuffer-generators, reemplazando cpp_builder por el lenguaje de programación de destino.
python scripts/generate_all.sh cpp_builder
El comando anterior crea un nuevo archivo para cada esquema en la carpeta catbuffer/_generated/cpp_builder.
Publique el código generado en un repositorio central (por ejemplo, Maven, NPM) y haga que el SDK dependa de esta biblioteca. Para cada tipo de transacción, use los constructores generados para serializar y deserializar transacciones.
Aquí puede encontrar algunos ejemplos de cómo usamos los generadores de transacciones:
Ver la lista completa de transactions.
Note
This section is incomplete.
Se requieren funciones criptográficas para firmar transacciones. Todas las funciones relacionadas con la criptografía se pueden encontrar en el core/crypto modulo.
Los SDK usan tweetnacl estándar (ed2559) para la generación de pares de claves, derivación de direcciones (a partir de clave pública) y firmas:
Los pares de claves se basan en tweetnacl 64 bytes secretKey (pública + privada) usando SHA-512.
Las firmas usan el modo separado de tweetnacl y también se generan usando SHA-512.
Finalmente, preste especial atención a los vectores de prueba. La mejor manera de asegurarse de que su implementación sea correcta es usar los archivos de vectores de prueba como entradas y salidas esperadas.
Ejemplos de pruebas de vectores:
Los servicios combinan varias solicitudes de REST API y brindan a los desarrolladores métodos prácticos que no se pueden recuperar directamente desde la API.
Los servicios se consideran funciones “agradables de tener�?y, por lo general, no se requieren para considerar que el SDK está completo. Recomendamos comenzar con los servicios de codificación solo si primero tiene un SDK completamente operativo y bien probado.
Ejemplos de servicios:
AggregateTransactionService: ayuda a los desarrolladores de aplicaciones a anunciar transacciones agregadas sin tener que desarrollar la lógica para esperar la confirmación del bloqueo hash.
MetadataTransactionService: crea transacciones de metadatos sin tener que pasar el valor anterior.
BlockService: proporciona métodos para verificar que los datos devueltos por un nodo determinado es válida.
Consulte la lista completa de servicios.
Los SDK deben ser adoptados por otros desarrolladores. Como desarrollador principal, nadie sabe mejor que usted cómo funciona el SDK. Considere ayudar a otros y difundir el uso del SDK proporcionando la siguiente documentación.
Apache-2.0: Apache License, version 2.0
BSD-2-Clause: OSI-approved BSD 2-clause license
BSD-3-Clause: OSI-approved BSD 3-clause license
CC0-1.0: Creative Commons CC0 1.0 Universal
GNU-All-Permissive: GNU All-Permissive License
LGPL-2.1+: GNU Lesser General Public License (LGPL), version 2.1 or newer
Last updated by John Doe
on 2023‑06‑19.
