O que há em um SDK?
O Couchbase Server oferece vários serviços para armazenar, recuperar, consultar e analisar seus dados. Cada serviço expõe uma API pública como API REST ou por meio do protocolo binário Memcached estendido de nível inferior. Com a autenticação adequada e as portas abertas, qualquer aplicativo pode usar essas APIs, mas elas têm um custo, uma complexidade e a falta de segurança de tipo na maioria das vezes. Sejamos francos, a maioria dos desenvolvedores de aplicativos não está preocupada em analisar uma resposta REST ou desempacotar pacotes do Memcached; eles querem criar suas soluções de forma rápida e eficiente para resolver suas necessidades comerciais exclusivas. Eles querem uma biblioteca que lide com gerenciamento de recursos, fragmentação, gerenciamento de alterações na topologia do cluster etc., que é a função do SDK do Couchbase.
Por que estamos mudando?
O SDK 1.0 estava alinhado com o Couchbase Server 1.x e suportava principalmente a leitura/gravação de pares de chave/valor em um formato binário e JSON usando o protocolo Memcached e as visualizações. Os SDKs foram desenvolvidos independentemente uns dos outros e não tinham uma interface de API consistente. Em alguns casos, as diferenças de empacotamento do Memcached tornavam os dados não compartilháveis entre os SDKs.
O SDK 2.0 oferecia suporte a novos recursos do Couchbase Server à medida que ele evoluía: N1QL, a linguagem semelhante ao SQL para consultar documentos JSON armazenados no Couchbase Server, autenticação aprimorada usando RBAC (Role Based Access Control, controle de acesso baseado em função), suporte aprimorado a JSON, análise, FTS (Full Text Search, pesquisa de texto completo) e outras ferramentas para interagir com seus dados. Na versão 2.X, alinhamos as interfaces e as tornamos consistentes, em sua maior parte, em todos os SDKs usando uma RFC para garantir a adesão às interfaces definidas e incluímos um componente Common Flags para garantir que os dados pudessem ser gravados e lidos em qualquer SDK. No lado negativo, a interface do IBucket ficou inchada e difícil de usar, pois várias APIs foram amontoadas nela.
O SDK 3.0 está alinhado com os novos recursos do Couchbase Server que se estendem da interface tradicional do Bucket: suporte para Escopos e Coleções que estarão disponíveis como um Visualização para desenvolvedores no Couchbase Server 6.5 e como GA no Couchbase Server 7.0. Além disso, ele consolida e refina as interfaces formalmente inchadas e baseadas em sobrecarga em uma interface menor e mais concisa, mantendo e melhorando a conformidade entre os SDKs.
Como fazemos a versão?
Todos os SDKs assinam o Controle de versão semântico 2.0.0 Especificação (SemVer) em que, para um determinado número de versão MAIOR.MENOR.PATCH é incrementado quando:
- MAIOR quando você faz alterações incompatíveis na API,
- MENOR quando você adiciona funcionalidades de forma compatível com as versões anteriores, e
- PATCH quando você faz correções de bugs compatíveis com as 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 3.0 usam a designação "alfa" mais um incremento para a versão alfa. Por exemplo, nossas primeiras visualizações do SDK 3.0 usaram a seguinte versão compatível com o SemVer: "3.0.0-alpha1". O próximo pré-lançamento, após as versões alfa, será "3.0.0-beta1" e, finalmente, uma versão GA totalmente compatível será "3.0.0". Em geral, espere mudanças significativas entre as versões "alfa", que não devem ocorrer (mas, em alguns casos, podem ser necessárias) quando a versão "beta" for lançada.
Observe que há uma pequena discrepância entre as versões do servidor, pois o Couchbase Server oferecerá pré-lançamentos como "developer previews" ou "dp" e, em seguida, "beta" e, finalmente, GA.
Escopos e coleções no Couchbase Server 6.5+
Nas versões do Couchbase Servers anteriores à 6.5, os Buckets eram usados como uma entidade lógica, nomeada pelo usuário, que agrupava itens, permitindo que 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 são bastante intensivos em recursos e um cluster só pode gerenciar com eficiência um número finito de buckets. Para arquiteturas de microsserviço modernas ou qualquer arquitetura em que o multilocatário fosse necessário, isso criava alguns desafios ao atender a uma grande quantidade de locatários. Isso é resolvido no Couchbase Server 6.5+ por Escopos e Coleções.
Um escopo no Couchbase 6.5+ representa uma unidade de multilocação e permite que os nomes de coleções sejam reutilizados; qualquer escopo pode conter exatamente um nome de coleção exclusivo. Um escopo é simplesmente um grupo de coleções. Cada Bucket contém um Escopo padrão com o nome "_default" e um identificador de escopo 0 (zero) que contém uma coleção padrão chamada "_default" e seu respectivo identificador de 0 (zero). Obviamente, para cada escopo específico, podem ser criadas várias coleções.
Isso tem o efeito de mover as operações de chave/valor que estavam no contexto do Bucket para SDK1.0 e SDK2.0 para o contexto da Coleção para SDK3.0. Ao mesmo tempo, as operações entre buckets, como FTS, Analytics e N1QL, agora são feitas no nível do cluster.
Série alfa do .NET SDK 3.0
O primeiro pacote de despejo do Couchbase .NET SDK 3.0 foi o Couchbase Alfa 2 (O Alpha 1 continha um bug que tornou necessário o lançamento e o aumento da versão). Alfa 3 foi lançado em 26 de abril - planejamos lançar vários outros! O foco em um pré-lançamento é fornecer os bits para programar operações de chave/valor e consultas N1QL no Couchbase Server. Ele contém as conhecidas estruturas lógicas Cluster e Bucket, bem como as novas estruturas Scope e Collections. Observe que, embora os escopos e as coleções façam parte do Couchbase 6.5, que não será lançado até o final deste ano ou no ano que vem, o SDK 3.0 também oferece suporte ao Couchbase 5.0 e superior usando o escopo e a coleção padrão explicados anteriormente.
Cluster e buckets no SDK 3.0
Assim como no SDK 2.0, os objetos Cluster e Bucket estão de volta no SDK 3.0, cada um representando suas equivalências de servidor. A conexão a um cluster e a abertura de um bucket são feitas de maneira semelhante à do SDK2.0:
|
1 2 3 4 5 6 7 8 |
/Configurar e abrir um objeto de cluster var agrupamento = novo Aglomerado(novo Configuração(). Com servidores("couchbase://localhost"). ComBucket("default"). ComCredenciais("Administrador", "senha")); //abrir um bucket chamado "default" var balde = aguardar Aglomerado.Balde("default"); |
Semelhante ao SDK2.0, os objetos Cluster e Bucket são objetos de longa duração, cuja vida útil geralmente vai da inicialização do aplicativo até o seu encerramento.
Usando o escopo e as coleções padrão no Couchbase Server 6.0
Todas as operações de chave/valor agora existem no nível das coleções, que sempre serão membros de exatamente um escopo. Aqui estão alguns exemplos de acesso a uma coleção e, em seguida, de leitura e gravação de dados na coleção.
|
1 2 3 4 5 6 7 8 9 10 11 |
//abrir a coleção/escopo padrão var coleção = aguardar balde.GetDefaultCollection(); //adicionar um novo documento aguardar coleção.Inserir(chave, novo {nome = "mike"}); //recuperar o documento usando (var resultado = aguardar coleção.Obter(chave)) { var conteúdo = resultado.ContentAs<dinâmico>(); Console.WriteLine(conteúdo.nome); } |
Observe que estamos usando o Couchbase Server 6.0 e, portanto, não temos suporte para Scope ou Collection (eles não estarão disponíveis até o Server 6.5); no entanto, podemos usar o Scope e a Collection "padrão" como se tivéssemos suporte para Scope e Collections. Observe que isso foi adicionado como um recurso de atualização para migrar para a versão mais recente do servidor. O escopo e a coleção "padrão" sempre estarão disponíveis; é semelhante ao funcionamento de um bucket nos SDKs anteriores à versão 3.0.
Observe que, após buscar um documento, o GetResult deve ser descartado para liberar recursos, caso contrário, os buffers internos serão "vazados"; essa é uma alteração do SDK 1.0 e 2.0.
Uso do escopo nomeado e das coleções no Couchbase Server 6.5+
Esse é o futuro do Couchbase: a capacidade de dividir um Bucket em vários escopos lógicos (multilocação) e coleções de documentos distintos. Isso substitui a exigência das primeiras versões do servidor Couchbase de adicionar um campo especial de "tipo" que designava uma espécie de agrupamento de documentos por nome, que poderia ser consultado independentemente em um Bucket. Acredito que você descobrirá que esse é um modelo de programação muito mais intuitivo e que permitirá avanços futuros dos recursos do servidor no futuro.
|
1 2 3 4 5 6 7 8 9 10 11 12 |
/Abrir um escopo e, em seguida, uma coleção var escopo = aguardar balde.Escopo("ACME"); var coleção = aguardar escopo.Coleção("ferramentas"); //adicionar um novo documentawait coleção.Inserir(chave, novo Ferramenta(Nome = "Martelo", Tipo="Bola peen"}); //recuperar o documento usando (var resultado = aguardar coleção.Obter(chave)) { var conteúdo = resultado.ContentAs<Ferramenta>(); Console.WriteLine(conteúdo.Nome); } |
Uso do cluster para consultas N1QL
O N1QL, assim como o Analytics e o FTS, é considerado de escopo "global", pois uma consulta pode fazer referência a vários Buckets. Inicialmente, no SDK 2.0, as consultas N1QL tinham escopo para o Bucket e, posteriormente, foram adicionadas ao Cluster. No SDK 3.0, atualmente, você só pode consultar a partir do objeto Cluster.
|
1 2 3 4 5 6 7 8 9 10 11 12 |
//executar uma consulta no cluster var declaração = "SELECT * FROM `default` WHERE type=$name;"; var resultado = aguardar agrupamento.Consulta<dinâmico>(declaração, parâmetros =>{parâmetros.Adicionar("name" (nome), "pessoa");}); //enumerar as linhas retornadas antes de(var fila em resultado){ Console.WriteLine(fila.nome); } //liberar os buffers internos resultado.Descarte(); |
De modo geral, todos os serviços (Query, FTS e Analytics) têm uma API pública muito semelhante à do SDK 2.0; no entanto, para fins de consistência, o campo obrigatório (a instrução SQL para N1QL) foi adicionado como um parâmetro no lado esquerdo e os parâmetros opcionais agora estão consolidados em um bloco ou estrutura de "opções" no lado direito. Você perceberá que isso continua em todo o SDK e melhora muito a consistência da API.
Obtendo as versões alfa do SDK do Couchbase .NET 3.0
Assim como em todas as versões do SDK do Couchbase .NET, oferecemos a opção de downloads do pacote NuGet e também será publicado no NuGet.
Por fim, um agradecimento especial a Brant Burnett, da Centeredge Software, por contribuir enormemente para o lançamento!
3.0 significa que você tem permissão para fazer alterações significativas?
Por que não seguir a convenção de sufixar métodos com Async quando eles são Async?
Olá, Thomas.
Sim, há muitas mudanças significativas - a API pública foi completamente reescrita a partir do SDK 2.X.
A razão para não usar o sufixo "Async" é que não há métodos de sincronização, portanto, não há motivo para diferenciar entre chamadas síncronas e assíncronas. Observe que isso pode mudar em versões futuras à medida que recebermos mais comentários como o seu.
Obrigado pelo feedback!
-Jeff