Chuyển tới nội dung chính

Khởi động & cấu hình lõi

Starter nền tảng cho service Spring Boot: cung cấp cấu hình mặc định cho async executor, Jackson, CORS, i18n, metrics và che dấu dữ liệu nhạy cảm, kèm context tĩnh để truy cập bean/property ở nơi không tiện inject. Đây là dependency nền của hầu hết thư viện khác trong bộ.

Khi nào sử dụng​

  • Mọi service Spring Boot trong hệ sinh thái — nên thêm dependency này đầu tiên để có các cấu hình mặc định thống nhất.
  • Cần thread pool async dùng chung, tự động mang context theo luồng sang thread con.
  • Cần thống nhất định dạng ngày/giờ khi (de)serialize JSON (dd/MM/yyyy, ISO...) mà không phải khai báo lại.
  • Cần che dấu số điện thoại, email, CCCD... khi trả response cho client.
  • Cần đọc thông điệp i18n dùng chung (error.notFound, error.system...) hoặc lấy bean/property từ static context.
  • Cần bật nhanh CORS, metrics/tracing, hoặc bỏ qua kiểm tra SSL ở môi trường phát triển.

Cài đặt​

Thêm dependency vào pom.xml, không cần khai báo version vì BOM đã quản lý:

<dependency>
    <groupId>vn.govex.cloud</groupId>
    <artifactId>govex-cloud-core</artifactId>
</dependency>

Hướng dẫn khai báo parent/BOM và Maven repository xem tại Cài đặt.

Cấu hình​

Các property thật của dependency (prefix govex):

PropertyMô tảMặc định
govex.app-codeMã định danh ứng dụng, dùng phân biệt nguồn dữ liệu giữa các service—
govex.async.core-pool-sizeSố luồng lõi của thread pool asyncSố processor của JVM
govex.async.max-pool-sizeSố luồng tối đa của poolGấp đôi core pool size
govex.async.queue-capacitySức chứa queue tác vụ đang chờ500
govex.async.await-terminationChờ tác vụ đang chạy hoàn thành khi shutdowntrue
govex.async.await-termination-periodThời gian chờ tối đa khi shutdown60s
govex.async.pool-nameTiền tố tên luồng trong poolGovex-Async-
govex.http.cache.time-to-live-in-daysThời gian sống của cache HTTP (ngày)1461
govex.cors.*Nhóm CORS: allowed-origins, allowed-methods, allowed-headers, exposed-headers, allow-credentials, max-age, allowed-origin-patterns, allow-private-networkMặc định của Spring
govex.log.enabledBật/tắt ghi log nghiệp vụfalse
govex.log.levelMức log tối thiểuinfo
govex.log.save-logLưu log vào kho dữ liệufalse
govex.log.show-argsGhi lại tham số đầu vào của requesttrue
govex.log.show-responseGhi lại dữ liệu trả về của requesttrue
govex.trace.enabledBật/tắt tracefalse
govex.ssl.bypassBỏ qua kiểm tra chứng thư SSL — chỉ dùng khi phát triểnfalse

Sử dụng​

Khởi động ứng dụng​

Dùng StartupSpringApplication thay cho SpringApplication để nhận banner, profile mặc định và log tiện ích khi khởi động:

@SpringBootApplication
public class CustomerApplication {

    public static void main(String[] args) {
        new StartupSpringApplication(CustomerApplication.class)
            .banner()
            .defaultProfileIfNotExists()
            .run(args);
    }
}

Ví dụ application.yml​

govex:
  app-code: customer-service
  async:
    core-pool-size: 8
    max-pool-size: 16
    queue-capacity: 500
    pool-name: Customer-Async-
  cors:
    allowed-origins:
      - https://portal.example.vn
    allow-credentials: true
  log:
    enabled: true

Truy cập bean/property từ static context​

// Lấy bean khi không tiện inject (utility class, static method...)
RedissonClient redisson = ServiceApplicationContext.getBean(RedissonClient.class);
RedissonClient optional = ServiceApplicationContext.findBean(RedissonClient.class); // null nếu không có bean

// Đọc property, tên ứng dụng và profile
String value = ServiceApplicationContext.getProperty("govex.app-code");
String appName = ServiceApplicationContext.getApplicationName();
String[] profiles = ServiceApplicationContext.getActiveProfiles();

Che dấu dữ liệu nhạy cảm​

public class UserDTO {

    @Sensitive(type = SensitiveType.PHONE)
    private String phone;

    @Sensitive(type = SensitiveType.EMAIL)
    private String email;

    @Sensitive(type = SensitiveType.ID_CARD)
    private String idCard;
}

Khi serialize response, các field trên được che dấu theo SensitiveType tương ứng (PHONE, EMAIL, ID_CARD, ADDRESS, BANK_CARD, PASSWORD). Muốn đổi cách che dấu hoặc tắt hẳn, khai báo bean SensitiveService riêng.

Thông điệp i18n​

String notFound = messageUtils.getMessage("error.notFound");
String badRequest = messageUtils.getMessage("error.badRequest", params);

Các mã dùng chung có sẵn: error.system, error.notFound, error.forbidden, error.unauthorized, error.badRequest.

Ghi đè bean mặc định​

Các bean auto-configuration đều có @ConditionalOnMissingBean; khai báo bean cùng loại trong ứng dụng để thay thế:

@Bean
public SensitiveService sensitiveService() {
    return new MySensitiveService();
}

Lưu ý​

  • govex.ssl.bypass=true chỉ dành cho môi trường phát triển — bundle bypass-ssl chấp nhận mọi chứng thư máy chủ, không dùng ở production.
  • govex.async.* nhường quyền nếu ứng dụng đã khai báo Executor/AsyncConfigurer riêng; khi đó thread pool mặc định không còn được tạo.
  • Nhóm govex.cors.* chỉ tác động khi classpath có spring-web/spring-webmvc.
  • Các property govex.log.* và govex.trace.enabled là cấu hình chung cho tính năng ghi log/trace của hệ thống.
  • Dependency kéo sẵn govex-cloud-common và govex-cloud-mapstruct; không cần khai báo lại.