Tenho o prazer de anunciar o Couchbase Go SDK 2.0 Alpha. Esse novo SDK traz uma série de alterações em todos os SDKs do Couchbase que a equipe vem desenvolvendo. Os novos SDKs trazem uma API completamente nova que é mais simples, preparada para o futuro e se integra aos desenvolvimentos mais recentes do ecossistema.
A versão 2.0 do Go SDK está alinhada com os novos recursos do Couchbase Server que se estendem para fora da interface tradicional do Bucket: suporte para escopos e coleções. Além disso, ela consolida e refina a interface, melhorando a conformidade entre SDKs.
Novos recursos do Couchbase Server: Escopos e coleções
Nas versões anteriores do Couchbase Server, os Buckets eram usados como entidades lógicas, nomeadas pelo usuário, que agrupavam itens. Isso permitia que eles fossem acessados, indexados, replicados e controlados por acesso. Esse era realmente o único meio de obter multitenancy usando o Couchbase Server e vinha com algumas limitações: Os próprios buckets consomem bastante recursos e um cluster só pode gerenciar com eficiência um número finito de buckets. Para arquiteturas de microsserviço modernas ou, na verdade, para qualquer arquitetura em que o multilocatário fosse necessário, isso criava alguns desafios ao atender a uma grande quantidade de locatários. Isso será resolvido em uma versão futura do Couchbase Server com os conceitos de Escopos e Coleções.
Um escopo representa uma unidade de vários locatários e é criado a partir de coleções. Uma coleção é efetivamente um nome exclusivo para um grupo de documentos. Dentro de um escopo, o nome de uma coleção deve ser exclusivo, mas o mesmo nome de coleção pode ser usado em vários escopos. Cada Bucket contém um Escopo padrão com o nome "_default" com um identificador de 0 (zero) que contém uma Coleção padrão chamada "_default" com seu identificador de acompanhamento de 0 (zero).
Isso tem o efeito de mover as operações de chave/valor que estavam no contexto do bucket do SDK 1.0 para o contexto da coleção do SDK 2.0. As operações entre buckets, como Search, Analytics e N1QL, agora são feitas no nível do cluster.
O Couchbase Server 6.5 oferecerá suporte a escopos e coleções como parte do "Developer Preview", o Developer Preview é não suportado para uso em produção. Enquanto isso, o SDK 2.0 também oferece suporte ao Couchbase 5.0 e superior usando o escopo e a coleção padrão.
Destaques da API do SDK 2.0
O foco desse alfa é fornecer a API para usar o Couchbase Server com operações de chave/valor, N1QL, pesquisa e consultas analíticas, além de exibições. Ele contém as estruturas lógicas conhecidas de Cluster e Bucket, bem como as novas estruturas de Escopo e Coleções. Os destaques podem ser agrupados em duas seções. A primeira é a nova API, que foi reformulada em todos os SDKs para oferecer padrões de acesso mais simples e mais preparados para o futuro. A segunda são os aprimoramentos específicos do Go SDK.
Aprimoramentos da API de valor-chave
A API foi significativamente reduzida e reformulada para que as chamadas de métodos individuais sejam mais fáceis de encontrar e mais uniformes. Para o Go, isso significa que não precisamos mais ter várias chamadas para funções semelhantes, mas diferentes. Também reduzimos o número de parâmetros necessários em algumas funções.
Por exemplo, no SDK 1.0, havia assinaturas de métodos como:
|
1 2 3 |
func (b *Balde) Inserir(chave string, valor interface{}, expiração uint32) (Cas, erro) func (b *Balde) InsertDura(chave string, valor interface{}, expiração uint32, replicarPara, persistTo uint) (Cas, erro) func (b *Balde) Obter(chave string, valuePtr interface{}) (Cas, erro) |
No SDK 2.0, isso foi alterado para:
|
1 2 |
func (c *Coleção) Inserir(chave string, val interface{}, opts *InsertOptions) (*Resultado da mutação, erro) func (c *Coleção) Obter(chave string, opts *GetOptions) (*ObterResultado, erro) |
Cada método retorna um *Resultado e tem um parâmetro opcional chamado *Opções. Tudo o que é necessário para que uma operação funcione é um parâmetro e as propriedades opcionais (como o tempo limite, os requisitos de durabilidade, o valor cas etc.) foram todas movidas para blocos de opções. Isso resultou em menos funções "sobrecarregadas" e em uma API geral mais simples. Os resultados da operação do tipo Mutação contêm coisas como valores CAS e Token de Mutação. Para operações do tipo Fetch, os resultados contêm maneiras de obter seu valor e a expiração do documento (se solicitado).
Os blocos de opções são estruturas que se parecem com:
|
1 2 3 4 5 6 7 8 9 10 11 |
tipo InsertOptions estrutura { ParentSpanContext rastreamento aberto.SpanContext Tempo limite tempo.Duração Contexto contexto.Contexto // A duração da expiração em segundos Vencimento uint32 PersistTo uint ReplicarPara uint Nível de durabilidade Nível de durabilidade Codificador Codificar } |
Isso proporciona muito mais flexibilidade em um nível de operação do que a API anterior. Isso significa que, anteriormente, se você quisesse fazer uma inserção com persistir para definido então você tinha que fazer InsertDura("chave", "valor", 0, 0, 1) agora é apenas Inserir("chave", "valor", &InsertOptions{PersistTo: 1}) .
Agora temos suporte para contexto.Contexto para cancelamento. Isso significa que você pode usar coisas como pegar o contexto do seu manipulador HTTP e fornecê-lo diretamente na sua operação gocb, de modo que você tenha a mesma estrutura de cancelamento usada em todo o seu manipulador de solicitações HTTP. Se você não quiser usar o Contexto para tempos limite, então não se preocupe, você pode simplesmente usar o Tempo limite em vez disso.
Aprimoramentos da API de consulta
As APIs de consulta, assim como a API de valor-chave, agora usam *Opções para propriedades de consulta opcionais. Anteriormente, as APIs eram semelhantes a:
|
1 2 3 4 |
func (c *Aglomerado) ExecutarN1qlQuery(q *N1qlQuery, parâmetros interface{}) (Resultados da consulta, erro) func (c *Aglomerado) ExecuteAnalyticsQuery(q *AnalyticsQuery, parâmetros interface{}) (Resultados da análise, erro) func (c *Aglomerado) ExecuteSearchQuery(q *Pesquisa) (Resultados da pesquisa, erro) func (b *Balde) Consulta(designDoc string, viewName string, opts *ViewOptions) (*Exibir resultados, erro) |
Agora parece:
|
1 2 3 4 |
func (c *Aglomerado) Consulta(declaração string, opts *Opções de consulta) (*Resultados da consulta, erro) func (c *Aglomerado) AnalyticsQuery(declaração string, opts *AnalyticsQueryOptions) (*Resultados da análise, erro) func (c *Aglomerado) Pesquisa(q Pesquisa, opts *Opções de pesquisa (SearchQueryOptions)) (*Resultados da pesquisa, erro) func (b *Balde) Consulta(designDoc string, viewName string, opts *ViewOptions) (*Exibir resultados, erro) |
Os blocos de opções para eles são grandes demais para serem incluídos aqui, mas têm aparência e funcionam de forma semelhante ao exemplo do Key Value acima. Também melhoramos a consistência da API nos serviços de consulta, atualizando a forma como os resultados são acessados. Ainda estamos trabalhando na transcodificação personalizada desses resultados. Todos os serviços agora também usam streaming para recuperar os resultados, o que significa que você pode consultar conjuntos de dados enormes sem ter que se preocupar com a falta de memória.
Aprimoramentos no tratamento de erros
Anteriormente, expusemos erros sentinelas (por exemplo se erro == gocb.ErrKeyNotFound ) que você tinha que comparar se a sua operação retornasse um erro e você tinha tipos de erro específicos que precisava tratar. Nós mudamos isso, agora expomos os erros como tipos e também fornecemos funções auxiliares para categorizar os erros. Agora você pode fazer se gocb.IsKeyNotFound(erro)ou digite assert o erro inteiro kvErr := erro.(gocb.KeyValueError) e obter acesso ao contexto subjacente sobre o erro, se precisar disso também.
Primeiros passos
Você pode começar a usar todos esses aprimoramentos fazendo isso: ir obter github.com/couchbase/gocb@v2.0.0-alfa.3
Depois de ter o SDK, você poderá se conectar a um cluster, abrir um bucket e usar a coleção padrão. Por enquanto, a menos que você use o modo Developer Preview no Couchbase Server 6.5, só poderá usar a coleção padrão.
|
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 |
agrupamento, erro := gocb.Conectar("localhost", gocb.ClusterOptions{Autenticador: gocb.PasswordAuthenticator{ Nome de usuário: "nome de usuário", Senha: "senha", }}) se erro != nulo { pânico("erro ao se conectar ao cluster:" + erro.Erro()) } balde := agrupamento.Balde("bucket-name" (nome do balde), nulo) coleção := balde.Coleção Padrão(nulo) // Agora você pode realizar operações: upsertResult, erro := coleção.Upsert("somekey", "somevalue" (algum valor), &gocb.UpsertOptions{Tempo limite: 10*tempo.Milissegundos}) se erro != nulo { pânico(erro) } fmt.Println(upsertResult.Cas()) getResult, erro := coleção.Obter("somekey", nulo) se erro != nulo { pânico(erro) } var myValue string erro = getResult.Conteúdo(&myValue) se erro != nulo { pânico(erro) } ctx, cancelar := contexto.Com tempo limite(contexto.Histórico(), 10*tempo.Milissegundos) adiar cancelar() resultados, erro := agrupamento.Consulta("SELECT `nome-do-bucket`.* from `nome-do-bucket` LIMIT 10", &gocb.Opções de consulta{ Contexto: ctx, }) se erro != nulo { pânico(erro) } var myQueryValue interface{} para resultados.Próximo(&myQueryValue) { } erro = resultados.Fechar() se erro != nulo { pânico(erro) } |
Observe que o bucket open não retorna mais um erro, embora ainda seja onde a conexão ocorre. Em vez disso, adiamos o retorno de erros até a primeira operação. No futuro, você poderá verificar a integridade da conexão do bucket antes de executar as operações.
Se quiser saber mais, dê uma olhada em nosso novo documentação que também está começando a se encaixar.
A API é bastante nova e alfa, portanto, ainda está sujeita a alterações, embora não deva mudar drasticamente. Gostaríamos muito de receber todos os comentários e relatórios de bugs para fazer deste o melhor SDK que já entregamos. Esta é a sua chance de ajudar a moldar o futuro do SDK do Couchbase Go.
Como fazemos a versão?
Todos os SDKs assinam a especificação Semantic Versioning 2.0.0 (SemVer), na qual, para qualquer número de versão MAIOR.MENOR.PATCHa versão é incrementada quando:
versão MAJOR quando você faz alterações incompatíveis na API,
Versão MENOR, quando você adiciona funcionalidade de forma compatível com as versões anteriores, e
Versão PATCH quando você faz correções de bugs compatíveis com versões anteriores.
Além disso, para pré-lançamentos e metadados de compilação, adicionamos extensões à especificação SemVer, conforme permitido por ela. Por exemplo, nossas primeiras versões do SDK 2.0 usam a designação alfa mais um incremento para a versão alfa. Por exemplo, nossas primeiras visualizações do SDK 2.0 usaram a seguinte versão compatível com o SemVer: 2.0.0-alfa.1 . O próximo pré-lançamento após as versões alfa será 2.0.0-beta.1 . Por fim, uma versão GA com suporte total será 2.0.0 . Em geral, espere mudanças significativas entre as versões alfa. As mudanças significativas não devem ocorrer (mas, em alguns casos, podem ser necessárias) quando a versão beta for lançada.
Imagem da capa por Maria Letta como parte da pacote gratuito de gophers.
