고급 설계 원칙

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1609459200
Retry-After: 3600

{
    "error": "Too Many Requests",
    "message": "Rate limit exceeded. Maximum 100 requests per hour allowed.",
    "retryAfter": 3600
}

// 의존성: com.bucket4j:bucket4j-core

@Component
public class RateLimitInterceptor implements HandlerInterceptor {

    private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();

    private Bucket createNewBucket() {
        Bandwidth limit = Bandwidth.classic(100, Refill.intervally(100, Duration.ofHours(1)));
        return Bucket.builder()
                .addLimit(limit)
                .build();
    }

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) throws Exception {

        String clientId = getClientId(request);
        Bucket bucket = buckets.computeIfAbsent(clientId, k -> createNewBucket());

        ConsumptionProbe probe = bucket.tryConsumeAndReturnRemaining(1);

        response.addHeader("X-RateLimit-Limit", "100");
        response.addHeader("X-RateLimit-Remaining",
            String.valueOf(probe.getRemainingTokens()));

        if (probe.isConsumed()) {
            return true;
        }

        response.addHeader("Retry-After",
            String.valueOf(probe.getNanosToWaitForRefill() / 1_000_000_000));
        response.sendError(HttpStatus.TOO_MANY_REQUESTS.value(),
            "Rate limit exceeded");
        return false;
    }

    private String getClientId(HttpServletRequest request) {
        // API 키 또는 IP 기반 식별
        String apiKey = request.getHeader("X-API-Key");
        return apiKey != null ? apiKey : request.getRemoteAddr();
    }
}

// 의존성: io.github.resilience4j:resilience4j-ratelimiter

@Configuration
public class RateLimiterConfig {

    @Bean
    public RateLimiter rateLimiter() {
        RateLimiterConfig config = RateLimiterConfig.custom()
                .limitForPeriod(100)                    // 시간당 100 요청
                .limitRefreshPeriod(Duration.ofHours(1))
                .timeoutDuration(Duration.ZERO)         // 대기 없이 즉시 거부
                .build();

        return RateLimiter.of("api-rate-limiter", config);
    }
}

@RestController
@RequestMapping("/api/v1")
public class ApiController {

    private final RateLimiter rateLimiter;

    @GetMapping("/data")
    public ResponseEntity<Data> getData() {
        return RateLimiter.decorateSupplier(rateLimiter, () -> {
            // 비즈니스 로직
            return ResponseEntity.ok(dataService.getData());
        }).get();
    }
}

GET /api/v1/users?page=2&size=20 HTTP/1.1

# 응답
HTTP/1.1 200 OK
Content-Type: application/json

{
    "content": [
        {"id": 21, "name": "User 21"},
        {"id": 22, "name": "User 22"},
        ...
    ],
    "page": 2,
    "size": 20,
    "totalElements": 1000,
    "totalPages": 50,
    "first": false,
    "last": false
}

// Spring Data JPA 구현
@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    @GetMapping
    public Page<User> getUsers(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size,
            @RequestParam(defaultValue = "id") String sort) {

        Pageable pageable = PageRequest.of(page, size, Sort.by(sort));
        return userRepository.findAll(pageable);
    }
}

# 요청
GET /api/v1/users?size=20&cursor=eyJpZCI6MTAwfQ== HTTP/1.1

# 응답
HTTP/1.1 200 OK

{
    "data": [
        {"id": 101, "name": "User 101"},
        {"id": 102, "name": "User 102"},
        ...
    ],
    "cursors": {
        "next": "eyJpZCI6MTIwfQ==",
        "previous": "eyJpZCI6MTAxfQ==",
        "hasNext": true,
        "hasPrevious": true
    }
}

// 커서 페이지네이션 구현
@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    @GetMapping
    public CursorPage<User> getUsers(
            @RequestParam(required = false) String cursor,
            @RequestParam(defaultValue = "20") int size) {

        Long lastId = decodeCursor(cursor);

        List<User> users = userRepository.findByIdGreaterThan(lastId,
                PageRequest.of(0, size + 1, Sort.by("id")));

        boolean hasNext = users.size() > size;
        if (hasNext) {
            users = users.subList(0, size);
        }

        String nextCursor = hasNext ? encodeCursor(users.get(size - 1).getId()) : null;

        return new CursorPage<>(users, nextCursor, hasNext);
    }

    private Long decodeCursor(String cursor) {
        if (cursor == null) return 0L;
        return Long.parseLong(new String(Base64.getDecoder().decode(cursor)));
    }

    private String encodeCursor(Long id) {
        return Base64.getEncoder().encodeToString(String.valueOf(id).getBytes());
    }
}

GET /api/v1/events?since=1609459200&until=1612137600&limit=50 HTTP/1.1

# 요청
GET /api/v1/products HTTP/1.1
Accept-Language: ko-KR, ko;q=0.9, en-US;q=0.8, en;q=0.7

# 응답
HTTP/1.1 200 OK
Content-Language: ko-KR
Content-Type: application/json

{
    "products": [
        {"name": "노트북", "description": "고성능 노트북"},
        {"name": "키보드", "description": "무선 키보드"}
    ]
}

@Configuration
public class LocaleConfig implements WebMvcConfigurer {

    @Bean
    public LocaleResolver localeResolver() {
        AcceptHeaderLocaleResolver resolver = new AcceptHeaderLocaleResolver();
        resolver.setDefaultLocale(Locale.KOREAN);
        return resolver;
    }

    @Bean
    public MessageSource messageSource() {
        ResourceBundleMessageSource source = new ResourceBundleMessageSource();
        source.setBasename("messages");
        source.setDefaultEncoding("UTF-8");
        return source;
    }
}

# messages_ko.properties
product.name=상품명
product.price=가격
error.not_found=해당 상품을 찾을 수 없습니다

# messages_en.properties
product.name=Product Name
product.price=Price
error.not_found=Product not found

{
    "id": 123,
    "title": "REST API Design",
    "isbn": "978-1234567890",
    "_links": {
        "self": {
            "href": "/api/books/123"
        },
        "author": {
            "href": "/api/authors/456"
        },
        "reviews": {
            "href": "/api/books/123/reviews"
        },
        "purchase": {
            "href": "/api/orders",
            "method": "POST"
        }
    },
    "_embedded": {
        "author": {
            "id": 456,
            "name": "John Doe",
            "_links": {
                "self": {"href": "/api/authors/456"}
            }
        }
    }
}

// 의존성: org.springframework.boot:spring-boot-starter-hateoas

@RestController
@RequestMapping("/api/v1/books")
public class BookController {

    @GetMapping("/{id}")
    public EntityModel<Book> getBook(@PathVariable Long id) {
        Book book = bookService.findById(id);

        return EntityModel.of(book,
            linkTo(methodOn(BookController.class).getBook(id)).withSelfRel(),
            linkTo(methodOn(BookController.class).getAllBooks()).withRel("collection"),
            linkTo(methodOn(AuthorController.class).getAuthor(book.getAuthorId()))
                .withRel("author"),
            linkTo(methodOn(ReviewController.class).getReviewsForBook(id))
                .withRel("reviews")
        );
    }

    @GetMapping
    public CollectionModel<EntityModel<Book>> getAllBooks() {
        List<EntityModel<Book>> books = bookService.findAll().stream()
            .map(book -> EntityModel.of(book,
                linkTo(methodOn(BookController.class).getBook(book.getId())).withSelfRel()
            ))
            .collect(Collectors.toList());

        return CollectionModel.of(books,
            linkTo(methodOn(BookController.class).getAllBooks()).withSelfRel()
        );
    }
}

// 응답 예시
{
    "id": 123,
    "title": "REST API Design",
    "isbn": "978-1234567890",
    "_links": {
        "self": {"href": "http://api.example.com/api/v1/books/123"},
        "collection": {"href": "http://api.example.com/api/v1/books"},
        "author": {"href": "http://api.example.com/api/v1/authors/456"},
        "reviews": {"href": "http://api.example.com/api/v1/books/123/reviews"}
    }
}

@GetMapping
public PagedModel<EntityModel<Book>> getBooks(Pageable pageable) {
    Page<Book> page = bookService.findAll(pageable);

    return pagedResourcesAssembler.toModel(page,
        book -> EntityModel.of(book,
            linkTo(methodOn(BookController.class).getBook(book.getId())).withSelfRel()
        )
    );
}

{
    "_embedded": {
        "books": [
            {"id": 1, "title": "Book 1", "_links": {...}},
            {"id": 2, "title": "Book 2", "_links": {...}}
        ]
    },
    "_links": {
        "self": {"href": "/api/v1/books?page=1&size=20"},
        "first": {"href": "/api/v1/books?page=0&size=20"},
        "prev": {"href": "/api/v1/books?page=0&size=20"},
        "next": {"href": "/api/v1/books?page=2&size=20"},
        "last": {"href": "/api/v1/books?page=9&size=20"}
    },
    "page": {
        "size": 20,
        "totalElements": 200,
        "totalPages": 10,
        "number": 1
    }
}

// 의존성: io.rest-assured:rest-assured

import static io.restassured.RestAssured.*;
import static org.hamcrest.Matchers.*;

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
public class BookApiTest {

    @LocalServerPort
    private int port;

    @BeforeEach
    void setUp() {
        RestAssured.port = port;
        RestAssured.basePath = "/api/v1";
    }

    @Test
    void shouldGetBookById() {
        given()
            .pathParam("id", 123)
        .when()
            .get("/books/{id}")
        .then()
            .statusCode(200)
            .contentType(ContentType.JSON)
            .body("id", equalTo(123))
            .body("title", notNullValue())
            .body("_links.self.href", containsString("/books/123"));
    }

    @Test
    void shouldCreateBook() {
        String requestBody = """
            {
                "title": "New Book",
                "isbn": "978-1234567890",
                "authorId": 456
            }
            """;

        given()
            .contentType(ContentType.JSON)
            .body(requestBody)
        .when()
            .post("/books")
        .then()
            .statusCode(201)
            .header("Location", containsString("/books/"))
            .body("id", notNullValue())
            .body("title", equalTo("New Book"));
    }

    @Test
    void shouldReturnNotFoundForMissingBook() {
        given()
            .pathParam("id", 99999)
        .when()
            .get("/books/{id}")
        .then()
            .statusCode(404)
            .body("error", equalTo("Not Found"));
    }

    @Test
    void shouldReturnTooManyRequestsWhenRateLimited() {
        // 100번 초과 요청
        for (int i = 0; i < 101; i++) {
            get("/books");
        }

        given()
        .when()
            .get("/books")
        .then()
            .statusCode(429)
            .header("Retry-After", notNullValue());
    }
}

// 의존성: org.springdoc:springdoc-openapi-starter-webmvc-ui

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Book API")
                        .version("1.0.0")
                        .description("RESTful API for Book Management")
                        .contact(new Contact()
                                .name("API Support")
                                .email("support@example.com")))
                .externalDocs(new ExternalDocumentation()
                        .description("Wiki Documentation")
                        .url("https://wiki.example.com/docs"));
    }
}

@RestController
@RequestMapping("/api/v1/books")
@Tag(name = "Books", description = "Book management API")
public class BookController {

    @Operation(
        summary = "Get a book by ID",
        description = "Returns a single book with HATEOAS links"
    )
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "Successfully retrieved book"),
        @ApiResponse(responseCode = "404", description = "Book not found"),
        @ApiResponse(responseCode = "429", description = "Rate limit exceeded")
    })
    @GetMapping("/{id}")
    public EntityModel<Book> getBook(
            @Parameter(description = "Book ID", required = true)
            @PathVariable Long id) {
        // ...
    }

    @Operation(summary = "Create a new book")
    @ApiResponse(responseCode = "201", description = "Book created successfully")
    @PostMapping
    public ResponseEntity<EntityModel<Book>> createBook(
            @io.swagger.v3.oas.annotations.parameters.RequestBody(
                description = "Book to create",
                required = true,
                content = @Content(schema = @Schema(implementation = BookRequest.class))
            )
            @RequestBody @Valid BookRequest request) {
        // ...
    }
}

# 생성된 OpenAPI 스펙 (일부)
openapi: 3.0.1
info:
  title: Book API
  version: 1.0.0
paths:
  /api/v1/books/{id}:
    get:
      tags:
        - Books
      summary: Get a book by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Successfully retrieved book
        '404':
          description: Book not found
        '429':
          description: Rate limit exceeded