Может ли @PathVariable быть обязательной?

@PathVariable — обязательна ли всегда?

По умолчанию @PathVariable является обязательной в Spring Framework. Если переменная пути отсутствует в URL, то будет ошибка 404 или 400. Однако можно сделать её опциональной через параметр required.

По умолчанию — обязательна

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {
    
    // ✓ @PathVariable обязательна
    @GetMapping("/users/{id}")
    public UserDto getUser(@PathVariable String id) {
        return userService.findById(id);
    }
    
    // Если вызвать без {id}:
    // GET /users → 404 Not Found (маршрут не найден)
    // GET /users/123 → OK, id="123"
}

Сделать @PathVariable опциональной

import org.springframework.web.bind.annotation.PathVariable;

@RestController
public class SearchController {
    
    // ❌ НЕПРАВИЛЬНО — обязательна, но параметр required=false
    @GetMapping("/search/{query}")
    public List<Result> search(
        @PathVariable(required = false) String query
    ) {
        // Это НЕ работает как ожидается!
        // required=false на @PathVariable не имеет смысла
        return searchService.search(query);
    }
    
    // Вызовы:
    // GET /search/spring → OK, query="spring"
    // GET /search → 404 Not Found (маршрут не совпадает!)
}

Проблема: @PathVariable, заявленная в шаблоне URL, будет всегда требоваться для совпадения маршрута. required=false не поможет.

Правильный подход — альтернативные маршруты

@RestController
public class SearchController {
    
    // ✓ Маршрут с параметром
    @GetMapping("/search/{query}")
    public List<Result> searchWithQuery(
        @PathVariable String query
    ) {
        return searchService.search(query);
    }
    
    // ✓ Маршрут без параметра
    @GetMapping("/search")
    public List<Result> searchAll() {
        return searchService.searchAll();
    }
    
    // Вызовы:
    // GET /search/spring → queryWithQuery, query="spring"
    // GET /search → searchAll
}

Использование @RequestParam вместо @PathVariable

Если параметр действительно опционален, используй @RequestParam:

@RestController
public class SearchController {
    
    // ✓ @RequestParam по умолчанию обязательна
    @GetMapping("/search")
    public List<Result> search(
        @RequestParam String query  // Обязательна
    ) {
        return searchService.search(query);
    }
    
    // Вызовы:
    // GET /search?query=spring → OK
    // GET /search → 400 Bad Request (параметр обязателен)
}

// ✓ Сделать @RequestParam опциональной
@GetMapping("/search")
public List<Result> search(
    @RequestParam(required = false) String query  // Опциональна
) {
    if (query == null || query.isEmpty()) {
        return searchService.searchAll();
    }
    return searchService.search(query);
}

// Вызовы:
// GET /search?query=spring → query="spring"
// GET /search → query=null, возвращаем все результаты

Различие между @PathVariable и @RequestParam

@RestController
public class DocumentController {
    
    // @PathVariable — часть маршрута, всегда видна в URL
    // GET /documents/123 → RESTful, требует обязательный ID
    @GetMapping("/documents/{documentId}")
    public DocumentDto getDocument(
        @PathVariable String documentId
    ) {
        return documentService.findById(documentId);
    }
    
    // @RequestParam — параметры запроса, опциональны
    // GET /documents?page=1&size=10 → параметры фильтрации
    @GetMapping("/documents")
    public Page<DocumentDto> listDocuments(
        @RequestParam(defaultValue = "1") int page,
        @RequestParam(defaultValue = "10") int size
    ) {
        return documentService.findAll(page, size);
    }
}

Типирование @PathVariable

@RestController
public class UserController {
    
    // ✓ Автоматическое преобразование типа
    @GetMapping("/users/{id}")
    public UserDto getUser(
        @PathVariable Long id  // String автоматически конвертируется в Long
    ) {
        return userService.findById(id);
    }
    
    // ✓ UUID также поддерживается
    @GetMapping("/posts/{postId}")
    public PostDto getPost(
        @PathVariable UUID postId
    ) {
        return postService.findById(postId);
    }
    
    // Вызовы:
    // GET /users/123 → id=123L (Long)
    // GET /users/abc → 400 Bad Request (не может конвертировать String в Long)
    // GET /posts/550e8400-e29b-41d4-a716-446655440000 → postId=UUID(...)
}

Обработка ошибок при отсутствии @PathVariable

@RestController
public class UserController {
    
    @GetMapping("/users/{id}")
    public ResponseEntity<UserDto> getUser(
        @PathVariable String id
    ) {
        try {
            UserDto user = userService.findById(id);
            return ResponseEntity.ok(user);
        } catch (UserNotFoundException e) {
            return ResponseEntity.status(404).body(null);
        }
    }
    
    // Глобальная обработка ошибок
    @ExceptionHandler(MethodArgumentTypeMismatchException.class)
    public ResponseEntity<ErrorResponse> handleTypeMismatch(MethodArgumentTypeMismatchException e) {
        ErrorResponse error = new ErrorResponse(
            "Invalid path variable: " + e.getMessage(),
            400
        );
        return ResponseEntity.badRequest().body(error);
    }
}

Именование параметров

@RestController
public class ArticleController {
    
    // ✓ По умолчанию параметр названию переменной
    @GetMapping("/articles/{articleId}")
    public ArticleDto getArticle(
        @PathVariable String articleId  // Совпадает с {articleId}
    ) {
        return articleService.findById(articleId);
    }
    
    // ✓ Явное указание имени
    @GetMapping("/articles/{id}")
    public ArticleDto getArticleById(
        @PathVariable("id") String articleId  // Переименовываем: {id} → articleId
    ) {
        return articleService.findById(articleId);
    }
    
    // Вызовы:
    // GET /articles/123 → articleId="123"
    // GET /articles/456 → articleId="456"
}

Несколько @PathVariable в одном методе

@RestController
public class CommentController {
    
    // ✓ Несколько обязательных параметров пути
    @GetMapping("/posts/{postId}/comments/{commentId}")
    public CommentDto getComment(
        @PathVariable Long postId,
        @PathVariable Long commentId
    ) {
        return commentService.findByIdInPost(postId, commentId);
    }
    
    // Вызовы:
    // GET /posts/1/comments/100 → postId=1, commentId=100
    // GET /posts/1 → 404 Not Found (не совпадает маршрут)
    // GET /posts/1/comments → 404 Not Found (commentId отсутствует)
}

Таблица сравнения обязательности

Best Practices

@RestController
@RequestMapping("/api/v1/users")
public class UserController {
    
    // ✓ Обязательная переменная пути
    @GetMapping("/{userId}")
    public UserDto getById(@PathVariable Long userId) {
        return userService.findById(userId);
    }
    
    // ✓ Опциональные параметры запроса
    @GetMapping
    public Page<UserDto> list(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "10") int size,
        @RequestParam(required = false) String name  // Опциональный фильтр
    ) {
        return userService.findAll(name, page, size);
    }
    
    // ✓ Создание с body
    @PostMapping
    public UserDto create(@RequestBody CreateUserRequest request) {
        return userService.create(request);
    }
    
    // ✓ Обновление с обязательным ID и body
    @PutMapping("/{userId}")
    public UserDto update(
        @PathVariable Long userId,
        @RequestBody UpdateUserRequest request
    ) {
        return userService.update(userId, request);
    }
    
    // ✓ Удаление
    @DeleteMapping("/{userId}")
    public void delete(@PathVariable Long userId) {
        userService.delete(userId);
    }
}

Вывод

1. @PathVariable всегда обязательна по умолчанию — если указана в маршруте, она должна присутствовать в URL
2. required=false не помогает — это не сделает параметр пути опциональным
3. Для опциональности используй несколько маршрутов — например, /search/{query} и /search
4. @RequestParam идеальна для опциональных параметров — используй её вместе с required=false
5. RESTful правило: @PathVariable для ресурсов (обязательны), @RequestParam для фильтров (опциональны)