В данной статье я рассмотрю процесс разработки простого веб-приложения с использованием Spring и Thymeleaf. Данный проект будет использоваться в последующих статьях, в рамках которых приложение будет описано дальнейшее развитие приложения. Исходный код проекта доступен по этой ссылке.
Содержание
- О проекте, его структура и зависимости
- Классы-сущности и репозитории
- Модульное и интеграционное тестирование
- Контроллеры
- Шаблоны Thymeleaf
- Интернационализация
О проекте
Разрабатываемый проект — простой хелпдеск, основная цель которого — предоставить пользователям возможность уведомлять службу технической поддержки о возникающих проблемах. Кроме возможности создания самих заявок (или обращений), должна быть реализована возможность оставлять комментарии к заявкам.
Для данного проекта потребуются следующие зависимости:
- Spring Data JPA для работы с базой данных
- Thymeleaf для описания шаблонов
- СУБД H2 в качестве хранилища данных
- Lombok для минимизации рутинного кода вроде get/set-методов и конструкторов
Project Lombok
Данный инструмент значительно упрощает процесс разработки, добавляя перед компиляцией необходимые рутинные элементы, такие как get/set-методы, конструкторы, логгеры и многое другое. Поддержка данного инструмента есть во всех главных Java IDE. Более подробно с Lombok можно ознакомиться на официальном сайе проекта.
В итоге pom.xml будет выглядеть следующим образом:
|
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 |
<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-thymeleaf</artifactId> </dependency> <dependency> <groupId>com.h2database</groupId> <artifactId>h2</artifactId> <scope>runtime</scope> </dependency> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies> |
Поскольку проект основан на Spring Boot, можно сгеренировать заготовку проекта при помощи Spring Initializr.
Классы-сущности и репозитории
Как уже было сказано, основные возможности нашего проекта — создание и обсуждение заявок. Следовательно, нам потребуется всего два класса-сущностей: для описания заявки и для описания комментария. Авторизация будет рассматриваться в следующей статье, так что в классах-сущностях информации об авторах записей не будет.
В классе, описывающем заявку или обращение, понадобится четыре свойства:
- Идентификатор
- Краткое описание проблемы
- Подробное описание проблемы
- Дата создания
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
@Entity @Data @NoArgsConstructor @AllArgsConstructor public class Ticket { @Id @GeneratedValue private int id; @Column(nullable = false) private String issue; @Column(columnDefinition = "TEXT") private String issueDetails; @Column(nullable = false, updatable = false) @Temporal(javax.persistence.TemporalType.TIMESTAMP) private Date dateCreated; } |
В классе, описывающем комментарий к заявке, понадобятся также четыре свойства:
- Идентификатор
- Текст комментария
- Дата создания
- Ссылка на заявку
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
@Entity @Data @NoArgsConstructor @AllArgsConstructor public class TicketComment { @Id @GeneratedValue private int id; @Column(columnDefinition = "TEXT") private String comment; @Column(nullable = false, updatable = false) @Temporal(javax.persistence.TemporalType.TIMESTAMP) private Date dateCreated; @ManyToOne private Ticket ticket; } |
Немножко задержимся на аннотациях, фигурирующих в наших классах-сущностях.
- @Entity — JPA-аннотация уровня типа, обозначающая, что данный класс проецируется на таблицу в базе данных.
- @Data — аннотация Lombok, добавляющая все рутинные методы классов сущностей, среди которых get/set-методы, hashCode, equals и toString.
- @NoArgsConstructor добавляет конструктор без аргументов.
- @AllArgsConstructor добавляет конструктор со всеми аргументами.
- @Id означает, что помеченное свойство является первичным ключом.
- @GeneratedValue означает, что значение данного свойства при сохранении должно быть сгенерировано. В Spring Boot по-умолчанию используется стратегия IDENTITY. Таким образом фактическое значение данной аннотации: @GeneratedValue(strategy = GenerationType.IDENTITY)
- @Column указывает дополнительные свойства колонки в таблице БД. Атрибут nullable=false указывает фреймворку, что свойство не может быть null, атрибут updatable=false — что свойство не может изменяться, а columnDefinition=»TEXT» — что тип колонки должен быть TEXT. Это важно, так как в некоторых колонках нужно хранить более 255 символов.
- @Temporal указывает, что свойство должно храниться в таблице БД как дата.
- @ManyToOne указывает на связанный объект. Для связи в таблице БД должна существовать колонка вида имя_свойства_id, в которой будет храниться первичный ключ связанной записи. В нашем случае имя колонки будет ticket_id.
Структура базы данных
Обратите внимание, что создавать отдельно структуру базы данных не нужно, это за нас сделает Spring Data JPA, так как мы будем использовать СУБД H2, которая расценивается связкой Spring Boot и Spring Data JPA как тестовая. Если есть необходимость автоматического создания структуры базы данных в полноценных СУБД, вроде PostgreSQL или MySQL, то это можно настроить в свойствах приложения. Однако данный подход не рекомендуется и является опасным при применении в рабочих решениях. Более подробно об этом рассказано в документации Spring Boot.
Для доступа к данным нам потребуются репозитории. Поскольку в нашем проекте может понадобится постраничная разбивка данных (пейджинация), мы будем использовать PagingAndSortingRepository.
Репозиторий для заявок:
|
1 2 |
public interface TicketRepository extends PagingAndSortingRepository<Ticket, Integer> { } |
Репозиторий для комментариев:
|
1 2 3 4 |
public interface TicketCommentRepository extends PagingAndSortingRepository<TicketComment, Integer> { Page<TicketComment> findByTicket(Ticket ticket, Pageable pageable); } |
Spring Data JPA при инициализации приложения создаст объекты репозиториев и реализует объявленный нами волшебный метод. О волшебных методах я писал в предыдущей статье.
Тестирование репозиториев
Нет никакого смысла тестировать репозитории, в которых нет собственных методов, а работоспособность стандартных методов проверяется тестами разработчиками Spring Data JPA. А вот собственные методы нужно тестировать при помощи интеграционных тестов.
Модульное и интеграционное тестирование
В современном мире разработки программного обеспечения тестирование является обязательным атрибутом. Я считаю, что разработку нужно вести через тестирование (TDD), так как такой подход, на мой взгляд, минимизирует количество ошибок, проявляющихся в итоговом продукте. Разработка через тестирование очень удобна при итеративном подходе, так как условия прохождения тестов легко генерируются из критериев, которым должен удовлетворять результат итерации.
На мой взгляд, нельзя выбирать между модульным и интеграционным тестированием, так как оба способа имеют свои особенности. Интеграционные тесты могут проверять то же самое, что и модульные, но в модульных тестах тестируемый объект независим от сторонних факторов.
Тестироваться должны все возможные варианты поведения компонента, как оптимистичные, так и пессимистичные. Таким образом для тестирования некоторых методов потребуется 4-5, а то и больше тестовых методов. В реальных проектах объём тестового кода может без проблем составлять 50-75%, что может создать впечатление пустой траты рабочего времени разработчика, что совершенно неверно, так как цена ошибок, которые могли быть обнаружены тестами, порой может быть очень высокой.
В нашем проекте будут использованы оба способа тестирования, но я не буду добавлять в статью весь код, относящийся к тестированию, так как его объём значительно больше тестируемого кода.
Контроллеры, тесты и реализация
По аналогии с репозиториями нам понадобятся два класса-контроллера: один — для работы с заявками, второй — для работы с комментариями.
Давайте взглянем на контроллер для работы с заявками:
|
1 2 3 4 5 6 7 8 9 10 |
@Controller @RequestMapping("tickets") @AllArgsConstructor public class TicketsController { private final TicketRepository repository; private final TicketCommentRepository ticketCommentRepository; } |
Здесь мы использовали следующие аннотации:
- @Controller — аннотация-стереотип Spring Framework, говорящая, что данный класс является классом-контроллером. Spring Framework, обнаружив данную аннотацию, создаст в контексте приложения экземпляр этого класса. В Spring Boot — это поведение по-умолчанию.
- @RequestMapping — аннотация, указывающая, что отмеченный класс-контроллер или метод будет обрабатывать HTTP-запросы с подходящим адресом. В нашем случае TicketsController будет обрабатывать запросы вида http://localhost:8080/tickets
- @AllArgsCostructor уже упоминалась, она при компиляции добавит конструктор со всеми атрибутами, которыми в нашем случае являются repository и ticketCommentRepository. Объекты этих типов будут получены из контекста приложения и переданы в конструктор средствами Spring Framework.
При разработке через тестирование заготовка контроллера должна быть минимальной — в ней не должно быть вообще ничего, даже указанных аннотаций.
Теперь на примере страницы со списком заявок мы разберём написание тестов и реализации.
Просмотр списка заявок
Реализуемая задача звучит следующим образом: «В приложении должна быть страница со списком всех заявок, на которой также должна находиться ссылка на страницу создания новой заявки».
В модульном тесте мы можем проверить, что:
- Метод должен вызываться с аргументом типа Pageable.
- Из репозитория был получен список заявок
- Возвращённая в ответе модель содержит список заявок
- Возвращённое в ответе имя шаблона соответствует ожидаемому
Код модульного теста:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
public class TicketsControllerTests { @Test public void indexShouldReturnModelAndView() { doReturn(new PageImpl<>(Arrays.asList(new Ticket(), new Ticket(), new Ticket()))).when(repository) .findAll(any(Pageable.class)); ModelAndView index = controller.index(new PageRequest(0, 10)); verify(repository).findAll(notNull(Pageable.class)); assertViewName(index, "tickets/index"); } } |
Обратите внимание, что результат работы сторонних компонентов мы имитируем. Имитация всех возможных вариантов поведения сторонних компонентов даёт возможность протестировать правильность работы тестируемого компонента в любых условиях.
В интеграционном тесте мы можем проверить, что GET-запрос к http://localhost:8080/tickets:
- Возвратит страницу, на которой есть ссылка на создание новой заявки
- Возвратит HTTP-статус 200 OK
Код интеграционного теста:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
@RunWith(SpringRunner.class) @SpringBootTest @AutoConfigureMockMvc public class TicketsControllerIntegrationTests { @Autowired private MockMvc mockMvc; @Test public void indexShouldReturnTicketsPage() throws Exception { mockMvc.perform(get("/tickets")) .andDo(print()) .andExpect(model().attributeExists("page")) .andExpect(view().name("tickets/index")) .andExpect(status().isOk()) .andExpect(xpath(".//a[@href='/tickets/create']").exists()); } } |
Код метода, который будет удовлетворять тестовым методам:
|
1 2 3 4 5 6 7 8 9 10 |
public class TicketsController { @GetMapping public ModelAndView index(Pageable page) { ModelAndView modelAndView = new ModelAndView("tickets/index"); modelAndView.addObject("page", repository.findAll(page)); return modelAndView; } } |
Аннотация @GetMapping является укороченной версией @RequestMapping(method = RequestMethod.GET).
Для прохождения интеграционного теста понадобится шаблон templates/tickets/index.html.
Шаблоны и Thymeleaf
В качестве библиотеки шаблонов в проекте мы используем Thymeleaf. По-умолчанию данная библиотека работает в режиме XHTML 5. Для использования тегов и атрибутов Thymeleaf необходимо подключить соответствующий неймспейс:
|
1 |
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:th="http://www.thymeleaf.org/"> |
Подробно описывать работу с Thymeleaf в рамках данной статьи я не буду, это обязательно будет сделано в одной из ближайших статей, но остановлюсь на основных моментах. Для использования возможностей Thymeleaf в шаблонах используются атрибуты и теги из его неймспейса, например th:text — для вывода текста внутри указанного тега или th:each — для обхода коллекции в стиле foreach:
|
1 2 3 |
<ul> <li th:each="user : ${users}" th:text="${user.name}"></li> </ul> |
Интернационализация
Современное приложение, рассчитанное на массовую аудиторию, сложно представить без интернационализации или локализации. В Spring Boot есть поддержка интернационализации прямо из коробки, и всё, что требуется от разработчика — добавить файлы перевода для разных локалей и настроить механизм переключения между локалями.
Для запоминания локали в нашем приложении на данном этапе мы будем использовать файлы Cookie. В классе-конфигурации для этого нужно добавить один метод:
|
1 2 3 4 |
@Bean public CookieLocaleResolver localeResolver() { return new CookieLocaleResolver(); } |
Переключаться между локалями мы будем при помощи гиперссылок на странице нашего приложения, соответственно, нам нужно настроить переключение локали по параметру запроса. Для этого в классе-конфигурации нужно зарегистрировать перехватчик LocaleChangeInterceptor, который будет искать в параметрах запроса параметр с выбранной локалью (по умолчанию — locale).
|
1 2 3 4 5 6 7 8 |
@Configuration public class WebConfig extends WebMvcConfigurerAdapter { @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new LocaleChangeInterceptor()); } } |
Теперь при переходе внутри приложения по любой ссылке, содержащей параметр locale, пользовательская локаль будет изменяться.
После этого останется в src/main/resources добавить файлы локализации для нужных локалей. В Spring используется имя бандла messages, соответственно, имя файла со значениями по умолчанию — messages.properties. Обращу внимание, что для корректной работы переключения между локалями может потребоваться отключение автоматического использования системной локали при отсутствии файла локализации с выбранной локалью (свойство spring.messages.fallback-to-system-locale).
После того, как всё настроено, можно использовать коды сообщений в шаблонах. Для этого в Thymeleaf используются выражения вида #{}, например — #{msg.greeting}.
Результат
Проект в текущем состоянии реализует базовые возможности, но не является завершённым и имеет проблемы с ограничением доступа и конкурентным доступом, а так же не гарантирует стопроцентной доступности. В следующих статьях я буду описывать способы решения этих проблем.