API GatewayAPI Gateway

tổng lưu lượng lúc cao điểmtotal traffic at peak

12k rps

tổng lưu lượng lúc cao điểmtotal traffic at peak

độ trễ p99 gateway thêm vàop99 latency added by the gateway

< 5 ms

độ trễ p99 gateway thêm vàop99 latency added by the gateway

giới hạn mỗi API key, burst 200limit per API key, burst 200

100 rps

giới hạn mỗi API key, burst 200limit per API key, burst 200

service phía sau một domainservices behind one domain

14

service phía sau một domainservices behind one domain

Mọi request từ web, mobile và đối tác đi qua một gateway (Kong, Spring Cloud Gateway hoặc Envoy). Gateway kiểm JWT bằng JWKS đã cache, đếm hạn mức trong Redis rồi chuyển tiếp tới service tương ứng. Bật “Token không hợp lệ” để xem request bị chặn ở biên; bật “Upstream sập” để xem gateway fail fast trong khi route khác vẫn chạy.Every request from web, mobile and partners goes through one gateway (Kong, Spring Cloud Gateway or Envoy). The gateway checks the JWT against a cached JWKS, counts the quota in Redis, then forwards to the matching service. Turn on “Invalid token” to see a request stopped at the edge; turn on “Upstream down” to see the gateway fail fast while other routes keep working.

1. 1

   Gateway thành nơi chứa nghiệp vụBusiness logic creeping into the gateway

   Tính giá, kiểm tồn kho hay gộp dữ liệu từ năm service trong plugin gateway biến nó thành một monolith khó deploy, ai sửa cũng phải đụng. Gateway chỉ làm việc chung cho mọi route: TLS, xác thực, giới hạn, định tuyến, header. Việc gộp dữ liệu cho một màn hình thuộc về BFF.Pricing, stock checks or merging data from five services inside gateway plugins turn it into a monolith that everyone must touch to ship. The gateway only does cross-cutting work: TLS, authentication, limits, routing, headers. Composing data for one screen belongs in a BFF.

   Facade
2. 2

   Chỉ xác thực ở biênAuthentication only at the edge

   Nếu service tin mọi request có header X-User-Id, một pod bị chiếm hoặc một lỗi cấu hình mạng là đủ để mạo danh. Gateway kiểm JWT để chặn rác sớm; service vẫn kiểm chữ ký, aud và quyền trên dữ liệu (zero trust). Gateway luôn xoá header X-User-Id do client gửi lên trước khi tự gắn.If services trust any request carrying X-User-Id, one compromised pod or a network misconfiguration is enough to impersonate users. The gateway checks the JWT to drop junk early; services still check the signature, aud and data-level permissions (zero trust). The gateway always strips any client-sent X-User-Id before setting its own.

   ProxyChain of Responsibility
3. 3

   Rate limit trên nhiều instance gatewayRate limits across gateway instances

   Đếm trong bộ nhớ từng instance thì 6 instance cho thực tế 600 rps thay vì 100. Dùng token bucket trong Redis bằng một script Lua nguyên tử (Spring Cloud Gateway RedisRateLimiter, Kong rate-limiting policy=redis). Redis lỗi thì cho qua (fail open) và cảnh báo, trừ endpoint đăng nhập nên fail closed.Counting in each instance's memory means 6 instances actually allow 600 rps instead of 100. Use a Redis token bucket updated by one atomic Lua script (Spring Cloud Gateway RedisRateLimiter, Kong rate-limiting with policy=redis). When Redis fails, let traffic through (fail open) and alert, except for login endpoints, which should fail closed.

   Rate Limiter
4. 4

   Một upstream chậm kéo cả gatewayOne slow upstream drags the whole gateway

   Không có timeout, request treo giữ connection và event loop cho tới khi gateway cạn tài nguyên, mọi route đều chậm. Mỗi route cần connect timeout, response timeout, pool kết nối riêng, health check chủ động và thụ động, và circuit breaker để fail fast bằng 503.Without timeouts, hanging requests hold connections and event-loop capacity until the gateway runs dry and every route slows down. Each route needs a connect timeout, a response timeout, its own connection pool, active and passive health checks, and a circuit breaker that fails fast with a 503.

   Circuit Breaker
5. 5

   Retry ở gateway nhân đôi đơn hàngGateway retries that duplicate orders

   Retry POST /orders khi upstream timeout có thể tạo hai đơn, vì request đầu có thể đã chạy xong. Chỉ retry GET, PUT, DELETE hoặc POST có Idempotency-Key, tối đa 1–2 lần, chỉ với lỗi kết nối và 503, và giữ retry ở một tầng duy nhất.Retrying POST /orders after an upstream timeout can create two orders, because the first request may have completed. Retry only GET, PUT, DELETE, or POST with an Idempotency-Key, at most 1–2 times, only on connection errors and 503s, and keep retries in a single layer.

   Retry with Exponential Backoff
6. 6

   Lần dấu một request qua nhiều serviceFollowing one request through many services

   Gateway là điểm đầu tiên thấy request nên sinh X-Request-Id (nếu client chưa gửi) và traceparent theo W3C, trả lại X-Request-Id cho client. Log của gateway và service cùng mang request_id, nên lỗi người dùng báo lên tra được ngay.The gateway is the first hop to see the request, so it creates X-Request-Id (unless the client sent one) and a W3C traceparent, and echoes X-Request-Id back to the client. Gateway and service logs share the request_id, so a user-reported error can be traced at once.

   Decorator
7. 7

   Một gateway chung cho mọi clientOne gateway for every client

   Web, mobile và đối tác cần dữ liệu khác nhau. Một gateway chung lo phần hạ tầng; mỗi client có thể có một BFF mỏng phía sau để gộp và cắt dữ liệu cho màn hình của mình, do chính team frontend đó sở hữu.Web, mobile and partners need different data. One shared gateway handles infrastructure concerns; each client may get a thin BFF behind it that composes and trims data for its own screens, owned by that frontend team.

   FacadeProxy

Hai route có timeout, breaker và chính sách retry riêng; JWT được kiểm trước khi định tuyến, request id gắn cho mọi request. Go dựng cùng chuỗi bằng middleware quanh httputil.ReverseProxy.Two routes with their own timeout, breaker and retry policy; the JWT is checked before routing and every request gets a request id. Go builds the same chain with middleware around httputil.ReverseProxy.

@Configuration
public class GatewayConfig {

    @Bean
    RouteLocator routes(RouteLocatorBuilder rb, RedisRateLimiter limiter, KeyResolver bySubject) {
        return rb.routes()
            .route("orders", r -> r.path("/api/orders/**")
                .filters(f -> f.stripPrefix(1)
                    .requestRateLimiter(c -> c.setRateLimiter(limiter).setKeyResolver(bySubject))1
                    .circuitBreaker(c -> c.setName("orders").setFallbackUri("forward:/unavailable"))
                    .retry(c -> c.setRetries(1).setMethods(HttpMethod.GET)))2
                .metadata(RESPONSE_TIMEOUT_ATTR, 2000)3
                .uri("lb://order-service"))
            .route("catalog", r -> r.path("/api/catalog/**")
                .filters(f -> f.stripPrefix(1)
                    .circuitBreaker(c -> c.setName("catalog").setFallbackUri("forward:/unavailable")))
                .metadata(RESPONSE_TIMEOUT_ATTR, 1000)
                .uri("lb://catalog-service"))
            .build();
    }

    @Bean
    SecurityWebFilterChain security(ServerHttpSecurity http) {
        return http
            .authorizeExchange(a -> a.pathMatchers("/actuator/health/**").permitAll()
                .anyExchange().authenticated())
            .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults())) // jwk-set-uri from Keycloak
            .build();
    }

    @Bean
    RedisRateLimiter limiter() {
        return new RedisRateLimiter(100, 200, 1); // 100 rps, burst 200
    }

    @Bean
    KeyResolver bySubject() {
        return ex -> ex.getPrincipal().map(Principal::getName).defaultIfEmpty("anonymous");
    }

    @Bean
    GlobalFilter requestId() {
        return (ex, chain) -> {
            String id = Optional.ofNullable(ex.getRequest().getHeaders().getFirst("X-Request-Id"))
                .orElseGet(() -> UUID.randomUUID().toString());
            ServerWebExchange next = ex.mutate()
                .request(r -> r.headers(h -> { h.remove("X-User-Id"); h.set("X-Request-Id", id); }))4
                .build();
            next.getResponse().getHeaders().set("X-Request-Id", id);
            return chain.filter(next);
        };
    }
}

func NewGateway(v *jwt.Validator, rl *RateLimiter) http.Handler {
	mux := http.NewServeMux()
	mux.Handle("/api/orders/", route("http://order-service:8080", 2*time.Second))
	mux.Handle("/api/catalog/", route("http://catalog-service:8080", time.Second))
	// outermost first: request id → auth → rate limit → route
	return chain(mux, withRequestID, withAuth(v), withRateLimit(rl))1
}

func chain(h http.Handler, mws ...func(http.Handler) http.Handler) http.Handler {
	for i := len(mws) - 1; i >= 0; i-- {
		h = mws[i](h)
	}
	return h
}

func withAuth(v *jwt.Validator) func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			claims, err := v.Validate(r.Context(), bearer(r)) // sig, exp, iss, aud; cached JWKS2
			if err != nil {
				w.Header().Set("WWW-Authenticate", `Bearer error="invalid_token"`)
				http.Error(w, "unauthorized", http.StatusUnauthorized)
				return
			}
			r.Header.Set("X-User-Id", claims.Subject) // overwrites any client value
			next.ServeHTTP(w, r)
		})
	}
}

func route(target string, timeout time.Duration) http.Handler {
	u, _ := url.Parse(target)
	proxy := httputil.NewSingleHostReverseProxy(u)
	proxy.Transport = &http.Transport{ResponseHeaderTimeout: timeout, MaxConnsPerHost: 200}3
	cb := gobreaker.NewTwoStepCircuitBreaker(gobreaker.Settings{
		Name:        target,
		Timeout:     30 * time.Second, // OPEN → HALF_OPEN
		ReadyToTrip: func(c gobreaker.Counts) bool { return c.ConsecutiveFailures >= 5 },
	})
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		done, err := cb.Allow()
		if err != nil { // breaker open: fail fast4
			w.Header().Set("Retry-After", "30")
			http.Error(w, "upstream unavailable", http.StatusServiceUnavailable)
			return
		}
		rec := &statusRecorder{ResponseWriter: w, code: http.StatusOK}
		proxy.ServeHTTP(rec, r)
		done(rec.code < 500)
	})
}

Mỗi pattern mở bài học tương ứng trong menu Pattern.Each one opens its lesson in the Patterns menu.