json_rest_server 是一個 Flutter/Dart 套件,可讓開發者使用 JSON 建立功能完整的 RESTful 伺服器。它提供內建的驗證、分頁以及建立完整應用程式所需的必要服務支援。專為後端開發設計,可在 macOS、Windows 和 Linux 上執行,適用於跨平台的伺服器端專案。此套件透過最少的設定簡化伺服器設定,讓 API 與資料驅動應用程式的快速開發成為可能。
適用情境
建構 REST API
使用者身分驗證系統
Web 應用中的資料分頁
全-stack 式 Flutter 應用程式
移動應用的後端服務
主要特色
RESTful API 支援
內建驗證
分頁處理
基於JSON的資料交換
跨平台伺服器部署
適合對象
Flutter 開發人員建構全端應用
尋求輕量級伺服器解決方案的後端開發人員
需要快速 API 原型設計的項目
使用 Dart 進行前端和後端開發的團隊
使用建議
需要理解 REST 原則
僅限 JSON 資料格式
最適合中小型應用
在未經自訂的情況下,不適合用於高流量生產伺服器
原始 README
以下為關聯原始碼儲存庫的 README 原文快照,最新內容請造訪原始碼儲存庫。
Json Rest Server is a RESTful server based on JSON
Languages:
Json Rest Server
Um RESTful server baseado em JSON
Tenha um servidor RESTful 100% funcional com autenticação, paginação e todos os serviços necessários para desenvolvimento de aplicações
Instalação
Faça a instalação do Dart (https://dart.dev/get-dart
). Lembrando que se você tem o Flutter instalado você não precisa fazer a instalação do Dart
Ative o Json Rest Server pelo pub
dart pub global activate json_rest_server
Configurações
No arquivo config.yaml ficam as configurações do servidor
Segue descrição dos parametros:
name -> Nomedo seu servidor
port -> porta de acesso
host -> Ip de acesso, caso queira que responda por ip e localhost coloque 0.0.0.0
database -> nome do arquivo do seu banco de dados
idType( uuid | int ) -> Agora o json_rest_server suporta que os ids sejam ou integer auto incremental ou uuid
Comandos
ATENÇÃO:
O executável padrão do projeto é json_rest_server porém você também pode utilizar jsonRestServer ou somente jrs facilitando assim a digitação ;-)
Atualizando:
Atualizando versão do Json Rest Server:
json_rest_server upgrade
Criando projeto
Os comando abaixo criarão toda a configuração necessária para rodar seu servidor
Em uma pasta vazia execute o comando
json_rest_server create
Caso queira que o Json Rest Server crie a pasta execute
json_rest_server create ./nome_pasta
Iniciando Servidor
O comando abaixo rodará o servidor basedo nas configurações que estão no arquivo config.yaml
Entre na pasta onde você executou o comando create e execute
json_rest_server run
Rotas
Quando rodamos o Json Rest Server será criado as rotas baseado no conceito RESTful basedo no arquivo database.json
Cada chave criada nesse arquivo terá suas rotas completas ex:
{"products":[{"id":0,"title":"Academia do flutter"},{"id":1,"title":"Jornada Dart"},{"id":2,"title":"Jornada GetX"}]}
Teremos as rotas:
GET /products -> Recuperar todos os produtos
GET /products?title=jornada -> Recuperar todos os produtos com filtro
GET /products?page=1&limit=10 -> Recuperar todos os produtos paginado
GET /products?page=1&limit=10&title=Jornada -> Recuperar todos os produtos paginado com filtro
GET /products/1 -> Recuperar 1 produto
POST /products -> Adicionar um produto
PUT /products/1 -> Editar um produto
PATCH /products/1 -> Editar um produto
DELETE /products/1 -> Deletar um produto
OBS: Lembre que os método post, put e patch devem conter um body json
Na pasta exemplos existe um arquivo postman com todos os exemplos mencionados acima
Teste de timeout
Em todas as suas requisições HTTP agora é possível interferir no request do http para que possa testar um timeout de conexão, como se fosse um delay do servidor.
Para o funcionamento é necessário que seja colocado no header da sua reqiusição um campo chamado mock-delay onde o seu valor é um inteiro em segundos
Exemplo:
mock-delay:10
Autenticação
Json Rest Server já vem com todo o processo de autenticação por meio de JWT.
Para habilita-lo você precisa adicionar a propriedade auth ao arquivo config.yaml
ex:
No exemplo abaixo, não será verificada a autenticação para o path /users no método post (Cadastro de um novo usuário).
Agora o segundo path /products/{*} você deve ter achado estranho o parâmetro {*}, mas ele é um coringa de acesso, pois, todos os paths configurados no database.json respondem a busca de dados por id, na url ex: /producs/1 e precisavamos ignorar o id para identificar a url, sendo assim criamos o coringa {*} deixando esse pedaço da url dinâmico permitindo que uma url /products/1 possa ser acessada sem autenticação.
O parâmetro authFields é opcional, e nele deve ser passado os campos que serão usados para fazer a autenticação. É necessário inserir nome do campo e o tipo de dado como no exemplo abaixo.
Tipos permitidos no authFields -> "string", "int" ou "double"
Obs: Caso o parâmetro authFields não seja definido no config.yaml, o Json Rest Server manterá a autenticação padrão, que utiliza "email" e "password", ambos como string.
auth:
jwtSecret: cwsMXDtuP447WZQ63nM4dWZ3RppyMl
jwtExpire:3600
unauthorizedStatusCode:403
urlSkip:
- /users:
method: post
- /products/{*}:
method: get
authFields:
- matricula:
type: int
- celular:
type: string
- nota:
type: double
Como realizar o login
Para realizar o login você precisa fazer um post para a url ex: http://localhost:8080/auth com o body:
// Exemplo de request padrão.{"email":"rodrigorahman@academiadoflutter.com.br","password":"123"}
Caso você tenha configurado o authFields para personalizar os campos de login, devem ser enviados os campos da forma como foram definidos no config.yaml.
// Exemplo de request customizada com authFields.{"matricula":102030,"celular":"+5535988881234","nota":8.5}
O Json Rest Server fará uma busca na sua tabela de users registrada no arquivo database.json e se tudo estiver correto será retornado um json com o token de acesso:
Dessa forma o Json Rest Server fará a busca na collection adm_users podendo assim fazer um login de administrador retornando um json diferente quando recuperado pelo /me, além de permitir o acesso aos métodos POST, PUT, DELETE para todas as collections cadastradas
Recuperando dados do usuário logado
Para recuperar os dados do usuário logado você deve acessar o path /me enviando o token jwt no header. Automaticamente o Json Rest Server vai recuperar o id do usuário de dentro do token e retornar os dados do usuário sem o atributo password.
Lembrando que fará uma busca na "table" users buscando pelo id.
O token de acesso tem a duração que você definiu dentro do arquivo config.yaml após esse tempo você não poderá mais acessar as rotas, mas sabemos que em aplicativos existe o processo de acesso permanente e o json_rest_client te ajuda também com isso disponibilizando uma rota para fazer o refresh do token de acesso, não obrigando o usuário a realizar um novo login
Para isso faça o seguinte procedimento.
Quando você realizou o login você recebeu o access_token e o refresh_token, o refresh token tem um tempo de vida de 7 dias, sendo assim para renovar o seu access_token dentro de um prazo de 7 dias envie uma requisição do tipo PUT para o endereço /auth/refresh.
Enviando o seu token de acesso no header e o token de refresh no body.
Basta agora enviar novamente a requisição passando o novo token.
ATENÇÃO: Lembre que agora você recebeu um novo token de acesso e o antigo DEVE ser descartado!
Criando referencia ao usuário logado no seu json
Você pode querer adicionar uma coluna com o dado do usuário que está logado.
Para fazer essa associação, basta enviar no value do field o valor #userAuthRef ex:
{"title":"Academia do flutter","user_id":"#userAuthRef"}
O Json Rest Server vai substituir o valor de #userAuthRef pelo id do usuário logado, lembrando que essa tag só poderá ser usada para serviços que utilizem autenticação pois o valor será substituido pelo id do usuário enviado no tokenJWT.
Buscando dados com filtro por usuário logado.
Para fazer a busca por um campo com o ID do usuário logado, você precisa enviar no filtro a tag #userAuthRef, o Json Rest Server vai substituir o valor pelo id do usuário logado ex:
O JRS vai substituir a tag #userAuthRef pelo o id do usuário logado e realizar o filtro no campo user_id
Sistema de broadcast event
Foi desenvolvido um sistema de broadcast para enviar dados para outras aplicações com uma configuração inicial simples no seu config.yaml
Inicialmente o sistema está compatível com o envio para socket e slack
enableSocket:true#Indica se você quer que inicie um servidor de socket junto com o servidor rest (true/false)socketPort:8081#Indica a porta de acesso do socket padrão (Websocket não utiliza essa porta): 8081broadcastProvider:socket#Indica pra qual tipo de broadcast ele quer enviar por padrão : ex socket,slack ou só socket ou só slackslack:slackUrl:#Indica a url do webhook do slackslackChannel:#Indica o canal do slack para ser enviado sempre começando com #
Para emitir os eventos, os providers precisam estar configurados , e no caso do socket somente se existir clientes conectados o envio é efetuado, assim garantindo que não seja disparado nenhum serviço sem necessidade
Voce pode incluir no header uma chave chamada socket-channel, e assim que o verbo (POST,PUT,DELETE,PATCH) for emitido, o socket irá emitir a resposta desse verbo no channel escolhido, caso não seja escolhido nada o nome do channel sera VERBO
Broadcast event com Websocket
O Json Rest server suporta também a comunicação socket para web utilizando websocket, quando você habilita o parâmetro enableSocket: true no config você automaticamente está habilitando também o websocket podendo receber socket pelo IO ou Websocket.
No websocket a porta de conexão sempre será a mesma do servidor.
Veja um exemplo de conexão utilizando o Flutter Web:
O exemplo acima mostra uma conexão websocket padrão onde qualquer alteração no backend será enviada e lida pelo websocket.
Filtro de notificação websocket
Em algumas situações não queremos escutar as alterações em todas as tabelas do sistema, sendo assim no websocket é possível adicionar um filtro por tabela que você gostaria de escutar.
Ex:
Vamos supor que você gostaria de receber no socket somente as alterações nas tabelas (user e products), sendo assim basta no momento da conexão com o websocket você enviar o parâmetro tables com as tabelas que você gostaria de escutar.
Pronto agora o seu websocket receberá alterações somente das tabelas users e products
Atenção: Caso você conect no socket com filtro você SÓ recebera alterações das tabelas informadas
Suporte a conteúdos estáticos (Imagens)
Json Rest Server agora da suporte a url de conteúdo (Imagens) estáticas.
Para habilitar o suporte a esse recurso em projetos existentes siga os passos abaixo:
1 - Na raiz do seu projeto, crie uma pasta storage
2 - Coloque as imagens dentro dessa pasta e agora você terá acesso a url http://localhost:8080/storage
Upload de arquivos
Para realizar upload de arquivos você deve fazer um post para a url http://localhost:8080/uploads e enviar o arquivo por formData.
Obs: é muito importante que você envie o nome do arquivo dentro do multpartFile