Escrevendo Clojure Webapps com anel

Solicitações são uma representação de solicitações HTTP recebidas. Ring represents a request as a map, allowing our Clojure application to interact with the individual fields easily. Há um conjunto padrão de chaves neste mapa, incluindo, mas não se limitando a:

Middleware may add more keys to this map as well conforme necessário.

Da mesma forma, as respostas são uma representação das respostas HTTP de saída. Ring also represents these as maps with three standard keys:

Como antes,Middleware may alter this between our handler producing it and the final result getting sent to the client.

Ring also provides some helpers to make building the responses easier.

A mais básica delas é a funçãoring.util.response/response, que cria uma resposta simples com um código de status de200 OK:

There are a few other methods that go along with this for common status codes - por exemplo,bad-request,not-found eredirect:

Também temos o métodostatus que converterá uma resposta existente para qualquer código de status arbitrário:

We then have some methods to adjust other features of the response similarly - por exemplo,content-type, header orset-cookie:

Observe quethe set-cookie method adds a whole new entry to the response map. This needs the wrap-cookies middleware para processá-lo corretamente para que funcione.

Agora que entendemos solicitações e respostas, podemos começar a escrever nossa função de manipulador para amarrá-la.

A handler is a simple function that takes the incoming request as a parameter and returns the outgoing response. O que fazemos nesta função depende inteiramente de nossa aplicação, desde que se ajuste a este contrato.

No mais simples, poderíamos escrever uma função que sempre retorna a mesma resposta:

Também podemos interagir com a solicitação, conforme necessário.

Por exemplo, poderíamos escrever um manipulador para retornar o endereço IP de entrada:

Middleware is a name that’s common in some languages but less so in the Java world. Conceitualmente, eles são semelhantes aos Servlet Filters e Spring Interceptors.

No Ring, o middleware se refere a funções simples que envolvem o manipulador principal e ajustam alguns aspectos dele de alguma maneira. Isso pode significar a mutação da solicitação de entrada antes de ser processada, a mutação da resposta de saída após ser gerada ou potencialmente não fazer nada mais do que registrar quanto tempo levou para processar.

Em geral,middleware functions take a first parameter of the handler to wrap and returns a new handler function with the new functionality.

The middleware can use as many other parameters as needed. Por exemplo, poderíamos usar o seguinte para definir o cabeçalhoContent-Type em cada resposta do manipulador empacotado:

Lendo isso, podemos ver que retornamos uma função que leva uma solicitação - este é o novo manipulador. Isso chamará o manipulador fornecido e retornará uma versão mutada da resposta.

Podemos usar isso para produzir um novo manipulador simplesmente encadeando-os:

Clojure also offers a way to chain many together in a more natural way – by the use of Threading Macros. Essa é uma maneira de fornecer uma lista de funções para chamar, cada uma com a saída da anterior.

In particular, we want the Thread First macro,*→*. Isso nos permitirá chamar cada middleware com o valor fornecido como o primeiro parâmetro:

Isso então produziu um manipulador que é o manipulador original envolvido em três funções de middleware diferentes.

Uma das funções mais simples que qualquer aplicativo da Web pode executar é servir recursos estáticos. Ring provides two middleware functions to make this easy – wrap-file and wrap-resource.

The wrap-file middleware takes a directory on the filesystem. Se a solicitação recebida corresponder a um arquivo nesse diretório, esse arquivo será retornado em vez de chamar a função de manipulador:

De maneira muito semelhante,the wrap-resource middleware takes a classpath prefix in which it looks for the files:

Em ambos os casos,the wrapped handler function is only ever called if a file isn’t found to return to the client.

O Ring também fornece middleware adicional para tornar esses filtros mais limpos na API HTTP:

O middlewarewrap-content-type determinará automaticamente o cabeçalhoContent-Type a ser definido com base na extensão de nome de arquivo solicitada. O middlewarewrap-not-modified compara o cabeçalhoIf-Not-Modified ao valorLast-Modified para suportar o cache HTTP, retornando o arquivo apenas se for necessário.

Ao processar uma solicitação, existem algumas maneiras importantes pelas quais o cliente pode fornecer informações ao servidor. Isso inclui parâmetros de sequência de consulta - incluídos nos parâmetros de URL e formulário - enviados como carga útil para solicitações POST e PUT.

Before we can use parameters, we must use the wrap-params middleware to wrap the handler. Isso analisa corretamente os parâmetros, suportando a codificação de URL e os disponibiliza para a solicitação. Opcionalmente, isso pode especificar a codificação de caracteres a ser usada, com o padrão UTF-8, se não for especificado:

Uma vez feito isso,the request will get updated to make the parameters available. Eles entram nas chaves apropriadas na solicitação recebida:

Podemos usar isso em nosso manipulador de solicitações exatamente como esperado.

Este manipulador retornará uma resposta contendo o valor do parâmetroinput.

Parameters map to a single string if only one value is present, or to a list if multiple values are present.

Por exemplo, obtemos os seguintes mapas de parâmetros:

Muitas vezes, queremos poder escrever aplicativos da Web nos quais os usuários podem fazer upload de arquivos. No protocolo HTTP, isso geralmente é tratado usando solicitações de várias partes. Isso permite que uma única solicitação contenha parâmetros de formulário e um conjunto de arquivos.

Ring comes with a middleware called wrap-multipart-params to handle this kind of request. Isso é semelhante à maneira quewrap-params analisa solicitações simples.

wrap-multipart-params decodifica e armazena automaticamente quaisquer arquivos carregados no sistema de arquivos e diz ao manipulador onde eles estão para trabalhar com eles:

Por padrão,the uploaded files get stored in the temporary system directory and automatically deleted after an hour. Observe que isso requer que a JVM ainda esteja em execução pela próxima hora para executar a limpeza.

Se preferir,there’s also an in-memory store, embora obviamente, haja o risco de ficar sem memória se arquivos grandes forem carregados.

Também podemos gravar nossos mecanismos de armazenamento, se necessário, desde que cumpram os requisitos da API.

Assim que este middleware estiver configurado,the uploaded files are available on the incoming request object under the params key. Isso é o mesmo que usar o smiddlewarewrap-params . Esta entrada é um mapa que contém os detalhes necessários para trabalhar com o arquivo, dependendo da loja usada.

Por exemplo, o armazenamento de arquivo temporário padrão retorna valores:

Onde o:tempfile entinela é um objetojava.io.File que representa diretamente o arquivo no sistema de arquivos.

Cookies are a mechanism where the server can provide a small amount of data that the client will continue to send back on subsequent requests. Isso geralmente é usado para IDs de sessão, tokens de acesso ou dados persistentes do usuário, como as configurações de localização definidas.

Ring has middleware that will allow us to work with cookies easily. This will automatically [.veryhardreadability] # analisa cookies em solicitações de entrada e também nos permite criar novos cookies em respostas de saída #.

A configuração deste middleware segue os mesmos padrões de antes:

Neste ponto,all incoming requests will have their cookies parsed and put into the :cookies key in the request. Isso conterá um mapa do nome e valor do cookie:

We can then add cookies to outgoing responses by adding the :cookies key to the outgoing response. Podemos fazer isso criando a resposta diretamente:

There’s also a helper function that we can use to add cookies to responses, de forma semelhante à forma como antes poderíamos definir códigos de status ou cabeçalhos:

Cookies can also have additional options set on them, conforme necessário para a especificação HTTP. Se estivermos usandoset-cookie, então os forneceremos como um parâmetro de mapa após a chave e o valor. As chaves deste mapa são:

Os cookies nos permitem armazenar bits de informações que o cliente envia de volta ao servidor a cada solicitação. Uma maneira mais poderosa de conseguir isso é usar sessões. Eles são armazenados inteiramente no servidor, mas o cliente mantém o identificador que determina qual sessão usar.

Como com tudo aqui,sessions are implemented using a middleware function:

Por padrão,this stores session data in memory. Podemos alterar isso, se necessário, e o Ring vem com um armazenamento alternativo que usa cookies para armazenar todos os dados da sessão.

Tal como acontece com o upload de arquivos,we can provide our storage function if needed.

We can also adjust the details of the cookie used to store the session key.

Por exemplo, para que o cookie da sessão persista por uma hora, poderíamos fazer:

Os atributos do cookie aqui são os mesmos suportados pelo middlewarewrap-cookies.

As sessões geralmente podem atuar como repositórios de dados para trabalhar. Isso nem sempre funciona bem em um modelo de programação funcional, então o Ring os implementa de maneira um pouco diferente.

Em vez disso,we access the session data from the request, and we return a map of data to store into it as part of the response. Esse é o estado inteiro da sessão a ser armazenado, não apenas os valores alterados.

Por exemplo, o seguinte mantém uma contagem contínua de quantas vezes o manipulador foi solicitado:

Trabalhando dessa forma, podemosremove data from the session simply by not including the key. Também podemos deletar a sessão inteira retornandonil para o novo mapa.

Assim que estiver configurado,we can now build a WAR file that we can deploy to any standard servlet container:

We can also build a standalone JAR file that will run our handler exactly as expected:

This JAR file will include a main class that will start the handler in the embedded container that we included. Isso também respeitará uma variável de ambiente dePORT, permitindo-nos executá-lo facilmente em um ambiente de produção:

Para fins de desenvolvimento,we can run the handler directly from Leiningen without needing to build and run it manually. Isso facilita as coisas para testar nosso aplicativo em um navegador real:

Isso também honra a variável de ambientePORT se tivermos definido isso.

Além disso,there’s a Ring Development library that we can add to our project. Se estiver disponível, entãothe development server will attempt to automatically reload any detected source changes. Isso pode nos fornecer um fluxo de trabalho eficiente para alterar o código e vê-lo ao vivo em nosso navegador. Isso requer a adição de dependênciaring-devel: