境與安全加密)
接手過不少Spring Boot項(xiàng)目也幫別人查過不少“本地好好的一到服務(wù)器就掛”的問題十次里有八次是配置文件在作祟。application.yml這個(gè)文件看起來就是幾十行key-value,實(shí)際上暗含了Spring Boot的整套配置加載機(jī)制、屬性綁定規(guī)則、多環(huán)境適配邏輯。哪怕你對(duì)Java語法再熟搞不懂它的運(yùn)行原理項(xiàng)目一復(fù)雜照樣被配置玩得團(tuán)團(tuán)轉(zhuǎn)。這篇內(nèi)容從YAML語法、配置優(yōu)先級(jí)、多環(huán)境Profile、自定義配置綁定到敏感信息加密和問題排查一條線全拆開講明白。不管是剛?cè)腴TSpring Boot的新手還是寫了幾年還在靠“復(fù)制粘貼配置”度日的開發(fā)者都能在這里找到可以直接落地到代碼里的東西。1. application.yml核心語法與Spring Boot的配置讀取邏輯1.1 YAML語法速覽縮進(jìn)、數(shù)組、特殊字符的坑YAML的全稱是“YAML Aint Markup Language”翻譯過來就是“YAML不是標(biāo)記語言”。它用縮進(jìn)和換行表示層級(jí)關(guān)系不喜歡花括號(hào)和尖括號(hào)好處是看起來干凈壞處是——它對(duì)縮進(jìn)極其敏感。Spring Boot選擇YAML作為默認(rèn)配置格式不是沒有道理的。跟JSON相比YAML寫起來沒有大括號(hào)、沒有引號(hào)滿天飛跟properties相比YAML天然支持層級(jí)結(jié)構(gòu)不用寫多段重復(fù)前綴。比如同樣表達(dá)一個(gè)數(shù)據(jù)源配置# application.yml寫法 spring: datasource: url: jdbc:mysql://localhost:3306/demo username: root password: 123456而用properties格式就要寫成spring.datasource.urljdbc:mysql://localhost:3306/demo spring.datasource.usernameroot spring.datasource.password123456層級(jí)一多properties這種平鋪格式的可讀性明顯下降。所以新生代項(xiàng)目基本都轉(zhuǎn)向了YAML。YAML里最容易踩的坑有三個(gè)。第一個(gè)是不能用Tab縮進(jìn)編輯器如果默認(rèn)把Tab鍵轉(zhuǎn)成空格就沒事如果混用了Tab和空格啟動(dòng)時(shí)大概率直接報(bào)while scanning for the next token這類解析錯(cuò)誤。第二個(gè)是冒號(hào)后面必須跟一個(gè)空格server:port: 8080這種寫法看起來沒錯(cuò)實(shí)際上冒號(hào)后面沒空格會(huì)導(dǎo)致整個(gè)配置解析失敗。第三個(gè)是某些值需要加引號(hào)比如包含特殊字符#、*、的值或者以數(shù)字開頭但語義上應(yīng)該是字符串的值。# 下面這種寫法極其陰間等你排查半天才發(fā)現(xiàn)是引號(hào)問題 app: name: demo#2.0 # #號(hào)被當(dāng)成注釋開始符實(shí)際值是demo desc: 深圳:南山 # 冒號(hào)沒加引號(hào)有些YAML解析器會(huì)直接報(bào)錯(cuò)正確的寫法是給可能出問題的值加上單引號(hào)或雙引號(hào)app: name: demo#2.0 desc: 深圳:南山實(shí)操中我建議凡是值里帶了:、#、*、{、}這些特殊字符一律加引號(hào)凡是純數(shù)字但希望被當(dāng)成字符串處理的也建議加引號(hào)。這個(gè)習(xí)慣能幫你省下大量排查語法問題的時(shí)間。還有一點(diǎn)有些人會(huì)問bootstrap.yml和application.yml的區(qū)別。簡(jiǎn)單說bootstrap.yml是Spring Cloud環(huán)境下用來做配置上下文初始化的加載優(yōu)先級(jí)比application.yml高沒有引入Spring Cloud組件的話只用application.yml就夠了。別一上來兩個(gè)文件各寫一遍弄出配置互相覆蓋的詭異問題。1.2 配置讀取的核心機(jī)制Environment與PropertySourceSpring Boot讀取配置不是直接把YAML文件里的內(nèi)容塞給代碼而是有一套統(tǒng)一抽象層叫Environment。Environment對(duì)象是整個(gè)Spring容器配置數(shù)據(jù)的“總倉庫”。它內(nèi)部維護(hù)了一個(gè)有序的PropertySource列表每個(gè)PropertySource代表一個(gè)配置來源。配置來源有優(yōu)先級(jí)之分高優(yōu)先級(jí)的來源會(huì)覆蓋低優(yōu)先級(jí)來源里的同名屬性。當(dāng)你在代碼里用Value(${server.port})取配置時(shí)Spring實(shí)際上做的事是從Environment里遍歷所有PropertySource找到第一個(gè)包含server.port這個(gè)key的來源然后把值返回給你。如果所有來源都找不到這個(gè)key就會(huì)在啟動(dòng)時(shí)拋IllegalArgumentException除非你寫了默認(rèn)值${server.port:8080}。application.yml被框架加載后的存放位置相當(dāng)于一個(gè)名為ConfigResourceApplicationListener注冊(cè)的低優(yōu)先級(jí)PropertySource。而更高優(yōu)先級(jí)的來源比如命令行參數(shù)、操作系統(tǒng)環(huán)境變量、JVM系統(tǒng)屬性都可能覆蓋application.yml里的同名配置。這個(gè)機(jī)制理解透了之后很多“配置不生效”的問題可以直接推理出原因。比如你在application.yml里寫了server.port: 8081但啟動(dòng)時(shí)用java -jar app.jar --server.port9090傳入命令行參數(shù)那么最終生效的是9090因?yàn)槊钚袇?shù)的優(yōu)先級(jí)高于配置文件。YAML文件被加載的時(shí)候Spring Boot使用SnakeYAML庫完成解析把YAML轉(zhuǎn)成Map結(jié)構(gòu)。application.yml里如果寫了多個(gè)---分隔的文檔塊YAML多文檔特性Spring Boot會(huì)特殊處理每個(gè)文檔塊會(huì)被合并在同一個(gè)Map里通常不適合用來表達(dá)不同環(huán)境配置而是配合Profile來用。2. 配置優(yōu)先級(jí)與多環(huán)境Profile讓測(cè)試、生產(chǎn)環(huán)境各走各的路2.1 配置優(yōu)先級(jí)從高到低一張表說清楚Spring Boot官方文檔里列出了一長串配置來源和它們之間的優(yōu)先級(jí)順序。我按開發(fā)中最常碰到的幾個(gè)整理成表優(yōu)先級(jí)配置來源舉例使用場(chǎng)景最高命令行參數(shù)--server.port8081容器部署時(shí)指定端口高JVM系統(tǒng)屬性-Dserver.port8081啟動(dòng)腳本中動(dòng)態(tài)傳入高操作系統(tǒng)環(huán)境變量SERVER_PORT8081命名規(guī)則不同Docker/K8s環(huán)境中application-{profile}.yml多環(huán)境配置文件按環(huán)境切換配置低application.yml默認(rèn)配置所有環(huán)境共享的默認(rèn)值更低application.properties若同時(shí)存在兼容需求老項(xiàng)目遷移優(yōu)先級(jí)高的來源會(huì)覆蓋優(yōu)先級(jí)低的。舉例application.yml里server.port配置了8080application-prod.yml里配置了8081啟動(dòng)時(shí)指定--spring.profiles.activeprod那么最終端口是8081因?yàn)镻rofile配置優(yōu)先級(jí)高于默認(rèn)配置。命令行參數(shù)優(yōu)先級(jí)最高這個(gè)特性在生產(chǎn)環(huán)境部署中很實(shí)用。同一個(gè)Jar包測(cè)試環(huán)境啟動(dòng)時(shí)傳--spring.profiles.activetest生產(chǎn)環(huán)境傳--spring.profiles.activeprod完全不需要改包里的配置文件。環(huán)境變量的優(yōu)先級(jí)也很值得留意。Spring Boot會(huì)把環(huán)境變量做“松散綁定”的轉(zhuǎn)換比如環(huán)境變量SERVER_PORT會(huì)被映射到配置項(xiàng)的server.port。所以你在云平臺(tái)控制臺(tái)配置環(huán)境變量時(shí)不需要管Spring Boot的內(nèi)部屬性名只要用全大寫下劃線格式就行。2.2 多環(huán)境Profile實(shí)戰(zhàn)dev、test、prod配置分離多環(huán)境配置的核心思路是把不同環(huán)境差異化的配置放在各自的Profile文件里通用的配置放在application.yml里。最常規(guī)的做法是維護(hù)以下文件結(jié)構(gòu)src/main/resources/ ├── application.yml # 公共配置 默認(rèn)Profile ├── application-dev.yml # 開發(fā)環(huán)境 ├── application-test.yml # 測(cè)試環(huán)境 └── application-prod.yml # 生產(chǎn)環(huán)境application.yml里通過spring.profiles.active指定激活哪個(gè)Profile也可以留空交由啟動(dòng)命令決定# application.yml 公共部分 server: port: 8080 spring: profiles: active: dev然后application-dev.yml里寫開發(fā)環(huán)境的數(shù)據(jù)庫、日志級(jí)別等# application-dev.yml spring: datasource: url: jdbc:mysql://localhost:3306/demo username: root password: root logging: level: com.example.demo: DEBUGapplication-prod.yml寫生產(chǎn)環(huán)境配置數(shù)據(jù)庫密碼建議用環(huán)境變量占位# application-prod.yml spring: datasource: url: jdbc:mysql://${DB_HOST}:${DB_PORT}/demo username: ${DB_USER} password: ${DB_PASSWORD} logging: level: com.example.demo: WARN這里用到${DB_HOST}這種占位符格式Spring Boot會(huì)從環(huán)境變量、系統(tǒng)屬性等來源查找對(duì)應(yīng)值。找不到時(shí)啟動(dòng)就會(huì)報(bào)錯(cuò)這其實(shí)是一種“fail fast”機(jī)制攔住了配置缺失問題。Spring Boot 2.4之后出現(xiàn)了一個(gè)變化spring.profiles.active依然可用但推薦用spring.config.activate.on-profile來定義Profile條件配置塊。比如在一個(gè)文件里寫多套配置# application.yml server: port: 8080 --- spring: config: activate: on-profile: dev server: port: 8081 --- spring: config: activate: on-profile: prod server: port: 8082這個(gè)寫法的好處是一個(gè)文件內(nèi)用---分隔多個(gè)文檔塊每個(gè)塊指定激活條件。不過實(shí)測(cè)體驗(yàn)下來如果項(xiàng)目環(huán)境差異比較大還是拆成多個(gè)文件更好維護(hù)。單文件多文檔塊適合配置差異很小的場(chǎng)景。激活Profile還有幾種方式啟動(dòng)命令后加--spring.profiles.activeprod、環(huán)境變量SPRING_PROFILES_ACTIVEprod、以及ActiveProfiles(test)注解用于測(cè)試類中。另外我還踩過一個(gè)坑application.yml里如果已經(jīng)寫了spring.profiles.active: dev到生產(chǎn)環(huán)境忘了覆蓋這個(gè)值就會(huì)帶著dev配置上線。正確做法是公共application.yml里不要寫死激活哪個(gè)Profile保持留空讓部署平臺(tái)通過環(huán)境變量或啟動(dòng)參數(shù)來指定。這個(gè)經(jīng)驗(yàn)很重要。2.3 外置配置文件不要在服務(wù)器上改Jar包里的配置有這樣一個(gè)場(chǎng)景測(cè)試環(huán)境聯(lián)調(diào)時(shí)數(shù)據(jù)庫地址經(jīng)常變每次都要重新打包發(fā)布非常麻煩。合理的做法是把配置文件外置Spring Boot會(huì)直接讀取Jar包同級(jí)目錄下的application.yml或config子目錄下的配置文件并且外部文件的優(yōu)先級(jí)高于Jar包內(nèi)的配置文件。實(shí)際部署時(shí)最簡(jiǎn)單的方式就是Jar包同級(jí)放一個(gè)config/application.yml# 目錄結(jié)構(gòu) /opt/app/ ├── app.jar └── config/ └── application.yml啟動(dòng)時(shí)Spring Boot自動(dòng)加載外部配置。這樣修改配置只需要改服務(wù)器上的文件再重啟服務(wù)不需要重新構(gòu)建Jar包。還可以通過--spring.config.location顯式指定配置文件路徑j(luò)ava -jar app.jar --spring.config.location/opt/config/application.ymlspring.config.location是比較冷門但很重要的一個(gè)參數(shù)多環(huán)境部署時(shí)強(qiáng)烈建議使用而不是每次重新打包。要注意多個(gè)位置的配置文件同時(shí)存在時(shí)Spring Boot會(huì)把它們合并不是簡(jiǎn)單覆蓋。相同屬性名時(shí)后加載的覆蓋先加載的具體優(yōu)先級(jí)順序是config/子目錄下的文件最優(yōu)先然后依次是Jar包當(dāng)前目錄、classpath下的/config/、classpath根目錄。3. 自定義配置綁定從Value到ConfigurationProperties3.1 Value的適用場(chǎng)景與局限開發(fā)中需要自己定義的業(yè)務(wù)配置最常見的接收方式有兩種Value和ConfigurationProperties。Value用起來確實(shí)簡(jiǎn)單Component public class AppInfo { Value(${app.name}) private String name; Value(${app.version}) private String version; }簡(jiǎn)單的單值注入Value很順手。但項(xiàng)目配置一多它的缺點(diǎn)就暴露了每個(gè)字段都要寫一個(gè)注解代碼里散布著各種${...}字符串那感覺就像到處粘貼便簽而且沒有類型安全Value(${app.enable:true})拿到的值如果被錯(cuò)誤配置成字符串truee運(yùn)行時(shí)才會(huì)報(bào)錯(cuò)。更麻煩的是Value對(duì)嵌套對(duì)象和集合的支持非常差。你總不能寫Value(${app.servers[0].ip})去逐個(gè)取每個(gè)服務(wù)器節(jié)點(diǎn)吧這樣代碼根本沒法維護(hù)。3.2 ConfigurationProperties完整方案類型安全配置綁定要說Spring Boot推薦的配置綁定方式非ConfigurationProperties莫屬。它能把整個(gè)配置前綴下的一組屬性自動(dòng)映射到一個(gè)Java對(duì)象的所有字段上。先看YAML配置app: name: demo-app version: 1.2.0 admin-email: opsexample.com再看Java類Component ConfigurationProperties(prefix app) public class AppProperties { private String name; private String version; private String adminEmail; // 必須提供getter/setter或者用Java記錄(record) }Spring Boot會(huì)把a(bǔ)pp.name、app.version、app.admin-email分別映射到name、version、adminEmail字段。注意admin-email和adminEmail這種連字符寫法Spring Boot的“寬松綁定”機(jī)制允許kebab-case、camelCase、snake_case各種格式互相轉(zhuǎn)換。這正是Value做不到的它要求Value里的key必須準(zhǔn)確對(duì)應(yīng)配置名而ConfigurationProperties利用寬松綁定容錯(cuò)性高得多尤其適合配置項(xiàng)本身帶連字符的情況。更復(fù)雜的配置結(jié)構(gòu)也能處理。比如配置一個(gè)連接池參數(shù)列表app: pools: - name: writePool max-size: 20 - name: readPool max-size: 30Java端用List接收Data Component ConfigurationProperties(prefix app) public class AppProperties { private ListPoolConfig pools new ArrayList(); Data public static class PoolConfig { private String name; private Integer maxSize; } }這才是真正企業(yè)級(jí)項(xiàng)目的寫法。所有配置項(xiàng)集中管理IDE還能自動(dòng)提示補(bǔ)全。建議配置項(xiàng)超過5個(gè)就開始用ConfigurationProperties而不是幾十個(gè)Value散落各處。如果用Java 17還可以用record來定義不可變配置類省去一堆樣板代碼效果類似。3.3 集合、Map配置與校驗(yàn)綁定細(xì)節(jié)決定成敗集合和Map的綁定有一些隱藏的細(xì)節(jié)不實(shí)測(cè)很容易踩坑。YAML里數(shù)組和Map的表現(xiàn)形式是app: servers: - ip: 192.168.1.1 port: 8080 - ip: 192.168.1.2 port: 8081 headers: X-Request-Id: req-123 X-User-Id: user-456對(duì)應(yīng)Java配置類接收的方式是List和MapData ConfigurationProperties(prefix app) public class AppProperties { private ListServer servers; private MapString, String headers; Data public static class Server { private String ip; private Integer port; } }這里要注意YAML中Map的key如果帶有特殊字符比如X-Request-Id綁定到Map的key時(shí)是原樣保留的不用擔(dān)心-被轉(zhuǎn)成駝峰。但如果是綁定到JavaBean的字段比如字段名是requestId那么在YAML里寫request-id沒問題寫requestId也行因?yàn)閷捤山壎〞?huì)統(tǒng)一處理。配置校驗(yàn)是很多人忽略的部分。ConfigurationProperties配合JSR 303校驗(yàn)注解可以在啟動(dòng)階段直接攔截非法配置而不是等運(yùn)行到某個(gè)業(yè)務(wù)邏輯才報(bào)錯(cuò)。做法是Data Component ConfigurationProperties(prefix app) Validated public class AppProperties { NotBlank(message app.name不能為空) private String name; Pattern(regexp \\d\\.\\d\\.\\d, message 版本號(hào)格式必須為 x.y.z) private String version; }啟動(dòng)時(shí)如果配置不符合規(guī)則應(yīng)用直接啟動(dòng)失敗并且錯(cuò)誤信息里會(huì)明確告訴你是哪個(gè)字段沒過校驗(yàn)。這個(gè)設(shè)計(jì)我覺得相當(dāng)有價(jià)值因?yàn)樗雅渲缅e(cuò)誤攔截在最前面而不是等用戶點(diǎn)了某個(gè)功能才發(fā)現(xiàn)數(shù)據(jù)不對(duì)。還有一個(gè)小細(xì)節(jié)ConfigurationProperties綁定的類建議用DataLombok或手動(dòng)生成getter/setter。不要用Accessors(chain true)過度改造有些版本組合下綁定會(huì)失靈。我自己遇到過一兩次這種詭異問題后來中規(guī)中矩用Data就再也沒出過事。4. 敏感信息與配置安全別把數(shù)據(jù)庫密碼直接提交到Git倉庫4.1 明文配置帶來的風(fēng)險(xiǎn)很多團(tuán)隊(duì)的代碼倉庫里application.yml直接寫著生產(chǎn)數(shù)據(jù)庫的賬號(hào)密碼、第三方API密鑰、短信服務(wù)的AppSecret。這些文件跟著代碼一起進(jìn)了Git倉庫凡是能訪問倉庫的人都能看到。前陣子幫一個(gè)團(tuán)隊(duì)檢查代碼發(fā)現(xiàn)他們把阿里云AccessKey直接寫在application-prod.yml里而那個(gè)倉庫帶著歷史版本一起打成了壓縮包發(fā)給外包同事。密碼一旦泄露對(duì)方的服務(wù)器就被拿去挖礦了。這不是嚇唬人這是真實(shí)發(fā)生過的事情而且復(fù)盤起來基本都有一個(gè)共同點(diǎn)秘密從配置文件里泄露出去的。對(duì)策分三個(gè)層次最小權(quán)限、動(dòng)態(tài)獲取、加密存儲(chǔ)。4.2 環(huán)境變量占位符最輕量的安全手段不改代碼的前提下最直接的做法是把敏感值從YAML里抽出來用環(huán)境變量引用spring: datasource: url: jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME}?useSSLfalsecharacterEncodingutf8 username: ${DB_USERNAME} password: ${DB_PASSWORD}部署平臺(tái)Docker、K8s、云服務(wù)器上通過環(huán)境變量注入YAML文件本身不含敏感信息可以放心提交Git。這套做法的缺點(diǎn)是環(huán)境變量在系統(tǒng)全局可見某些運(yùn)維場(chǎng)景下還是不夠隔離。但比起把密碼明文寫在代碼倉庫里已經(jīng)前進(jìn)了一大步。4.3 Jasypt加密把密碼變成密文放進(jìn)配置文件如果不想把秘密交給環(huán)境變量而希望配置里存的是密文業(yè)界常用方案是用JasyptJava Simplified Encryption。這個(gè)工具的定位很明確給Spring Boot配置里的敏感字段做加密。引入依賴以Maven為例dependency groupIdcom.github.ulisesbocchio/groupId artifactIdjasypt-spring-boot-starter/artifactId version3.0.5/version /dependency生成密文時(shí)可以用Jasypt自帶的工具類import org.jasypt.util.text.BasicTextEncryptor; public class EncryptTest { public static void main(String[] args) { BasicTextEncryptor encryptor new BasicTextEncryptor(); encryptor.setPassword(your-salt); // 鹽值需保密 String encrypted encryptor.encrypt(my-db-password); System.out.println(encrypted); } }把輸出的密文填到配置文件里spring: datasource: password: ENC(加密后的密文)這里ENC(...)是Jasypt約定的密文包裹格式。啟動(dòng)時(shí)Jasypt會(huì)攔截配置解析發(fā)現(xiàn)ENC(前綴后自動(dòng)解密還原。解密所需的鹽值不要寫在配置文件里通過JVM參數(shù)或環(huán)境變量傳入java -jar app.jar --jasypt.encryptor.password${JASYPT_SALT}這個(gè)方案實(shí)踐中有幾個(gè)注意點(diǎn)。鹽值泄露等于密文白搭所以鹽值本身存儲(chǔ)位置要安全。另外Jasypt默認(rèn)使用的算法是PBEWITHMD5ANDDES強(qiáng)度偏弱建議在配置里指定更強(qiáng)的算法jasypt: encryptor: algorithm: PBEWITHHMACSHA512ANDAES_256 iv-generator-classname: org.jasypt.iv.NoIvGenerator這個(gè)算法切換在Jasypt 3.x里是支持的。我實(shí)測(cè)過用默認(rèn)算法加密的密文在部分安全掃描工具里會(huì)被標(biāo)記為弱加密換了AES-256之后才通過檢查。另外要提醒加密不等于絕對(duì)安全。鹽值如果是在命令行里明文傳的進(jìn)程列表里還是能看到過程只是比存文件里稍微隱蔽一點(diǎn)。真正的生產(chǎn)安全還需要配合密鑰管理系統(tǒng)比如云廠商的KMS來做不過那已經(jīng)是另外一個(gè)主題了。5. 常見問題排查與進(jìn)階技巧實(shí)錄5.1 YAML語法報(bào)錯(cuò)先學(xué)會(huì)看錯(cuò)誤信息Spring Boot啟動(dòng)階段如果配置解析失敗控制臺(tái)一般會(huì)給出類似這樣的錯(cuò)誤Caused by: org.yaml.snakeyaml.parser.ParserException: while parsing a block mapping in reader, line 5, column 3: server: ^ expected block end, but found block mapping start這種報(bào)錯(cuò)十有八九是縮進(jìn)不一致。排查方法很機(jī)械把整個(gè)配置文件復(fù)制到支持YAML校驗(yàn)的編輯器IDEA自帶、VS Code裝個(gè)YAML插件它會(huì)直接標(biāo)出具體行和列的錯(cuò)誤位置。不要用肉眼一行行找效率太低。常見的原因還有配置文件里混入了中文全角冒號(hào)而不是半角:值前面多了空格導(dǎo)致被當(dāng)成嵌套文件末尾缺少換行符導(dǎo)致最后一個(gè)屬性解析異常。還有一個(gè)冷門的坑YAML文件里的---多文檔分隔符。如果用到多文檔但某個(gè)文檔塊沒有正確閉合spring.config.activate.on-profile寫錯(cuò)會(huì)導(dǎo)致配置被靜默跳過。啟動(dòng)后沒有報(bào)錯(cuò)但配置就是不生效這種問題最難排查。調(diào)用的方法是用spring-boot-starter-actuator暴露/actuator/env接口實(shí)時(shí)查看當(dāng)前生效的配置項(xiàng)有哪些一目了然。5.2 中文亂碼問題先看文件編碼再看IDE設(shè)置application.yml里寫了中文注釋或中文默認(rèn)值部署到Linux服務(wù)器后亂碼這屬于經(jīng)典問題。排查步驟固定先確認(rèn)文件本身是UTF-8編碼。用IntelliJ IDEA右下角的編碼信息可以查看和轉(zhuǎn)換。然后確認(rèn)打包時(shí)沒有改變編碼Maven項(xiàng)目中pom.xml里建議指明properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties最后確認(rèn)運(yùn)行環(huán)境的file.encoding。啟動(dòng)時(shí)加參數(shù)最穩(wěn)妥java -Dfile.encodingUTF-8 -jar app.jar還有一點(diǎn)很容易被忽略IDEA里文件顯示正常不代表文件就是UTF-8。Windows環(huán)境下IDEA的默認(rèn)文件編碼跟Linux服務(wù)器不一致是家常便飯建議在IDEA的Settings里把項(xiàng)目編碼統(tǒng)一設(shè)置為UTF-8并且勾選“透明存儲(chǔ)native-to-ascii轉(zhuǎn)換”選項(xiàng)來規(guī)避.properties的亂碼問題。YAML文件不存在這個(gè)native-to-ascii機(jī)制所以只要文件本身編碼對(duì)基本不會(huì)亂。5.3 配置不生效三分鐘定位到底是誰覆蓋了誰遇到“配置寫了但沒生效”的問題不要直接改代碼加日志就用Spring Boot提供的現(xiàn)成機(jī)制排查。在application.yml中先開啟management: endpoints: web: exposure: include: env然后啟動(dòng)項(xiàng)目訪問http://localhost:8080/actuator/env。這個(gè)接口返回的信息非常豐富它會(huì)展示當(dāng)前Spring環(huán)境中所有配置項(xiàng)的來源以及最終生效值還會(huì)標(biāo)明每個(gè)值來自哪個(gè)PropertySource。比如你想查server.port是誰決定生效值的打開響應(yīng)后搜索server.port能看到類似這樣的結(jié)構(gòu){ propertySources: [ { name: commandLineArgs, properties: { server.port: { value: 9090 } } }, { name: applicationConfig: [classpath:/application.yml], properties: { server.port: { value: 8080 } } } ] }這時(shí)候誰覆蓋誰一眼就能看出。這個(gè)習(xí)慣養(yǎng)成之后配置排查效率直接質(zhì)的飛躍。還有一個(gè)常見的“不生效”原因ConfigurationProperties類里的字段名拼錯(cuò)了。寬松綁定雖然能轉(zhuǎn)換kebab-case和camelCase但字段名本身拼錯(cuò)是無法映射的且不報(bào)錯(cuò)——字段值就是null。碰到這種情況可以先給配置類打上Validated并加上非空校驗(yàn)啟動(dòng)時(shí)強(qiáng)行檢查綁定的結(jié)果是不是為空。5.4 進(jìn)階技巧隨機(jī)數(shù)、Duration類型、占位符引用配置文件里隱藏著幾個(gè)被低估的特性。第一個(gè)是隨機(jī)值app: token: retry-times: ${random.int(1,10)} id: base: ${random.long}這里${random.int(1,10)}會(huì)在啟動(dòng)時(shí)隨機(jī)生成1到10之間的整數(shù)。這種寫法在模擬重試次數(shù)、測(cè)試數(shù)據(jù)生成的場(chǎng)景中很有用。第二個(gè)是Duration與DataSize類型。Spring Boot的寬松綁定能自動(dòng)把文本格式的時(shí)長轉(zhuǎn)換到j(luò)ava.time.Duration類型spring: task: execution: thread-name-prefix: async- mvc: async: request-timeout: 5s代碼里直接用Duration對(duì)象接收。這個(gè)特性避免了“毫秒和秒之間傻傻分不清”的糾紛配置里寫了多少單位就是多少單位。第三個(gè)是配置項(xiàng)之間的引用。比如同一個(gè)值時(shí)你希望一個(gè)配置繼承另一個(gè)配置中的值app: bizA: topic: topic-user bizB: topic: ${app.bizA.topic}_backup引用別的配置用占位符格式。這種方式比在各處重復(fù)寫值好得多改一處全局生效。但要注意循環(huán)引用A引用B、B引用A啟動(dòng)時(shí)會(huì)報(bào)PlaceholderResolutionException這個(gè)錯(cuò)誤信息很直白按提示改就行。還有個(gè)實(shí)用技巧配置中可以用符號(hào)指定Profile條件化屬性比如spring: config: activate: on-profile: !prod表示該文檔塊在非prod環(huán)境下才激活。這個(gè)語法我在多環(huán)境公共配置抽取時(shí)用得比較多比拆文件更靈活但可讀性稍有下降使用前要跟團(tuán)隊(duì)確認(rèn)編碼規(guī)范。最后再分享一個(gè)配置管理的好習(xí)慣維護(hù)了這么多年項(xiàng)目我體會(huì)最深的是配置文件需要被當(dāng)作代碼一樣嚴(yán)格對(duì)待。寫Java代碼大家會(huì)講究封裝、復(fù)用、單元測(cè)試但一寫配置文件就放飛自我什么硬編碼、魔法值、加密裸奔都出來了。建議團(tuán)隊(duì)里推行配置的Code Review制度單獨(dú)把a(bǔ)pplication.yml及其多環(huán)境變體作為一個(gè)review關(guān)注點(diǎn)。審查標(biāo)準(zhǔn)就三條是否含敏感明文、是否有多環(huán)境差異化配置缺失、是否有未知來源的覆蓋來源。這三條把住了生產(chǎn)事故至少能少一半。另外給項(xiàng)目接入CI/CD的時(shí)候記得在流水線里加一個(gè)步驟做配置校驗(yàn)。用spring-boot-configuration-processor能在編譯期生成配置元數(shù)據(jù)IDEA里寫配置時(shí)有自動(dòng)補(bǔ)全和類型提示用spring-boot-starter-validation能在啟動(dòng)時(shí)攔截非法配置。這兩種手段配合起來配置類的問題在開發(fā)階段就能暴露而不是要等到部署到生產(chǎn)環(huán)境才被發(fā)現(xiàn)。配置管理沒有多么高深的技術(shù)就是把該驗(yàn)證的驗(yàn)證、該加密的加密、該隔離的隔離然后形成習(xí)慣。這套流程跑通之后你會(huì)發(fā)現(xiàn)“配置又出問題了”這個(gè)聲音會(huì)越來越少出現(xiàn)在團(tuán)隊(duì)群里。 Spring Boot配置全解析：從YAML語法到多環(huán)境與安全加密
接手過不少Spring Boot項(xiàng)目也幫別人查過不少“本地好好的一到服務(wù)器就掛”的問題十次里有八次是配置文件在作祟。application.yml這個(gè)文件看起來就是幾十行key-value,實(shí)際上暗含了Spring Boot的整套配置加載機(jī)制、屬性綁定規(guī)則、多環(huán)境適配邏輯。哪怕你對(duì)Java語法再熟搞不懂它的運(yùn)行原理項(xiàng)目一復(fù)雜照樣被配置玩得團(tuán)團(tuán)轉(zhuǎn)。這篇內(nèi)容從YAML語法、配置優(yōu)先級(jí)、多環(huán)境Profile、自定義配置綁定到敏感信息加密和問題排查一條線全拆開講明白。不管是剛?cè)腴TSpring Boot的新手還是寫了幾年還在靠“復(fù)制粘貼配置”度日的開發(fā)者都能在這里找到可以直接落地到代碼里的東西。1. application.yml核心語法與Spring Boot的配置讀取邏輯1.1 YAML語法速覽縮進(jìn)、數(shù)組、特殊字符的坑YAML的全稱是“YAML Aint Markup Language”翻譯過來就是“YAML不是標(biāo)記語言”。它用縮進(jìn)和換行表示層級(jí)關(guān)系不喜歡花括號(hào)和尖括號(hào)好處是看起來干凈壞處是——它對(duì)縮進(jìn)極其敏感。Spring Boot選擇YAML作為默認(rèn)配置格式不是沒有道理的。跟JSON相比YAML寫起來沒有大括號(hào)、沒有引號(hào)滿天飛跟properties相比YAML天然支持層級(jí)結(jié)構(gòu)不用寫多段重復(fù)前綴。比如同樣表達(dá)一個(gè)數(shù)據(jù)源配置# application.yml寫法 spring: datasource: url: jdbc:mysql://localhost:3306/demo username: root password: 123456而用properties格式就要寫成spring.datasource.urljdbc:mysql://localhost:3306/demo spring.datasource.usernameroot spring.datasource.password123456層級(jí)一多properties這種平鋪格式的可讀性明顯下降。所以新生代項(xiàng)目基本都轉(zhuǎn)向了YAML。YAML里最容易踩的坑有三個(gè)。第一個(gè)是不能用Tab縮進(jìn)編輯器如果默認(rèn)把Tab鍵轉(zhuǎn)成空格就沒事如果混用了Tab和空格啟動(dòng)時(shí)大概率直接報(bào)while scanning for the next token這類解析錯(cuò)誤。第二個(gè)是冒號(hào)后面必須跟一個(gè)空格server:port: 8080這種寫法看起來沒錯(cuò)實(shí)際上冒號(hào)后面沒空格會(huì)導(dǎo)致整個(gè)配置解析失敗。第三個(gè)是某些值需要加引號(hào)比如包含特殊字符#、*、的值或者以數(shù)字開頭但語義上應(yīng)該是字符串的值。# 下面這種寫法極其陰間等你排查半天才發(fā)現(xiàn)是引號(hào)問題 app: name: demo#2.0 # #號(hào)被當(dāng)成注釋開始符實(shí)際值是demo desc: 深圳:南山 # 冒號(hào)沒加引號(hào)有些YAML解析器會(huì)直接報(bào)錯(cuò)正確的寫法是給可能出問題的值加上單引號(hào)或雙引號(hào)app: name: demo#2.0 desc: 深圳:南山實(shí)操中我建議凡是值里帶了:、#、*、{、}這些特殊字符一律加引號(hào)凡是純數(shù)字但希望被當(dāng)成字符串處理的也建議加引號(hào)。這個(gè)習(xí)慣能幫你省下大量排查語法問題的時(shí)間。還有一點(diǎn)有些人會(huì)問bootstrap.yml和application.yml的區(qū)別。簡(jiǎn)單說bootstrap.yml是Spring Cloud環(huán)境下用來做配置上下文初始化的加載優(yōu)先級(jí)比application.yml高沒有引入Spring Cloud組件的話只用application.yml就夠了。別一上來兩個(gè)文件各寫一遍弄出配置互相覆蓋的詭異問題。1.2 配置讀取的核心機(jī)制Environment與PropertySourceSpring Boot讀取配置不是直接把YAML文件里的內(nèi)容塞給代碼而是有一套統(tǒng)一抽象層叫Environment。Environment對(duì)象是整個(gè)Spring容器配置數(shù)據(jù)的“總倉庫”。它內(nèi)部維護(hù)了一個(gè)有序的PropertySource列表每個(gè)PropertySource代表一個(gè)配置來源。配置來源有優(yōu)先級(jí)之分高優(yōu)先級(jí)的來源會(huì)覆蓋低優(yōu)先級(jí)來源里的同名屬性。當(dāng)你在代碼里用Value(${server.port})取配置時(shí)Spring實(shí)際上做的事是從Environment里遍歷所有PropertySource找到第一個(gè)包含server.port這個(gè)key的來源然后把值返回給你。如果所有來源都找不到這個(gè)key就會(huì)在啟動(dòng)時(shí)拋IllegalArgumentException除非你寫了默認(rèn)值${server.port:8080}。application.yml被框架加載后的存放位置相當(dāng)于一個(gè)名為ConfigResourceApplicationListener注冊(cè)的低優(yōu)先級(jí)PropertySource。而更高優(yōu)先級(jí)的來源比如命令行參數(shù)、操作系統(tǒng)環(huán)境變量、JVM系統(tǒng)屬性都可能覆蓋application.yml里的同名配置。這個(gè)機(jī)制理解透了之后很多“配置不生效”的問題可以直接推理出原因。比如你在application.yml里寫了server.port: 8081但啟動(dòng)時(shí)用java -jar app.jar --server.port9090傳入命令行參數(shù)那么最終生效的是9090因?yàn)槊钚袇?shù)的優(yōu)先級(jí)高于配置文件。YAML文件被加載的時(shí)候Spring Boot使用SnakeYAML庫完成解析把YAML轉(zhuǎn)成Map結(jié)構(gòu)。application.yml里如果寫了多個(gè)---分隔的文檔塊YAML多文檔特性Spring Boot會(huì)特殊處理每個(gè)文檔塊會(huì)被合并在同一個(gè)Map里通常不適合用來表達(dá)不同環(huán)境配置而是配合Profile來用。2. 配置優(yōu)先級(jí)與多環(huán)境Profile讓測(cè)試、生產(chǎn)環(huán)境各走各的路2.1 配置優(yōu)先級(jí)從高到低一張表說清楚Spring Boot官方文檔里列出了一長串配置來源和它們之間的優(yōu)先級(jí)順序。我按開發(fā)中最常碰到的幾個(gè)整理成表優(yōu)先級(jí)配置來源舉例使用場(chǎng)景最高命令行參數(shù)--server.port8081容器部署時(shí)指定端口高JVM系統(tǒng)屬性-Dserver.port8081啟動(dòng)腳本中動(dòng)態(tài)傳入高操作系統(tǒng)環(huán)境變量SERVER_PORT8081命名規(guī)則不同Docker/K8s環(huán)境中application-{profile}.yml多環(huán)境配置文件按環(huán)境切換配置低application.yml默認(rèn)配置所有環(huán)境共享的默認(rèn)值更低application.properties若同時(shí)存在兼容需求老項(xiàng)目遷移優(yōu)先級(jí)高的來源會(huì)覆蓋優(yōu)先級(jí)低的。舉例application.yml里server.port配置了8080application-prod.yml里配置了8081啟動(dòng)時(shí)指定--spring.profiles.activeprod那么最終端口是8081因?yàn)镻rofile配置優(yōu)先級(jí)高于默認(rèn)配置。命令行參數(shù)優(yōu)先級(jí)最高這個(gè)特性在生產(chǎn)環(huán)境部署中很實(shí)用。同一個(gè)Jar包測(cè)試環(huán)境啟動(dòng)時(shí)傳--spring.profiles.activetest生產(chǎn)環(huán)境傳--spring.profiles.activeprod完全不需要改包里的配置文件。環(huán)境變量的優(yōu)先級(jí)也很值得留意。Spring Boot會(huì)把環(huán)境變量做“松散綁定”的轉(zhuǎn)換比如環(huán)境變量SERVER_PORT會(huì)被映射到配置項(xiàng)的server.port。所以你在云平臺(tái)控制臺(tái)配置環(huán)境變量時(shí)不需要管Spring Boot的內(nèi)部屬性名只要用全大寫下劃線格式就行。2.2 多環(huán)境Profile實(shí)戰(zhàn)dev、test、prod配置分離多環(huán)境配置的核心思路是把不同環(huán)境差異化的配置放在各自的Profile文件里通用的配置放在application.yml里。最常規(guī)的做法是維護(hù)以下文件結(jié)構(gòu)src/main/resources/ ├── application.yml # 公共配置 默認(rèn)Profile ├── application-dev.yml # 開發(fā)環(huán)境 ├── application-test.yml # 測(cè)試環(huán)境 └── application-prod.yml # 生產(chǎn)環(huán)境application.yml里通過spring.profiles.active指定激活哪個(gè)Profile也可以留空交由啟動(dòng)命令決定# application.yml 公共部分 server: port: 8080 spring: profiles: active: dev然后application-dev.yml里寫開發(fā)環(huán)境的數(shù)據(jù)庫、日志級(jí)別等# application-dev.yml spring: datasource: url: jdbc:mysql://localhost:3306/demo username: root password: root logging: level: com.example.demo: DEBUGapplication-prod.yml寫生產(chǎn)環(huán)境配置數(shù)據(jù)庫密碼建議用環(huán)境變量占位# application-prod.yml spring: datasource: url: jdbc:mysql://${DB_HOST}:${DB_PORT}/demo username: ${DB_USER} password: ${DB_PASSWORD} logging: level: com.example.demo: WARN這里用到${DB_HOST}這種占位符格式Spring Boot會(huì)從環(huán)境變量、系統(tǒng)屬性等來源查找對(duì)應(yīng)值。找不到時(shí)啟動(dòng)就會(huì)報(bào)錯(cuò)這其實(shí)是一種“fail fast”機(jī)制攔住了配置缺失問題。Spring Boot 2.4之后出現(xiàn)了一個(gè)變化spring.profiles.active依然可用但推薦用spring.config.activate.on-profile來定義Profile條件配置塊。比如在一個(gè)文件里寫多套配置# application.yml server: port: 8080 --- spring: config: activate: on-profile: dev server: port: 8081 --- spring: config: activate: on-profile: prod server: port: 8082這個(gè)寫法的好處是一個(gè)文件內(nèi)用---分隔多個(gè)文檔塊每個(gè)塊指定激活條件。不過實(shí)測(cè)體驗(yàn)下來如果項(xiàng)目環(huán)境差異比較大還是拆成多個(gè)文件更好維護(hù)。單文件多文檔塊適合配置差異很小的場(chǎng)景。激活Profile還有幾種方式啟動(dòng)命令后加--spring.profiles.activeprod、環(huán)境變量SPRING_PROFILES_ACTIVEprod、以及ActiveProfiles(test)注解用于測(cè)試類中。另外我還踩過一個(gè)坑application.yml里如果已經(jīng)寫了spring.profiles.active: dev到生產(chǎn)環(huán)境忘了覆蓋這個(gè)值就會(huì)帶著dev配置上線。正確做法是公共application.yml里不要寫死激活哪個(gè)Profile保持留空讓部署平臺(tái)通過環(huán)境變量或啟動(dòng)參數(shù)來指定。這個(gè)經(jīng)驗(yàn)很重要。2.3 外置配置文件不要在服務(wù)器上改Jar包里的配置有這樣一個(gè)場(chǎng)景測(cè)試環(huán)境聯(lián)調(diào)時(shí)數(shù)據(jù)庫地址經(jīng)常變每次都要重新打包發(fā)布非常麻煩。合理的做法是把配置文件外置Spring Boot會(huì)直接讀取Jar包同級(jí)目錄下的application.yml或config子目錄下的配置文件并且外部文件的優(yōu)先級(jí)高于Jar包內(nèi)的配置文件。實(shí)際部署時(shí)最簡(jiǎn)單的方式就是Jar包同級(jí)放一個(gè)config/application.yml# 目錄結(jié)構(gòu) /opt/app/ ├── app.jar └── config/ └── application.yml啟動(dòng)時(shí)Spring Boot自動(dòng)加載外部配置。這樣修改配置只需要改服務(wù)器上的文件再重啟服務(wù)不需要重新構(gòu)建Jar包。還可以通過--spring.config.location顯式指定配置文件路徑j(luò)ava -jar app.jar --spring.config.location/opt/config/application.ymlspring.config.location是比較冷門但很重要的一個(gè)參數(shù)多環(huán)境部署時(shí)強(qiáng)烈建議使用而不是每次重新打包。要注意多個(gè)位置的配置文件同時(shí)存在時(shí)Spring Boot會(huì)把它們合并不是簡(jiǎn)單覆蓋。相同屬性名時(shí)后加載的覆蓋先加載的具體優(yōu)先級(jí)順序是config/子目錄下的文件最優(yōu)先然后依次是Jar包當(dāng)前目錄、classpath下的/config/、classpath根目錄。3. 自定義配置綁定從Value到ConfigurationProperties3.1 Value的適用場(chǎng)景與局限開發(fā)中需要自己定義的業(yè)務(wù)配置最常見的接收方式有兩種Value和ConfigurationProperties。Value用起來確實(shí)簡(jiǎn)單Component public class AppInfo { Value(${app.name}) private String name; Value(${app.version}) private String version; }簡(jiǎn)單的單值注入Value很順手。但項(xiàng)目配置一多它的缺點(diǎn)就暴露了每個(gè)字段都要寫一個(gè)注解代碼里散布著各種${...}字符串那感覺就像到處粘貼便簽而且沒有類型安全Value(${app.enable:true})拿到的值如果被錯(cuò)誤配置成字符串truee運(yùn)行時(shí)才會(huì)報(bào)錯(cuò)。更麻煩的是Value對(duì)嵌套對(duì)象和集合的支持非常差。你總不能寫Value(${app.servers[0].ip})去逐個(gè)取每個(gè)服務(wù)器節(jié)點(diǎn)吧這樣代碼根本沒法維護(hù)。3.2 ConfigurationProperties完整方案類型安全配置綁定要說Spring Boot推薦的配置綁定方式非ConfigurationProperties莫屬。它能把整個(gè)配置前綴下的一組屬性自動(dòng)映射到一個(gè)Java對(duì)象的所有字段上。先看YAML配置app: name: demo-app version: 1.2.0 admin-email: opsexample.com再看Java類Component ConfigurationProperties(prefix app) public class AppProperties { private String name; private String version; private String adminEmail; // 必須提供getter/setter或者用Java記錄(record) }Spring Boot會(huì)把a(bǔ)pp.name、app.version、app.admin-email分別映射到name、version、adminEmail字段。注意admin-email和adminEmail這種連字符寫法Spring Boot的“寬松綁定”機(jī)制允許kebab-case、camelCase、snake_case各種格式互相轉(zhuǎn)換。這正是Value做不到的它要求Value里的key必須準(zhǔn)確對(duì)應(yīng)配置名而ConfigurationProperties利用寬松綁定容錯(cuò)性高得多尤其適合配置項(xiàng)本身帶連字符的情況。更復(fù)雜的配置結(jié)構(gòu)也能處理。比如配置一個(gè)連接池參數(shù)列表app: pools: - name: writePool max-size: 20 - name: readPool max-size: 30Java端用List接收Data Component ConfigurationProperties(prefix app) public class AppProperties { private ListPoolConfig pools new ArrayList(); Data public static class PoolConfig { private String name; private Integer maxSize; } }這才是真正企業(yè)級(jí)項(xiàng)目的寫法。所有配置項(xiàng)集中管理IDE還能自動(dòng)提示補(bǔ)全。建議配置項(xiàng)超過5個(gè)就開始用ConfigurationProperties而不是幾十個(gè)Value散落各處。如果用Java 17還可以用record來定義不可變配置類省去一堆樣板代碼效果類似。3.3 集合、Map配置與校驗(yàn)綁定細(xì)節(jié)決定成敗集合和Map的綁定有一些隱藏的細(xì)節(jié)不實(shí)測(cè)很容易踩坑。YAML里數(shù)組和Map的表現(xiàn)形式是app: servers: - ip: 192.168.1.1 port: 8080 - ip: 192.168.1.2 port: 8081 headers: X-Request-Id: req-123 X-User-Id: user-456對(duì)應(yīng)Java配置類接收的方式是List和MapData ConfigurationProperties(prefix app) public class AppProperties { private ListServer servers; private MapString, String headers; Data public static class Server { private String ip; private Integer port; } }這里要注意YAML中Map的key如果帶有特殊字符比如X-Request-Id綁定到Map的key時(shí)是原樣保留的不用擔(dān)心-被轉(zhuǎn)成駝峰。但如果是綁定到JavaBean的字段比如字段名是requestId那么在YAML里寫request-id沒問題寫requestId也行因?yàn)閷捤山壎〞?huì)統(tǒng)一處理。配置校驗(yàn)是很多人忽略的部分。ConfigurationProperties配合JSR 303校驗(yàn)注解可以在啟動(dòng)階段直接攔截非法配置而不是等運(yùn)行到某個(gè)業(yè)務(wù)邏輯才報(bào)錯(cuò)。做法是Data Component ConfigurationProperties(prefix app) Validated public class AppProperties { NotBlank(message app.name不能為空) private String name; Pattern(regexp \\d\\.\\d\\.\\d, message 版本號(hào)格式必須為 x.y.z) private String version; }啟動(dòng)時(shí)如果配置不符合規(guī)則應(yīng)用直接啟動(dòng)失敗并且錯(cuò)誤信息里會(huì)明確告訴你是哪個(gè)字段沒過校驗(yàn)。這個(gè)設(shè)計(jì)我覺得相當(dāng)有價(jià)值因?yàn)樗雅渲缅e(cuò)誤攔截在最前面而不是等用戶點(diǎn)了某個(gè)功能才發(fā)現(xiàn)數(shù)據(jù)不對(duì)。還有一個(gè)小細(xì)節(jié)ConfigurationProperties綁定的類建議用DataLombok或手動(dòng)生成getter/setter。不要用Accessors(chain true)過度改造有些版本組合下綁定會(huì)失靈。我自己遇到過一兩次這種詭異問題后來中規(guī)中矩用Data就再也沒出過事。4. 敏感信息與配置安全別把數(shù)據(jù)庫密碼直接提交到Git倉庫4.1 明文配置帶來的風(fēng)險(xiǎn)很多團(tuán)隊(duì)的代碼倉庫里application.yml直接寫著生產(chǎn)數(shù)據(jù)庫的賬號(hào)密碼、第三方API密鑰、短信服務(wù)的AppSecret。這些文件跟著代碼一起進(jìn)了Git倉庫凡是能訪問倉庫的人都能看到。前陣子幫一個(gè)團(tuán)隊(duì)檢查代碼發(fā)現(xiàn)他們把阿里云AccessKey直接寫在application-prod.yml里而那個(gè)倉庫帶著歷史版本一起打成了壓縮包發(fā)給外包同事。密碼一旦泄露對(duì)方的服務(wù)器就被拿去挖礦了。這不是嚇唬人這是真實(shí)發(fā)生過的事情而且復(fù)盤起來基本都有一個(gè)共同點(diǎn)秘密從配置文件里泄露出去的。對(duì)策分三個(gè)層次最小權(quán)限、動(dòng)態(tài)獲取、加密存儲(chǔ)。4.2 環(huán)境變量占位符最輕量的安全手段不改代碼的前提下最直接的做法是把敏感值從YAML里抽出來用環(huán)境變量引用spring: datasource: url: jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME}?useSSLfalsecharacterEncodingutf8 username: ${DB_USERNAME} password: ${DB_PASSWORD}部署平臺(tái)Docker、K8s、云服務(wù)器上通過環(huán)境變量注入YAML文件本身不含敏感信息可以放心提交Git。這套做法的缺點(diǎn)是環(huán)境變量在系統(tǒng)全局可見某些運(yùn)維場(chǎng)景下還是不夠隔離。但比起把密碼明文寫在代碼倉庫里已經(jīng)前進(jìn)了一大步。4.3 Jasypt加密把密碼變成密文放進(jìn)配置文件如果不想把秘密交給環(huán)境變量而希望配置里存的是密文業(yè)界常用方案是用JasyptJava Simplified Encryption。這個(gè)工具的定位很明確給Spring Boot配置里的敏感字段做加密。引入依賴以Maven為例dependency groupIdcom.github.ulisesbocchio/groupId artifactIdjasypt-spring-boot-starter/artifactId version3.0.5/version /dependency生成密文時(shí)可以用Jasypt自帶的工具類import org.jasypt.util.text.BasicTextEncryptor; public class EncryptTest { public static void main(String[] args) { BasicTextEncryptor encryptor new BasicTextEncryptor(); encryptor.setPassword(your-salt); // 鹽值需保密 String encrypted encryptor.encrypt(my-db-password); System.out.println(encrypted); } }把輸出的密文填到配置文件里spring: datasource: password: ENC(加密后的密文)這里ENC(...)是Jasypt約定的密文包裹格式。啟動(dòng)時(shí)Jasypt會(huì)攔截配置解析發(fā)現(xiàn)ENC(前綴后自動(dòng)解密還原。解密所需的鹽值不要寫在配置文件里通過JVM參數(shù)或環(huán)境變量傳入java -jar app.jar --jasypt.encryptor.password${JASYPT_SALT}這個(gè)方案實(shí)踐中有幾個(gè)注意點(diǎn)。鹽值泄露等于密文白搭所以鹽值本身存儲(chǔ)位置要安全。另外Jasypt默認(rèn)使用的算法是PBEWITHMD5ANDDES強(qiáng)度偏弱建議在配置里指定更強(qiáng)的算法jasypt: encryptor: algorithm: PBEWITHHMACSHA512ANDAES_256 iv-generator-classname: org.jasypt.iv.NoIvGenerator這個(gè)算法切換在Jasypt 3.x里是支持的。我實(shí)測(cè)過用默認(rèn)算法加密的密文在部分安全掃描工具里會(huì)被標(biāo)記為弱加密換了AES-256之后才通過檢查。另外要提醒加密不等于絕對(duì)安全。鹽值如果是在命令行里明文傳的進(jìn)程列表里還是能看到過程只是比存文件里稍微隱蔽一點(diǎn)。真正的生產(chǎn)安全還需要配合密鑰管理系統(tǒng)比如云廠商的KMS來做不過那已經(jīng)是另外一個(gè)主題了。5. 常見問題排查與進(jìn)階技巧實(shí)錄5.1 YAML語法報(bào)錯(cuò)先學(xué)會(huì)看錯(cuò)誤信息Spring Boot啟動(dòng)階段如果配置解析失敗控制臺(tái)一般會(huì)給出類似這樣的錯(cuò)誤Caused by: org.yaml.snakeyaml.parser.ParserException: while parsing a block mapping in reader, line 5, column 3: server: ^ expected block end, but found block mapping start這種報(bào)錯(cuò)十有八九是縮進(jìn)不一致。排查方法很機(jī)械把整個(gè)配置文件復(fù)制到支持YAML校驗(yàn)的編輯器IDEA自帶、VS Code裝個(gè)YAML插件它會(huì)直接標(biāo)出具體行和列的錯(cuò)誤位置。不要用肉眼一行行找效率太低。常見的原因還有配置文件里混入了中文全角冒號(hào)而不是半角:值前面多了空格導(dǎo)致被當(dāng)成嵌套文件末尾缺少換行符導(dǎo)致最后一個(gè)屬性解析異常。還有一個(gè)冷門的坑YAML文件里的---多文檔分隔符。如果用到多文檔但某個(gè)文檔塊沒有正確閉合spring.config.activate.on-profile寫錯(cuò)會(huì)導(dǎo)致配置被靜默跳過。啟動(dòng)后沒有報(bào)錯(cuò)但配置就是不生效這種問題最難排查。調(diào)用的方法是用spring-boot-starter-actuator暴露/actuator/env接口實(shí)時(shí)查看當(dāng)前生效的配置項(xiàng)有哪些一目了然。5.2 中文亂碼問題先看文件編碼再看IDE設(shè)置application.yml里寫了中文注釋或中文默認(rèn)值部署到Linux服務(wù)器后亂碼這屬于經(jīng)典問題。排查步驟固定先確認(rèn)文件本身是UTF-8編碼。用IntelliJ IDEA右下角的編碼信息可以查看和轉(zhuǎn)換。然后確認(rèn)打包時(shí)沒有改變編碼Maven項(xiàng)目中pom.xml里建議指明properties project.build.sourceEncodingUTF-8/project.build.sourceEncoding /properties最后確認(rèn)運(yùn)行環(huán)境的file.encoding。啟動(dòng)時(shí)加參數(shù)最穩(wěn)妥java -Dfile.encodingUTF-8 -jar app.jar還有一點(diǎn)很容易被忽略IDEA里文件顯示正常不代表文件就是UTF-8。Windows環(huán)境下IDEA的默認(rèn)文件編碼跟Linux服務(wù)器不一致是家常便飯建議在IDEA的Settings里把項(xiàng)目編碼統(tǒng)一設(shè)置為UTF-8并且勾選“透明存儲(chǔ)native-to-ascii轉(zhuǎn)換”選項(xiàng)來規(guī)避.properties的亂碼問題。YAML文件不存在這個(gè)native-to-ascii機(jī)制所以只要文件本身編碼對(duì)基本不會(huì)亂。5.3 配置不生效三分鐘定位到底是誰覆蓋了誰遇到“配置寫了但沒生效”的問題不要直接改代碼加日志就用Spring Boot提供的現(xiàn)成機(jī)制排查。在application.yml中先開啟management: endpoints: web: exposure: include: env然后啟動(dòng)項(xiàng)目訪問http://localhost:8080/actuator/env。這個(gè)接口返回的信息非常豐富它會(huì)展示當(dāng)前Spring環(huán)境中所有配置項(xiàng)的來源以及最終生效值還會(huì)標(biāo)明每個(gè)值來自哪個(gè)PropertySource。比如你想查server.port是誰決定生效值的打開響應(yīng)后搜索server.port能看到類似這樣的結(jié)構(gòu){ propertySources: [ { name: commandLineArgs, properties: { server.port: { value: 9090 } } }, { name: applicationConfig: [classpath:/application.yml], properties: { server.port: { value: 8080 } } } ] }這時(shí)候誰覆蓋誰一眼就能看出。這個(gè)習(xí)慣養(yǎng)成之后配置排查效率直接質(zhì)的飛躍。還有一個(gè)常見的“不生效”原因ConfigurationProperties類里的字段名拼錯(cuò)了。寬松綁定雖然能轉(zhuǎn)換kebab-case和camelCase但字段名本身拼錯(cuò)是無法映射的且不報(bào)錯(cuò)——字段值就是null。碰到這種情況可以先給配置類打上Validated并加上非空校驗(yàn)啟動(dòng)時(shí)強(qiáng)行檢查綁定的結(jié)果是不是為空。5.4 進(jìn)階技巧隨機(jī)數(shù)、Duration類型、占位符引用配置文件里隱藏著幾個(gè)被低估的特性。第一個(gè)是隨機(jī)值app: token: retry-times: ${random.int(1,10)} id: base: ${random.long}這里${random.int(1,10)}會(huì)在啟動(dòng)時(shí)隨機(jī)生成1到10之間的整數(shù)。這種寫法在模擬重試次數(shù)、測(cè)試數(shù)據(jù)生成的場(chǎng)景中很有用。第二個(gè)是Duration與DataSize類型。Spring Boot的寬松綁定能自動(dòng)把文本格式的時(shí)長轉(zhuǎn)換到j(luò)ava.time.Duration類型spring: task: execution: thread-name-prefix: async- mvc: async: request-timeout: 5s代碼里直接用Duration對(duì)象接收。這個(gè)特性避免了“毫秒和秒之間傻傻分不清”的糾紛配置里寫了多少單位就是多少單位。第三個(gè)是配置項(xiàng)之間的引用。比如同一個(gè)值時(shí)你希望一個(gè)配置繼承另一個(gè)配置中的值app: bizA: topic: topic-user bizB: topic: ${app.bizA.topic}_backup引用別的配置用占位符格式。這種方式比在各處重復(fù)寫值好得多改一處全局生效。但要注意循環(huán)引用A引用B、B引用A啟動(dòng)時(shí)會(huì)報(bào)PlaceholderResolutionException這個(gè)錯(cuò)誤信息很直白按提示改就行。還有個(gè)實(shí)用技巧配置中可以用符號(hào)指定Profile條件化屬性比如spring: config: activate: on-profile: !prod表示該文檔塊在非prod環(huán)境下才激活。這個(gè)語法我在多環(huán)境公共配置抽取時(shí)用得比較多比拆文件更靈活但可讀性稍有下降使用前要跟團(tuán)隊(duì)確認(rèn)編碼規(guī)范。最后再分享一個(gè)配置管理的好習(xí)慣維護(hù)了這么多年項(xiàng)目我體會(huì)最深的是配置文件需要被當(dāng)作代碼一樣嚴(yán)格對(duì)待。寫Java代碼大家會(huì)講究封裝、復(fù)用、單元測(cè)試但一寫配置文件就放飛自我什么硬編碼、魔法值、加密裸奔都出來了。建議團(tuán)隊(duì)里推行配置的Code Review制度單獨(dú)把a(bǔ)pplication.yml及其多環(huán)境變體作為一個(gè)review關(guān)注點(diǎn)。審查標(biāo)準(zhǔn)就三條是否含敏感明文、是否有多環(huán)境差異化配置缺失、是否有未知來源的覆蓋來源。這三條把住了生產(chǎn)事故至少能少一半。另外給項(xiàng)目接入CI/CD的時(shí)候記得在流水線里加一個(gè)步驟做配置校驗(yàn)。用spring-boot-configuration-processor能在編譯期生成配置元數(shù)據(jù)IDEA里寫配置時(shí)有自動(dòng)補(bǔ)全和類型提示用spring-boot-starter-validation能在啟動(dòng)時(shí)攔截非法配置。這兩種手段配合起來配置類的問題在開發(fā)階段就能暴露而不是要等到部署到生產(chǎn)環(huán)境才被發(fā)現(xiàn)。配置管理沒有多么高深的技術(shù)就是把該驗(yàn)證的驗(yàn)證、該加密的加密、該隔離的隔離然后形成習(xí)慣。這套流程跑通之后你會(huì)發(fā)現(xiàn)“配置又出問題了”這個(gè)聲音會(huì)越來越少出現(xiàn)在團(tuán)隊(duì)群里。