Краткое руководство по матричным переменным Spring MVC

1. Обзор

Спецификация URI RFC 3986 определила параметры пути URI как пары имя-значение. Переменные матрицы-это термин, придуманный весной, и альтернативная реализация для передачи и анализа параметров пути URI.

Поддержка матричных переменных стала доступна в Spring MVC 3.2 и предназначена для упрощения запросов с большим количеством параметров .

В этой статье мы покажем, как мы можем упростить сложные запросы GET, которые используют переменные или необязательные параметры пути внутри различных сегментов пути URI.

2. Конфигурация

Чтобы включить переменные матрицы Spring MVC, давайте начнем с конфигурации:

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        UrlPathHelper urlPathHelper = new UrlPathHelper();
        urlPathHelper.setRemoveSemicolonContent(false);
        configurer.setUrlPathHelper(urlPathHelper);
    }
}

В противном случае они отключены по умолчанию.

3. Как использовать переменные матрицы

Эти переменные могут появляться в любой части пути, и символ equals (“=”) используется для указания значений, а точка с запятой (“;”) – для разграничения каждой переменной матрицы. На том же пути мы также можем повторить одно и то же имя переменной или разделить разные значения с помощью запятой(‘,’).

В нашем примере есть контроллер, который предоставляет информацию о сотрудниках. У каждого сотрудника есть рабочая зона, и мы можем искать по этому атрибуту. Для поиска можно использовать следующий запрос:

http://localhost:8080/spring-mvc-java-2/employeeArea/workingArea=rh,informatics,admin

или вот так:

http://localhost:8080/spring-mvc-java-2
  /employeeArea/workingArea=rh;workingArea=informatics;workingArea=admin

Когда мы хотим ссылаться на эти переменные в Spring MVC, мы должны использовать аннотацию @MatrixVariable .

В наших примерах мы будем использовать класс Employee :

public class Employee {

    private long id;
    private String name;
    private String contactNumber;

    // standard setters and getters 
}

А также Компания класс:

public class Company {

    private long id;
    private String name;

    // standard setters and getters
}

Эти два класса свяжут параметры запроса.

4. Определение Свойств Переменных Матрицы

Мы можем указать обязательные или стандартные свойства для переменной. В следующем примере требуется контактный номер , поэтому он должен быть включен в наш путь, что-то вроде этого:

http://localhost:8080/spring-mvc-java-2/employeesContacts/contactNumber=223334411

Запрос будет обработан следующим способом:

@RequestMapping(value = "/employeesContacts/{contactNumber}", 
  method = RequestMethod.GET)
@ResponseBody
public ResponseEntity> getEmployeeBycontactNumber(
  @MatrixVariable(required = true) String contactNumber) {
    List employeesList = new ArrayList();
    ...
    return new ResponseEntity>(employeesList, HttpStatus.OK);
}

В результате мы получим всех сотрудников, у которых есть контактный номер 223334411 .

5. Параметр Дополнения

Переменные матрицы могут дополнять переменные пути.

Например, мы ищем сотрудника по его имени, но мы также можем указать начальные номера его контактного номера.

Запрос на этот поиск должен быть таким:

http://localhost:8080/spring-mvc-java-2/employees/John;beginContactNumber=22001

Запрос будет обработан следующим способом:

@RequestMapping(value = "/employees/{name}", method = RequestMethod.GET)
@ResponseBody
public ResponseEntity> getEmployeeByNameAndBeginContactNumber(
  @PathVariable String name, @MatrixVariable String beginContactNumber) {
    List employeesList = new ArrayList();
    ...
    return new ResponseEntity<>(employeesList, HttpStatus.OK);
}

В результате мы получим всех сотрудников, у которых есть контактный номер 22001 или чье имя Джон .

6. Привязка Всех Переменных Матрицы

Если по какой-то причине мы хотим получить все переменные, доступные на пути, мы можем привязать их к карте :

http://localhost:8080/spring-mvc-java-2/employeeData/id=1;name=John;contactNumber=2200112334

Этот запрос будет обработан следующим способом:

@GetMapping("employeeData/{employee}")
@ResponseBody
public ResponseEntity> getEmployeeData(
  @MatrixVariable Map matrixVars) {
    return new ResponseEntity<>(matrixVars, HttpStatus.OK);
}

Конечно, мы можем ограничить привязку к переменным матрицы определенной части пути. Например, если у нас есть такой запрос:

http://localhost:8080/spring-mvc-java-2/
  companyEmployee/id=2;name=Xpto/employeeData/id=1;name=John;
  contactNumber=2200112334

И мы хотим получить только все переменные, которые принадлежат данным сотрудника ; тогда мы должны использовать в качестве входного параметра это:

@RequestMapping(
 value = "/companyEmployee/{company}/employeeData/{employee}",
 method = RequestMethod.GET)
@ResponseBody
public ResponseEntity> getEmployeeDataFromCompany(
  @MatrixVariable(pathVar = "employee") Map matrixVars) {
  ...
}

7. Частичная Привязка

Помимо простоты, гибкость является еще одним преимуществом, матричные переменные могут использоваться различными способами. Например, мы можем получить каждую переменную из каждого сегмента пути. Рассмотрим следующий запрос:

http://localhost:8080/spring-mvc-java-2/
  companyData/id=2;name=Xpto/employeeData/id=1;name=John;
  contactNumber=2200112334

Если мы хотим знать только переменную матрицы имя сегмента данных компании , то мы должны использовать в качестве входного параметра следующее:

@MatrixVariable(value="name", pathVar="company") String name

8. Заключение

В этой статье проиллюстрированы некоторые из различных способов использования матричных переменных.

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

Реализация всех этих примеров и фрагментов кода может быть найдена в проекте GitHub – это проект на основе Maven, поэтому его должно быть легко импортировать и запускать как есть.