В этой статье вы узнаете, как использовать Spring for GraphQL в своем приложении Spring Boot.
Spring for GraphQL — относительно новый проект. Версия 1.0 была выпущена несколько месяцев назад. До этого релиза нам приходилось подключать сторонние библиотеки, чтобы упростить реализацию GraphQL в приложении Spring Boot. Я уже описал два альтернативных решения в своих предыдущих статьях. В следующей статье вы узнаете о проекте GraphQL Java Kickstart. В другой статье вы увидите, как создавать более сложные запросы GraphQL с помощью библиотеки Netflix DGS.
Мы будем использовать очень похожую схему и модель сущностей, как и в этих двух статьях о Spring Boot и GraphQL.
Исходный код
Если вы хотите попробовать сделать это самостоятельно, вы всегда можете посмотреть на мой исходный код. Для этого вам нужно клонировать мой репозиторий GitHub. Затем просто следуйте моим инструкциям.
Во-первых, вы должны перейти в каталог sample-app-spring-graphql. Наш пример на Spring Boot предоставляет API на базе GraphQL и подключается к базе данных H2 в памяти. Он использует Spring Data JPA в качестве слоя для взаимодействия с базой данных. Есть три сущности Employee, Department и Organization. Каждая из них хранится в отдельной таблице. Вот модель отношений.
Начало работы со Spring for GraphQL
В дополнение к стандартным модулям Spring Boot нам необходимо включить следующие две зависимости:
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-graphql</artifactId> </dependency> <dependency> <groupId>org.springframework.graphql</groupId> <artifactId>spring-graphql-test</artifactId> <scope>test</scope> </dependency>spring-graph-test предоставляет дополнительные возможности для построения модульных тестов. Стартер поставляется с необходимыми библиотеками и автоконфигурацией. Однако он не включает интерфейс GraphiQL. Чтобы включить его, мы должны установить следующее свойство в файле application.yml:
spring: graphql: graphiql: enabled: trueПо умолчанию Spring for GraphQL пытается загрузить файлы схемы из каталога src/main/resources/graphql. Он ищет там файлы с расширениями .graphqls или .gqls. Приведем схему GraphQL для сущности Department. Тип Department ссылается на два других типа: Organization и Employee (список сотрудников). Есть два запроса для поиска всех отделов и отдела по id и одна мутация для добавления нового отдела.
type Query { departments: [Department] department(id: ID!): Department! } type Mutation { newDepartment(department: DepartmentInput!): Department } input DepartmentInput { name: String! organizationId: Int } type Department { id: ID! name: String! organization: Organization employees: [Employee] }Схема типа Organization очень похожа. Из более сложных вещей нам нужно обрабатывать соединения с типами Employee и Department.
extend type Query { organizations: [Organization] organization(id: ID!): Organization! } extend type Mutation { newOrganization(organization: OrganizationInput!): Organization } input OrganizationInput { name: String! } type Organization { id: ID! name: String! employees: [Employee] departments: [Department] }И последняя схема — для типа Employee. В отличие от предыдущих схем, она определяет тип, отвечающий за обработку фильтрации. EmployeeFilter может фильтровать по зарплате, должности или возрасту. Существует также метод запроса для обработки фильтрации — employeesWithFilter.
extend type Query { employees: [Employee] employeesWithFilter(filter: EmployeeFilter): [Employee] employee(id: ID!): Employee! } extend type Mutation { newEmployee(employee: EmployeeInput!): Employee } input EmployeeInput { firstName: String! lastName: String! position: String! salary: Int age: Int organizationId: Int! departmentId: Int! } type Employee { id: ID! firstName: String! lastName: String! position: String! salary: Int age: Int department: Department organization: Organization } input EmployeeFilter { salary: FilterField age: FilterField position: FilterField } input FilterField { operator: String! value: String! }Создание сущностей
Не держите на меня зла, но я использую Lombok при реализации сущностей. Вот сущность Employee, соответствующая типу Employee, определенному в схеме GraphQL.
@Entity @Data @NoArgsConstructor @AllArgsConstructor @EqualsAndHashCode(onlyExplicitlyIncluded = true) public class Employee { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) @EqualsAndHashCode.Include private Integer id; private String firstName; private String lastName; private String position; private int salary; private int age; @ManyToOne(fetch = FetchType.LAZY) private Department department; @ManyToOne(fetch = FetchType.LAZY) private Organization organization; }Здесь создается сущность Department.
@Entity @Data @AllArgsConstructor @NoArgsConstructor @EqualsAndHashCode(onlyExplicitlyIncluded = true) public class Department { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) @EqualsAndHashCode.Include private Integer id; private String name; @OneToMany(mappedBy = "department") private Set<Employee> employees; @ManyToOne(fetch = FetchType.LAZY) private Organization organization; }Наконец, мы можем взглянуть на сущность Organization.
@Entity @Data @AllArgsConstructor @NoArgsConstructor @EqualsAndHashCode(onlyExplicitlyIncluded = true) public class Organization { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) @EqualsAndHashCode.Include private Integer id; private String name; @OneToMany(mappedBy = "organization") private Set<Department> departments; @OneToMany(mappedBy = "organization") private Set<Employee> employees; }Использование GraphQL for Spring со Spring Boot
Spring for GraphQL предоставляет модель программирования на основе аннотаций, используя известный паттерн @Controller. Также можно адаптировать библиотеку Querydsl и использовать ее вместе со Spring Data JPA. Затем вы можете использовать ее в своих репозиториях Spring Data, аннотированных с помощью @GraphQLRepository. В этой статье я буду использовать стандартный JPA Criteria API для генерации более сложных запросов с фильтрами и объединениями.
Начнем с нашего первого контроллера. По сравнению с обеими предыдущими статьями о Netflix DGS и GraphQL Java Kickstart, мы будем хранить запросы и мутации в одном классе. Нам нужно аннотировать методы запросов с помощью @QueryMapping, а методы мутации с помощью @MutationMapping. Последний метод запроса employeesWithFilter выполняет расширенную фильтрацию на основе динамического списка полей, переданных во входном типе EmployeeFilter. Чтобы передать входной параметр, мы должны аннотировать аргумент метода с помощью @Argument.
@Controller public class EmployeeController { DepartmentRepository departmentRepository; EmployeeRepository employeeRepository; OrganizationRepository organizationRepository; EmployeeController(DepartmentRepository departmentRepository, EmployeeRepository employeeRepository, OrganizationRepository organizationRepository) { this.departmentRepository = departmentRepository; this.employeeRepository = employeeRepository; this.organizationRepository = organizationRepository; } @QueryMapping public Iterable<Employee> employees() { return employeeRepository.findAll(); } @QueryMapping public Employee employee(@Argument Integer id) { return employeeRepository.findById(id).orElseThrow(); } @MutationMapping public Employee newEmployee(@Argument EmployeeInput employee) { Department department = departmentRepository .findById(employee.getDepartmentId()).get(); Organization organization = organizationRepository .findById(employee.getOrganizationId()).get(); return employeeRepository.save(new Employee(null, employee.getFirstName(), employee.getLastName(), employee.getPosition(), employee.getAge(), employee.getSalary(), department, organization)); } @QueryMapping public Iterable<Employee> employeesWithFilter( @Argument EmployeeFilter filter) { Specification<Employee> spec = null; if (filter.getSalary() != null) spec = bySalary(filter.getSalary()); if (filter.getAge() != null) spec = (spec == null ? byAge(filter.getAge()) : spec.and(byAge(filter.getAge()))); if (filter.getPosition() != null) spec = (spec == null ? byPosition(filter.getPosition()) : spec.and(byPosition(filter.getPosition()))); if (spec != null) return employeeRepository.findAll(spec); else return employeeRepository.findAll(); } private Specification<Employee> bySalary(FilterField filterField) { return (root, query, builder) -> filterField .generateCriteria(builder, root.get("salary")); } private Specification<Employee> byAge(FilterField filterField) { return (root, query, builder) -> filterField .generateCriteria(builder, root.get("age")); } private Specification<Employee> byPosition(FilterField filterField) { return (root, query, builder) -> filterField .generateCriteria(builder, root.get("position")); } }Вот наша реализация репозитория JPA. Чтобы использовать JPA Criteria API, нам необходимо, чтобы он расширял интерфейс JpaSpecificationExecutor. Это же правило применяется и к другим репозиториям: DepartmentRepository и OrganizationRepository.
public interface EmployeeRepository extends CrudRepository<Employee, Integer>, JpaSpecificationExecutor<Employee> { }Теперь давайте переключимся на другой контроллер. Вот реализация контроллера DepartmentController. Здесь показан пример выборки отношений. Мы используем DataFetchingEnvironment, чтобы определить, содержит ли входной запрос поле отношения. В нашем случае это могут быть employees или organization. Если любое из этих полей определено, мы добавляем конкретное отношение в оператор JOIN. Тот же подход применяется к методам department и deparments.
@Controller public class DepartmentController { DepartmentRepository departmentRepository; OrganizationRepository organizationRepository; DepartmentController(DepartmentRepository departmentRepository, OrganizationRepository organizationRepository) { this.departmentRepository = departmentRepository; this.organizationRepository = organizationRepository; } @MutationMapping public Department newDepartment(@Argument DepartmentInput department) { Organization organization = organizationRepository .findById(department.getOrganizationId()).get(); return departmentRepository.save(new Department(null, department.getName(), null, organization)); } @QueryMapping public Iterable<Department> departments(DataFetchingEnvironment environment) { DataFetchingFieldSelectionSet s = environment.getSelectionSet(); List<Specification<Department>> specifications = new ArrayList<>(); if (s.contains("employees") && !s.contains("organization")) return departmentRepository.findAll(fetchEmployees()); else if (!s.contains("employees") && s.contains("organization")) return departmentRepository.findAll(fetchOrganization()); else if (s.contains("employees") && s.contains("organization")) return departmentRepository.findAll(fetchEmployees().and(fetchOrganization())); else return departmentRepository.findAll(); } @QueryMapping public Department department(@Argument Integer id, DataFetchingEnvironment environment) { Specification<Department> spec = byId(id); DataFetchingFieldSelectionSet selectionSet = environment .getSelectionSet(); if (selectionSet.contains("employees")) spec = spec.and(fetchEmployees()); if (selectionSet.contains("organization")) spec = spec.and(fetchOrganization()); return departmentRepository.findOne(spec).orElseThrow(NoSuchElementException::new); } private Specification<Department> fetchOrganization() { return (root, query, builder) -> { Fetch<Department, Organization> f = root .fetch("organization", JoinType.LEFT); Join<Department, Organization> join = (Join<Department, Organization>) f; return join.getOn(); }; } private Specification<Department> fetchEmployees() { return (root, query, builder) -> { Fetch<Department, Employee> f = root .fetch("employees", JoinType.LEFT); Join<Department, Employee> join = (Join<Department, Employee>) f; return join.getOn(); }; } private Specification<Department> byId(Integer id) { return (root, query, builder) -> builder.equal(root.get("id"), id); } }Вот реализация контроллера OrganizationController.
@Controller public class OrganizationController { OrganizationRepository repository; OrganizationController(OrganizationRepository repository) { this.repository = repository; } @MutationMapping public Organization newOrganization(@Argument OrganizationInput organization) { return repository.save(new Organization(null, organization.getName(), null, null)); } @QueryMapping public Iterable<Organization> organizations() { return repository.findAll(); } @QueryMapping public Organization organization(@Argument Integer id, DataFetchingEnvironment environment) { Specification<Organization> spec = byId(id); DataFetchingFieldSelectionSet selectionSet = environment .getSelectionSet(); if (selectionSet.contains("employees")) spec = spec.and(fetchEmployees()); if (selectionSet.contains("departments")) spec = spec.and(fetchDepartments()); return repository.findOne(spec).orElseThrow(); } private Specification<Organization> fetchDepartments() { return (root, query, builder) -> { Fetch<Organization, Department> f = root .fetch("departments", JoinType.LEFT); Join<Organization, Department> join = (Join<Organization, Department>) f; return join.getOn(); }; } private Specification<Organization> fetchEmployees() { return (root, query, builder) -> { Fetch<Organization, Employee> f = root .fetch("employees", JoinType.LEFT); Join<Organization, Employee> join = (Join<Organization, Employee>) f; return join.getOn(); }; } private Specification<Organization> byId(Integer id) { return (root, query, builder) -> builder.equal(root.get("id"), id); } }Создание модульных тестов
После того как мы создали всю логику, пришло время ее протестировать. В следующем разделе я покажу вам, как использовать для этого GraphiQL IDE.
Здесь мы сосредоточимся на модульных тестах. Самый простой способ начать тестировать Spring for GraphQL — использовать bean-компонент GraphQLTester. Мы можем использовать его в мок веб-среде. Вы также можете создавать тесты для уровня HTTP с помощью другого компонента — HttpGraphQlTester. Однако для этого требуется предоставить экземпляр WebTestClient.
Вот тест для Employee @Controller. Каждый раз мы создаем встроенный запрос, используя нотацию GraphQL. Нам нужно аннотировать весь тестовый класс с помощью @AutoConfigureGraphQlTester. Затем мы можем использовать DSL API, предоставляемый GraphQLTester для получения и проверки данных из бэкенда. Помимо двух простых тестов, мы также проверяем, нормально ли работает EmployeeFilter в методе findWithFilter.
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.MOCK) @AutoConfigureGraphQlTester public class EmployeeControllerTests { @Autowired private GraphQlTester tester; @Test void addEmployee() { String query = "mutation { newEmployee(employee: { firstName: \"John\" lastName: \"Wick\" position: \"developer\" salary: 10000 age: 20 departmentId: 1 organizationId: 1}) { id } }"; Employee employee = tester.document(query) .execute() .path("data.newEmployee") .entity(Employee.class) .get(); Assertions.assertNotNull(employee); Assertions.assertNotNull(employee.getId()); } @Test void findAll() { String query = "{ employees { id firstName lastName salary } }"; List<Employee> employees = tester.document(query) .execute() .path("data.employees[*]") .entityList(Employee.class) .get(); Assertions.assertTrue(employees.size() > 0); Assertions.assertNotNull(employees.get(0).getId()); Assertions.assertNotNull(employees.get(0).getFirstName()); } @Test void findById() { String query = "{ employee(id: 1) { id firstName lastName salary } }"; Employee employee = tester.document(query) .execute() .path("data.employee") .entity(Employee.class) .get(); Assertions.assertNotNull(employee); Assertions.assertNotNull(employee.getId()); Assertions.assertNotNull(employee.getFirstName()); } @Test void findWithFilter() { String query = "{ employeesWithFilter(filter: { salary: { operator: \"gt\" value: \"12000\" } }) { id firstName lastName salary } }"; List<Employee> employees = tester.document(query) .execute() .path("data.employeesWithFilter[*]") .entityList(Employee.class) .get(); Assertions.assertTrue(employees.size() > 0); Assertions.assertNotNull(employees.get(0).getId()); Assertions.assertNotNull(employees.get(0).getFirstName()); } }Тесты для типа Deparment очень похожи. Кроме того, мы тестируем операторы соединения в тестовом методе findById, объявляя поле organization в запросе.
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.MOCK) @AutoConfigureGraphQlTester public class DepartmentControllerTests { @Autowired private GraphQlTester tester; @Test void addDepartment() { String query = "mutation { newDepartment(department: { name: \"Test10\" organizationId: 1}) { id } }"; Department department = tester.document(query) .execute() .path("data.newDepartment") .entity(Department.class) .get(); Assertions.assertNotNull(department); Assertions.assertNotNull(department.getId()); } @Test void findAll() { String query = "{ departments { id name } }"; List<Department> departments = tester.document(query) .execute() .path("data.departments[*]") .entityList(Department.class) .get(); Assertions.assertTrue(departments.size() > 0); Assertions.assertNotNull(departments.get(0).getId()); Assertions.assertNotNull(departments.get(0).getName()); } @Test void findById() { String query = "{ department(id: 1) { id name organization { id } } }"; Department department = tester.document(query) .execute() .path("data.department") .entity(Department.class) .get(); Assertions.assertNotNull(department); Assertions.assertNotNull(department.getId()); Assertions.assertNotNull(department.getOrganization()); Assertions.assertNotNull(department.getOrganization().getId()); } }Каждый раз, клонируя мой репозиторий, вы можете быть уверены, что примеры работают нормально благодаря автоматизированным тестам. Вы всегда можете проверить статус сборки репозитория в моем конвейере CircleCI.
Тестирование с помощью GraphiQL
Мы можем легко запустить приложение с помощью следующей команды Maven:
$ mvn clean spring-boot:runКак только вы это сделаете, вы сможете получить доступ к инструменту GraphiQL по адресу http://localhost:8080/graphiql. При запуске приложение вставляет некоторые демонстрационные данные в базу данных H2. GraphiQL предоставляет контекстную помощь при построении запросов GraphQL. Вот пример запроса, протестированного там.
Заключительные мысли
Spring for GraphQL — очень интересный проект, и я буду внимательно следить за его развитием.
Помимо поддержки @Controller, я попытался использовать интеграцию querydsl с репозиториями Spring Data JPA. Однако у меня возникли некоторые проблемы с этим, и поэтому я не стал помещать эту тему в статью.
На данный момент Spring for GraphQL является третьим надежным Java-фреймворком с высокоуровневой поддержкой GraphQL для Spring Boot. Моим выбором по-прежнему остается Netflix DGS, но Spring for GraphQL находится в стадии активной разработки. Так что, вероятно, в скором времени мы можем ожидать новых и полезных функций.
ссылка на оригинал статьи https://habr.com/ru/articles/720360/
Добавить комментарий