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 *Bucket) Insert(key string, value interface{}, expiry uint32) (Cas, error) func (b *Bucket) InsertDura(key string, value interface{}, expiry uint32, replicateTo, persistTo uint) (Cas, error) func (b *Bucket) Get(key string, valuePtr interface{}) (Cas, error) |
No SDK 2.0, isso foi alterado para:
|
1 2 |
func (c *Collection) Insert(key string, val interface{}, opts *InsertOptions) (*MutationResult, error) func (c *Collection) Get(key string, opts *GetOptions) (*GetResult, error) |
Cada método retorna um *Result e tem um parâmetro opcional chamado *Options. 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 |
type InsertOptions struct { ParentSpanContext opentracing.SpanContext Timeout time.Duration Context context.Context // The expiration length in seconds Expiration uint32 PersistTo uint ReplicateTo uint DurabilityLevel DurabilityLevel Encoder Encode } |
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 persist to definido então você tinha que fazer InsertDura("key", "value", 0, 0, 1) agora é apenas Insert("key", "value", &InsertOptions{PersistTo: 1}) .
Agora temos suporte para context.Context 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 Context para tempos limite, então não se preocupe, você pode simplesmente usar o Timeout em vez disso.
Aprimoramentos da API de consulta
As APIs de consulta, assim como a API de valor-chave, agora usam *Options para propriedades de consulta opcionais. Anteriormente, as APIs eram semelhantes a:
|
1 2 3 4 |
func (c *Cluster) ExecuteN1qlQuery(q *N1qlQuery, params interface{}) (QueryResults, error) func (c *Cluster) ExecuteAnalyticsQuery(q *AnalyticsQuery, params interface{}) (AnalyticsResults, error) func (c *Cluster) ExecuteSearchQuery(q *SearchQuery) (SearchResults, error) func (b *Bucket) ViewQuery(designDoc string, viewName string, opts *ViewOptions) (*ViewResults, error) |
Agora parece:
|
1 2 3 4 |
func (c *Cluster) Query(statement string, opts *QueryOptions) (*QueryResults, error) func (c *Cluster) AnalyticsQuery(statement string, opts *AnalyticsQueryOptions) (*AnalyticsResults, error) func (c *Cluster) SearchQuery(q SearchQuery, opts *SearchQueryOptions) (*SearchResults, error) func (b *Bucket) ViewQuery(designDoc string, viewName string, opts *ViewOptions) (*ViewResults, error) |
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 if err == 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 if gocb.IsKeyNotFound(err)ou digite assert o erro inteiro kvErr := err.(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: go get github.com/couchbase/gocb@v2.0.0-alpha.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 |
cluster, err := gocb.Connect("localhost", gocb.ClusterOptions{Authenticator: gocb.PasswordAuthenticator{ Username: "username", Password: "password", }}) if err != nil { panic("error connecting to cluster:" + err.Error()) } bucket := cluster.Bucket("bucket-name", nil) collection := bucket.DefaultCollection(nil) // Now you can perform operations: upsertResult, err := collection.Upsert("somekey", "somevalue", &gocb.UpsertOptions{Timeout: 10*time.Millisecond}) if err != nil { panic(err) } fmt.Println(upsertResult.Cas()) getResult, err := collection.Get("somekey", nil) if err != nil { panic(err) } var myValue string err = getResult.Content(&myValue) if err != nil { panic(err) } ctx, cancel := context.WithTimeout(context.Background(), 10*time.Millisecond) defer cancel() results, err := cluster.Query("SELECT `bucket-name`.* from `bucket-name` LIMIT 10", &gocb.QueryOptions{ Context: ctx, }) if err != nil { panic(err) } var myQueryValue interface{} for results.Next(&myQueryValue) { } err = results.Close() if err != nil { panic(err) } |
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 MAJOR.MINOR.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-alpha.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.
