Как я писал в предыдущей статье, две главные вещи, которые определяют HTTP запрос, это путь и метод. Однако, если есть главные вещи, должны быть и второстепенные и их есть. Давайте посмотрим на типичный HTTP запрос к какому-нибудь приложению:
|
1
2
3
4
5
6
7
8
9
10
11
|
> GET /notes HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.52.1
> Accept: */*
>
< HTTP/1.1 200
< Content-Type: application/json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Tue, 01 May 2018 16:17:51 GMT
<
["mynote - id=mynote&Second+note="]
|
Кроме метода и пути в обе стороны отправляются заголовки запроса, заголовки ответа и данные, как ответа, так и запроса. И всё это можно использовать в обработчиках запросов Spring Web MVC.
HEAD и OPTION
И начать я бы хотел всё таки с дополнительных методов. В статье о обработчиках HTTP запросов я рассматривал четыре основных HTTP метода, которые изменяют или возвращают данные. Однако существует два метода, которые работают не с данными, а с самим HTTP и отображением запросов. В первую очередь это метод HEAD, который ведёт себя точно так же, как и GET, за одним исключением — тело запроса не возвращается, возвращаются только заголовки запроса. Это позволяет проверять, какой будет ответ сервера (например его размер), без получения собственно ответа. Spring автоматически включает поддержку HEAD для всех GET запросов. Для примера я сделаю простой контроллер с GET обработчиком и обращусь к нему с методами GET и HEAD:
|
1
2
3
4
5
6
7
8
|
@RestController
@RequestMapping("/api")
public class HttpController {
@GetMapping("/strings")
List<String> listStrings() {
return Arrays.asList("Lorem", "ipsum", "dolor", "sit", "amet");
}
}
|
|
1
2
3
4
5
6
7
8
9
10
11
12
|
>curl -v http://localhost:8080/api/strings/
> GET /api/strings/ HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.52.1
> Accept: */*
>
< HTTP/1.1 200
< Content-Type: application/json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Tue, 01 May 2018 16:35:07 GMT
<
["Lorem","ipsum","dolor","sit","amet"]
|
|
1
2
3
4
5
6
7
8
9
10
11
12
|
>curl --head -v http://localhost:8080/api/strings/
> HEAD /api/strings/ HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.52.1
> Accept: */*
>
< HTTP/1.1 200
< Content-Type: application/json;charset=UTF-8
< Content-Length: 38
< Date: Tue, 01 May 2018 16:36:07 GMT
<
|
Видно, что заголовки в первом и во втором случае практически не отличаются, добавился лишь Content-Length, указывающий, сколько будет передано данных в случае GET запроса, но сами данные в HEAD запросе не передаются.
Второй важный метод, работающий не с вашими данными, а с HTTP как таковым — OPTIONS. OPTIONS, вызванный для пути, сообщает, какие методы можно вызывать для этого пути и какие значения прочих заголовков могут приниматься. Обработчик метода OPTIONS так же создаётся автоматически.
|
1
2
3
4
5
6
7
8
9
10
11
|
>curl -X OPTIONS -v http://localhost:8080/api/strings/
> OPTIONS /api/strings/ HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.52.1
> Accept: */*
>
< HTTP/1.1 200
< Allow: GET,HEAD
< Content-Length: 0
< Date: Tue, 01 May 2018 16:40:21 GMT
<
|
Заголовок Allow говорит нам, что для /api/strings можно вызывать методы GET и HEAD.
Заголовки запроса
Раз уж речь зашла о залоговках, давайте научимся их читать из запроса. Для этого используется аннотация @RequestHeader, которая навешивается на параметр метода:
|
1
2
3
4
5
6
7
|
@GetMapping("/private")
String getTruth(@RequestHeader("Authorization") String authorization) {
if (!"password".equals(authorization)) {
throw new NotAuthorizedException();
}
return "The banana is big, but the skin is bigger.";
}
|
Кстати, если вы хотите получить все заголовки запроса, просто используйте параметр типа HttpHeaders с этой аннотацией.
Проверим, что без пароля доступа нет, а с паролем есть:
|
1
2
3
4
5
6
7
8
9
10
11
12
|
>curl -v http://localhost:8080/api/private
> GET /api/private HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.52.1
> Accept: */*
>
< HTTP/1.1 403
< Content-Type: application/json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Tue, 01 May 2018 16:54:44 GMT
<
{"timestamp":1525193684036,"status":403,"error":"Forbidden","message":"No message available","path":"/api/private"}
|
|
1
2
3
4
5
6
7
8
9
10
11
12
13
|
>curl -H "Authorization:password" -v http://localhost:8080/api/private
> GET /api/private HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.52.1
> Accept: */*
> Authorization:password
>
< HTTP/1.1 200
< Content-Type: text/plain;charset=ISO-8859-1
< Content-Length: 42
< Date: Tue, 01 May 2018 16:55:42 GMT
<
The banana is big, but the skin is bigger.
|
Принимаемые и отправляемые типы данных
Некоторые заголовки настолько важны, что для них сделана особая поддержка. Заголовок Content-Type указывает на тип данных, передающихся с запросом или с ответом. В Spring можно задать, какой тип данных готов обработать метод-обработчик запроса. Более того, можно завести несколько методов, которые будут отличаться только обрабатываемым типом данных.
Как пример, если вы хотите сделать сервис по созданию заметок, который принимает данные и в JSON и в XML, он может выглядеть как-то так:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
|
@PostMapping(value = "/note", consumes = "application/json;charset=UTF-8")
@ResponseStatus(HttpStatus.CREATED)
String createJsonNote(@RequestBody String data) throws IOException {
ObjectMapper mapper = new ObjectMapper();
TypeReference<HashMap<String, String>> typeRef
= new TypeReference<HashMap<String, String>>() {};
Map<String, String> note = mapper.readValue(data, typeRef);
return String.format("title=%s\ncontent=%s\n", note.get("title"), note.get("content"));
}
@PostMapping(value = "/note", consumes = "text/xml")
@ResponseStatus(HttpStatus.CREATED)
String createXMLNote(@RequestBody String data) throws IOException {
XStream mapper = new XStream();
mapper.registerConverter(new MapConverter());
mapper.alias("note", Map.class);
Map<String, String> note = (Map<String, String>) mapper.fromXML(data);
return String.format("title=%s\ncontent=%s\n", note.get("title"), note.get("content"));
}
|
Оба обработчика работают с методом POST и обрабатывают один и тот же путь. Разница только в типе передаываемых данных. В зависимости от содержимого заголовка Content-Type будет вызван тот или иной метод:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
>curl -X POST -d "{\"title\":\"JSON note\", \"content\": \"Very important note\"}" -H "Content-Type: application/json;charset=UTF-8" -v http://localhost:8080/api/note
> POST /api/note HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.52.1
> Accept: */*
> Content-Type: application/json;charset=UTF-8
> Content-Length: 55
>
* upload completely sent off: 55 out of 55 bytes
< HTTP/1.1 201
< Content-Type: text/plain;charset=ISO-8859-1
< Content-Length: 44
< Date: Tue, 01 May 2018 17:45:31 GMT
<
title=JSON note
content=Very important note
|
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
>curl -X POST -d "<note><title>XML note</title><content>Old school note</content></note>" -H "Content-Type: text/xml" -v http://localhost:8080/api/note
> POST /api/note HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.52.1
> Accept: */*
> Content-Type: text/xml
> Content-Length: 70
>
* upload completely sent off: 70 out of 70 bytes
< HTTP/1.1 201
< Content-Type: text/plain;charset=ISO-8859-1
< Content-Length: 39
< Date: Tue, 01 May 2018 17:46:28 GMT
<
title=XML note
content=Old school note
|
Что интересно, если указать не тот Content-Type или не указать его вообще, Spring автоматически вернёт ошибку:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
>curl -X POST -d "Text only note" -H "Content-Type: text/plain" -v http://localhost:8080/api/note
* Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8080 (#0)
> POST /api/note HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.52.1
> Accept: */*
> Content-Type: text/plain
> Content-Length: 14
>
* upload completely sent off: 14 out of 14 bytes
< HTTP/1.1 415
< Content-Type: application/json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Tue, 01 May 2018 17:48:32 GMT
<
{"timestamp":1525196912312,"status":415,"error":"Unsupported Media Type","message":"Content type 'text/plain' not supported","path":"/api/note"}
|
Content-Type передаётся как с запросом, так и с ответом. Обычно Spring довольно неплохо сам определяет тип передаваемых данных и самостоятельно выставляет корректное значение Content-Type, но, при необходимости, можно задать его и вручную. А ещё можно задать несколько разных Content-Type, на случай, если мы хотим возвращать разные данные для одного вызова.
Например, в сервисе заметок, описанном выше, вы хотели бы строго следовать принципам REST и иметь один единственный уникальный путь к каждой заметке и при этом предоставлять как машинно читаемое API, так и HTML страницы для человека. Это можно реализовать с помощью двух методов, отдающих контент разных типов:
|
1
2
3
4
5
6
7
8
9
|
@GetMapping(value = "/note", produces = "application/json;charset=UTF-8")
String getJsonNote() {
return "{\"title\":\"Stored note\", \"content\": \"A note on the server\"}";
}
@GetMapping(value = "/note", produces = "application/html")
String getHtmlNote() {
return "<html><head><title>Stored note</title></head><body><h1>Stored note</h1><p>A note on the server</p></body></html>";
}
|
А чтобы выбрать соответствующий метод, необходимо передать заголовок Accept в запросе:
|
1
2
3
4
5
6
7
8
9
10
11
12
|
>curl -v -H "Accept: application/json" http://localhost:8080/api/note
> GET /api/note HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.52.1
> Accept: application/json
>
< HTTP/1.1 200
< Content-Type: application/json;charset=UTF-8
< Content-Length: 58
< Date: Tue, 01 May 2018 18:05:18 GMT
<
{"title":"Stored note", "content": "A note on the server"}
|
|
1
2
3
4
5
6
7
8
9
10
11
12
|
>curl -v http://localhost:8080/api/note
> GET /api/note HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.52.1
> Accept: */*
>
< HTTP/1.1 200
< Content-Type: application/html;charset=ISO-8859-1
< Content-Length: 112
< Date: Tue, 01 May 2018 18:16:36 GMT
<
<html><head><title>Stored note</title></head><body><h1>Stored note</h1><p>A note on the server</p></body></html>* Curl_http_done: called premature == 0
|
Если Accept не передавать или указывать в нём достаточно широкие варианты, по умолчанию будет выбран text/html. А вот если указать неподдерживаемый тип, будет возвращена ошибка.
Описанный выше трюк называется content negotiation и позволяет клиенту указывать, какой именно ответ он ожидает — тип данных, кодировка, язык и так далее. Однако описание всех возможностей content negotiation выходит за пределы данной статьи и ознакомиться с ним можно в других местах.
Cookies
Cookies представляют собой небольшие (до 4 килобайт) наборы данных, которые сервер может послать клиенту, а клиент будет обязан записать их и отправлять обратно серверу при каждом запросе. Cookie передаются с использованием HTTP заголовков, но, так как этот механизм тоже очень важен, в Spring Web MVC есть специальная поддержка для получения данных из Cookie.
Каждый Cookie идентифицируется тремя вещами — доменом, чтобы браузер знал, какому сайту его отправлять; путём, чтобы иметь возможность ставить разные Cookie для разных частей сайта и именем. Последнее и используется в Spring Web MVC для доступа к Cookie:
|
1
2
3
4
|
@GetMapping(value = "/cookie")
String readCookie(@CookieValue(value = "data", defaultValue = "") String data) {
return String.format("Cookie value is '%s'", data);
}
|
Так как мой код только читает Cookie, но не выставляет его значение, придётся сымитировать браузер:
|
1
2
3
4
5
6
7
8
9
10
11
12
13
|
>curl --cookie "data=Come_to_the_dark_side" -v http://localhost:8080/api/cookie
> GET /api/cookie HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.52.1
> Accept: */*
> Cookie: data=Come_to_the_dark_side
>
< HTTP/1.1 200
< Content-Type: text/plain;charset=ISO-8859-1
< Content-Length: 39
< Date: Tue, 01 May 2018 18:53:09 GMT
<
Cookie value is 'Come_to_the_dark_side'
|
HttpServletResponse
К сожалению, Spring Web MVC не предоставляет простого метода для установки Cookie. Поэтому нам придётся познакомиться с более низкими уровнями реализации HTTP в java. Весь Spring Web MVC реализован поверх Servlet API, которое построено вокруг двух объектов — запрос от клиента оборачивается в HttpSerlvetRequest, а ответ формируется из заполненного вашим кодом HttoServletResponse. Имея доступ к этим объектам, вы получаете полный контроль над всей HTTP сессией. Spring Web MVC позволяет обращаться к этим объектам напрямую, при этом отключается вся его автоматизация.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
|
@GetMapping(value = "/darkside")
void setCookie(HttpServletResponse response) throws IOException {
Cookie cookie = new Cookie("data", "Come_to_the_dark_side");
cookie.setPath("/");
cookie.setMaxAge(86400);
response.addCookie(cookie);
response.setContentType("text/plain");
response.setStatus(HttpServletResponse.SC_OK);
response.getWriter().write("We have cookies");
response.getWriter().flush();
response.getWriter().close();
}
|
Код выше создаёт объект Cookie, назначает ему срок годности и путь, и добавляет его к ответу. Всё остальное, это задание стандартных заголовков и не менее стандартного кода ответа. Обратите внимание, что метод setCookie() ничего не возвращает в Spring Web MVC и формирование всего ответа сервера происходит только путём вызова методов HttpServletResponse.
Cookie будет выслан в ответе в особом заголовке. При этом метод в запросе не играет никакой роли — Cookie будет отправлен для любого метода (кроме OPTIONS).
|
1
2
3
4
5
6
7
8
9
10
11
12
13
|
>curl -v http://localhost:8080/api/darkside
> GET /api/darkside HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.52.1
> Accept: */*
>
< HTTP/1.1 200
< Set-Cookie: data=Come_to_the_dark_side; Max-Age=86400; Expires=Wed, 02-May-2018 19:03:31 GMT; Path=/
< Content-Type: text/plain;charset=ISO-8859-1
< Transfer-Encoding: chunked
< Date: Tue, 01 May 2018 19:03:31 GMT
<
We have cookies
|
Статья уже получилась довольно длинной, поэтому я разобью её на две. В следующей части мы рассмотрим управлением кэшированием, обработку формп и загрузку файлов. Код примера доступен на github.