Spring Boot auto configuration: application.yml và profile

Spring Boot auto configuration hoạt động thế nào? Hiểu cơ chế tự cấu hình, viết application.yml, tách cấu hình dev và prod bằng profile.

Auto configuration là cơ chế Spring Boot tự cấu hình ứng dụng dựa trên những thư viện có trong project: thấy Spring MVC thì dựng sẵn DispatcherServlet và máy chủ Tomcat. Bạn chỉ chỉnh những gì cần đổi, bằng file application.yml, và đổi theo môi trường bằng profile.

Ở bài trước, mình dựng order-api cho quán Mộc (quán cà phê tình huống minh họa của loạt bài) và thấy một chuyện lạ: mình mới thêm một dependency, mà Tomcat đã tự chạy trên cổng 8080 và JSON đã tự được dựng, không có dòng cấu hình nào. Bài này mở nắp chuyện đó, rồi dạy bạn chỉnh các thứ ấy khi cần: đổi cổng, đưa quy tắc giảm giá ra khỏi code, và dùng những giá trị khác nhau cho máy dev và máy chủ thật.

Ai đã khởi động Tomcat khi mình không cấu hình gì?

Câu trả lời nằm ở chú thích @SpringBootApplication trên class có main. Theo tài liệu của Spring Boot, nó là cách viết gọn của ba chú thích. Một là @SpringBootConfiguration (class này chứa cấu hình). Hai là @ComponentScan (quét tìm bean, như bài trước đã nói). Ba là @EnableAutoConfiguration, thứ mà bài này quan tâm.

@EnableAutoConfiguration bảo Spring Boot đọc một danh sách các class cấu hình sẵn có và áp dụng những class nào hợp với project của bạn. Danh sách đó nằm ngay trong các file jar của Spring Boot. Mình mở thử file jar spring-boot-webmvc (thư viện mà starter web kéo về) để xem. Trong Spring Boot 4, phần tự cấu hình được chia thành nhiều jar theo từng mảng, và mỗi jar có file META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports liệt kê các class của nó:

Nội dung AutoConfiguration.imports trong spring-boot-webmvc-4.1.2.jar
org.springframework.boot.webmvc.autoconfigure.DispatcherServletAutoConfiguration
org.springframework.boot.webmvc.autoconfigure.WebMvcAutoConfiguration
org.springframework.boot.webmvc.autoconfigure.WebMvcObservationAutoConfiguration
org.springframework.boot.webmvc.autoconfigure.actuate.endpoint.web.WebMvcHealthEndpointExtensionAutoConfiguration
org.springframework.boot.webmvc.autoconfigure.actuate.web.mappings.WebMvcMappingsAutoConfiguration
org.springframework.boot.webmvc.autoconfigure.error.ErrorMvcAutoConfiguration

Mỗi class trong danh sách có điều kiện để được bật, thường là "chỉ khi có class X trong classpath" hoặc "chỉ khi bạn chưa tự khai báo bean Y". Điều kiện làm nên sự tự động: bạn thêm thư viện, điều kiện thành đúng, cấu hình bật lên. Mình có thể xem Spring Boot đã quyết định gì bằng cách chạy với cờ --debug, nó in một báo cáo gọi là "conditions evaluation report":

Chạy (trong thư mục order-api, sau mvn package)
java -Dstdout.encoding=UTF-8 -jar target/order-api-0.0.1-SNAPSHOT.jar --debug
Kết quả (vài đoạn của báo cáo)
Positive matches:
-----------------

   DispatcherServletAutoConfiguration matched:
      - @ConditionalOnClass found required class 'org.springframework.web.servlet.DispatcherServlet' (OnClassCondition)
      - found 'session' scope (OnWebApplicationCondition)

Negative matches:
-----------------

   GsonHttpMessageConvertersConfiguration:
      Did not match:
         - @ConditionalOnClass did not find required class 'com.google.gson.Gson' (OnClassCondition)

Phần Positive matches liệt kê những gì đã bật, kèm lý do. DispatcherServletAutoConfiguration được bật vì Spring Boot tìm thấy class DispatcherServlet trong classpath. Đó là kết quả của việc mình thêm starter web.

Phần Negative matches liệt kê những gì bị bỏ qua. Cấu hình dùng thư viện JSON Gson không được bật, vì project không có Gson. Đây cũng là công cụ debug đầu tiên mình nghĩ tới mỗi khi Spring Boot "tự nhiên" làm điều bạn không ngờ, hoặc không làm điều bạn đã mong chờ.

Luồng tự cấu hình
  classpath có gì? ──> đọc các file AutoConfiguration.imports ──> kiểm tra điều kiện từng class
  (thư viện bạn           (danh sách ứng viên nằm trong          (có class X? đã có bean Y chưa?
   thêm vào pom.xml)       jar của Spring Boot)                    có property này không?)
                                                                          │
                                                       đúng ──> tạo bean cấu hình sẵn (Tomcat, JSON...)
                                                       sai  ──> bỏ qua

Nếu mình muốn tự cấu hình thì sao, Spring Boot có cản không?

Không cản, và đây là nguyên tắc quan trọng: tự cấu hình luôn "lùi lại" khi bạn tự khai báo cái tương ứng. Phần lớn bean tự cấu hình có điều kiện @ConditionalOnMissingBean, nghĩa là "chỉ tạo nếu chưa có bean loại này". Mình thử với JSON. Mặc định order-api trả JSON gọn một dòng. Mình thêm một lớp cấu hình tự khai báo JsonMapper (đối tượng đổi dữ liệu qua JSON trong Spring Boot 4) có bật in thụt lề, chỉ hoạt động khi chạy với profile tên json-dep:

JsonDepConfig.java
package vn.moc.orderapi;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import tools.jackson.databind.SerializationFeature;
import tools.jackson.databind.json.JsonMapper;

@Configuration
@Profile("json-dep")
public class JsonDepConfig {

    @Bean
    public JsonMapper jsonMapper() {
        return JsonMapper.builder()
                .enable(SerializationFeature.INDENT_OUTPUT)
                .build();
    }
}

Chú thích @Configuration đánh dấu lớp này chứa các khai báo bean, và @Bean trên method nói rằng giá trị method trả về là một bean. Mình sẽ giải thích @Profile ở một phần sau. Với bean này, kết quả của API đổi hình dạng: chạy với --spring.profiles.active=json-dep rồi gọi API giảm giá (mình sẽ viết ở phần dưới) ta thấy JSON xuống dòng, thụt lề. Chạy tiếp với cờ --debug thì báo cáo ghi rõ vì sao:

Báo cáo --debug khi profile json-dep bật
   JacksonAutoConfiguration#jacksonJsonMapper:
      Did not match:
         - @ConditionalOnMissingBean (types: tools.jackson.databind.json.JsonMapper; SearchStrategy: all) found beans of type 'tools.jackson.databind.json.JsonMapper' jsonMapper (OnBeanCondition)

Spring Boot thấy đã có bean jsonMapper của mình, nên bỏ bean jacksonJsonMapper mặc định của nó. Tóm lại, cách làm việc với Spring Boot là: cứ để nó cấu hình mặc định, và chỉ khi mặc định không đúng ý bạn thì khai báo cái của bạn. Mình thấy đây là điểm khác lớn nhất so với việc tự cấu hình mọi thứ bằng tay.

Viết cấu hình vào application.yml như thế nào?

Bài về kiểu dữ liệu đã đặt quy tắc: đơn từ 100.000 đồng trở lên được giảm 10%. Nếu quy tắc nằm cứng trong code, mỗi lần quán đổi khuyến mãi phải sửa code và build lại. Mình đưa nó ra file cấu hình. Spring Boot đọc file src/main/resources/application.yml (YAML là định dạng viết dữ liệu theo cấp, thụt đầu dòng để chỉ quan hệ cha con):

src/main/resources/application.yml
spring:
  application:
    name: order-api

server:
  port: 8080

# Quy tắc giảm giá của quán Mộc: đơn từ nguong đồng trở lên giảm phan-tram %.
moc:
  giam-gia:
    nguong: 100000
    phan-tram: 10

Phần spring.application.name và server.port là các thiết lập có sẵn của Spring Boot (cổng 8080 là mặc định, mình ghi ra cho rõ). Phần moc.giam-gia là thiết lập của riêng mình. Để dùng nó trong code, mình gom nó vào một đối tượng có kiểu bằng @ConfigurationProperties:

MocProperties.java
package vn.moc.orderapi;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "moc")
public record MocProperties(GiamGia giamGia) {

    public record GiamGia(long nguong, int phanTram) {
    }
}

prefix = "moc" nói rằng mọi thiết lập bắt đầu bằng moc. được đổ vào đối tượng này. Tên giam-gia trong file YAML tự khớp với giamGia trong code, vì Spring Boot chấp nhận nhiều kiểu viết tên (gọi là relaxed binding), và phan-tram khớp phanTram. Mình thêm @ConfigurationPropertiesScan lên class OrderApiApplication để Spring tự tìm các lớp loại này. Tiếp theo là service tính giảm giá. Nó nhận MocProperties qua constructor (đúng DI của bài trước), nên không còn con số cứng nào trong code:

GiamGiaService.java
package vn.moc.orderapi;

import org.springframework.stereotype.Service;

@Service
public class GiamGiaService {

    private final MocProperties.GiamGia quyTac;

    public GiamGiaService(MocProperties properties) {
        this.quyTac = properties.giamGia();
    }

    // Đơn từ ngưỡng trở lên được giảm phanTram %; phần lẻ dưới 1 đồng bị cắt xuống.
    public long tinhGiamGia(long tongTien) {
        if (tongTien >= quyTac.nguong()) {
            return tongTien * quyTac.phanTram() / 100;
        }
        return 0;
    }

    public MocProperties.GiamGia quyTac() {
        return quyTac;
    }
}

Cuối cùng, một endpoint để thử. GET /giam-gia?tong=170000 nhận tổng tiền và trả về tiền giảm theo quy tắc đang cấu hình, kèm chính quy tắc đó để bạn thấy nó đang chạy với giá trị nào:

GiamGiaController.java
package vn.moc.orderapi;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GiamGiaController {

    public record KetQua(long tong, long giam, long phaiTra, long nguong, int phanTram) {
    }

    private final GiamGiaService service;

    public GiamGiaController(GiamGiaService service) {
        this.service = service;
    }

    @GetMapping("/giam-gia")
    public KetQua tinh(@RequestParam long tong) {
        long giam = service.tinhGiamGia(tong);
        return new KetQua(tong, giam, tong - giam, service.quyTac().nguong(), service.quyTac().phanTram());
    }
}
Chạy
mvn package
java -Dstdout.encoding=UTF-8 -jar target/order-api-0.0.1-SNAPSHOT.jar
curl "http://localhost:8080/giam-gia?tong=170000"
curl "http://localhost:8080/giam-gia?tong=99999"
Kết quả
{"tong":170000,"giam":17000,"phaiTra":153000,"nguong":100000,"phanTram":10}
{"tong":99999,"giam":0,"phaiTra":99999,"nguong":100000,"phanTram":10}

Đơn 170.000 đồng được giảm 17.000 (trả 153.000, đúng con số ở bài về debug), còn đơn 99.999 đồng chưa đủ ngưỡng nên không giảm. Trường nguong và phanTram ở cuối là giá trị đọc từ application.yml.

Profile giúp dùng cấu hình khác nhau cho từng môi trường thế nào?

Máy bạn khi đang viết code (dev) và máy chủ chạy thật (prod) cần những giá trị khác nhau: cổng, mức log, thậm chí khuyến mãi để thử. Profile là cách Spring Boot gom các thiết lập đó theo tên môi trường. Bạn tạo thêm file application-{tên}.yml, và nó chỉ được nạp khi profile ấy bật. Mình tạo hai file, và mỗi file chỉ ghi các khóa muốn đổi:

src/main/resources/application-dev.yml
# Profile "dev": bật khi chạy với --spring.profiles.active=dev
server:
  port: 8081

moc:
  giam-gia:
    phan-tram: 15   # khuyến mãi thử trên máy dev
src/main/resources/application-prod.yml
# Profile "prod": bật khi chạy với --spring.profiles.active=prod
server:
  port: 80

logging:
  level:
    root: WARN

Bật profile bằng tham số --spring.profiles.active. Spring Boot đọc application.yml trước, rồi chồng file của profile lên, nên dev chỉ cần ghi chỗ khác biệt: nguong vẫn là 100000 mà không phải khai báo lại.

Chạy
java -Dstdout.encoding=UTF-8 -jar target/order-api-0.0.1-SNAPSHOT.jar --spring.profiles.active=dev
curl "http://localhost:8081/giam-gia?tong=170000"
Kết quả
{"tong":170000,"giam":25500,"phaiTra":144500,"nguong":100000,"phanTram":15}

Cổng là 8081 và mức giảm là 15% (25.500 đồng), đúng như application-dev.yml. Dòng log đầu cũng ghi The following 1 profile is active: "dev". Với profile prod, cổng 80 và log chỉ còn mức cảnh báo trở lên, nhưng mình không chạy nó trên máy này để khỏi chiếm cổng 80. Nếu bạn không chọn profile nào, Spring Boot chạy với profile default và chỉ dùng application.yml. Chi tiết ở phần profile của tài liệu Spring Boot.

Khi một giá trị khai báo ở nhiều nơi, cái nào thắng?

Đây là chỗ nhiều người mới mất cả buổi chiều. Spring Boot đọc cấu hình từ nhiều nguồn và có thứ tự ưu tiên. Theo tài liệu về cấu hình ngoài, các nguồn mà bài này dùng xếp từ mạnh tới yếu như sau:

  1. Tham số dòng lệnh, ví dụ --moc.giam-gia.phan-tram=25.
  2. Biến môi trường của hệ điều hành.
  3. File application-{profile}.yml đóng gói trong jar.
  4. File application.yml đóng gói trong jar.

Mình kiểm chứng bằng cách chạy chồng nhiều tầng. Biến môi trường MOC_GIAMGIA_PHANTRAM ứng với khóa moc.giam-gia.phan-tram (Spring Boot đổi dấu chấm và gạch nối thành gạch dưới, viết hoa). Mình đổi thêm cổng bằng tham số để khỏi trùng với lần chạy trước:

Chạy: profile dev (15%) cộng thêm biến môi trường (20%)
MOC_GIAMGIA_PHANTRAM=20 java -Dstdout.encoding=UTF-8 -jar target/order-api-0.0.1-SNAPSHOT.jar --spring.profiles.active=dev --server.port=8082
curl "http://localhost:8082/giam-gia?tong=170000"
Kết quả
{"tong":170000,"giam":34000,"phaiTra":136000,"nguong":100000,"phanTram":20}
Chạy: thêm tham số dòng lệnh (25%)
MOC_GIAMGIA_PHANTRAM=20 java -Dstdout.encoding=UTF-8 -jar target/order-api-0.0.1-SNAPSHOT.jar --spring.profiles.active=dev --server.port=8083 --moc.giam-gia.phan-tram=25
curl "http://localhost:8083/giam-gia?tong=170000"
Kết quả
{"tong":170000,"giam":42500,"phaiTra":127500,"nguong":100000,"phanTram":25}

Cùng một khóa với bốn giá trị (10 trong application.yml, 15 trong profile dev, 20 trong biến môi trường, 25 trong tham số), và kết quả ra 20 rồi 25: tầng mạnh hơn thắng. Điều này hữu ích về sau, khi bạn đưa ứng dụng lên máy chủ: bạn build một file jar duy nhất, rồi đổi cấu hình cho từng môi trường bằng biến môi trường, không phải build lại. Thông tin nhạy cảm như mật khẩu database cũng nên đi theo đường biến môi trường, không ghi vào file trong code.

Lỗi cấu hình nào hay gặp?

Hai lỗi mình gặp nhiều nhất khi làm với application.yml đều có thể tái hiện nhanh. Lỗi đầu tiên là viết sai tên khóa mà Spring Boot không báo gì. Mình chạy với một khóa gõ nhầm: --moc.giam-gia.nguon=50000, định đổi ngưỡng thành 50.000 nhưng thiếu chữ g ở nguong:

Chạy
java -Dstdout.encoding=UTF-8 -jar target/order-api-0.0.1-SNAPSHOT.jar --server.port=8084 --moc.giam-gia.nguon=50000
curl "http://localhost:8084/giam-gia?tong=60000"
Kết quả
{"tong":60000,"giam":0,"phaiTra":60000,"nguong":100000,"phanTram":10}

Ứng dụng chạy bình thường, nhưng ngưỡng vẫn là 100.000 và đơn 60.000 không được giảm, vì Spring Boot mặc định bỏ qua khóa nó không biết. Không có lỗi hay cảnh báo nào. Khi một cấu hình "không có tác dụng", hãy so từng chữ tên khóa trước, rồi nhìn vào chính đối tượng cấu hình (như trường nguong trong kết quả trên) để xem giá trị thật. Công cụ như IDE hay spring-boot-configuration-processor giúp gợi ý tên khóa, còn việc kiểm tra giá trị bắt buộc sẽ nói ở bài về validation.

Lỗi thứ hai là thụt đầu dòng sai trong YAML. Mình thử application.yml mà nguong thụt lề 3 dấu cách, còn phan-tram thụt 4:

application.yml bị lệch lề (đặt ở config/application.yml để thử)
moc:
  giam-gia:
   nguong: 100000
    phan-tram: 10
Kết quả khi chạy
ERROR org.springframework.boot.SpringApplication -- Application run failed
mapping values are not allowed here
 in 'reader', line 4, column 14:
        phan-tram: 10
                 ^

Lần này ứng dụng không chạy lên và chỉ đúng dòng 4. Mình xếp lỗi này vào nhóm dễ chịu, vì nó hỏng ngay và nói rõ chỗ hỏng; lỗi gõ sai khóa mới là loại nguy hiểm. YAML thụt lề bằng dấu cách, nên hãy cấu hình editor chèn dấu cách khi bạn bấm Tab.

Hỏi phỏng vấn thế nào?

Ở mức Spring Boot cơ bản, người phỏng vấn thường hỏi: "Auto-configuration hoạt động thế nào?", "@SpringBootApplication gồm những gì?", "Profile dùng để làm gì?". Một câu trả lời đáng nhớ nối ba ý của bài: chú thích gồm ba phần trong đó có @EnableAutoConfiguration; auto-configuration đọc danh sách ứng viên và kiểm tra điều kiện như @ConditionalOnClass và @ConditionalOnMissingBean; còn bạn muốn đổi thì khai báo bean của mình hoặc đổi property. Nếu bạn nhắc được cờ --debug để xem báo cáo và thứ tự ưu tiên giữa tham số, biến môi trường và file, bạn cho họ thấy bạn đã dùng thật. Bạn có thể xem thêm ở mục phỏng vấn.

Bước tiếp theo là gì?

Giờ order-api có cấu hình rõ ràng và chạy được trên nhiều môi trường. Mình vẫn còn một điều chưa kể: khi bạn gõ curl localhost:8080/menu/3, request đi từ Tomcat tới method get của MenuController bằng cách nào? Ai đổi số 3 trong đường dẫn thành tham số id, ai đổi đối tượng trả về thành JSON, và nếu bạn muốn chen vào giữa, ví dụ để ghi log mọi request, thì chen ở đâu? Đó là hành trình của một request qua DispatcherServlet, nội dung bài kế tiếp trong series Học Spring Boot: xây API đặt hàng từ con số 0.

Nhận bài tiếp theo qua email.

Một email mỗi tuần, chỉ khi có điều đáng đọc. Không spam.