Английская версия

🗺️ Xmap (Карта мест)

❓ Небольшая помощь для разработчиков

👉 Как открыть Swagger документацию:

http://localhost:8080/swagger-ui/index.html

👉 Как получить коллекцию для Postman:

Скачайте последнюю версию с https://github.com/ShulV/Xmap/tree/main/postman и импортируйте в Postman.

👉 Как инициализировать базу данных (PostgreSQL):

• Создайте все таблицы, индексы, функции и т.д., также вставьте основные справочники: https://github.com/ShulV/Xmap/blob/main/sql/generate_DB.sql
• Вставьте справочники для стран/регионов/городов: https://github.com/ShulV/Xmap/blob/main/sql/insert_cities_regions_countries.sql
• Вставьте пользователя и некоторые реальные споты: https://github.com/ShulV/Xmap/blob/main/sql/additional_insert_scripts.sql

👉 Как просмотреть модель базы данных:

Скачайте и откройте в специальных UML-инструментах: https://github.com/ShulV/Xmap/blob/main/uml/relation_model.csv

Разработчики должны держать эту модель в актуальном состоянии или добавлять в репо новые её версии, указывая в названии дату изменения.

👉 Как писать логи:

• Используйте snake_case для переменных
• Записывайте переменные в квадратных скобках ('[', ']')
• Пишите двоеточие (':') перед блоком переменных
• logger.info() - информация, logger.warn() - предупреждения, logger.error() - критические ошибки

logger.info("Информация об изображении создана: [image_info_id = '{}']", imageInfo.getId());

👉 Код стайл:

Максимальное количество символов в строке - 130. По дефолту IntelliJ IDEA устанавливает ограничительную линию на 120 (перенастроить).

Как называть ключи JSON:

(snake_case)

"some_key_name" : "value" 

Многие библиотеки JSON (в Spring Framework), такие как Jackson, поддерживают формат camelCase из коробки.

Но было решено, что snake_case более удобен для чтения.

Как называть ключи в структурах данных например в HashMap ("key_name", "value"):

snake_case

Map<String, String>; someMap = new HashMap<>();
someMap.put("key_name_in_snake_case", "value");

Как называть пути роутов (эндпоинтов):

kebab-case

@RequestMapping("/api/v1/image-service") //для всего контроллера

@PostMapping("/spot-image/{id}") //для метода

Размеры методов и классов:

Максимальная длина методов - 100 строк. Максимальная длина класса - 1000 строк.

Если размер метода или класса превышает эти значения, новая бизнес-логика может быть добавлена только в виде вызовов методов других функций.

Но лучше внимательно рефакторить!

Структура пакетов:

Когда появляется более одного контроллера, сервиса, репозитория, модели, DTO и т.д., мы объединяем их в один пакет.

👉 Внедрение зависимостей с использованием Lombok:

Используйте @RequiredArgsConstructor и только его. 1 конструктор для внедрения зависимостей (без аннотации @Autowired).

Lombok сгенерирует конструктор, который принимает все необходимые зависимости, помеченные из переменных final или @NonNull.

👉 Swagger V.3

• @Operation: Эта аннотация используется для документирования отдельных операций в вашем контроллере. Она позволяет предоставить подробное описание операции, включая краткое описание (summary), подробное описание (description), теги (tags), параметры запроса, схему запроса и ответа.

      ```java
        @Operation(
          summary = "Get user by ID",
          description = "Returns a single user by ID",
          parameters = {
              @Parameter(name = "userId", description = "User ID", in = ParameterIn.PATH)
          },
          responses = {
              @ApiResponse(responseCode = "200", description = "Successful operation", 
                content = @Content(mediaType = "application/json")),
              @ApiResponse(responseCode = "404", description = "User not found")
          },
          tags = {"User Operations"}
          )
        ```
  

• @Parameter: Используется для описания параметров запроса. Например, параметры пути, параметры запроса, параметры заголовков и т. д.

      ```java
        @Parameter(name = "userId", description = "User ID", in = ParameterIn.PATH)
        ```
  

• @RequestBody: Определяет тело запроса для операции. Используется для описания тела запроса для операций типа POST, PUT, и др.

      ```java
        @RequestBody(description = "User details", required = true, content = @Content(mediaType = "application/json"))
        ```
  

• @ApiResponse: Описывает возможные ответы от операции. Указывает код состояния HTTP, описание и схему ответа.

      ```java
        @ApiResponses(value = {
          @ApiResponse(responseCode = "200", description = "Successful operation", 
          content = @Content(mediaType = "application/json")),
          @ApiResponse(responseCode = "404", description = "User not found")
          })
        ```
  

• @Hidden: Скрывает операцию в документации Swagger. Полезно, например, если вы хотите временно исключить операцию из документации.

      ```java
        @Hidden
        ```
  

• @Tag: Используется для группировки операций в документации Swagger по тегам. Это удобно для организации и структурирования больших API.

      ```java
        @Tag(name = "User Operations", description = "Endpoints for user-related operations")
        ```
  

👉 Работа с access и refresh токенами

Как кодировать/декодировать?

❓ Некоторые пока что нерешенные проблемы приложения:

• Проблема Hibernate N+1
• LOMBOK в тестах не работает, не понял почему. Внедряем зависимости там с помощью одного конструктора с @Autowired (без него даже с одним конструктором почему-то не работает).