Me complace anunciar el Couchbase Go SDK 2.0 Alpha. Este nuevo SDK trae una serie de cambios en todos los SDKs de Couchbase que el equipo ha estado creando. Los nuevos SDKs traen una API completamente nueva que es más simple, a prueba de futuro y se integra con los últimos desarrollos del ecosistema.
La versión 2.0 del SDK Go se alinea con las nuevas características de Couchbase Server que se extienden fuera de la interfaz tradicional Bucket: soporte para Scopes y Collection. Además, consolida y refina la interfaz, mejorando la conformidad entre SDKs.
Nuevas características de Couchbase Server: Ámbitos y Colecciones
En versiones anteriores de Couchbase Server, los buckets se utilizaban como entidades lógicas con nombre de usuario que agrupaban elementos. Esto permitía acceder a ellos, indexarlos, replicarlos y controlar el acceso. Este era realmente el único medio de lograr multi-tenancy usando Couchbase Server y venía con algunas limitaciones: Los buckets en sí son bastante intensivos en recursos y un cluster sólo puede gestionar eficientemente un número finito de buckets. Para las modernas arquitecturas de micro-servicios, o realmente cualquier arquitectura en la que se necesite multi-tenancy, esto suponía algunos retos a la hora de servir a una gran cantidad de inquilinos. Esto se resolverá en una futura versión de Couchbase Server con los conceptos de Scopes y Collections.
Un Ámbito representa una unidad de multitenencia y se construye a partir de Colecciones. Una colección es un nombre único para un grupo de documentos. Dentro de un ámbito, el nombre de una colección debe ser único, pero el mismo nombre de colección puede utilizarse en varios ámbitos. Cada cubo contiene un ámbito predeterminado con el nombre "_default" y un identificador 0 (cero), que a su vez contiene una colección predeterminada con el nombre "_default" y un identificador 0 (cero).
Esto tiene el efecto de trasladar las operaciones clave/valor que estaban en el contexto de bucket para SDK 1.0 al contexto de colección para SDK 2.0. Las operaciones entre buckets como Search, Analytics y N1QL se realizan ahora a nivel de clúster.
Couchbase Server 6.5 soportará Scopes y Collections como parte de "Developer Preview", Developer Preview es no para su uso en producción. Mientras tanto, el SDK 2.0 también es compatible con Couchbase 5.0 y superiores utilizando el Scope y la Collection por defecto.
Aspectos destacados de la API SDK 2.0
El objetivo de esta alfa es proporcionar la API para usar Couchbase Server con operaciones Key/Value, N1QL, búsqueda y consultas analíticas, así como vistas. Contiene las conocidas estructuras lógicas Cluster y Bucket, así como las nuevas estructuras Scope y Collections. Los aspectos más destacados pueden agruparse en dos secciones. La primera es la nueva API, que se ha renovado en todos los SDK para ofrecer patrones de acceso más sencillos y preparados para el futuro. La segunda son las mejoras específicas de Go SDK.
Mejoras en la API de valores clave
La API ha sido significativamente adelgazada y reelaborada para que las llamadas a métodos individuales sean más fáciles de encontrar y más uniformes. Para Go esto significa que ya no necesitamos tener múltiples llamadas para funciones similares, pero diferentes. También hemos reducido el número de parámetros necesarios en algunas funciones.
Por ejemplo, en SDK 1.0 había firmas de métodos como:
|
1 2 3 |
func (b *Cubo) Inserte(clave cadena, valor interfaz{}, caducidad uint32) (Cas, error) func (b *Cubo) InsertDura(clave cadena, valor interfaz{}, caducidad uint32, replicateTo, persistTo uint) (Cas, error) func (b *Cubo) Visite(clave cadena, valuePtr interfaz{}) (Cas, error) |
En SDK 2.0 esto ha cambiado a:
|
1 2 |
func (c *Colección) Inserte(clave cadena, val interfaz{}, opta *InsertOptions) (*MutationResult, error) func (c *Colección) Visite(clave cadena, opta *GetOptions) (*ObtenerResultado, error) |
Cada método devuelve un *Resultado y tiene un parámetro opcional llamado *Opciones. Todo lo necesario para que una operación funcione es un parámetro y las propiedades opcionales (como el tiempo de espera, los requisitos de durabilidad, el valor cas, etc.) se han trasladado a bloques de opciones. Esto ha dado lugar a un menor número de funciones "sobrecargadas" y a una API general más sencilla. Los resultados de las operaciones de tipo mutación contienen elementos como los valores CAS y el token de mutación. Para las operaciones de tipo Fetch, los resultados contienen formas de obtener su valor y la caducidad del documento (si se solicita).
Los bloques de opciones son structs con el siguiente aspecto
|
1 2 3 4 5 6 7 8 9 10 11 |
tipo InsertOptions struct { ParentSpanContext opentracing.SpanContext Tiempo de espera tiempo.Duración Contexto contexto.Contexto // La duración de la expiración en segundos Caducidad uint32 PersistTo uint ReplicateTo uint Nivel de durabilidad Nivel de durabilidad Codificador Codificar } |
Esto proporciona mucha más flexibilidad a nivel de operaciones que la API anterior. Esto significa que antes si querías hacer una inserción con persistir a conjunto entonces tenías que hacer InsertDura("llave", "valor", 0, 0, 1) , ahora es sólo Inserte("llave", "valor", &InsertOptions{PersistTo: 1}) .
Ahora tenemos soporte para contexto.Contexto para la cancelación. Lo que esto significa es que puedes usar cosas como tomar el contexto de tu manejador HTTP y suministrarlo directamente a tu operación gocb, de modo que tengas la misma estructura de cancelación usada en todo tu manejador de peticiones HTTP. Si no quieres usar Contexto no se preocupe, puede utilizar el botón Tiempo de espera en su lugar.
Mejoras en la API de consulta
Las API de consulta, al igual que la API de valor clave, utilizan ahora *Opciones para propiedades de consulta opcionales. Anteriormente, las API tenían el aspecto siguiente:
|
1 2 3 4 |
func (c *Grupo) EjecutarN1qlQuery(q *N1qlQuery, parámetros interfaz{}) (Resultados de la consulta, error) func (c *Grupo) EjecutarAnalyticsQuery(q *AnalyticsQuery, parámetros interfaz{}) (AnálisisResultados, error) func (c *Grupo) EjecutarBúsquedaConsulta(q *BúsquedaQuery) (Resultados de la búsqueda, error) func (b *Cubo) ViewQuery(designDoc cadena, viewName cadena, opta *VerOpciones) (*VerResultados, error) |
Ahora parece:
|
1 2 3 4 |
func (c *Grupo) Consulta(declaración cadena, opta *Opciones de consulta) (*Resultados de la consulta, error) func (c *Grupo) AnalyticsQuery(declaración cadena, opta *AnalyticsQueryOptions) (*AnálisisResultados, error) func (c *Grupo) BúsquedaQuery(q BúsquedaQuery, opta *SearchQueryOptions) (*Resultados de la búsqueda, error) func (b *Cubo) ViewQuery(designDoc cadena, viewName cadena, opta *VerOpciones) (*VerResultados, error) |
Los bloques de opciones son demasiado grandes para incluirlos aquí, pero su aspecto y funcionamiento son similares a los del ejemplo de valor clave anterior. También hemos mejorado la coherencia de la API en todos los servicios de consulta actualizando la forma de acceder a los resultados. Todavía estamos trabajando en la transcodificación personalizada de estos resultados. Ahora todos los servicios también utilizan streaming para recuperar los resultados, lo que significa que puedes consultar conjuntos de datos enormes sin tener que preocuparte por quedarte sin memoria.
Mejoras en la gestión de errores
Anteriormente, expusimos errores centinela (p. ej. si err == gocb.ErrKeyNotFound ) que debías comparar si tu operación devolvía un error y tenías tipos de error específicos que debías manejar. Hemos cambiado esto, ahora exponemos los errores como tipos y también proporcionamos funciones de ayuda para categorizar los errores. Ahora puedes hacer si gocb.IsKeyNotFound(err)o escriba el error completo kvErr := err.(gocb.KeyValueError) y accede al contexto subyacente sobre el error si también lo necesitas.
Primeros pasos
Puedes empezar a utilizar todas estas mejoras haciendo: ir consiga github.com/couchbase/gocb@v2.0.0-alfa.3
Una vez que tengas el SDK podrás conectarte a un cluster, abrir un bucket y usar la colección por defecto. Por ahora, a menos que uses el modo Developer Preview en Couchbase Server 6.5, solo podrás usar la colección por defecto.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 |
grupo, err := gocb.Conectar("localhost", gocb.ClusterOptions{Autentificador: gocb.PasswordAuthenticator{ Nombre de usuario: "nombre de usuario", Contraseña: "contraseña", }}) si err != nil { pánico("error de conexión al cluster:" + err.Error()) } cubo := grupo.Cubo("nombre-cubo", nil) colección := cubo.ColecciónPorDefecto(nil) // Ahora puedes realizar operaciones: upsertResultado, err := colección.Upsert("alguna llave", "algún valor", &gocb.UpsertOptions{Tiempo de espera: 10*tiempo.Milisegundo}) si err != nil { pánico(err) } fmt.Imprimir(upsertResultado.Cas()) obtenerResultado, err := colección.Visite("alguna llave", nil) si err != nil { pánico(err) } var miValor cadena err = obtenerResultado.Contenido(&miValor) si err != nil { pánico(err) } ctx, cancelar := contexto.WithTimeout(contexto.Fondo(), 10*tiempo.Milisegundo) aplazar cancelar() resultados, err := grupo.Consulta("SELECT `nombre-cubo`.* from `nombre-cubo` LIMIT 10", &gocb.Opciones de consulta{ Contexto: ctx, }) si err != nil { pánico(err) } var myQueryValue interfaz{} para resultados.Siguiente(&myQueryValue) { } err = resultados.Cerrar() si err != nil { pánico(err) } |
Observe que la apertura de cubos ya no devuelve un error, aunque sigue siendo el lugar donde se produce la conexión. En su lugar, aplazamos la devolución de errores hasta la primera operación. En el futuro podrás comprobar la salud de la conexión del cubo antes de realizar operaciones.
Si quiere saber más, eche un vistazo a nuestro nuevo documentación que también está empezando a cuajar.
La API es bastante nueva, y alfa, por lo que todavía está sujeta a cambios - aunque no debería cambiar drásticamente. Apreciaríamos todos los comentarios y reportes de errores para hacer de este el mejor SDK que hayamos entregado. Esta es tu oportunidad para ayudar a dar forma al futuro del SDK de Couchbase Go.
¿Cómo se versiona?
Todos los SDK se suscriben a la especificación Semantic Versioning 2.0.0 (SemVer) en la que, para cualquier número de versión dado MAYOR.MENOR.PATCHla versión se incrementa cuando:
versión MAJOR cuando realice cambios incompatibles en la API,
versión MINOR cuando se añaden funciones de forma compatible con versiones anteriores, y
Versión PATCH cuando realice correcciones de errores compatibles con versiones anteriores.
Además, para las versiones preliminares y los metadatos de compilación, añadimos extensiones a la especificación SemVer según lo permita. Por ejemplo, nuestras primeras versiones del SDK 2.0 utilizan la designación alfa más un incremento para la versión alfa. Por ejemplo, nuestras primeras versiones preliminares de SDK 2.0 utilizaban la siguiente versión compatible con SemVer: 2.0.0-alfa.1 . La próxima versión preliminar después de las versiones alfa será 2.0.0-beta.1 . Por último, se lanzará una versión GA totalmente compatible 2.0.0 . En general, se esperan cambios de última hora entre las versiones alfa. Los cambios de última hora no deberían producirse (pero en algunos casos pueden ser necesarios) una vez que se publique la versión beta.
Imagen de portada de Maria Letta en el marco de la paquete de topos gratis.
