Ao criar aplicativos com Couchbase Mobile há muitas possibilidades interessantes de integração no lado do servidor.
A criação de lógica comercial para resolver conflitos de sincronização é um uso comum. O Gateway de sincronização O feed "changes" do documento também facilita a implementação de todos os tipos de operações orientadas por eventos. Explorarei isso nas próximas postagens.
Um aplicativo pode usar ambos Gateway de sincronização e Couchbase Lite chamando diretamente a API ReST para cada um deles. No entanto, isso requer a escrita de um monte de código padrão que não é muito divertido. O PouchDB oferece uma opção JavaScript compatível, mas agora há uma alternativa mais leve.
Há pouco tempo, o Couchbase passou a usar o Swagger para documentar o Couchbase Mobile APIs. O Swagger faz muito mais do que criar
documentação, no entanto. Com uma única especificação Swagger, você pode gerar documentação, código stub de servidor, casos de teste, um site sandbox e muito mais. O melhor de tudo para mim é que o Swagger pode gerar SDKs de clientes... em 40 idiomas diferentes!
Neste post, mostrarei como usar o cliente Swagger Node.js. Criaremos um aplicativo super simples que monitora as alterações em documentos no Couchbase. Isso se tornará a base para a criação de outras coisas legais que estão por vir. Vamos nos aprofundar.
O que precisamos
Para acompanhar o processo, você precisará de
- Node.js (estou usando a versão 6.9.1 em um Mac)
- Swagger JS (O cliente Swagger Node.js)
- Gateway de sincronização do Couchbase
- A especificação Swagger do Sync Gateway
Presumo que você já tenha o Node.js instalado.
Instalar a biblioteca Swagger JS
Em um shell de linha de comando, mude para o diretório onde você manterá seu projeto.
Para obter o cliente e as dependências do Swagger, execute
|
1 |
$ npm instalar arrogância-cliente |
(Você verá alguns avisos, que podem ser ignorados).
Instalar o Sync Gateway
Faça o download do pacote Sync Gateway para sua plataforma aqui. (Se você estiver executando o Linux e não encontrar um pacote para sua distribuição, consulte as instruções em
esta postagem do blog para obter ajuda).
Para executar o Sync Gateway, precisamos criar um arquivo de configuração. Aqui está uma configuração simples que podemos usar. Copie o texto aqui e cole-o em um arquivo chamado "sync-gateway-config.json", ou algo semelhante.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
{ "log": ["HTTP+"], "adminInterface": "127.0.0.1:4985", "interface": "127.0.0.1:4984", "CORS": { "origem":["*"], "loginorigin":["*"], "cabeçalhos":["Content-Type"], "maxAge": 1728000 }, "bancos de dados": { "teste": { "servidor": "walrus:", "usuários": { "CONVIDADO": {"desativado": falso, "admin_channels": ["*"] } } } } } |
Essa configuração usa um banco de dados interno criado para testar o Sync Gateway. O servidor também só responderá a conexões no localhost. Você pode encontrar recursos para saber mais sobre a configuração do Sync Gateway no final desta postagem.
Inicie o Sync Gateway executando
|
1 |
$ /caminho/para/portais de sincronização sincronização-portal-configuração.json |
Você verá alguns resultados de registro. Pode ser interessante observar os logs ao executar o aplicativo mais tarde.
Faça uma cópia da especificação Swagger do Sync Gateway
Você pode encontrar a especificação Swagger para a APi pública do Sync Gateway ReST (em comparação com a API de administração) em https://docs.couchbase.com/sync-gateway/current/_attachments/sync-gateway-admin.yaml.
As especificações do Swagger são armazenadas como JSON. Embora o Swagger possa fazer o download do texto diretamente, é melhor fazer uma cópia. Dessa forma, se a especificação for alterada, isso não prejudicará seu aplicativo.
Copie as informações em um arquivo no diretório do seu projeto chamado sync-gateway-spec.json, ou algo semelhante. O arquivo precisa de uma extensão .json para que o Node o processe.
Criar o aplicativo Node.js
Vamos montar o aplicativo. Abra um novo arquivo no diretório do seu projeto que termine com uma extensão .js. Usei um arquivo chamado app.js.
|
1 2 |
const Swagger = exigir('swagger-client'); const especificação = exigir('./sync-gateway-spec.json'); |
A primeira linha importa o cliente Swagger e o torna disponível. A segunda linha é um pouco mais incomum. Ela inicializa o especificação do objeto JSON no arquivo. É por isso que a extensão .json é importante. É assim que o Node reconhece que estamos
importando JSON, não um pacote normal.
O arquivo de especificações tem um host conectado, mas vamos configurá-lo nós mesmos.
|
1 2 3 4 |
const HOST DO GATEWAY DE SINCRONIZAÇÃO = 'localhost:4984'; especificação.hospedeiro = HOST DO GATEWAY DE SINCRONIZAÇÃO; |
Em seguida, prepararemos os parâmetros para nossa chamada ao _mudanças ponto final.
|
1 2 3 4 5 6 7 8 9 |
deixar consulta = { db: 'teste', filtro: 'sync_gateway/bychannel', canais: "notificação, active_only: verdadeiro, incluir_docs: verdadeiro, alimentação: 'longpoll', tempo limite: 0 }; |
Observe que temos aqui uma combinação do nome do banco de dados (teste), que acaba fazendo parte do URL do endpoint, e algumas opções que queremos definir.
Agora que já inicializamos o que precisamos, podemos criar a instância do cliente Swagger.
|
1 2 3 4 5 6 7 8 9 10 |
deixar cliente = novo Swagger({ especificação: especificação, sucesso: função() { monitor(cliente); }, função(erro) { console.registro('erro do cliente: ', erro.statusText); processo.saída(1); } }); |
Há vários aspectos importantes a serem observados aqui.
Estamos usando o cliente de forma síncrona. Se quiser, você pode usar o JavaScript Promises especificando usePromise: true. Eu não queria fazer isso porque não estou fazendo nenhum processamento real e isso complica um pouco o código.
Em vez de especificações: especificaçõesPoderíamos ter listado uma url para a especificação do Swagger usando url:. Novamente, você deve evitar isso, pelo menos na produção, porque a especificação pode mudar remotamente e quebrar seu código.
O sucesso: especifica duas funções. Ambas são retornos de chamada. A primeira é chamada se a construção for bem-sucedida e a segunda se falhar. Elas são "globais", de certa forma. Essas funções funcionam como padrão se não especificarmos funções diferentes para a entrada
chamadas individuais. Isso é muito útil no caso de erros.
Atribuímos a instância a uma variável cliente. A instância do cliente é preenchida de forma assíncrona. Ela não está pronta para ser usada até que ocorra a chamada de retorno de sucesso. Portanto, temos a interessante construção de que cliente é usado internamente no
callback. Na versão Promises, o cliente seria passado como argumento no .então cláusula.
Na próxima parte do código, usamos o cliente para ouvir o _mudanças ponto final.
|
1 2 3 |
função monitor(cliente) { cliente.banco de dados.get_db_changes(consulta, mensagem); } |
Isso apresenta um problema: como descobrimos o nome da função que queremos chamar? Não há um mapeamento fixo entre endpoints e nomes de funções. Esse é outro recurso útil do Swagger. A classe cliente é autodocumentada. Você chama ajuda() em qualquer nível que você precisar. Por exemplo, para saber mais sobre endpoints no banco de dados, adicione o seguinte em seu código:
|
1 |
cliente.banco de dados.ajuda(); |
A saída de ajuda é exibida na saída da linha de comando (ou no console do seu IDE). Ela descreverá os pontos de extremidade e todos os parâmetros possíveis.
Voltando à chamada do cliente, vemos que passamos o nome do banco de dados (obrigatório) e vários parâmetros agrupados no parâmetro consulta objeto. Isso foi um pouco confuso. Você pode esperar que eles sejam separados, mas isso não acontece.
trabalho. Nenhum dos exemplos que encontrei explicava isso.
Fornecemos uma função de retorno de chamada mensagem. (Observe que isso é usado se a chamada ReST for bem-sucedida. Contamos com o padrão para lidar com falhas).
|
1 2 3 4 5 |
função mensagem(resposta) { console.registro(resposta.dados); consulta.desde = resposta.obj.última_seq; monitor(cliente); } |
O retorno de chamada recebe um objeto que contém todos os detalhes da resposta. Escrevi esse aplicativo apenas para mostrar a estrutura de loop necessária para ouvir o feed de alterações do Sync Gateway. Por isso, o mensagem não faz muita coisa. Escrevemos a chamada
para fins de depuração. Em seguida, queremos voltar e ouvir a próxima atualização. O Sync Gateway sabe o que enviar com base nas IDs de sequência. Para controlar isso, usamos a função última_seq informações de nossa última resposta.
É isso aí. Aqui está o código completo do aplicativo.
|
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 |
const Swagger = exigir('swagger-client'); const especificação = exigir('./sync-gateway-spec.json'); const HOST DO GATEWAY DE SINCRONIZAÇÃO = 'localhost:4984'; especificação.hospedeiro = HOST DO GATEWAY DE SINCRONIZAÇÃO; deixar consulta = { db: 'teste', filtro: 'sync_gateway/bychannel', canais: "notificação, active_only: verdadeiro, incluir_docs: verdadeiro, alimentação: 'longpoll', tempo limite: 0 }; deixar cliente = novo Swagger({ especificação: especificação, sucesso: função() { monitor(cliente); }, função(erro) { console.registro('erro do cliente: ', erro.statusText); processo.saída(1); } }); função monitor(cliente) { cliente.banco de dados.get_db_changes(consulta, mensagem); } função mensagem(resposta) { console.registro(resposta.dados); consulta.desde = resposta.obj.última_seq; monitor(cliente); } |
Notas finais
Você pode iniciar seu aplicativo e experimentá-lo. Certifique-se de que o Sync Gateway esteja em execução. Em seguida, execute
|
1 |
$ nó aplicativo.js |
Você deverá ver uma resposta nos logs do Sync Gateway e algo parecido com esta saída do próprio aplicativo:
|
1 2 3 4 |
{"resultados":[ {"seq":1,"id":"_user/GUEST","mudanças":[]} ], "last_seq":"1"} |
Agora, adicione um novo documento. Você pode fazer isso com o cURL na linha de comando. Aqui está um exemplo.
|
1 |
$ enrolar -X PUT -H "Content-Type: application/json" -d '{"key": "value", "channels": "notification" }' http://localhost:4984/test/doc |
Seu aplicativo Node deve produzir algo parecido com isto:
|
1 2 3 4 |
{"resultados":[ {"seq":2,"id":"doc","doc":{"_id":"doc","_rev":"1-d0efa985de274451fc7cdcf471152ce2","canais":"notificação","chave":"valor"},"mudanças":[{"rev":"1-d0efa985de274451fc7cdcf471152ce2"}]} ], "last_seq":"2"} |
Outros recursos
Leia mais sobre Couchbase Mobile.
Leia sobre o Gateway de sincronização APIs ReST.
O Repositório GitHub do cliente Swagger JS tem uma documentação útil incluída.
Saiba mais sobre o Swagger em http://swagger.io.
O editor Swagger on-line é muito útil. Você pode gerar SDKs de cliente aqui ou até mesmo experimentar a API diretamente. Basta colar a especificação do Swagger no editor. http://editor.swagger.io/
Há um projeto da comunidade React Native Couchbase que usa o cliente JavaScript. Você pode encontrar alguns exemplos interessantes em https://github.com/couchbaselabs/react-native-couchbase-lite
Pós-escrito
Confira mais recursos em nosso portal do desenvolvedor e nos siga no Twitter @CouchbaseDev.
Você pode postar perguntas em nosso fóruns. E participamos ativamente de Estouro de pilha.
Você pode me seguir pessoalmente em @HodGreeley
De forma um tanto irônica, o link para o Swagger sync-gateway spec.json está inválido no momento. O código aqui é muito útil e interessante. Você tem um link atualizado para esse arquivo de especificações?
Parece acessível em http://docs.couchbasemobile.com/sync-gateway-public/spec.json
Além disso, os documentos estão renderizando a ferramenta de teste corretamente em
https://developer.couchbase.com/documentation/mobile/current/references/couchbase-lite/rest-api/index.html
Talvez tenha sido um problema temporário
Acho que só disparei sinalizadores suficientes e alguém me resgatou :P Obrigado!
Outra pergunta, desta vez sobre o
usePromiseno Swagger. Como faço para manter o monitoramento contínuo ao usar Promessas (assim como no seu exemplo sem promessa)?Reescrevi os métodos para usar Promises, mas obtenho uma passagem na saída do registro contendo a sequência de alterações e o software é encerrado, em vez de permanecer ativo. Alguma ideia de como configurá-lo?
cliente = new Swagger({options})
.then(monitor)
.then(message)
.catch(error)
Perdoe-me por estar praticando em minha pequena câmara de eco :-P
Se alguém quiser usar promessas, o padrão é retornar um novo cliente Swagger sempre que uma mensagem for registrada. A promessa no cliente inicial será cumprida. O novo cliente precisará ser criado, o qual será monitorado após a conclusão da pendência. Não posso publicar o código aqui, mas ele funciona de forma encantadora.
Basicamente, você precisa criar um loop em que a resolução da promessa passe para o próximo estágio. Vou escrever um exemplo completo, mas aqui está um trecho para dar uma ideia.
novo Swagger({
especificações: especificações,
usePromise: true
})
.catch(error => die('Não foi possível criar a instância do cliente:', error))
.then(result => main(result))
.catch(error => die('Failure in main:', error));
função main(client) {
// Algum código de inicialização
Changes.monitor(client);
}
classe Changes {
static init(client) {
Changes.query = {
db: db.db,
active_only: false,
include_docs: true,
alimentação: 'longpoll',
timeout: 0
};
}
monitor estático(cliente) {
client.database.get_db_changes(Changes.query)
.then(response => Changes.parse(client, response))
.catch(error => warn("error receiving changes:", error));
}
static parse(client, response) {
for (const record of response.obj.results) {
// Lógica do aplicativo
Changes.query.since = record.seq;
}
Changes.monitor(client);
}
}
Estou disposto a comparar anotações com você por e-mail, Hod. Por motivos legais, não posso publicar o código aqui, mas posso fazê-lo por e-mail do trabalho (porque temos um NDA com o CB registrado). Consegui fazê-lo funcionar em 30 linhas de ES6.
Legal, sim, eu gostaria de ver como você está abordando o assunto. Acho que você tem meu e-mail, mas é só um hod
em…[...] Depois de definir a especificação da API para seus pontos de extremidade, você obtém vários recursos valiosos. Meus dois favoritos são a documentação incorporável "ao vivo" e as bibliotecas de clientes. Dê uma olhada neste vídeo curto para ver uma demonstração de alguns dos recursos do Swagger. Para ver um exemplo de uso de um cliente JavaScript do Swagger, dê uma olhada nesta publicação do blog: https://www.couchbase.com/node-js-swagger-monitor-document-changes-couchbase-mobile/ […]
Obrigado pelo artigo, ele é muito bom, mas, para ser sincero, estou um pouco confuso. Acho que a afirmação... "O PouchDB oferece uma opção JavaScript compatível, mas agora há uma alternativa mais leve" é a causa da minha confusão. Isso não me parece uma alternativa ao uso de um banco de dados off-line como o PouchDB que sincroniza com o couchbase.
Eu quis dizer compatível no sentido de atuar como um cliente de nível superior para a API ReST do Sync Gateway. Leia como "tanto o PouchDB quanto o Swagger + a especificação correta fornecem a você clientes ReST compatíveis com o Sync Gateway".
Estou falando de um nó no lado do servidor, o que pressupõe implicitamente que você só estará fora da rede quando algo estiver seriamente errado. Portanto, o armazenamento local não é necessário. Não é para descartar os cenários off-line interessantes, apenas para dizer que não é disso que estou tratando aqui.