Apresentando o Ottoman v2.0: Um ODM para Node.js e Couchbase

Em nome da equipe do CouchbaseEstou muito feliz em anunciar a disponibilidade geral do Ottoman 2.0.

Otomana é uma biblioteca Object Document Mapper (ODM) para Couchbase e Node.js que mapeia documentos JSON armazenados no Couchbase para objetos JavaScript nativos. O Ottoman é alimentado por o SDK do Couchbase Node.js e tem suporte integrado para JavaScript e TypeScript.

Um aplicativo da Web típico consiste em um front-end, um back-end e um armazenamento de dados. O Ottoman é um componente em seu backend que atua como um elo entre a estrutura do aplicativo cliente e o CouchbaseSeu armazenamento de dados.

Por que você precisa de um ODM para o Couchbase

A maioria dos aplicativos cliente-servidor precisa de algum tipo de abstração que permita o gerenciamento do acesso aos dados. O termo "acesso a dados" pode parecer trivial para alguns e pode ser rapidamente confundido com operações CRUD (criar, ler, atualizar e excluir) básicas, mas isso não é totalmente exato.

O gerenciamento de dados em um aplicativo moderno vai desde o simples acesso aos dados até a transformação, a validação e a modelagem dos dados de acordo com as necessidades dos diferentes usuários e sistemas. Você pode decidir escolher um banco de dados poliglota e seus padrões de acesso a dados relacionados, mas, de qualquer forma, a qualidade dos seus dados deve ser limpa e legítima.

Se você é um usuário que vem de um banco de dados relacional, talvez já esteja familiarizado com os esquemas e as restrições que vêm nativamente com esses bancos de dados e que garantem a integridade dos dados. No entanto, isso pode ser um desafio quando se usa um banco de dados NoSQL como o Couchbase, em que a estrutura dos dados é fluida.

Nesse caso, talvez você sinta que precisa criar sua própria biblioteca de "gerenciador de esquema", que precisa definir o esquema, criar modelos de dados, validar dados, garantir restrições, gerenciar relacionamentos e muito mais. Criar algo assim por conta própria pode rapidamente sair do controle. Esses sistemas não só são difíceis de manter e escalonar, como também podem acabar sendo propensos a erros e demorados, resultando em atrasos nas entregas e comprometimento da qualidade dos dados.

Encontrar uma biblioteca que já englobe todos os itens acima é essencial. É nesse ponto que um ODM como a Ottoman faz com que tudo pareça fácil.

Como o Ottoman facilita o desenvolvimento em Node.js

Para entender como o Ottoman ajuda suas equipes de desenvolvimento, vamos examinar mais de perto os novos recursos do Ottoman 2.0.

Os exemplos deste blog são baseados no amostra de viagem e são apenas para fins ilustrativos. Além disso, este blog pressupõe que o usuário tenha algum conhecimento básico de escopos e coleções no Couchbase 7.0.

Esquemas e modelos de dados

Documentos JSON em Servidor Couchbase 7.0 pode ser organizado em escopos e coleções, oferecendo aos usuários finais a capacidade de criar aplicativos baseados em microsserviços multilocatários.

No Ottoman, o modelo de dados instrui em qual escopo e coleção o documento está armazenado e fornece vários métodos para acessar esses documentos. Os esquemas, por outro lado, definem a forma do documento.

Vamos dar uma olhada mais de perto em esquemas e modelos com um exemplo simples.

O exemplo de código abaixo define um esquema de companhia aérea que tem cinco campos com algumas restrições e valores padrão especificados. Por exemplo, o campo país só pode ter os valores de Estados Unidos e Canadá e é necessário ao criar um documento. A capacidade, por outro lado, é um número que pode ter um valor máximo de 1000, se especificado.

Por padrão, os esquemas são "rigorosos", o que significa que o Ottoman é instruído a garantir que o documento salvo no banco de dados esteja em conformidade com a estrutura de esquema definida, e quaisquer campos adicionais definidos são ignorados durante o salvamento. Essa opção estrita pode ser substituída usando opções de esquema.

Para usar o airlineSchemaPara isso, é necessário criar um modelo:

O primeiro parâmetro é o nome do modelo, que também é o nome da coleção se não for substituído usando opções de modelos.

Os documentos Ottoman representam um mapeamento de um para um para documentos armazenados no Couchbase. Cada documento é uma instância de seu modelo.

Ao chamar o salvar no método modelo de companhia aérea, você acaba criando um documento dentro do Companhia aérea localizado na coleção Padrão escopo do seu banco de dados do Couchbase.

Carimbos de data/hora

A opção de esquema de registro de data e hora instrui o Ottoman a adicionar automaticamente um createdAt e updatedAt datetime com um valor padrão de data e hora atuais sempre que um documento é criado. Toda vez que o documento é atualizado, o updatedAt também é atualizado.

A seguir, um exemplo de adição de uma opção de carimbo de data/hora ao esquema da companhia aérea:

Essa etapa (acima) basicamente estende o esquema para adicionar implicitamente dois novos campos. Você também pode chamá-los explicitamente, se necessário, e substituir seus nomes, conforme mostrado abaixo:

Imutável

Designar um campo como "Imutável" preserva os valores originais e impede qualquer mutação nos campos designados. Na definição de timestamps do esquema, toda vez que o documento é atualizado, ambos os campos created_at e updated_at são atualizados.

O ideal, no entanto, é que você não queira que seu created_at a ser modificado. Isso ocorre porque ele é usado para rastrear quando um documento foi criado. É nesse ponto que a opção imutável é útil.

Há ocasiões em que você deseja que um campo imutável seja atualizado. Isso é especialmente verdadeiro no caso em que um documento está sendo criado e o campo imutável não tem um valor padrão ou quando, por algum outro motivo, uma atualização é inevitável. Nesse caso, você pode passar uma opção adicional, novo : verdadeiroe, em seguida, para a operação de mutação.

Essa etapa pressupõe que o airlineSchema tem um campo imutável contact, e você está usando a operação de modelo findOneandUpdate em airlineModel.

Ganchos

Ganchos no Ottoman são funções assíncronas de middleware que você escreve e registra com eventos predefinidos nos quais você pode querer agir antes de o evento ser acionado (pré-hooks) ou depois de o evento ser acionado (post-hooks).

Os hooks devem ser definidos antes da definição dos modelos, portanto, é sempre uma boa prática definir os hooks juntamente com a definição do esquema no fluxo de trabalho.

Anteriormente, observamos que o updated_at é atualizado após a mutação. Internamente, isso é feito com a ajuda de um pré-gancho que escuta um evento de atualização.

Normalmente, um gancho recebe o nome do evento como o primeiro argumento, seguido de uma função de retorno de chamada que será eventualmente chamada. Os ganchos podem ser registrados para validar, salvar, atualizar e remover eventos.

Alguns dos casos de uso que você pode considerar para registrar um gancho incluem:

• • Registro em log
  • Limpeza de recursos
  • Envio de notificações
  • Atualização de outros documentos relacionados

Plugins

Um dos principais benefícios de usar o Ottoman é o desenvolvimento ágil, porque você não precisa se repetir. Em vez disso, você acaba criando e usando componentes plugáveis que não apenas economizam tempo e esforço, mas também produzem um código que é fácil de depurar e manter.

Plugins estendem o comportamento dos hooks, permitindo que você componha determinados recursos de modo a criá-los uma vez e aplicá-los a vários esquemas.

Neste ponto, suponha que todos os seus esquemas tenham um campo chamado nomee você deseja alterar o valor para minúsculas sempre que um documento for salvo. Isso pode ser feito com certeza usando um pré-gancho no evento de salvamento, mas você também precisa que isso seja aplicado a todos os esquemas. É nesse caso que os plug-ins podem ser usados.

Nesse caso, você está definindo um plugin "lowercase" que converte o valor associado ao nome do campo em letras minúsculas:

Em seguida, você instrui o esquema a usar o plug-in:

Também é possível registrar plug-ins globalmente para que você possa usá-los em todos os projetos.

Tipos de esquemas personalizados

Fora da caixa, o Ottoman fornece alguns tipos de esquema padrão como string, número, booleano, data, matriz etc. No entanto, há ocasiões em que você pode querer criar um tipo de esquema personalizado complexo que seja reutilizável e bem definido.

Por exemplo, digamos que você queira adicionar website_url para o airlineSchema. Que opções você tem? A única opção disponível é a corda. Não há nada de errado em escolher uma string, no entanto, a única ressalva é que não há garantia de que o website_url é bem formado. Esse é um caso de uso típico em que você deve optar por um tipo de esquema personalizado.

A criação de um tipo de esquema personalizado é um processo de três etapas:

1. Defina o tipo de esquema personalizado:

A função isLink contém a lógica para validar se um URL está bem formado.

2. Registre o tipo de esquema personalizado:

3. Use o tipo de esquema personalizado:

Agora, toda vez que um documento é criado ou atualizado, website_url é validado para um URL bem formado.

Validadores personalizados

Há ocasiões em que a verificação da integridade de um campo vai além do uso de restrições básicas como padrão, mínimo, máximo ou tipos de esquema. Por exemplo, você pode querer declarar um tipo de campo como uma matriz, mas também pode querer restringir o comprimento da matriz. É nesse momento que você deve usar validadores personalizados.

Vamos estender o airlineSchema para aceitar uma matriz de números de telefone, mas não para aceitar mais de dois números de telefone. Primeiro, é necessário registrar o validador usando a função addValidators conforme mostrado abaixo:

Referência

A modelagem de dados - às vezes chamada de "design de documentos" no mundo dos bancos de dados NoSQL - é uma parte essencial do gerenciamento de dados. Em um banco de dados relacional, os dados são armazenados em tabelas e os relacionamentos entre as tabelas são gerenciados por chaves referenciais, também conhecidas como chaves estrangeiras.

No Couchbase, os dados de tipos semelhantes são armazenados nas mesmas coleções, e eles se referem a outros documentos usando uma chave de documento (ou simplesmente "chave"). Quando os documentos são projetados dessa forma, o Ottoman não apenas fornece os meios para fazer referência a eles durante o projeto do esquema, mas também os preenche automaticamente usando o método populate.

Para entender melhor esse recurso, criaremos uma rota definindo um routeSchema e um routeModel. A rota tem um companhia aérea que se refere a um modelo de companhia aérea usando o campo ref palavra-chave.

Abaixo, criamos um documento de rota que faz referência ao companhia aérea id 10.

Ao chamar o salvar no método routeModel você cria um documento no Rota localizado na coleção Padrão escopo do banco de dados do Couchbase.

Por fim, recuperamos o documento e o preenchemos.

Recuperamos o documento de rota com os dados da companhia aérea incorporados, conforme mostrado abaixo:

Criador de consultas

O Ottoman tem uma API muito rica que lida com muitas operações complexas suportadas pelo Couchbase e pelo a linguagem de consulta SQL++ (anteriormente conhecido como N1QL, conforme usado abaixo).

O Criador de consultas O Query Builder cria as instruções N1QL nos bastidores para você. Ao usar o Query Builder, você tem três opções de modo:

• • Usar parâmetros
  • Funções de acesso
  • Parâmetros e funções de acesso

Índices

Índices desempenham um papel importante no acesso aos seus documentos a partir do banco de dados do Couchbase.

Não ter os índices corretos no lugar pode resultar em uma degradação do desempenho. Portanto, é essencial conhecer o design do documento (ou seja, o modelo de dados) e as consultas que você usará com antecedência. A criação de índices é uma etapa crucial ao trabalhar com dados. O Ottoman oferece três tipos de índices que você pode associar ao seu esquema.

Tipo de índice #1: NIQL

O índice N1QL é o tipo de índice padrão usado pelo Ottoman e, às vezes, também é chamado de GSI ou índices secundários globais. Durante o processo de inicialização, o Ottoman cria automaticamente vários índices secundários, garantindo que algumas das operações básicas sejam eficientes desde o início. Esse é o mais recomendado tipo de índice.

Tipo de índice #2: Refdoc

O tipo de índice refdoc gerencia determinados requisitos em que a exclusividade precisa ser garantida. Há alguns aspectos importantes dos quais você precisa estar ciente antes de considerar um índice refdoc:

• • Os índices refdoc são estritamente gerenciados pelo Ottoman e não pelo banco de dados Couchbase. Isso significa que qualquer atualização feita no documento fora do Ottoman fará com que o índice refdoc fique fora de sincronia.
  • Os índices refdoc criam um documento binário adicional que contém referências à chave do documento que está sendo indexado. Em resumo, você verá um documento adicional para cada documento criado que usa o índice refdoc.

Por exemplo, digamos que você queira garantir que website_url em airlineSchema é exclusivo. Você criaria um índice refdoc conforme mostrado abaixo:

A prática recomendada geral para o índice refdoc é ter cuidado e lidar com a mutação de dados estritamente por meio do Ottoman.

Tipo de índice #3: Visualizações

Esse tipo de índice está obsoleto e será removido em breve. Esse tipo de índice existe apenas para compatibilidade com versões anteriores. O uso desse índice é fortemente desencorajado.

Enxuto

O Ottoman oferece muitos métodos de modelo para recuperar documentos de uma coleção. Esses métodos incluem encontrar, findById, findOneetc.

O encontrar é de longe o mais popular e retorna vários documentos com base na condição de pesquisa especificada. A recuperação de um grande número de documentos de uma só vez a partir de uma coleção acarreta uma sobrecarga de desempenho que talvez você não veja ao trabalhar com um conjunto menor de documentos. A sobrecarga se deve principalmente ao fato de que todos os métodos de modelo especificados retornam uma instância da classe Ottoman Document, que contém muitas informações de rastreamento do Ottoman-internal-state-of-change-tracking.

Ativação da opção enxuta diz ao Ottoman para pular a instanciação de um documento Ottoman completo e, em vez disso, retornar apenas o objeto JavaScript antigo e simples (POJO).

Embora isso possa aumentar o desempenho, é uma desvantagem em relação aos recursos integrados do Ottoman, como rastreamento de alterações, validações, ganchos e métodos de modelo típicos, como salvar, remover etc. Portanto, é recomendável usar enxuto com extrema cautela e consciência.

O resultado no exemplo acima terá todos os documentos da companhia aérea em que o nome é como americanomas todos esses documentos serão JavaScript simples (ou seja, você perde toda a magia associada a um documento otomano).

Métodos de modelo

Navios modelo da Ottoman com vários métodos auxiliares que atendem a diferentes finalidades. A seguir estão alguns dos métodos de modelo usados com mais frequência:

encontrar: encontrar é um método genérico que usa o Serviço de Consulta nos bastidores e é usado para recuperar um ou mais documentos de uma coleção do Couchbase com base na condição de filtro fornecida. Uma maneira eficiente de usar o encontrar garante a criação de índices secundários apropriados (ou seja, índices N1QL).

A seguinte operação de busca retorna todos os documentos de companhias aéreas em que o país é os Estados Unidos e ignora a diferenciação de maiúsculas e minúsculas.

findOneAndUpdate: encontrar é um documento único com base na condição de filtro passada a ele e atualiza o documento com os novos valores fornecidos. Passando uma opção upsert : true garante que um novo documento seja criado caso nenhum documento correspondente seja encontrado.

Operações em massa: Há casos em que você pode querer alterar mais de um documento ao mesmo tempo. O Ottoman vem com três métodos de modelo que ajudam com essa preocupação, e todos eles usam o Query Service nos bastidores:

• • createMany: Cria vários documentos em uma única chamada
  • removeMany: Remove vários documentos em uma única chamada
  • updateMany: Atualiza vários documentos em uma única chamada

O status da resposta para todas as operações em massa será "Success" (Sucesso), desde que não ocorra nenhum erro; caso contrário, será "Failure" (Falha).

Depuração

Como você já viu, há várias operações de modelo que usam a linguagem de consulta N1QL nos bastidores. Otimizar a consulta N1QL e criar os índices corretos é uma parte essencial do desenvolvimento.

Para fazer isso, é importante saber que tipo de consulta N1QL está sendo usada por essas operações de modelo. O Ottoman permite a depuração o que resulta na impressão de instruções N1QL no console de desenvolvimento, que podem ser efetivamente usadas pelo desenvolvedor para analisar e criar índices usando a interface do usuário apropriadamente.

Qual é a diferença entre o Ottoman e o SDK do Node.js?

Embora o Ottoman seja alimentado pelo SDK do Node.js, vale a pena observar que há determinados recursos que só estão disponíveis para você por meio do Ottoman. Talvez você queira considerar os seguintes recursos ao escolher um em vez do outro.

Outros benefícios do uso da otomana

Espero que você esteja animado e preparado para escrever seu primeiro aplicativo usando o Ottoman. A seguir estão alguns dos principais motivos pelos quais nossos clientes preferem o Ottoman:

Adaptabilidade
Você não precisa de habilidades especializadas, basta conhecer JavaScript ou TypeScript e pronto.

Acessibilidade
Aproveite todos os benefícios de ser de código aberto. Sem aprisionamento a um fornecedor, com redução de despesas de capital e sem licenças proprietárias, etc.

Capacidade de suporte e sustentabilidade
Deixe conosco o ônus da varredura e da aplicação de patches de vulnerabilidades de segurança no software. Obtenha atualizações constantes do software para se alinhar com as versões do servidor e obtenha suporte total da nossa equipe de suporte e da grande comunidade de desenvolvedores.

Agilidade
Seja um líder em seu espaço: crie e forneça aplicativos de forma rápida e oportuna. Não há necessidade de criar seus aplicativos camada de dados do zero. Gaste seu tempo resolvendo problemas de negócios em vez de codificá-los. Escreva blocos de código menores que sejam fáceis de manter e ler. Seu código terá a mesma aparência mesmo depois de muitas iterações, porque é simples assim.

Qualidade dos dados
Garantir a qualidade dos dados usando esquemas, validadores, restrições e outros módulos disponíveis. Produza código livre de erros com o encanamento do Ottoman, que é o resultado de uma observação bem pensada e elaborada de desafios repetitivos de design e desenvolvimento. O Ottoman resolve muitos problemas comuns que, de outra forma, poderiam ser difíceis e propensos a erros se fossem codificados manualmente.

Comece a usar o Ottoman hoje mesmo

Agora que você tem um entendimento básico de por que e quando deve considerar o Ottoman para seu próximo projeto Node.js, é hora de colocar a mão na massa!

Aqui estão alguns links úteis para você começar:

• • Leia a documentação otomana
  • Contribua com o repositório Ottoman
  • Faça (ou responda!) uma pergunta nos fóruns do Couchbase
  • Leia a postagem do blog sobre o Ottoman 1.0
  • Ouça um podcast sobre a Otomana
  • Assista à apresentação do Couchbase Connect de 2020 sobre o Ottoman