我見過太多次這個(gè)啟動(dòng)失敗了項(xiàng)目跑得好好的加了一個(gè)新的配置類或者順手升級(jí)了一次 Spring Boot結(jié)果一啟動(dòng)就紅屏核心報(bào)錯(cuò)就一句——The bean messageSender could not be registered. A bean with that name has already been defined ... and overriding is disabled。第一次踩的人通常很懵我明明沒有重復(fù)定義 Bean 啊等他把spring.main.allow-bean-definition-overridingtrue一開啟動(dòng)倒是過了過幾天又冒出來一個(gè)NoUniqueBeanDefinitionException或者更陰險(xiǎn)的——某個(gè)注入點(diǎn)悄悄用上了錯(cuò)誤的實(shí)現(xiàn)連異常都沒有。這篇就把 Bean 定義覆蓋Bean Definition Overriding和Primary之間那點(diǎn)糾纏不清的關(guān)系徹底拆一遍適合兩類人一類是剛被啟動(dòng)報(bào)錯(cuò)和注入歧義折磨的 Spring Boot 使用者另一類是寫公共配置、starter 的庫作者想搞清楚怎么避免自己的定義被別人覆蓋。1. 先從那個(gè)讓人頭疼的啟動(dòng)報(bào)錯(cuò)說起1.1 啟動(dòng)失敗和那條容易被忽略的 Debug 日志Spring Boot 2.1 是一個(gè)分水嶺。從它開始spring.main.allow-bean-definition-overriding的默認(rèn)值變成了false。也就是說容器在注冊(cè)一個(gè)新 Bean 時(shí)只要發(fā)現(xiàn)已經(jīng)存在一個(gè)同名的 BeanDefinition就直接拋BeanDefinitionOverrideException整個(gè)應(yīng)用啟動(dòng)失敗。你看到的失敗界面長(zhǎng)這樣*************************** APPLICATION FAILED TO START *************************** Description: The bean messageSender, defined in class path resource [com/example/config/EmailSenderConfiguration.class], could not be registered. A bean with that name has already been defined in class path resource [com/example/config/SmsSenderConfiguration.class] and overriding is disabled. Action: Consider renaming one of the beans or enabling overriding by setting spring.main.allow-bean-definition-overridingtrue這段報(bào)錯(cuò)信息其實(shí)已經(jīng)把答案寫在臉上了有人在你之前注冊(cè)了一個(gè)叫messageSender的定義你這次又注冊(cè)一個(gè)同名定義默認(rèn)行為不允許覆蓋。很多人的直覺反應(yīng)是那我把spring.main.allow-bean-definition-overriding改成true不就行了確實(shí)能啟動(dòng)但代價(jià)是把問題從啟動(dòng)期暴露推遲到了運(yùn)行期埋雷。當(dāng)你打開org.springframework.beans.factory.support.DefaultListableBeanFactory的 DEBUG 日志時(shí)會(huì)看到這樣一條輸出DEBUG ... Overriding bean definition for bean messageSender with a different definition: replacing [Generic bean: class [com.example.sender.SmsMessageSender]; primarytrue; ...] with [Generic bean: class [com.example.sender.EmailMessageSender]; primaryfalse; ...]注意看末尾的兩個(gè)屬性primarytrue變成了primaryfalse。這就是覆蓋和Primary產(chǎn)生沖突的核心覆蓋從頭到尾只管名字這一個(gè)維度它根本不關(guān)心被換掉的那個(gè)定義是不是被標(biāo)記成了 primary。環(huán)境配置同名 Bean 注冊(cè)的結(jié)果Spring Boot 2.1底層 Framework 默認(rèn)允許覆蓋后注冊(cè)的定義靜默替換先注冊(cè)的默認(rèn)無日志Spring Boot 2.1allow-bean-definition-overridingfalse默認(rèn)啟動(dòng)失敗拋BeanDefinitionOverrideExceptionSpring Boot 2.1allow-bean-definition-overridingtrue啟動(dòng)通過按角色輸出 INFO/DEBUG/TRACE 覆蓋日志1.2 盲目開啟覆蓋后真正的坑是 Primary 失效我見過很多團(tuán)隊(duì)在啟動(dòng)失敗后采用的第一個(gè)方案就是打開覆蓋開關(guān)然后理直氣壯地繼續(xù)開發(fā)。結(jié)果沒過多久項(xiàng)目里冒出NoUniqueBeanDefinitionExceptionNoUniqueBeanDefinitionException: No qualifying bean of type MessageSender available: expected single matching bean but found 2: messageSender, wechatMessageSender為什么會(huì)這樣用一個(gè)很直白的比喻Bean 定義覆蓋就像換宿舍。原來是 A 同學(xué)住在messageSender這個(gè)房間里還掛著寢室長(zhǎng)Primary的牌子。覆蓋動(dòng)作是把整個(gè)房間的住客換成 B 同學(xué)而 B 同學(xué)身上沒有戴牌子。于是當(dāng)同類型的其他同學(xué)數(shù)量超過一個(gè)時(shí)大家就不知道默認(rèn)該聽誰的了。更麻煩的是覆蓋這個(gè)過程沒有任何提示遷移的機(jī)制。原來掛在舊定義上的Primary、qualifier、scope 等標(biāo)記全部隨舊定義一起被丟棄。新定義說了算。所以問題的本質(zhì)不是要不要允許覆蓋而是覆蓋之后依賴注入該怎么仍然保持正確。這也是為什么這篇文章要把兩者放在一起講只談覆蓋不講Primary你早晚會(huì)在運(yùn)行期再踩一遍坑。2. 容器里到底發(fā)生了什么同名 Bean 注冊(cè)與覆蓋的底層邏輯2.1 bean 名是怎么來的方法名、類名、顯式命名要理解覆蓋先要理解名字從哪里來。Spring 內(nèi)部用DefaultListableBeanFactory的beanDefinitionMap一個(gè)ConcurrentHashMapString, BeanDefinition保存 Bean 定義key 就是 Bean 的名字。名字的生成規(guī)則很多實(shí)踐中最容易撞名的有這幾類組件掃描Component沒有指定名字時(shí)默認(rèn)是類名的首字母小寫SmsMessageSender變成smsMessageSenderBean方法沒有指定名字時(shí)默認(rèn)是方法名本身比如Bean public MessageSender messageSender()的 bean 名就是messageSender顯式命名Bean(smsMessageSender)、Component(smsMessageSender)這種最不容易撞別名Bean({smsMessageSender, primarySender})會(huì)產(chǎn)生一個(gè)主名和多個(gè)別名但別名的判斷邏輯和主名不完全一樣。覆蓋發(fā)生的條件只有一個(gè)兩個(gè)不同來源的 Bean 定義最終注冊(cè)了同一個(gè)主名。舉例說明下面這兩個(gè)定義一定是沖突的// 配置類 A Configuration public class SmsSenderConfiguration { Bean public MessageSender messageSender() { return new SmsMessageSender(); } } // 配置類 B Configuration public class EmailSenderConfiguration { Bean public MessageSender messageSender() { return new EmailMessageSender(); } }不管兩個(gè)類在工程里擺放的位置多優(yōu)雅、包名多清晰在容器眼里它們都往beanDefinitionMap里塞了同一個(gè) keymessageSender。第二次 put 就是在覆蓋第一次 put。2.2 registerBeanDefinition 的覆蓋判定源碼拆解覆蓋的判定邏輯集中在DefaultListableBeanFactory.registerBeanDefinition。核心邏輯我簡(jiǎn)化后大概是這樣的BeanDefinition existing beanDefinitionMap.get(beanName); if (existing ! null) { // 1. 不允許覆蓋直接拋異常 if (!isAllowBeanDefinitionOverriding()) { throw new BeanDefinitionOverrideException(beanName, beanDefinition, existing); } // 2. 新定義的角色更“框架內(nèi)部”打 INFO if (existing.getRole() beanDefinition.getRole()) { logger.info(Overriding user-defined bean definition for bean beanName with a framework-generated bean definition: replacing [ existing ] with [ beanDefinition ]); } // 3. 新舊定義內(nèi)容不同打 DEBUG else if (!beanDefinition.equals(existing)) { logger.debug(Overriding bean definition for bean beanName with a different definition: replacing [ existing ] with [ beanDefinition ]); } // 4. 新舊定義完全等價(jià)打 TRACE else { logger.trace(Overriding bean definition for bean beanName with an equivalent definition: replacing [ existing ] with [ beanDefinition ]); } beanDefinitionMap.put(beanName, beanDefinition); } else { beanDefinitionMap.put(beanName, beanDefinition); }這段邏輯里有幾個(gè)值得記住的細(xì)節(jié)第一BeanDefinitionOverrideException是 Spring Framework 5.1 才加入的。在老的 Framework 版本里即使你想關(guān)掉覆蓋也沒有專門的異常類型可用。第二日志級(jí)別由角色role和定義是否相等共同決定。ROLE_APPLICATION0是用戶 BeanROLE_INFRASTRUCTURE2是框架內(nèi)部 Bean。當(dāng)一個(gè)框架內(nèi)部定義替換掉你的用戶定義時(shí)會(huì)打 INFO所以偶爾能在默認(rèn)日志里看到但兩個(gè)用戶定義互相替換時(shí)默認(rèn)只是 DEBUG。很多人開了覆蓋開關(guān)后什么都沒看到就是因?yàn)闆]開 DEBUG 日志。第三equals是逐字段比較的。你只是給后來的Bean方法加了一個(gè)Primary就會(huì)讓新定義和舊定義不相等從而從 TRACE 升級(jí)成 DEBUG但又不會(huì)到 INFO。這也是為什么覆蓋日志經(jīng)?？吹靡娪挚床灰?。2.3 為什么 Spring Boot 2.1 把默認(rèn)值改成了 false有人會(huì)問Framework 默認(rèn)本來允許覆蓋Boot 為什么要冒天下之大不韙改成 false因?yàn)楦采w這件事的默認(rèn)行為太危險(xiǎn)了。在允許覆蓋且不輸出日志的情況下一個(gè)第三方庫的配置完全可以把你自己定義的RestTemplate、ObjectMapper、DataSource靜默替換成它自己的實(shí)現(xiàn)。應(yīng)用照樣啟動(dòng)線上表現(xiàn)卻突然不對(duì)勁排查成本極高。Spring Boot 2.1 做了一次吃力不討好的安全加固默認(rèn)禁止覆蓋寧可讓你在啟動(dòng)時(shí)看到紅屏也不要讓你在凌晨三點(diǎn)被一個(gè)不知道哪里來的 Bean背刺。需要明確一點(diǎn)這個(gè)默認(rèn)值是 Boot 層面的不是 Spring Framework 的。如果你脫離 Boot純用AnnotationConfigApplicationContext手動(dòng)構(gòu)建容器allowBeanDefinitionOverriding默認(rèn)仍然是 true。這也是為什么很多 Spring 老教程里根本沒有這個(gè)概念——他們用的是純 Framework 的老行為。3. Primary 介入注入競(jìng)爭(zhēng)的完整規(guī)則3.1 從 determineAutowireCandidate 看 Bean 的選擇順序Primary解決的是完全不同的問題當(dāng)容器里有多個(gè)不同類型的同名 Bean 時(shí)不存在所謂選擇困難因?yàn)橥皇Ｒ粋€(gè)了Primary處理的是多個(gè)不同名字的同類型 Bean默認(rèn)注入時(shí)該選誰。依賴注入的解析入口是DefaultListableBeanFactory.doResolveDependency大致流程是根據(jù)注入點(diǎn)的類型收集所有該類型的候選 Bean如果只有一個(gè)候選直接使用如果多個(gè)候選調(diào)用determineAutowireCandidate決出勝者決不出就拋NoUniqueBeanDefinitionException。determineAutowireCandidate的簡(jiǎn)化邏輯如下protected String determineAutowireCandidate(MapString, Object candidates, DependencyDescriptor descriptor) { // 第一優(yōu)先找 Primary 標(biāo)記的候選 String primaryCandidate determinePrimaryCandidate(candidates, requiredType); if (primaryCandidate ! null) { return primaryCandidate; } // 第二優(yōu)先按 Qualifier、字段名/參數(shù)名匹配 String qualifierCandidate determineQualifierCandidate(candidates, descriptor); if (qualifierCandidate ! null) { return qualifierCandidate; } // 都沒有返回 null由上層拋 NoUniqueBeanDefinitionException return null; }注意determinePrimaryCandidate內(nèi)部的實(shí)現(xiàn)很關(guān)鍵它會(huì)遍歷所有候選只要發(fā)現(xiàn)兩個(gè)候選都帶Primary直接拋 more than one primary bean found among candidates 的異常。也就是說Primary不是簡(jiǎn)單的優(yōu)先標(biāo)記它要求同一類型里有且只有一個(gè)事實(shí)上的默認(rèn)項(xiàng)。3.2 Primary、Qualifier、字段名回退優(yōu)先級(jí)到底誰高很多人的誤區(qū)是有了 Primary 就萬事大吉。實(shí)際上從上面的代碼能看到Spring 的注入偏好順序是Primary標(biāo)記Qualifier顯式指定的 qualifier或者字段名/參數(shù)名與某個(gè) Bean 名恰好一致都不滿足拋異常。用一張表概括場(chǎng)景結(jié)果多個(gè)候選恰好一個(gè)帶Primary用這個(gè) primary Bean多個(gè)候選兩個(gè)以上帶PrimaryNoUniqueBeanDefinitionException提示有多個(gè) primary沒有 primary字段名/參數(shù)名與某個(gè) Bean 名相同按名字回退選中它沒有 primary但注入點(diǎn)帶Qualifier按 qualifier 匹配沒有 primary字段名也對(duì)不上NoUniqueBeanDefinitionException另外一個(gè)容易混淆的是Resource(name xxx)。它不是走doResolveDependency這條鏈路的而是由CommonAnnotationBeanPostProcessor按名字直接找 Bean基本不參與Primary競(jìng)爭(zhēng)。所以如果你在字段上用Resource把它當(dāng)成按名字注入來理解就對(duì)了。還有一個(gè)經(jīng)常被忽略的細(xì)節(jié)Primary不是掛在實(shí)例上的而是掛在 BeanDefinition 上。AbstractBeanDefinition里有個(gè)primary布爾字段配置解析階段如果發(fā)現(xiàn) Bean 方法或組件類上有Primary就把它設(shè)為 true。這解釋了為什么覆蓋會(huì)丟掉 primary——覆蓋是整體替換 BeanDefinition舊的字段設(shè)置當(dāng)然跟著沒了。4. 三個(gè)真實(shí)沖突現(xiàn)場(chǎng)代碼、報(bào)錯(cuò)與根因4.1 現(xiàn)場(chǎng)一覆蓋開啟后Primary 靜默丟失場(chǎng)景是這樣項(xiàng)目里有一個(gè)MessageSender接口原本有 Sms 和 WeChat 兩個(gè)實(shí)現(xiàn)。Sms 通過Primary當(dāng)默認(rèn)實(shí)現(xiàn)WeChat 用獨(dú)立名字。Configuration public class SmsSenderConfiguration { Bean Primary public MessageSender messageSender() { return new SmsMessageSender(); } } Configuration public class WeChatSenderConfiguration { Bean public MessageSender wechatMessageSender() { return new WeChatMessageSender(); } }這個(gè)階段一切正常。某天同事加了一個(gè)郵件發(fā)送實(shí)現(xiàn)他圖省事把 Bean 方法名也寫成了messageSenderConfiguration public class EmailSenderConfiguration { Bean public MessageSender messageSender() { return new EmailMessageSender(); } }在 Spring Boot 2.1 默認(rèn)配置下啟動(dòng)直接失敗。同事為了快速解決問題往application.yml里加了spring: main: allow-bean-definition-overriding: true啟動(dòng)果然通過了。但此時(shí)容器里的messageSender已經(jīng)變成了EmailMessageSender而且沒有Primary。于是下面這個(gè)注入點(diǎn)在只有messageSender和wechatMessageSender兩個(gè)候選且都沒有 primary 的情況下開始看字段名回退Service public class NotificationService { private final MessageSender sender; public NotificationService(MessageSender sender) { this.sender sender; } }參數(shù)名sender既不匹配messageSender也不匹配wechatMessageSender直接拋NoUniqueBeanDefinitionException。更陰險(xiǎn)的變體是如果同事把構(gòu)造參數(shù)名正好寫成messageSenderSpring 會(huì)通過名字回退把EmailMessageSender靜默注入進(jìn)去整個(gè)系統(tǒng)一聲不吭。線上該發(fā)短信的地方全發(fā)了郵件這種事故比啟動(dòng)失敗難查十倍。根因覆蓋開關(guān)解決了啟動(dòng)失敗但沒有解決默認(rèn)實(shí)現(xiàn)被換掉的事實(shí)。Primary標(biāo)記丟失后所有依賴默認(rèn)實(shí)現(xiàn)的注入點(diǎn)全部懸空。4.2 現(xiàn)場(chǎng)二兩個(gè) Primary 的朋友誰都不讓誰這個(gè)場(chǎng)景和覆蓋關(guān)系不大但經(jīng)常被混在一起討論。假設(shè)兩個(gè)配置類分別聲明了不同的 Bean 名卻同時(shí)都標(biāo)了PrimaryConfiguration public class SmsSenderConfiguration { Bean Primary public MessageSender smsSender() { return new SmsMessageSender(); } } Configuration public class EmailSenderConfiguration { Bean Primary public MessageSender emailSender() { return new EmailMessageSender(); } }兩個(gè) Bean 的名字不沖突覆蓋從來不會(huì)發(fā)生。但當(dāng)你Autowired MessageSender時(shí)determinePrimaryCandidate會(huì)發(fā)現(xiàn)兩個(gè) primary于是拋異常NoUniqueBeanDefinitionException: No qualifying bean of type MessageSender available: expected single matching bean but found 2: emailSender, smsSender注意這個(gè)異常信息里有一個(gè)關(guān)鍵提示more than one primary bean found among candidates。這就是 多個(gè)同類型 Bean 多個(gè) Primary 的組合拳。Primary的設(shè)計(jì)前提是只有一個(gè)事實(shí)默認(rèn)項(xiàng)當(dāng)兩個(gè)人都想當(dāng)老大時(shí)容器直接罷工。根因Primary的約束不是可以用但不能多用而是同類型里只能有一個(gè)。這個(gè)約束由容器在注入時(shí)強(qiáng)制執(zhí)行。4.3 現(xiàn)場(chǎng)三第三方庫與業(yè)務(wù)代碼的同名換尸還有一個(gè)高頻場(chǎng)景來自公共庫。假設(shè)你們維護(hù)了一個(gè)user-common-starter里面定義了Configuration public class UserCommonAutoConfiguration { Bean public PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } }業(yè)務(wù)工程里安全團(tuán)隊(duì)又寫了Configuration public class AppSecurityConfig { Bean public PasswordEncoder passwordEncoder() { return new CustomPasswordEncoder(); } }結(jié)果依然是啟動(dòng)失敗。為什么自動(dòng)配置里的ConditionalOnMissingBean沒有生效因?yàn)?Spring Boot 的自動(dòng)配置類是通過DeferredImportSelector加載的處理時(shí)機(jī)晚于普通用戶配置類。如果你的業(yè)務(wù)配置先注冊(cè)了passwordEncoder自動(dòng)配置的條件可以感知到并退讓。但如果你和第三庫都是普通Configuration它們的處理順序由配置類解析順序決定沒有先來后到的保障同名定義就撞上了。這個(gè)場(chǎng)景的典型誘惑是把庫里的 Bean 名改掉。但如果庫是第三方的你改不了如果庫是自研的你又擔(dān)心改了名字會(huì)影響歷史調(diào)用方。根因自動(dòng)配置有 back-off 機(jī)制普通庫未必有。依賴注入只看類型和名字/qualifier不看這個(gè) Bean 是我寫的還是庫寫的。5. 合理的解決姿勢(shì)從命名規(guī)范到 BeanFactoryPostProcessor5.1 根治一顯式命名消滅同名所有覆蓋問題的第一道防線是讓 Bean 名從一開始就不一樣。這是成本最低、效果最穩(wěn)的方案。Configuration public class SmsSenderConfiguration { Bean(smsMessageSender) Primary public MessageSender smsMessageSender() { return new SmsMessageSender(); } } Configuration public class EmailSenderConfiguration { Bean(emailMessageSender) public MessageSender emailMessageSender() { return new EmailMessageSender(); } }這樣兩個(gè)實(shí)現(xiàn)各有獨(dú)立名字類型相同也不影響共存。誰想當(dāng)默認(rèn)實(shí)現(xiàn)誰掛Primary誰想精確指定誰用Qualifier(emailMessageSender)。命名規(guī)范其實(shí)比大多數(shù)人想象的重要。我看到很多團(tuán)隊(duì)反復(fù)踩覆蓋坑根源是Bean方法名隨意取英文單詞就那幾個(gè)userService、dataSource、restTemplate到處撞。項(xiàng)目里強(qiáng)制統(tǒng)一規(guī)則后覆蓋問題能減少七八成。5.2 根治二把用哪個(gè)的意圖寫進(jìn)注入點(diǎn)Primary適合表達(dá)默認(rèn)用哪個(gè)但它不是一個(gè)排他性的協(xié)議。如果你真的需要精確選擇某個(gè)實(shí)現(xiàn)應(yīng)該把意圖明確寫在注入點(diǎn)上而不是指望選擇容器里的幸運(yùn)兒。構(gòu)造器注入里可以這樣寫Service public class NotificationService { private final MessageSender smsMessageSender; public NotificationService(Qualifier(smsMessageSender) MessageSender smsMessageSender) { this.smsMessageSender smsMessageSender; } }字段注入可以配合Resource(name smsMessageSender)或者干脆Service public class NotificationService { private final ObjectProviderMessageSender senders; public NotificationService(ObjectProviderMessageSender senders) { this.senders senders; } public void notify() { MessageSender primary senders.getIfAvailable(); // 或者遍歷所有實(shí)現(xiàn) senders.orderedStream().forEach(sender - sender.send(...)); } }ObjectProvider很適合默認(rèn)選 primary同時(shí)不排除其他實(shí)現(xiàn)的場(chǎng)景。它把選擇邏輯從容器內(nèi)部搬到了你的代碼里雖然多寫幾行但語義清楚得多。5.3 根治三順著條件裝配的規(guī)矩來讓自動(dòng)配置主動(dòng)退讓如果你是 starter 或者公共模塊的作者問題不能只靠使用方改名解決。要讓使用方覆蓋你的 Bean 時(shí)不產(chǎn)生沖突最好把條件裝配寫完整。Spring Boot 自動(dòng)配置的推薦做法是用ConditionalOnMissingBean表示使用方已經(jīng)定義了我就不注冊(cè)了用ConditionalOnProperty、ConditionalOnClass控制觸發(fā)范圍用AutoConfiguration(after ...)控制與其它自動(dòng)配置的先后關(guān)系如果擔(dān)心名字撞車Bean 名盡量帶模塊前綴比如userCommonPasswordEncoder。自動(dòng)配置因?yàn)镃onditionalOnMissingBean的存在天然逃避了大部分覆蓋沖突。普通Configuration庫沒有這個(gè)保護(hù)所以公共庫要么改成自動(dòng)配置要么至少要確保自己的 Bean 名足夠獨(dú)特?？吹揭粋€(gè)第三方庫用了dataSource、restTemplate這種爛大街的名字你就該意識(shí)到它遲早給你惹麻煩。5.4 兜底四BeanFactoryPostProcessor 精確手術(shù)有些場(chǎng)景是誰也不能改名誰也不能刪但必須把 primary 調(diào)過來。這時(shí)候可以動(dòng)用BeanFactoryPostProcessor對(duì) BeanDefinition 做定點(diǎn)修改。Component public class PrimaryMarkerFixer implements BeanFactoryPostProcessor { Override public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException { DefaultListableBeanFactory dlbf (DefaultListableBeanFactory) beanFactory; BeanDefinition bd dlbf.getBeanDefinition(smsMessageSender); if (bd instanceof AbstractBeanDefinition abd) { abd.setPrimary(true); } } }原理是BeanFactoryPostProcessor的執(zhí)行時(shí)機(jī)在全部 BeanDefinition 注冊(cè)完成之后、Bean 實(shí)例化之前而且普通BeanFactoryPostProcessor的執(zhí)行順序晚于ConfigurationClassPostProcessor所以能拿到最終的注冊(cè)結(jié)果。但這個(gè)方法有幾個(gè)使用前提你要準(zhǔn)確知道目標(biāo) Bean 的名字和當(dāng)前狀態(tài)getBeanDefinition拿到的必須是同一個(gè)AbstractBeanDefinition不要在這里做任何實(shí)例化操作否則會(huì)打亂容器的初始化順序。這是一把手術(shù)刀不是常規(guī)武器。能用命名解決的就用命名不要一上來就改定義。5.5 最后的手段allow-bean-definition-overriding 什么時(shí)候真的值得開講了這么多必須承認(rèn)有些場(chǎng)景確實(shí)必須開spring.main.allow-bean-definition-overridingtrue。典型的場(chǎng)景包括從 Spring Boot 1.x 升級(jí)到 2.x/3.x老項(xiàng)目里有大量裸奔的同名 Bean短期改不完接入了閉源第三方庫對(duì)方的名字無法修改又沒有條件裝配測(cè)試環(huán)境需要快速替換某個(gè) Bean 的實(shí)現(xiàn)不值得大動(dòng)干戈。開啟前請(qǐng)至少做三件事把logging.level.org.springframework.beans.factory.support.DefaultListableBeanFactory臨時(shí)調(diào)到DEBUG看清到底有哪些覆蓋發(fā)生在啟動(dòng)日志里確認(rèn)每次覆蓋的舊定義和新定義分別是誰記錄覆蓋清單給后續(xù)清理留一個(gè)待辦。如果只是為了避免一次啟動(dòng)失敗而草率開啟那它就是在給運(yùn)行期埋雷。開啟后覆蓋日志里出現(xiàn)的每一行都是一個(gè)潛在的事故點(diǎn)。我的習(xí)慣是能不開就不開開了之后就當(dāng)自己欠了技術(shù)債必須盡快用命名和條件裝配把覆蓋點(diǎn)清掉。場(chǎng)景推薦做法自己的兩個(gè)配置類同名顯式命名給Bean(xxx)想給多個(gè)實(shí)現(xiàn)指定默認(rèn)其中一個(gè)加Primary其它用Qualifier精確選擇第三方庫同名且無法改名用BeanFactoryPostProcessor定位調(diào)整必要時(shí)才開覆蓋開關(guān)需要替換自動(dòng)配置的 Bean遵循ConditionalOnMissingBean換一個(gè)不同的名字同類型出現(xiàn)多個(gè) primary只保留一個(gè)Primary6. 排查清單按這個(gè)順序找問題最快6.1 先判斷你遇到的是哪一種覆蓋問題遇到問題別急著改配置先按下面的分支判斷啟動(dòng)直接失敗報(bào)could not be registered ... overriding is disabled→ 禁用覆蓋下的同名沖突啟動(dòng)成功但 DEBUG 日志里出現(xiàn)了Overriding bean definition for bean X ...→ 啟用覆蓋下正在發(fā)生替換你還沒意識(shí)到NoUniqueBeanDefinitionException提示found N: ...→ 這是注入決策問題先看有沒有 primary再看字段名NoUniqueBeanDefinitionException提示more than one primary bean found→Primary加多了。判斷錯(cuò)誤表格現(xiàn)象問題域解決方向啟動(dòng)失敗 同名注冊(cè)定義覆蓋改名 / 條件裝配調(diào)試日志出現(xiàn)覆蓋輸出定義覆蓋審計(jì)新舊定義來源注入歧義 無 primaryPrimary缺失指定 primary 或 qualifier注入歧義 多個(gè) primaryPrimary沖突只保留一個(gè) primary6.2 用 Actuator 和臨時(shí) Runner 把 Bean 定義攤開來看建議直接把 Spring Boot Actuator 的 beans 端點(diǎn)打開這是排查 bean 問題的第一利器。management: endpoints: web: exposure: include: beans啟動(dòng)后訪問/actuator/beans在返回的 JSON 里搜索你的 Bean 名。你會(huì)看到每個(gè) Bean 的resource來自哪個(gè)配置類、哪個(gè)方法、dependencies、scope等關(guān)鍵信息。兩個(gè)同名定義里只有一個(gè)最終存活從 JSON 里就能看出存活的是誰。如果需要更細(xì)的信息尤其是 primary 標(biāo)記直接寫一個(gè)臨時(shí)的 RunnerComponent public class BeanDefinitionDumper implements ApplicationRunner { private final ConfigurableApplicationContext context; public BeanDefinitionDumper(ConfigurableApplicationContext context) { this.context context; } Override public void run(ApplicationArguments args) { DefaultListableBeanFactory factory (DefaultListableBeanFactory) context.getAutowireCapableBeanFactory(); for (String beanName : factory.getBeanDefinitionNames()) { BeanDefinition bd factory.getBeanDefinition(beanName); String primary (bd instanceof AbstractBeanDefinition abd) ? String.valueOf(abd.getPrimary()) : N/A; System.out.printf(%s | %s | primary%s%n, beanName, bd.getBeanClassName(), primary); } } }把輸出的內(nèi)容存成文件按類型分組看。兩步就能確認(rèn)三件事哪些 Bean 名重復(fù)、最終留的是哪個(gè)定義、primary 標(biāo)記加在誰身上。6.3 別把另一條 BeanPostProcessor 警告混進(jìn)來排查時(shí)還會(huì)遇到一條看起來長(zhǎng)得差不多的日志Bean xxx of type [...] is not eligible for getting processed by all BeanPostProcessors ...這條和覆蓋沒有關(guān)系。它出現(xiàn)在某個(gè) Bean 在BeanPostProcessor注冊(cè)完成之前就被提前實(shí)例化的時(shí)候典型來源是BeanFactoryPostProcessor或BeanDefinitionRegistryPostProcessor里手賤調(diào)了getBean?？吹剿灰采w方向查要查的是誰在容器早期階段提前初始化了這個(gè) Bean。這兩條日志經(jīng)常在同一次啟動(dòng)里一起出現(xiàn)導(dǎo)致很多人把它們當(dāng)成同一個(gè)問題。分清楚之后排查會(huì)少走很多彎路。最后說個(gè)我自己的排查習(xí)慣處理這類問題我從來不先問Primary 加在哪而是先回答三個(gè)問題——這個(gè) Bean 叫什么名字、誰最后寫入了這個(gè)名字、注入點(diǎn)訂閱的到底是類型還是名字。三個(gè)問題答完九成的覆蓋沖突已經(jīng)能用命名和Qualifier解決剩下的才輪到覆蓋開關(guān)和BeanFactoryPostProcessor這種大殺器。Bean 定義覆蓋是配置之間的打架Primary只是裁判但裁判判不了名字完全相同的兩個(gè)人。先把名字理清楚比什么都管用。