Cấu hình động

Quản lý cấu hình động theo nghiệp vụ (bảng setting), kèm cơ chế refresh cấu hình không cần khởi động lại service và bean EncryptService mặc định dùng khoá AES lưu trong database.

Khi nào sử dụng

• Service cần đọc/ghi cấu hình vận hành (tham số nghiệp vụ, khoá bí mật...) mà không muốn deploy lại.
• Cần refresh cấu hình cho các bean @RefreshScope ngay khi admin thay đổi giá trị.
• Cần EncryptService — đây là nơi cung cấp implementation mã hoá AES mặc định, đọc khoá từ setting security.aes_secret.

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-config</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ấu hình hoạt động dựa trên dữ liệu trong database và hạ tầng đi kèm:

Hạng mục	Giá trị	Mô tả
Khoá AES	setting security.aes_secret	EncryptService đọc từ bảng setting; bắt buộc tồn tại trước khi dùng
Topic refresh	iam-config-refresh	Topic Redisson để phát thông báo refresh cấu hình
Refresh toàn bộ	__REFRESH_ALL__	Key đặc biệt để refresh tất cả bean @RefreshScope
Liquibase changelog	db/changelog/config/changelog-master.yaml	Cần include vào changelog master của ứng dụng để tạo bảng setting

Sử dụng

Quản lý setting qua REST API

Đọc giá trị theo key:

GET /api/v1/setting/security.aes_secret

Lưu giá trị (tạo mới hoặc cập nhật theo name):

POST /api/v1/setting/save
Content-Type: application/json

{
  "name": "security.aes_secret",
  "value": "khoa-aes-base64",
  "desc": "Khoá AES dùng cho mã hoá"
}

Lấy chi tiết setting (gồm cả entity): GET /api/v1/setting/{key}/detail.

Dùng EncryptService trong code

@Service
@RequiredArgsConstructor
public class PaymentService {

    private final EncryptService encryptService;

    public String encode(String raw) {
        return encryptService.encrypt(raw);
    }

    public String decode(String encrypted) {
        return encryptService.decrypt(encrypted);
    }
}

Refresh cấu hình

// Refresh theo key cấu hình
RefreshService.refresh("some.config.key");

// Refresh toàn bộ bean @RefreshScope
RefreshService.refresh("__REFRESH_ALL__");

Lưu ý

• Ứng dụng cần include Liquibase changelog của dependency (db/changelog/config/changelog-master.yaml) để bảng setting tồn tại trước khi khởi động.
• Cần JPA và Redisson hoạt động: dependency phụ thuộc govex-cloud-data-jpa, govex-cloud-redisson, govex-cloud-crypto và govex-cloud-validation.
• EncryptService ném lỗi nếu setting security.aes_secret chưa tồn tại — tạo setting này trước khi gọi mã hoá/giải mã.
• SettingServiceImpl là implementation dùng chung, không phải bean của dependency này; service muốn dùng trực tiếp có thể kế thừa nó (các dependency mail/sms đã làm vậy) hoặc thao tác qua REST API.
• Các endpoint quản trị setting cần được bảo vệ bởi tầng security của ứng dụng trước khi mở ra ngoài.
• Khi không kết nối được Redisson, listener refresh chỉ ghi log lỗi và không làm fail quá trình khởi động.