Criar uma API REST usando um ODM com Couchbase + Node.js + Express e Ottoman

Histórico

Couchbase + Nodejs = desenvolvimento rápido

No ano passado, o proprietário de todas as coisas nodejs no Couchbase, Brett Lawson, estreou uma prévia de nosso ODM (Object Data Mapper) para Node.js, conhecido como "Ottoman". Desde então, ele tem sido consistentemente um dos itens mais solicitados pelos desenvolvedores de nós do Couchbase - "quando poderemos ter o Ottoman?" Chegou a hora! Com o lançamento oficial do Ottoman, tenho o prazer de apresentar um passo a passo da criação de um aplicativo nodejs de amostra e como o uso do Couchbase e do Ottoman facilita uma experiência de desenvolvimento rápida e poderosa, especialmente ao criar APIs REST e prototipar modelos de dados complexos.

Por que otomano?

Por que é tão desejável ter um ODM - já existe um cliente Node.js realmente maduro para o Couchbase? Para entender a resposta a essa pergunta, vejamos um exemplo do mundo real de um aplicativo de inventário para uma concessionária de motocicletas criado usando Node.js e Couchbase.

Pilote mais, codifique menos

• Um ODM permite que o desenvolvedor:
• Trabalhar nativamente com objetos. A partir do nodejs v0.12, isso se tornará cada vez mais importante
• Prototipar e definir rapidamente seu modelo de dados, incluindo relacionamentos
• Deixe que outra pessoa cuide do trabalho pesado e das tarefas tediosas.
• Suporta muitos tipos de dados diferentes, vários dos quais são predefinidos no Ottoman
• Suporte a tipos de dados personalizados, incluindo validadores personalizados
• Modele seus dados para incorporar objetos ou referências e mantenha essas relações nítidas.
• Oferece suporte para localizações genéricas
• Oferece suporte a várias estratégias de indexação, de forma nativa
• Controle e imponha o modelo de dados de dentro do aplicativo.
• Definir programaticamente os métodos de objeto que mapeiam o modelo de dados.

Criação de um aplicativo Node.js usando um ODM e o Couchbase

Para referência, o código de amostra está disponível em github   Há três etapas fáceis para começar a criar aplicativos de nó com o Couchbase. Vamos tirar isso do caminho antes de prosseguirmos:

Faça o download e instale o CB 4.0 Enterprise. A versão empresarial do produto é totalmente gratuita para uso em qualquer capacidade de desenvolvimento. O download da versão mais recente pode ser feito em nosso site. Após a instalação, abra seu navegador na porta 8091, onde o Couchbase está instalado, e a interface gráfica do usuário orientará o processo de configuração. Para fins deste passo a passo e deste aplicativo, vamos supor que o Couchbase esteja instalado no mesmo sistema operacional em que o aplicativo será desenvolvido. Para se conectar à instância do Couchbase que foi instalada, abra um navegador em https://127.0.0.1:8091. Certifique-se de selecionar todos os três serviços Data, Index, Query na página "configure server" (configurar servidor) em "Start a new Cluster" (iniciar um novo cluster). Precisaremos deles para criar nosso aplicativo de amostra.

Não é necessário usar um dos buckets de amostra incluídos neste tutorial. Clique em next na página que diz "Sample Buckets" sem selecionar nenhum. Continue com a configuração, adicionando um bucket padrão, e agora devemos estar prontos para continuar com a criação do nosso aplicativo

Instale o nodejs no site do node. Depois que o nodejs estiver instalado, poderemos inicializar nosso aplicativo. Para inicializar o aplicativo, crie um diretório e clone o repositório no github. No terminal

O arquivo package.json no diretório raiz do aplicativo lista as dependências do aplicativo. No momento, o Ottoman está listado como o ramo beta armazenado no github, enquanto a versão mais recente das outras dependências será instalada.

A próxima etapa é instalar as dependências. No terminal, execute

bikeshop-cb

Os requisitos para esse aplicativo são:

• Aplicativo de inventário para bicicletas de catalogação.
• O aplicativo deve armazenar as informações do cliente e do vendedor para rastrear os passeios de teste e as informações de compra
• O Couchbase será o sistema de registro.
• O aplicativo precisa ser desacoplado das estruturas de front-end e suportar a integração com outros sistemas de back-end por meio da API HTTP REST.

Modelo de dados

A flexibilidade e a natureza dinâmica de um banco de dados de documentos NOSQL e JSON simplificam a criação do modelo de dados. Para o aplicativo de loja de bicicletas, usaremos três tipos de objetos e os definiremos em módulos específicos no aplicativo de nó.

• clientes
• funcionários
• bicicletas

Uma pasta sob a raiz do aplicativo chamada /schema é onde o modelo de dados é definido, e em /schema/model são definidos arquivos de modelo separados para cada objeto. Vamos examinar o modelo de dados começando com o módulo customer.js.

Modelo de cliente

A primeira seção do módulo customer.js instancia as dependências do módulo, que são o Ottoman e o arquivo de banco de dados em que as informações sobre a instância do Couchbase são armazenadas para esse exemplo específico.

Em seguida, uma função de validação personalizada é definida para garantir que um número de telefone no formato padrão dos EUA seja criado.

O modelo do objeto Customer é definido, usando vários dos tipos incorporados que o Ottoman suporta. Para obter referências adicionais, consulte ottomanjs.com. Vários índices são definidos junto com o modelo. Os índices são utilizados como métodos para cada instância do objeto Customer. O Ottoman oferece suporte a tipos de dados complexos, referências incorporadas a outros modelos e personalização.

No modelo de cliente acima, há quatro índices explícitos definidos. Por padrão, se um tipo de índice não for especificado, o Ottoman selecionará o índice disponível mais rápido suportado no cluster atual do Couchbase. Além de utilizar o suporte de índice secundário incorporado no Couchbase, o Ottoman também pode utilizar documentos referenciais e manter a integridade referencial para atualizações e exclusões. Esse é um recurso poderoso que permite pesquisas incrivelmente rápidas por um campo específico. Esse tipo de índice no Ottoman é útil para encontrar um objeto específico por um campo exclusivo, como o ID do cliente ou o endereço de e-mail no exemplo acima. Além de qualquer índice explícito, o Ottoman também fornece um recurso de localização genérico usando a API de consulta e o N1QL.

O próximo bloco de código no modelo Customer é uma função que permite que o aplicativo crie e salve uma nova instância de um cliente em uma única etapa. O método "create" é um método padrão fornecido pelo Ottoman para objetos como uma conveniência. Também é possível instanciar um novo objeto, atribuir todos os campos e, em seguida, salvar o objeto usando o método "save" que o Ottoman fornece para cada objeto. Um exemplo dessa maneira está incluído no modelo de bicicleta abaixo. Por fim, o modelo Ottoman do Cliente é exportado para uso em outros módulos

Modelo de bicicleta

O módulo bike.js começa da mesma forma que o módulo customer.js. É importante observar aqui que os objetos que são referenciados por outros objetos ottoman não precisam ser declarados especificamente como módulos de dependências de nós dentro de outros módulos. Por exemplo, para definir um campo como uma referência no modelo Bike para o módulo Customer definido acima, não é necessário incluir o módulo Customer como uma referência.

Como no exemplo do modelo Customer, o objeto Bike é definido com vários tipos de dados diferentes, referências incorporadas a outros modelos Ottoman e índices secundários explicitamente definidos.

Os índices, como no exemplo do cliente, são uma mistura de refdoc's e índices secundários padrão. Assim como no módulo do cliente, um método abreviado de criar e salvar é utilizado para instanciar uma nova instância do objeto Bike.

Um exemplo da mesma sequência de instanciar um novo objeto, atribuir valores a todos os campos e, em seguida, salvar o objeto usado na função abreviada acima é mostrado para referência.

O módulo Bike tem um método especial que é instanciado com cada nova instância do objeto Bike. Esse método permite adicionar um teste de direção à matriz de testes de direção para registrar cada teste de direção específico em uma bicicleta específica. Por fim, o modelo Bike é exportado para ser usado por outros módulos.

Aplicativo e rotas

Agora que o modelo está definido acima, a funcionalidade do controlador é definida no arquivo app.js no diretório /raiz e no arquivo routes.js no diretório /routes.

Módulo de aplicativo

O arquivo app.js é o ponto de entrada do aplicativo e define como ele funcionará. O código dentro do arquivo é o seguinte:

Rotas

Para fins de simplicidade, grande parte da lógica do aplicativo ocorre nos próprios manipuladores de rota. Em um aplicativo de nó de produção, essa funcionalidade normalmente seria abstraída junto com o uso de middleware para lidar com coisas como autenticação. Vejamos um exemplo de como novos documentos são criados com o aplicativo. A funcionalidade de como uma nova bicicleta é adicionada ao aplicativo é um bom lugar para começar, no módulo routes.js:

O uso do método createAndSave definido no módulo bike.js nos permite adicionar facilmente essa entrada ao banco de dados. Depois que a entrada é adicionada, podemos usar os índices que definimos usando Ottoman para o Bike Model como métodos de consulta para uma lista de bicicletas ou uma bicicleta específica. Este exemplo no módulo routes.js usa o índice refdoc definido para stockID no modelo de bicicleta:

Um dos recursos mais avançados do Couchbase, na versão 4.0 e posteriores, é a API de consulta. Ao usar consultas sql na linguagem N1QL, podemos realizar consultas estruturadas em documentos JSON armazenados no Couchbase. O Ottoman faz uso desse recurso fornecendo um método de consulta genérico padrão para cada tipo de objeto definido com um modelo Ottoman. O exemplo de como isso pode ser usado para o modelo de bicicleta também está no módulo routes.js:

Rotas e funcionalidades semelhantes são definidas no módulo routes.js para os outros dois tipos de objetos que definimos em nosso modelo: clientes e funcionários. Um Object Mapper acelera rapidamente o tempo de desenvolvimento e ajuda a criar uma linguagem de padrão avançada para que o aplicativo possa interagir com objetos complexos e, ao mesmo tempo, ser completamente abstraído da camada de armazenamento. Um exemplo disso é o conjunto de objetos incorporados que foram definidos no modelo de bicicleta. Isso permite que o aplicativo registre efetivamente uma lista de passeios de teste mapeados para o cliente específico, funcionário específico e armazenados com cada bicicleta. Usar o Ottoman para modelar os objetos sobre o Couchbase significa não ter de se preocupar com a forma como esses relacionamentos complexos são armazenados na camada de armazenamento e não ter de escrever todo o código que extrai e representa esses itens armazenados para o aplicativo. Por exemplo, a rota que adiciona uma nova viagem de teste no módulo routes.js:

• Verifica se a bicicleta existe para o número de vin especificado
• Verifica se o cliente existe para o endereço de e-mail do cliente especificado
• Verifica se o funcionário existe para o endereço de e-mail de funcionário especificado
• Adiciona uma entrada no histórico de viagens com base nas informações acima, na quilometragem e na data da viagem.

O manuseio do mapeamento de objetos para a camada de armazenamento facilita muito a vida e permite a criação rápida de protótipos. Aqui está o exemplo no módulo routes.js que executa as etapas acima:

Executar o aplicativo

Para ver um exemplo real de como isso se parece com alguns dados reais, tente executar o aplicativo e chamar a API REST. Os exemplos abaixo usam o curl, executado a partir de um terminal no OSX, com a saída canalizada para um script python "-mjson.tool" para obter um JSON legível

Resumo

O Ottoman aprimora o tempo de prototipagem rápida para a estratégia de mercado do uso do Couchbase com o Node.js. Um ODM fornece ao desenvolvedor uma linguagem de padrão avançada para projetar, criar protótipos e desenvolver aplicativos rapidamente sem a carga de código de manter a integridade referencial e o gerenciamento de dependências. Ride More, Code Less.