[Spring/기초] RestController 완벽 정리 (return type, 파라미터, 추가 개념 및 기능)

내가 정리해두고 두고두고 볼라고 만든
RestController 완벽 정리

정리할 것, 예시코드 예시코드를 사용한 상세 설명 순으로 구성했다.

Title - Excode - Description(3쌍)

---

Return Type 정리

1.기본 객체 및 컬렉션

단일 객체

@GetMapping("/user/{id}")
public User getUser(@PathVariable Long id) {
    return userService.findById(id);
}

//예시 Json 응답
{
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com"
}

 

객체를 반환 json으로 변환 해줌

 

리스트 or 맵 같은 컬렉션

@GetMapping("/users")
public List<User> getAllUsers() {
    return userService.findAll();
}

//예시 Json 응답
[
    {
        "id": 1,
        "name": "John Doe",
        "email": "john.doe@example.com"
    },
    {
        "id": 2,
        "name": "Jane Smith",
        "email": "jane.smith@example.com"
    }
]

 

객체들을 list로 변환하고 json으로 변환해서 보내줌

2. ResponseEntity<T>

@GetMapping("/user/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    User user = userService.findById(id);
    if (user == null) {
        return new ResponseEntity<>(HttpStatus.NOT_FOUND);
    }
    return new ResponseEntity<>(user, HttpStatus.OK);
}

//Json 응답 성공시
{
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com"
}

//응답 실패시
{
    "status": 404,
    "error": "Not Found",
    "message": "No user found with ID 1"
}

 

헤더를 변경해서 지금 어떤 상황인지 알려줄 수 있음

아래 글은 ResponseEntitiy 커스터 마이징 하는 방법

public class ErrorResponse {
    private int status;
    private String error;
    private String message;

    public ErrorResponse(int status, String error, String message) {
        this.status = status;
        this.error = error;
        this.message = message;
    }
}

이런식으로 에러 코드를 담는 클래스를 만들고

 

@GetMapping("/user/{id}")
public ResponseEntity<Object> getUser(@PathVariable Long id) {
    User user = userService.findById(id);
    if (user == null) {
        ErrorResponse errorResponse = new ErrorResponse(404, "Not Found", "No user found with ID " + id);
        return new ResponseEntity<>(errorResponse, HttpStatus.NOT_FOUND);
    }
    return new ResponseEntity<>(user, HttpStatus.OK);
}

이런식으로 클래스에 내가 넣고 싶은 값들을 넣고 보내주면 된다.

 

{
    "status": 404,
    "error": "Not Found",
    "message": "No user found with ID 1"
}

클라이언트 쪽에선 이런 응답을 받게 됨

3. String

@GetMapping("/hello")
public String sayHello() {
    return "Hello, World!";
}

//응답 예시
"Hello, World!"

 

json이 아닌 단순 한 문자열로 반환 하게 된다.

4. void

@DeleteMapping("/user/{id}")
public void deleteUser(@PathVariable Long id) {
    userService.delete(id);
}

//예시 
(HTTP 204 No Content, body emtpy)

204 상태 코드만 전송된다. 간결하게 작성 가능하나 유지보수를 위해서 ResponseEntity를 사용하는 것이 더 좋을 것 같음

5. HttpHeaders

@GetMapping("/headers")
public HttpHeaders getHeaders() {
    HttpHeaders headers = new HttpHeaders();
    headers.add("Custom-Header", "foo");
    return headers;
}

//예시
(헤더에 Custom-Header: foo 추가, 바디 없음)

헤더 정보로만 처리할 수 있게 해야함

---

파라미터 정리

1. @PathVariable

@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {
    return userService.findById(id);
}

 

URL에서 변수 값 추출

{id}에 있는 값을 Long id에 넣어주는데 PathVariable이 여러개라면? 아래 접은글 참조

@GetMapping("/users/{userId}/orders/{orderId}")
public ResponseEntity<Order> getOrder(
    @PathVariable Long userId,
    @PathVariable Long orderId) {
}

 

PathVaribale은 앞에서부터 받아서 앞에둔 userId가 userId값을 orderId가 orderId값을 매핑하게 된다.

2. @RequestParam

@GetMapping("/users")
public List<User> getUsersByAge(@RequestParam int age) {
    return userService.findByAge(age);
}

쿼리 파라미터에서 값을 추출한다

요청 URL : /users?age = 25

그럼 age에 25값이 들어간다.

3. @RequestBody

@PostMapping("/users")
public User createUser(@RequestBody User user) {
    return userService.save(user);
}

 

User객체가

name이랑 email을 가지고 있다고 할때 클라이언트는 아래와 같은 방식으로 값을 보낼 것이고 이걸 user에 매핑할 수 있다.

curl -X POST http://localhost:8080/users \
-H "Content-Type: application/json" \
-d '{
  "name": "김철수",
  "email": "kinilonwater@tistory.com"
}'

다른 예시는 접은글 참조

여기서 json형식으로 데이터를 주면 JsonObject로 받아야 하는거 아닌가요? 라는 질문이 생길 수 있는데

spring에서 자동으로 json형식을 객체로 변환해주기 때문에 안그래도 된다.

curl -X POST http://localhost:8080/users \
-H "Content-Type: application/json" \
-d '[
  {
    "name": "박대기",
    "email": "wating@tistory.com"
  },
  {
    "name": "이민호",
    "email": "towMin@tistory.com"
  }
]'

요런식으로 리스트로 값이 들어오는 요청일경우

 

@PostMapping("/users")
public ResponseEntity<String> createUsers(@RequestBody List<User> users) {
}

이렇게 list로 받으면 된다.

 

curl -X POST http://localhost:8080/process-data \
-H "Content-Type: application/json" \
-d '{
  "user": {
    "name": "김왕",
    "email": "kimKing@tistory.com"
  },
  "order": {
    "orderId": "ORD-12345",
    "total": 100.50,
    "items": [
      {"productId": "P1", "quantity": 2},
      {"productId": "P2", "quantity": 1}
    ]
  }
}'

요런식으로 복잡한 json으로 온다면

 

@PostMapping("/process-data")
public ResponseEntity<String> processData(@RequestBody Map<String, Object> requestData) {
}

오브잭트로 받아서 처리해도 된다.

4. @RequestHeader

@GetMapping("/user")
public User getUser(@RequestHeader("Authorization") String authToken) {
    // authToken을 사용하여 사용자 인증/인가 처리
}

요청 헤더에서 값을 추출

요청 헤더: Authorization: Bearer some-token

토큰을 받아서 사용자 인증

5. @RequestHeader

@GetMapping("/profile")
public Profile getProfile(@CookieValue("sessionId") String sessionId) {
    return profileService.findBySessionId(sessionId);
}

쿠키에서 값을 추출

요청 쿠키: sessionId=abc123

6. @ModelAttribute

@PostMapping("/user")
public User createUser(@ModelAttribute User user) {
    return userService.save(user);
}

요청 파라미터: name=John&email=john.doe@example.com

User객체에 바로 매핑

이때 Attribute로 들어오는 Key가 User에 없다면 무시됨

7. @RequestPart

@PostMapping("/upload")
public ResponseEntity<String> handleFileUpload(
    @RequestPart("name") String name,
    @RequestPart("file") MultipartFile file) {
    
    // name과 file을 사용하여 파일 업로드 처리 로직을 작성합니다.
    
    return ResponseEntity.ok("파일 업로드가 성공적으로 완료되었습니다.");
}

주로 파일 업로드 할때 사용

사용자가 보낸 요청에서 여러 부분을 분리해서 각각을 메서드의 매개변수로 처리할 수 있음

<form action="/upload" method="post" enctype="multipart/form-data">
    <input type="text" name="name">
    <input type="file" name="file">
    <input type="submit" value="Upload">
</form>

8. HttpServletRequest & HttpServletResponse

@GetMapping("/example")
public void handleExampleRequest(HttpServletRequest request, HttpServletResponse response) throws IOException {
    String userAgent = request.getHeader("User-Agent");
    System.out.println("User-Agent: " + userAgent);

    response.setContentType("text/plain");
    response.setCharacterEncoding("UTF-8");
    response.getWriter().write("Hello from ExampleController!");
}

 

사용자의 응답을 HTTP방식 통신값으로 받아들이거나 반환해줄때 사용할 수 있다.

---

기타 정리

CORS 설정

@CrossOrigin(origins = "http://example.com")
@GetMapping("/users")
public List<User> getUsers() {
    return userService.findAll();
}

http://example.com 여기서 온 요청만이 /users 에 접근할 수 있다는 뜻

설정 origins에서만 CORS정책이 적용된다.

CORS란? 접근글 참조

CORS(Cross-Origin Resource Sharing) 정책은 웹 애플리케이션에서 다른 출처(origin)로부터 리소스에 대한 접근을 제어하는 보안 메커니즘이다. 웹 브라우저는 보안 상의 이유로 동일 출처(origin) 정책을 따르며, 즉, 웹 페이지가 리소스를 요청할 때 동일 출처에서만 리소스를 요청할 수 있다. 하지만 CORS는 이 제한을 완화하여 다른 출처에서도 제한된 조건 하에서 리소스에 접근할 수 있도록 허용한다.

CORS의 목적:

• 다른 출처에서 리소스에 접근하는 것을 제한하지만, 필요한 경우 이를 허용할 수 있도록 하여 웹 애플리케이션의 유연성을 높인다.
• 보안적인 이유로 기본적으로는 요청을 차단하며, 필요한 출처와 메서드에 대해서만 제한된 접근을 허용한다.
• 모던 웹 애플리케이션의 요구사항을 충족시키기 위해 API 접근을 보호하면서도 외부에서의 접근을 허용할 수 있는 방법을 제공한다.