GraphQL или REST в Java: проектирование API для современных фронтендов

@RestController
@RequestMapping("/api/users")
public class UserController {
    @GetMapping("/{id}")
    public UserDTO getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
    
    @GetMapping("/{id}/posts")
    public List<PostDTO> getUserPosts(@PathVariable Long id) {
        return postService.findByUserId(id);
    }
}

@GetMapping("/mobile/v3/user-profile-screen/{userId}")
public UserProfileScreenDTO getUserProfileScreen(@PathVariable Long userId) {
    // Собираем данные из 6 разных сервисов
}

// Пример GraphQL резолвера, который объединяет данные из разных микросервисов
@Component
public class UserWithOrdersResolver implements DataFetcher<CompletableFuture<User>> {
    private final UserService userService;
    private final OrderService orderService;
    
    @Override
    public CompletableFuture<User> get(DataFetchingEnvironment env) {
        Long userId = env.getArgument("id");
        
        // Параллельно запрашиваем данные из разных сервисов
        CompletableFuture<User> userFuture = 
            CompletableFuture.supplyAsync(() -> userService.findById(userId));
        
        CompletableFuture<List<Order>> ordersFuture = 
            CompletableFuture.supplyAsync(() -> orderService.findByUserId(userId));
        
        // Ожидаем выполнения обоих запросов и соединяем результаты
        return userFuture.thenCombine(ordersFuture, (user, orders) -> {
            user.setOrders(orders);
            return user;
        });
    }
}

GET /api/users/42?fields=id,name,posts(title,createdAt)

@RestController
@RequestMapping("/api/v1/products")
public class ProductController {
    private final ProductService productService;
    
    // Конструктор для внедрения зависимости
    public ProductController(ProductService productService) {
        this.productService = productService;
    }
    
    @GetMapping
    public List<ProductDTO> getAllProducts(
            @RequestParam(required = false) String category,
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {
        return productService.findProducts(category, page, size);
    }
    
    @GetMapping("/{id}")
    public ResponseEntity<ProductDTO> getProduct(@PathVariable Long id) {
        return productService.findById(id)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }
    
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public ProductDTO createProduct(@Valid @RequestBody ProductDTO product) {
        return productService.save(product);
    }
    
    // И так далее для PUT, DELETE и других операций
}

@RestController
@RequestMapping("/api/v1/orders")
public class OrderController {
    private final OrderRepository orderRepository;
    
    public OrderController(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }
    
    @GetMapping
    public Flux<OrderDTO> getAllOrders() {
        return orderRepository.findAll()
                .map(this::convertToDTO);
    }
    
    @GetMapping("/{id}")
    public Mono<ResponseEntity<OrderDTO>> getOrder(@PathVariable String id) {
        return orderRepository.findById(id)
                .map(this::convertToDTO)
                .map(ResponseEntity::ok)
                .defaultIfEmpty(ResponseEntity.notFound().build());
    }
    
    private OrderDTO convertToDTO(Order order) {
        // Конвертация модели в DTO
        return new OrderDTO(/* ... */);
    }
}

@Path("/customers")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class CustomerResource {
    @Inject
    CustomerService customerService;
    
    @GET
    public List<Customer> getAll() {
        return customerService.findAll();
    }
    
    @GET
    @Path("/{id}")
    public Response getById(@PathParam("id") Long id) {
        return customerService.findById(id)
                .map(customer -> Response.ok(customer).build())
                .orElse(Response.status(Response.Status.NOT_FOUND).build());
    }
    
    // Остальные методы
}

@GetMapping("/products/{id}")
public ResponseEntity<ProductDTO> getProduct(@PathVariable Long id) {
    ProductDTO product = productService.findById(id);
    return ResponseEntity.ok()
            .cacheControl(CacheControl.maxAge(30, TimeUnit.MINUTES))
            .eTag(generateETag(product))
            .body(product);
}

@JsonInclude(JsonInclude.Include.NON_NULL)
public class ProductDTO {
    private Long id;
    private String name;
    private BigDecimal price;
    
    @JsonIgnore
    private LocalDateTime internalUpdateTimestamp;
    
    @JsonProperty("brand_name")
    private String brandName;
    
    // Геттеры, сеттеры и так далее
}

@Operation(summary = "Get product by ID", description = "Returns a product based on ID")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "Product found",
                content = {@Content(mediaType = "application/json",
                            schema = @Schema(implementation = ProductDTO.class))}),
    @ApiResponse(responseCode = "404", description = "Product not found")
})
@GetMapping("/{id}")
public ResponseEntity<ProductDTO> getProduct(@PathVariable Long id) {
    // Реализация
}

@RestController
@RequestMapping("/api/orders")
public class OrderController {
    private final OrderService orderService;
    private final MeterRegistry meterRegistry;
    
    public OrderController(OrderService orderService, MeterRegistry meterRegistry) {
        this.orderService = orderService;
        this.meterRegistry = meterRegistry;
    }
    
    @PostMapping
    public ResponseEntity<OrderDTO> createOrder(@RequestBody OrderDTO order) {
        Timer.Sample sample = Timer.start(meterRegistry);
        try {
            OrderDTO created = orderService.createOrder(order);
            return ResponseEntity.status(HttpStatus.CREATED).body(created);
        } finally {
            sample.stop(meterRegistry.timer("api.order.create"));
        }
    }
}

@GetMapping("/products")
public List<ProductDTO> getProducts() {
    List<Product> products = productRepository.findAll();
    return products.stream()
            .map(this::convertToDTO)
            .collect(Collectors.toList());
}
 
private ProductDTO convertToDTO(Product product) {
    ProductDTO dto = new ProductDTO();
    dto.setId(product.getId());
    dto.setName(product.getName());
    
    // Вот здесь может скрываться N+1 проблема!
    Category category = categoryService.findById(product.getCategoryId());
    dto.setCategoryName(category.getName());
    
    return dto;
}

@Repository
public interface ProductRepository extends JpaRepository<Product, Long> {
    @Query("SELECT p FROM Product p LEFT JOIN FETCH p.category")
    List<Product> findAllWithCategories();
}

@Service
public class CategoryServiceImpl implements CategoryService {
    private final CategoryRepository repository;
    private final LoadingCache<Long, Category> cache;
    
    public CategoryServiceImpl(CategoryRepository repository) {
        this.repository = repository;
        this.cache = Caffeine.newBuilder()
                .maximumSize(1000)
                .expireAfterWrite(10, TimeUnit.MINUTES)
                .build(this::loadCategory);
    }
    
    private Category loadCategory(Long id) {
        return repository.findById(id).orElseThrow(() -> 
                new EntityNotFoundException("Category not found: " + id));
    }
    
    @Override
    public Category findById(Long id) {
        return cache.get(id);
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleResourceNotFound(ResourceNotFoundException ex) {
        ErrorResponse error = new ErrorResponse("NOT_FOUND", ex.getMessage());
        return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
    }
    
    @ExceptionHandler(ValidationException.class)
    public ResponseEntity<ValidationErrorResponse> handleValidationErrors(ValidationException ex) {
        ValidationErrorResponse error = new ValidationErrorResponse(ex.getErrors());
        return new ResponseEntity<>(error, HttpStatus.BAD_REQUEST);
    }
    
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGenericError(Exception ex) {
        ErrorResponse error = new ErrorResponse("INTERNAL_ERROR", "An unexpected error occurred");
        return new ResponseEntity<>(error, HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    
    @Autowired
    private JwtTokenFilter jwtTokenFilter;
    
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.csrf().disable()
            .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            .and()
            .authorizeRequests()
            .antMatchers("/api/auth/[B]").permitAll()
            .antMatchers("/api/public/[/B]").permitAll()
            .antMatchers(HttpMethod.GET, "/api/products/**").permitAll()
            .anyRequest().authenticated()
            .and()
            .addFilterBefore(jwtTokenFilter, UsernamePasswordAuthenticationFilter.class);
    }
}

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureMockMvc
public class ProductControllerTests {
    
    @Autowired
    private MockMvc mockMvc;
    
    @Test
    public void givenValidProduct_whenCreateProduct_thenStatus201() throws Exception {
        String productJson = "{\"name\":\"Test Product\",\"price\":99.99}";
        
        mockMvc.perform(post("/api/products")
                .contentType(MediaType.APPLICATION_JSON)
                .content(productJson))
                .andExpect(status().isCreated())
                .andExpect(jsonPath("$.id").exists())
                .andExpect(jsonPath("$.name").value("Test Product"))
                .andExpect(jsonPath("$.price").value(99.99));
    }
}

@Configuration
public class GatewayConfig {
    
    @Bean
    public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
        return builder.routes()
            .route("product_service", r -> r.path("/api/products/**")
                .filters(f -> f.rewritePath("/api/products/(?<segment>.*)", "/products/${segment}")
                             .addRequestHeader("X-Gateway-Source", "API-Gateway"))
                .uri("lb://product-service"))
            .route("order_service", r -> r.path("/api/orders/**")
                .filters(f -> f.rewritePath("/api/orders/(?<segment>.*)", "/orders/${segment}")
                             .circuitBreaker(c -> c.setName("orderServiceCircuitBreaker")
                                              .setFallbackUri("forward:/fallback/orders")))
                .uri("lb://order-service"))
            .build();
    }
}

@Controller
public class ProductController {
  private final ProductService productService;
  
  public ProductController(ProductService productService) {
      this.productService = productService;
  }
  
  @QueryMapping
  public Product product(@Argument Long id) {
      return productService.findById(id);
  }
  
  @QueryMapping
  public List<Product> products(@Argument String category) {
      if (category != null) {
          return productService.findByCategory(category);
      }
      return productService.findAll();
  }
  
  @SchemaMapping(typeName = "Product", field = "reviews")
  public List<Review> reviews(Product product) {
      return reviewService.findByProductId(product.getId());
  }
}

@Component
public class ReviewDataLoader {
  private final ReviewRepository reviewRepository;
  
  public ReviewDataLoader(ReviewRepository reviewRepository) {
      this.reviewRepository = reviewRepository;
  }
  
  @BatchMapping(typeName = "Product", field = "reviews")
  public Mono<Map<Product, List<Review>>> getReviewsForProducts(List<Product> products) {
      List<Long> productIds = products.stream()
              .map(Product::getId)
              .collect(Collectors.toList());
      
      return Mono.fromCallable(() -> {
          List<Review> allReviews = reviewRepository.findByProductIdIn(productIds);
          
          Map<Long, List<Review>> reviewsByProductId = allReviews.stream()
                  .collect(Collectors.groupingBy(Review::getProductId));
          
          Map<Product, List<Review>> result = new HashMap<>();
          for (Product product : products) {
              result.put(product, reviewsByProductId.getOrDefault(product.getId(), Collections.emptyList()));
          }
          
          return result;
      });
  }
}

@Configuration
public class GraphQLConfig {
  
  @Bean
  public GraphiQlConfigurer graphiQlConfigurer() {
      return new GraphiQlConfigurer();
  }
}

// Сервис пользователей
type User @key(fields: "id") {
  id: ID!
  name: String!
  email: String!
}
 
// Сервис заказов
type Order {
  id: ID!
  products: [Product]
  user: User @requires(fields: "userId")
  userId: ID! @external
}
 
extend type User @key(fields: "id") {
  id: ID! @external
  orders: [Order]
}

@PreAuthorize("hasRole('ADMIN')")
@SchemaMapping(typeName = "User", field = "email")
public String email(User user) {
    return user.getEmail();
}

@Bean
public GraphQLExecutionStrategy executionStrategy() {
    return new AsyncExecutionStrategy(new SimpleDataFetcherExceptionHandler());
}
 
@Bean
public Instrumentation maxQueryComplexityInstrumentation() {
    return new MaxQueryComplexityInstrumentation(100);
}
 
@Bean
public Instrumentation maxQueryDepthInstrumentation() {
    return new MaxQueryDepthInstrumentation(7);
}

@Bean
public CacheManager cacheManager() {
    CaffeineCacheManager cacheManager = new CaffeineCacheManager();
    cacheManager.setCaffeine(Caffeine.newBuilder()
            .expireAfterWrite(5, TimeUnit.MINUTES)
            .maximumSize(100));
    return cacheManager;
}
 
@Cacheable(value = "products", key = "#id")
public Product findProductById(Long id) {
    return productRepository.findById(id)
            .orElseThrow(() -> new NotFoundException("Product not found: " + id));
}

@Bean
public GraphQLSchema schema() {
    return GraphQLSchema.newSchema()
            .query(queryType)
            .mutation(mutationType)
            .subscription(subscriptionType)
            .additionalType(dateTimeScalar)
            // Отключаем интроспекцию в определенных окружениях
            .codeRegistry(GraphQLCodeRegistry.newCodeRegistry()
                    .fieldVisibility(environment.acceptsProfiles(Profiles.of("prod")) 
                            ? NoIntrospectionGraphqlFieldVisibility.NO_INTROSPECTION_FIELD_VISIBILITY 
                            : DEFAULT_FIELD_VISIBILITY)
                    .build())
            .build();
}

@ExceptionHandler(EntityNotFoundException.class)
public GraphQLError handleNotFoundException(EntityNotFoundException e) {
    return GraphQLError.newError()
            .message(e.getMessage())
            .extensions(Map.of("code", "NOT_FOUND"))
            .build();
}

@Test
void shouldReturnUserWithOrders() {
    String query = """
        query {
          user(id: "1") {
            name
            email
            orders {
              id
              totalAmount
            }
          }
        }
    """;
    
    graphQlTester.document(query)
            .execute()
            .path("user.name").entity(String.class).isEqualTo("John Doe")
            .path("user.orders").entityList(Order.class).hasSize(2);
}

// Результаты нагрузочного тестирования для запроса профиля пользователя с заказами
Метрика               | REST API           | GraphQL API
---------------------|--------------------|------------------
Среднее время ответа | 245 мс             | 178 мс
Пропускная способность| 220 запр/сек       | 290 запр/сек
Размер ответа        | 24.3 KB            | 8.7 KB
Использование CPU    | 62%                | 74%
Использование памяти | 1.8 GB             | 2.2 GB

// Пример конфигурации метрик для REST и GraphQL API
@Configuration
public class MetricsConfig {
  
  @Bean
  public MeterRegistryCustomizer<MeterRegistry> metricsCommonTags() {
    return registry -> registry.config().commonTags("application", "api-service");
  }
  
  @Bean
  public TimedAspect timedAspect(MeterRegistry registry) {
    return new TimedAspect(registry);
  }
}
 
// Использование метрик в REST-контроллере
@RestController
@RequestMapping("/api/v1/orders")
public class OrderController {
  
  private final MeterRegistry meterRegistry;
  
  @Timed(value = "rest.orders.get", description = "Time to retrieve orders via REST")
  @GetMapping
  public ResponseEntity<List<OrderDTO>> getOrders() {
    Timer.Sample sample = Timer.start(meterRegistry);
    List<OrderDTO> orders = orderService.findAll();
    sample.stop(meterRegistry.timer("rest.orders.data.size", 
                                  Tags.of("count", String.valueOf(orders.size()))));
    return ResponseEntity.ok(orders);
  }
}
 
// Аналогичные метрики для GraphQL-резолвера
@Component
public class OrderResolver implements GraphQLQueryResolver {
  
  private final MeterRegistry meterRegistry;
  
  @Timed(value = "graphql.orders.get", description = "Time to retrieve orders via GraphQL")
  public List<Order> getOrders(DataFetchingEnvironment env) {
    Timer.Sample sample = Timer.start(meterRegistry);
    List<Order> orders = orderService.findAll();
    sample.stop(meterRegistry.timer("graphql.orders.data.size", 
                                  Tags.of("count", String.valueOf(orders.size()))));
    return orders;
  }
}

// Конфигурация GraphQL метрик для Micrometer
@Bean
public Instrumentation meterInstrumentation(MeterRegistry registry) {
  return new MeterInstrumentation(registry, 
      options -> options.tags(Tags.of("service", "product-catalog")));
}

@Component
public class ProductGraphQLAdapter {
    private final ProductService productService;
    
    public ProductGraphQLAdapter(ProductService productService) {
        this.productService = productService;
    }
    
    @SchemaMapping(typeName = "Query", field = "product")
    public ProductDTO getProduct(@Argument Long id) {
        // Используем тот же сервис, что и REST-контроллер
        return productService.findById(id);
    }
    
    @SchemaMapping(typeName = "Query", field = "products")
    public List<ProductDTO> getProducts(@Argument String category,
                                       @Argument Integer page,
                                       @Argument Integer size) {
        // Повторно используем логику REST API
        return productService.findProducts(category, 
                                          page != null ? page : 0, 
                                          size != null ? size : 20);
    }
}

Архитектура с BFF:
                   ┌────────────┐
                   │  Мобильное │
                   │ приложение │
                   └──────┬─────┘
                          │
                          ▼
┌───────────────┐  ┌─────────────┐  ┌───────────┐
│  Партнерские  │  │    Mobile   │  │    Web    │
│   системы     │◄─┤     BFF     │  │    BFF    │◄─┐
└───────┬───────┘  │  (GraphQL)  │  │(REST+GraphQL)│ │
        │          └─────┬───────┘  └─────┬───────┘ │
        │                │                │         │
        ▼                ▼                ▼         │
┌───────────────┐  ┌─────────────┐  ┌───────────┐  │
│    REST API   │  │  GraphQL API│  │  REST API │  │
└───────┬───────┘  └─────┬───────┘  └─────┬─────┘  │
        │                │                │         │
        └────────────────┼────────────────┘         │
                         │                          │
                         ▼                          │
                 ┌──────────────────┐               │
                 │ Микросервисы и   │               │
                 │ бизнес-логика    │───────────────┘
                 └──────────────────┘

@Configuration
public class ApiGatewayConfig {
    
    @Bean
    public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
        return builder.routes()
            // REST-эндпоинты
            .route("rest_products", r -> r
                .path("/api/v1/products/**")
                .filters(f -> f.rewritePath("/api/v1/products/(?<segment>.*)", "/products/${segment}"))
                .uri("lb://product-service"))
            
            // GraphQL-эндпоинт
            .route("graphql_endpoint", r -> r
                .path("/graphql")
                .uri("lb://graphql-service"))
            
            // Документация GraphQL
            .route("graphql_playground", r -> r
                .path("/playground")
                .uri("lb://graphql-service"))
            
            .build();
    }
}

// Общий сервис, используемый и REST, и GraphQL
@Service
public class OrderServiceImpl implements OrderService {
    private final OrderRepository orderRepository;
    private final ProductService productService;
    
    // Конструктор, внедрение зависимостей...
    
    @Override
    @Transactional
    public OrderDTO createOrder(OrderRequest request) {
        // Валидация, бизнес-логика, сохранение...
        // Код используется и REST, и GraphQL контроллерами
    }
    
    // Другие методы...
}
 
// REST-контроллер
@RestController
@RequestMapping("/api/v1/orders")
public class OrderController {
    private final OrderService orderService;
    
    @PostMapping
    public ResponseEntity<OrderDTO> createOrder(@RequestBody OrderRequest request) {
        return ResponseEntity.status(HttpStatus.CREATED)
                .body(orderService.createOrder(request));
    }
}
 
// GraphQL-резолвер
@Component
public class OrderMutation {
    private final OrderService orderService;
    
    @MutationMapping
    public OrderDTO createOrder(@Argument OrderInput input) {
        OrderRequest request = convertInputToRequest(input);
        return orderService.createOrder(request);
    }
    
    private OrderRequest convertInputToRequest(OrderInput input) {
        // Конвертация GraphQL-специфичного ввода в общий формат
    }
}

// Конфигурация безопасности для REST API
@Configuration
@EnableWebSecurity
public class RestSecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.csrf().disable()
            .authorizeRequests()
            .antMatchers("/api/v1/public/**").permitAll()
            .anyRequest().authenticated()
            .and()
            .oauth2ResourceServer().jwt();
    }
}
 
// Конфигурация безопасности для GraphQL
@Configuration
public class GraphQLSecurityConfig {
    @Bean
    public AuthenticationDirective authenticationDirective(AuthenticationManager authManager) {
        return new AuthenticationDirective(authManager);
    }
}