Примечание: эти рекомендации - адаптированный под публикацию результат 5-летних проверок выпускных работ участников нашей стажировки "Enterprise Java-разработчик". Часть из них относится только к выполнению тестового задания при устройстве на работу: Java-приложение с REST API. Часть - к разработке на Java. И часть - к разработке любых приложений. Надеюсь, что каждый найдет что-то полезное. Буду рад обсуждению спорных тем в комментариях.
Общие рекомендации при реализации тестового задания:
Не изобретай велосипедов! Грубая ошибка - пытаться сделать стандартные вещи по-своему, чаще всего криво. На проекте все должно быть единообразно. Найди небольшой проект с кодом, который сделан красиво и правильно (хотя бы Spring Pet Clinic) и сделай все максимально в этом стиле.
Рекомендую писать проект на востребованном на рынке стеке: на Java это Spring Boot + Spring Data JPA (работа с БД) + Swagger/OpenAPI 3.0 (REST документация).
Представьте себе, что ПМ (лид, архитектор) дал вам ТЗ и некоторое время недоступен. У вас, конечно, есть много мыслей, для чего нужно приложение, как исправить ТЗ, дополнить его и сделать правильно. НО НЕ НАДО ИХ РЕАЛИЗОВЫВАТЬ В КОДЕ. Нужно сделать все строго по ТЗ, максимально просто, удобно для доработок и для использования со стороны клиента.
Совершенство достигнуто не тогда, когда нечего добавить, а тогда, когда нечего отнять
Антуан де Сент-Экзюпери
Рекомендации по разделам:
1: ТЗ (Тех.задание)
1.1: Читай ТЗ ОЧЕНЬ внимательно, НЕ надо ничего своего туда домысливать и творчески изменять
1.2: Учитывай, что пользователей может быть много, а админов - мало (если в ТЗ есть такие роли)
1.3: Сначала сделай основные сценарий по ТЗ. Все остальное (если очень хочется, 3 раза подумай) - потом
2. API
2.1: API продумывай не с точки зрения программиста и объектов, а с точки зрения того, кто им будет пользоваться (клиента, UI)
2.2: Тщательно считай количество запросов в API для отображения нужной информации
2.3: Из потребностей приложения (клиента) реализуй только очевидные сценарии. Необходимо и достаточно: ВСЕ НЕОБХОДИМОЕ для клиента и НИЧЕГО ЛИШНЕГО. Процесс творческий, приходит с опытом
2.4: Делаем REST API в соответствии с концепцией REST (url в общем имеют вид
{ресурс}/{id_ресурсa}[/{подресурс}/{id_подресурсa}][параметры]). Имена ресурсов во множественном числе! Самая распространенная и грубая ошибка - не придерживаться этих простых правил2.5: Разделение на роли я предпочитаю на уровне URL. Сразу и однозначно видно, какой API у админа, какое у пользователя (API админа начинается, например, с /admin/...)
2.6: На управление (CRUD) разными ресурсами должны быть ОТДЕЛЬНЫЕ контроллеры. Не надо все, что может админ, сваливать в одну кучу
2.7: Проверьте в Swagger, что в POST и PUT нет ничего лишнего, а в GET есть все необходимые данные
2.8. Исключите из Swagger служебные контроллеры, которые не относятся к API
3: Код:
3.1: Строго соблюдайте соглашения Java по именованию: пакеты только маленькими буквами, методы начинаются с маленькой буквы, классы с большой. Незнания Java Core - тестовое задание сразу в корзину
3.2 В проекте (и тестовом задании на работу), в отличие от учебного, оставляйте только необходимый для работы по ТЗ приложения код, ничего лишнего
3.2.1: НЕ надо делать разные профили базы и работы с ней
3.2.2: НЕ надо делать абстрактных контроллеров на всякий случай
3.2.3: НЕ обязательно делать сервисы, если там нет ничего, кроме делегирования в репозитории
3.2.4: НЕ нужны локализация, UI (если по ТЗ нужен только REST API), типы ошибок, Json View
3.3: Название пакетов, имен классов для
model/to/webстандартные (например,model/domain). НЕ надо придумывать своих собственных правил3.4: Вместо
return ResponseEntity.ok(entity)в контроллерах пишитеreturn entity. Проще!
4: Модель
4.1: Если в приложении есть БД, обычно там хранятся все введенные пользователем и админом данные (история). Они не удаляются и не переписываются заново
4.2: Не делайте в модели объектов, которые не будут использоваться в коде (например, не надо двунаправленных связей, если достаточно однонаправленных)
4.3: Еще раз про hashCode/equals в Entity: не делайте в модели сравнение по полям!
4.4: ORM работает с объектами. Иногда, для упрощения логики, fk_id как поля допустимы
5: Архитектура
5.1: Можно:
или подключить Spring Data Rest. Контроллеры генерируются автоматически по репозиториям, требуется настройка ресурсов в кастомных контроллерах
или делать без Spring Data Rest
Нельзя смешивать эти подходы вместе (делать собственные контроллеры в дополнение к тем, что автогенерируются). Я рекомендую 2-й вариант, без Spring Data Rest. Обязательно посмотрите в Swagger, какие контроллеры получились в результате.
5.2: Не размещайте бизнес-логику приложения и преобразования в Transfer Objects (TO) в слое доступа к DB
5.3: Не смешивайте TO и Entity вместе (в частности не передавать Entity в конструктор TO). Они должны быть независимыми друг от друга. Есть разные варианты реализации приложений, c использованием TO и без. Тестовое задание делаем максимально просто.
6. Доступ к БД
6.1: Используйте Spring Data JPA. Методы Repository можно вызывать напрямую из сервиса или из контроллера.
6.2: Если приложению в объекте требуется только его id, используйте reference (
getByIdв последних версиях spring-data-jpa)6.3: В DATA-JPA 2.x используются
Optional. Попробуйте работать с ними, это безопасный способ работать с null-значениями (используйтеorElseThrow)6.4: Не делайте при обновлении записи ради экономии пары строчек кода так:
if(updateCondition)
repository.delete(entity)
}
repository.save(entity)Обновление записи базы должно быть через
UPDATE.
7: База Данных
7.1: Берите без установки (embedded, например H2 или HSQLDB) и создавайте в памяти! Ваше приложение должно сразу запуститься, без всяких настроек и переменных окружения
7.2: Тщательно считайте количество обращений в базу на каждый запрос. Особенно при запросах от пользователей, которых может быть очень много. Также на сложность запросов от них, чтобы не положить базу
7.3: Сделайте индексы к таблицам. Попробуйте обеспечить UNIQUE. Следите за порядком полей в индексе, от этого зависит индексирование запросов.
7.4: При популировании данных, связанных с датами можно использовать
now(), чтобы всегда были актуальные исходные данные7.5: Поля базы case insensitive, не пишите camelStyle (для которых нужны кавычки)
7.6: Таблицы я предпочитаю именовать в единственном числе. Исключение -
users,ordersи другие зарезервированные слова7.7:
date/timestamp- зарезервированные слова, лучше избегать их при именовании полей
8: Security
8.1: Проверьте, станет ли код проще с
@AuthenticationPrincipal8.2: Я предпочитаю четкое разделение ролей на основе URL. Например, для админа URL содержит
/admin
9: Кэширование
9.1: Кэширование желательно для частых и редко меняющихся запросов от пользователей. Тщательно продумайте, что надо кэшировать (самые частые запросы), а что нет (большие или редко запрашиваемые данные)
9.2: Проверьте соответствие ключей к кэшу (параметры кэшируемого метода) с конфигурацией кэша
10: Валидация
10.1: Одних аннотаций валидации недостаточно. Должны быть
@Valid/ @Validation10.2: Проверяйте входные данные Primary Key при
create/updateв контроллерах. Public API you should be conservative when you reply, but accept liberally
11: Дополнительно
11.1: JUnit-тесты очень желательны. Можно не делать 100% покрытие, только основные сценарии
11.2: Уделяйте внимание обработке ошибок. Чтобы кастомизировать обработку в Spring Boot, можно наследоваться от
ResponseEntityExceptionHandler.
12: Readme.md
12.1: В начале
readmeдолжно быть ТЗ или ссылка на него - будет понятно о чем проект12.2: Если задание на English, описание пиши также на English (то же самое относится к языку резюме: вакансия на English предполагает резюме на English)
12.3: Помести в
readmeссылку на Swagger UI с креденшелами для выполнения запросов12.4: Проверяют задания люди с опытом в Java: не надо писать инструкций, как устанавливать Java и Maven
13: Git
13.1: Должна быть история комитов с внятными комментариями. Это смотрят.
13.2: Не комить служебные файлы: логи, DB, настройки IDEA и пр., это грубая ошибка.
13.3: Все служебные файлы должны быть в
.gitignore
Проверка
Попробуй подергать свое API по всем типичным сценариям ТЗ
Удобно использовать? Можно сделать проще?
Сколько раз пришлось вызвать API для типичного сценария?
Сколько запросов к базе было сделано? Можно ли сократить (например с
FETCH/Graphили через кэширование)?Еще раз - проверь все запросы в Swagger, смотри на формат запросов и данные в ответе. Все должно работать, есть все данные и нет ничего лишнего
API ДОЛЖЕН соответствовать принципам REST (см. ссылки выше)
ОБЯЗАТЕЛЬНО: запусти
mvn test- ошибок быть не должноОБЯЗАТЕЛЬНО: запусти приложение без всяких предварительных настроек (базы, переменных окружения, ..), лучше на другом компьютере. Приложение должно запускаться и работать!
Спасибо за внимание!
Буду рад, если часть советов пригодится и вашим замечаниям и дополнениям.
