Spring Bean Scopes: Singleton, Prototype, và Hơn Thế Nữa | Java Spring Roadmap

Bean của bạn hiếm khi hỏng vì thiếu annotation. Nó hỏng vì hai request cùng ghi vào một field, hoặc vì một prototype bị capture trong singleton ngay lúc khởi động. Cả hai là lỗi scope, và cả hai đều im lặng: không exception, không log, chỉ có dữ liệu sai.

Spring Bean Scopes trả lời hai câu hỏi: container tạo bao nhiêu instance, và instance đó sống đến khi nào. Bài này đi qua cả sáu scope của Framework 7, dừng ở ba chỗ hay sai nhất: singleton giữ trạng thái, prototype bị giữ lại, request/session scope dùng ngoài web context. Code chạy trên Boot 4.1.2, Framework 7.0.10, Java 25 LTS.

Cập nhật 2026

  • Không có scope mới. Framework 7.0.10 và Boot 4.1.2 vẫn đúng sáu scope, và @Scope, @RequestScope, @SessionScope, @ApplicationScope giữ nguyên tên lẫn package.
  • Web scope cần web-aware context. Bốn scope web chỉ được đăng ký khi context có servlet environment; không có thì request và session không tồn tại, và lỗi hiện ra lúc resolve dependency.
  • javax đã bị bỏ. HttpSession, filter, listener giờ nằm trong jakarta.servlet (Jakarta EE 11). Code copy từ blog cũ sẽ không compile.
  • ThreadLocal vẫn là per-thread. Java 25 (JEP 506) làm ScopedValue thành final cho context chỉ đọc, nhưng virtual thread không làm ThreadLocal miễn phí.

Spring Bean Scopes trong Framework 7: sáu lựa chọn, một mặc định

Scope là thuộc tính của bean definition, không phải của class. Cùng một class có thể là singleton trong context này và prototype trong context khác nếu bạn khai báo hai definition. Container đọc scope lúc resolve dependency rồi quyết định lấy instance từ đâu.

Scope Instance Container gọi destroy?
singleton Một, cho mỗi context Có, khi context đóng
prototype Mới mỗi lần lookup Không
request Một, cho mỗi HTTP request Có, khi request kết thúc
session Một, cho mỗi HTTP session Có, khi session invalidate hoặc hết hạn
application Một, cho mỗi ServletContext Có, khi context đóng
websocket Một, cho mỗi WebSocket session Có, khi socket đóng

Ba scope đầu không cần web. Ba scope sau chỉ có nghĩa trong ứng dụng web, nên vấn đề thực tế thường là “scope không tồn tại ở đây” chứ không phải khai báo sai cú pháp. application gắn với ServletContext (nhiều context trong một JVM thì mỗi context một instance), websocket theo một phiên WebSocket; cả hai cần proxy nếu inject vào bean sống lâu hơn.

Vì sao singleton là mặc định

Mặc định này là hệ quả kinh tế, không phải sở thích kiến trúc. Phần lớn bean là service, repository, controller, HTTP client — không giữ trạng thái của riêng ai. Một instance dùng chung rẻ hơn tạo mới mỗi lần gọi, và container quản lý trọn vòng đời, từ @PostConstruct đến @PreDestroy.

Giá phải trả là mọi field trở thành tài sản chung. Hai request đồng thời nhìn thấy cùng một object, cùng một ArrayList. Field đó thay đổi theo request thì bạn vừa tạo ra một biến toàn cục đội lốt dependency injection.

// File: src/main/java/com/example/shop/metrics/ViewCounter.java
package com.example.shop.metrics;

import java.util.concurrent.atomic.AtomicLong;

import org.springframework.stereotype.Service;

@Service // singleton: mot instance duy nhat cho ca context
public class ViewCounter {

    private long total;                          // mutable state dung chung
    private final AtomicLong safeTotal = new AtomicLong();

    public long broken() {
        return ++total;                          // doc-sua-ghi, khong nguyen tu
    }

    public long fixed() {
        return safeTotal.incrementAndGet();      // mot thao tac nguyen tu
    }
}

++total là ba bước đọc, cộng, ghi; hai thread chen nhau giữa ba bước đó làm mất cập nhật. synchronized hay AtomicLong chữa được một biến, nhưng không chữa được bất biến (invariant) trên nhiều field — ví dụ “tổng tiền phải khớp số dòng”. Cách bền vững là bỏ trạng thái khỏi singleton: truyền dữ liệu qua tham số, giữ kết quả trong local variable, hoặc đặt state vào bean có scope hẹp hơn.

Hai hệ quả khác ít được nói tới: field ghi sau khi singleton đã publish mà không có happens-before có thể không hiện ra với thread khác, và HashMap làm cache sẽ hỏng cấu trúc khi ghi đồng thời; còn Connection hay EntityManager trong field nghĩa là một kết nối dùng chung cho toàn app — EntityManager không thread-safe.

Đồng bộ trong singleton: ThreadLocal và virtual threads

Khi buộc phải giữ context theo thread — correlation ID, tenant, security context — nhiều người dùng ThreadLocal. Ba cái bẫy: thread pool giữ biến sang task kế tiếp, nên luôn remove() trong finally; @Async hay executor không tự lan giá trị, nên RequestContextHolder rỗng và request-scoped bean ném lỗi; virtual thread vẫn có một ThreadLocalMap mỗi thread, và vài trăm nghìn thread đang sống là vài trăm nghìn bản copy trong heap.

ScopedValue (final từ Java 25, JEP 506) sửa hai điểm đầu: khai báo static final ScopedValue<String> ID = ScopedValue.newInstance() rồi bind bằng ScopedValue.where(ID, id).run(() -> ...). Binding immutable, chỉ sống trong phạm vi run, được kế thừa bởi thread con tạo bên trong phạm vi đó, và không cần remove().

Đừng dùng ScopedValue cho trạng thái thay đổi được, và đừng giả định nó lan qua mọi thread pool của Boot 4.1: nó chỉ đến thread con tạo trong phạm vi binding. MDC của SLF4J vẫn là ThreadLocal, nên log cần correlation ID vẫn phải MDC.put.

Prototype: instance mới mỗi lần lookup

Prototype đảo ngược singleton: mỗi lần container trả bean, nó gọi constructor lần nữa. Không có cache, nên chi phí tạo object tính cho người gọi. Đổi lại, mỗi nơi nhận một object riêng, đặt state thoải mái mà không sợ thread khác giẫm lên.

// File: src/main/java/com/example/shop/report/ReportBuffer.java
package com.example.shop.report;

import org.springframework.context.annotation.Scope;
import org.springframework.stereotype.Component;

@Component
@Scope("prototype")
public class ReportBuffer {

    private final StringBuilder rows = new StringBuilder();

    void add(String row) {
        rows.append(row).append('\n');
    }

    String render() {
        return rows.toString();
    }
}

Điểm dễ hiểu sai nhất: container không quản lý prototype sau khi giao. @PostConstruct vẫn chạy, nhưng @PreDestroy thì không. Nếu prototype mở stream hay đăng ký listener, bạn phải tự đóng trong code gọi.

Prototype lọt vào singleton

Đây là lỗi phổ biến nhất của cả bài. Singleton được tạo một lần, nên field prototype của nó được resolve đúng một lần và giữ nguyên instance đó cho đến khi context đóng.

// File: src/main/java/com/example/shop/report/ReportService.java
package com.example.shop.report;

import java.util.List;

import org.springframework.beans.factory.ObjectProvider;
import org.springframework.stereotype.Service;

@Service
public class ReportService {

    private final ObjectProvider<ReportBuffer> buffers;

    public ReportService(ObjectProvider<ReportBuffer> buffers) {
        this.buffers = buffers;
    }

    public String build(List<String> rows) {
        ReportBuffer buffer = buffers.getObject();   // instance moi moi lan goi
        rows.forEach(buffer::add);
        return buffer.render();
    }
}

ObjectProvider là dependency đúng cho prototype: nó là factory, không phải instance, nên mỗi getObject() tạo bean mới, và có thêm getIfAvailable cho dependency optional. @Lookup trên method abstract là cách cũ nhưng vẫn hợp lệ; applicationContext.getBean() biến DI thành service locator.

@Lazy không chữa được lỗi này. Nó hoãn resolve đến lần gọi đầu tiên, rồi proxy cache instance đó. Bạn đổi thời điểm capture, không đổi bản chất. Cần instance mới mỗi lần thì dùng ObjectProvider.

Scoped proxy: TARGET_CLASS và INTERFACES

Singleton không thể giữ trực tiếp bean request-scoped: lúc khởi động chưa có request nào để tạo instance, nên container từ chối resolve dependency. Giải pháp là inject một proxy — object đứng tên bean, nhưng mỗi method call mới đi tìm instance thật trong scope hiện tại.

proxyMode = ScopedProxyMode.TARGET_CLASS tạo subclass proxy (CGLIB trong Spring hiện tại): không cần interface, nhưng class phải không final và method không được private hay final, nếu không lời gọi đi thẳng vào method cha và bỏ qua proxy. ScopedProxyMode.INTERFACES tạo JDK dynamic proxy, nhẹ hơn, nhưng chỉ proxy method khai báo trong interface.

Với scope web, không phải viết tay: @RequestScope chính là @Scope(value = "request", proxyMode = ScopedProxyMode.TARGET_CLASS), @SessionScope tương tự. Chỉ khai báo proxyMode khi tự đặt @Scope.

Prototype + proxy có một cái bẫy riêng: proxy resolve target mỗi lần gọi method, nên buffer.add(row) và buffer.render() có thể chạm hai instance khác nhau. State phải sống qua nhiều lời gọi thì đừng dùng proxy prototype; giữ biến local như ReportService.

Request scope: correlation ID cho một request

Use case rõ nhất là dữ liệu chỉ có nghĩa trong một request: correlation ID, thông tin người gọi đã xác thực, cờ read-only của transaction. Bean request-scoped chết cùng request, nên không có gì để dọn.

// File: src/main/java/com/example/shop/web/RequestContext.java
package com.example.shop.web;

import org.springframework.stereotype.Component;
import org.springframework.web.context.annotation.RequestScope;

@Component
@RequestScope
public class RequestContext {

    private String correlationId;

    public String correlationId() {
        return correlationId;
    }

    public void correlationId(String value) {
        this.correlationId = value;
    }
}
// File: src/main/java/com/example/shop/web/CorrelationFilter.java
package com.example.shop.web;

import java.io.IOException;
import java.util.UUID;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

@Component
public class CorrelationFilter extends OncePerRequestFilter {

    private final RequestContext context;   // proxy, khong phai instance that

    public CorrelationFilter(RequestContext context) {
        this.context = context;
    }

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        String id = UUID.randomUUID().toString();
        context.correlationId(id);
        response.setHeader("X-Correlation-Id", id);
        chain.doFilter(request, response);   // request scope ket thuc sau lenh nay
    }
}

Chi phí gần như bằng không: một object mỗi request, chết khi request xong. Rủi ro nằm ở chỗ khác — scope không lan sang thread khác: gọi @Async, ExecutorService hay CompletableFuture.supplyAsync rồi đọc RequestContext trong đó sẽ nhận IllegalStateException “No thread-bound request found”. Truyền giá trị qua tham số hoặc dùng TaskDecorator để copy context.

Trong Boot bạn không cần đăng ký RequestContextListener thủ công — RequestContextFilter đã được auto-configure. Chỉ khi chạy DispatcherServlet ngoài Boot mới phải tự thêm listener; đó là lý do các bài cũ nhắc đến nó.

Session scope: giỏ hàng và cái giá bộ nhớ

Session scope sống theo HttpSession, hợp cho dữ liệu nhỏ gắn với một người dùng qua nhiều request: giỏ hàng, wizard nhiều bước, tùy chọn hiển thị chưa lưu vào tài khoản.

// File: src/main/java/com/example/shop/cart/Cart.java
package com.example.shop.cart;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.List;

import org.springframework.stereotype.Component;
import org.springframework.web.context.annotation.SessionScope;

@Component
@SessionScope
public class Cart implements Serializable {

    private final List<CartLine> lines = new ArrayList<>();

    public synchronized void add(CartLine line) {
        lines.add(line);
    }

    public synchronized List<CartLine> lines() {
        return List.copyOf(lines);
    }
}

synchronized ở đây không thừa: hai tab của cùng một người dùng có thể gửi hai request song song, và cả hai chạm cùng một instance trong cùng session. Nếu CartLine nặng, lưu ID rồi đọc từ database; session chỉ nên chứa thứ nhỏ và tái tạo được.

Chi phí thật của session scope là bộ nhớ và vòng đời: một instance mỗi session, sống tới khi hết hạn (mặc định 30 phút ở Boot) hoặc bị invalidate. Năm mươi nghìn session đồng thời là năm mươi nghìn object, cộng cả graph bên trong. Dùng session replication hay Spring Session thì bean và mọi field phải Serializable — một field không serialize được làm hỏng cả session, thường chỉ lộ ra khi scale nhiều node.

Session scope không hợp với JWT stateless. Khi cấu hình SessionCreationPolicy.STATELESS, server không tạo HttpSession, nên không có chỗ để treo bean session-scoped. Giỏ hàng lúc đó phải nằm ở client (cookie hoặc token có ký) hoặc ở store phía server khóa theo user ID — đó là quyết định kiến trúc, không phải annotation sửa được.

Sáu lỗi thường gặp

  • Prototype trong singleton. Resolve một lần rồi dùng lại mãi; sửa bằng ObjectProvider hoặc @Lookup, không bằng @Lazy.
  • Quên @Scope("prototype"). Bean có field trạng thái mà không khai báo scope thì thành singleton dùng chung.
  • Request scope ngoài request thread. @Async, scheduler, Kafka consumer, test webEnvironment = NONE đều không có request.
  • Session scope phình bộ nhớ. Object lớn hay graph JPA trong session làm heap tăng theo số session.
  • Singleton giữ tài nguyên có trạng thái. Connection và EntityManager không thread-safe; inject DataSource thay vì giữ chúng trong field.
  • Proxy trên class final hoặc method private. TARGET_CLASS không tạo được subclass, proxy bị bỏ qua im lặng.

Chọn scope nào?

Scope Dùng khi Tránh khi
singleton Service, repository, client, config bất biến Cần trạng thái riêng cho user hoặc request
prototype Object có state dùng một lần, builder, buffer Inject trực tiếp vào singleton mà không có provider
request Correlation ID, dữ liệu sống trong một request Chuyển việc sang thread khác hoặc ngoài web context
session Giỏ hàng nhỏ, wizard nhiều bước JWT stateless, object lớn, session phân tán

Bắt đầu bằng singleton và giữ nó stateless. Khi cần state, hạ scope xuống mức hẹp nhất còn đủ dùng: request trước, session sau, prototype khi object chỉ sống trong một lời gọi.

Nhìn về 2027

Boot 4.2 và Framework 7.1 đang ở RC, đừng viết tài liệu nội bộ dựa trên chúng. Scope API nhiều khả năng giữ nguyên; đáng theo dõi là cách Spring lan context qua virtual thread và thread pool. Java 29 là LTS kế tiếp, dự kiến 2027.

Checklist

  • Singleton chỉ giữ collaborator và config bất biến; state request nằm ở tham số hoặc scope hẹp.
  • Field mutable trong singleton phải là Atomic, concurrent collection, hoặc được bảo vệ có chủ đích.
  • ThreadLocal luôn có remove() trong finally; context chỉ đọc thì cân nhắc ScopedValue.
  • Prototype vào singleton phải đi qua ObjectProvider, không qua field injection; bean request/session inject vào bean sống lâu hơn phải có proxyMode.
  • Kiểm tra HttpSession có thật trước khi dùng session scope — JWT stateless thì không.

Nền tảng của bài này là hai bài trước trong series: Spring IoC trong thực tế và Hiểu về Dependency Injection. Muốn ôn lại các annotation liên quan tới scope, xem Tất tần tật về Spring Annotations; bức tranh tổng thể nằm ở Spring Boot Roadmap.