[Carefree MongoDB] Spring Boot MongoDB 自動化配置

最近在製做一個 spring boot 小應用時使用了 MongoDB，鑑於官方庫的簡陋配置，決定本身造個輪子，源碼發佈在 GitHub Carefree MongoDB，jar 已在中央倉庫發佈，能夠直接引用。

English | 中文

Spring Data MongoDB 爲面向 MongoDB 的開發提供了一套基於 Spring 的編程模型，在 Spring Boot 中使用 spring-boot-starter-data-mongodb 能夠很方便的引入 Spring Data MongoDB 以及 MongoDB Java Driver。

然而，Spring Data MongoDB 只提供了最簡單的 MongoDB 客戶端選項，且不支持多數據源配置。爲了使用鏈接池、集羣等 MongoDB 高級特性，及知足多數據源的需求，咱們不得不進行一些額外的配置和編碼工做。

Carefree MongoDB 由此而生，除了支持完整的 MongoDB 客戶端選項及多數據源配置以外，還提供了一些其它的實用功能。使用後，Carefree MongoDB 將自動建立並注入 MongoTemplate 以及 GridFsTemplate 實例。

快速使用

可使用 Gradle 或 Maven 快速引入 Carefree MongoDB。將同時引入 spring-data-mongodb 和 mongo-java-driver，所以無需再額外定義兩者的引入。

Gradle

compile group: 'org.kweny.carefree', name: 'carefree-mongodb-spring-boot-starter', version: '1.0.1'

Maven

<dependency>
  <groupId>org.kweny.carefree</groupId>
  <artifactId>carefree-mongodb-spring-boot-starter</artifactId>
  <version>1.0.1</version>
</dependency>

@EnableMongoCarefree

在應用主類上添加 @EnableMongoCarefree 註解開啓自動配置，同時禁用 Spring Boot 默認的 MongoDB 自動配置——

@EnableMongoCarefree
@SpringBootApplication(exclude = {MongoAutoConfiguration.class, MongoDataAutoConfiguration.class})
public class Application {
   public static void main(String[] args) {
       SpringApplication.run(Application.class, args);
   }
}

Carefree MongoDB 將自動加載配置文件 application.properties 或 application.yml 中以 carefree.mongodb 爲前綴的屬性。

屬性名的前綴可自定義，如——

@EnableMongoCarefree("mongodb.custom.prefix")

同時支持佔位符，用以引用定義好的屬性值，如——

@EnableMongoCarefree("mongodb.${placeholder}.prefix")
@EnableMongoCarefree("${mongodb.placeholder.prefix}")

配置選項

Carefree MongoDB 支持完整的 MongoDB Java Driver 客戶端選項，及多數據源配置，同時也提供了一些額外的配置項。

配置示例

application.yml

carefree:
  mongodb:
    enable: true
    options:
      primary: true
      uri: mongodb://[username:password@]host1[:port1][,host2[:port2],…[,hostN[:portN]]][/[database][?options]]
      addresses:
      - 192.168.1.1:27017
      - 192.168.1.2:27017
      database: test_db
      auth: true
      username: test_user
      password: test_pwd
      authentication-mechanism: SCRAM-SHA-1
      authentication-source: admin
      description: some description
      application-name: test app
      connect-timeout: 10000
      socket-timeout: 0
      max-wait-time: 120000
      min-connections-per-host: 0
      max-connections-per-host: 100
      max-connection-idle-time: 0
      max-connection-life-time: 0
      threads-allowed-to-block-for-connection-multiplier: 5
      heartbeat-frequency: 10000
      min-heartbeat-frequency: 500
      heartbeat-connect-timeout: 20000
      heartbeat-socket-timeout: 20000
      retry-writes: false
      always-use-m-beans: false
      ssl-enabled: false
      ssl-invalid-host-name-allowed: false
      local-threshold: 15
      server-selection-timeout: 30000
      server-selector: com.xxx.CustomServerSelector
      required-replica-set-name: replica_name
      write-concern: w1
      read-concern: local
      read-preference: primary
      cursor-finalizer-enabled: true
      command-listeners:
      - com.xxx.CustomCommandListener
      cluster-listeners:
      - com.xxx.CustomClusterListener
      connection-pool-listeners:
      - com.xxx.CustomConnectionPoolListener
      server-listeners:
      - com.xxx.CustomServerListener
      server-monitor-listeners:
      - com.xxx.CustomServerMonitorListener
      type-key: _class
      grid-fs-template-name: gridFsTemplate
      grid-fs-database: test_db
      field-naming-strategy: com.xxx.CustomFieldNamingStrategy
      optioned-listeners:
      - com.xxx.CustomOptionedListener

application.properties

carefree.mongodb.enable=true
carefree.mongodb.options.uri=mongodb://[username:password@]host1[:port1][,host2[:port2],…[,hostN[:portN]]][/[database][?options]]
carefree.mongodb.options.primary=true
carefree.mongodb.options.addresses[0]=192.168.1.1:27017
carefree.mongodb.options.addresses[1]=192.168.1.2:27017
carefree.mongodb.options.database=test_db
carefree.mongodb.options.auth=true
carefree.mongodb.options.username=test_user
carefree.mongodb.options.password=test_pwd
carefree.mongodb.options.authentication-mechanism=SCRAM-SHA-1
carefree.mongodb.options.authentication-source=admin
carefree.mongodb.options.description=some description
carefree.mongodb.options.application-name=test app
carefree.mongodb.options.connect-timeout=10000
carefree.mongodb.options.socket-timeout=0
carefree.mongodb.options.max-wait-time=120000
carefree.mongodb.options.min-connections-per-host=0
carefree.mongodb.options.max-connections-per-host=100
carefree.mongodb.options.max-connection-idle-time=0
carefree.mongodb.options.max-connection-life-time=0
carefree.mongodb.options.threads-allowed-to-block-for-connection-multiplier=5
carefree.mongodb.options.heartbeat-frequency=10000
carefree.mongodb.options.min-heartbeat-frequency=500
carefree.mongodb.options.heartbeat-connect-timeout=20000
carefree.mongodb.options.heartbeat-socket-timeout=20000
carefree.mongodb.options.retry-writes=false
carefree.mongodb.options.always-use-m-beans=false
carefree.mongodb.options.ssl-enabled=false
carefree.mongodb.options.ssl-invalid-host-name-allowed=false
carefree.mongodb.options.local-threshold=15
carefree.mongodb.options.server-selection-timeout=30000
carefree.mongodb.options.server-selector=com.xxx.CustomServerSelector
carefree.mongodb.options.required-replica-set-name=replica_name
carefree.mongodb.options.write-concern=w1
carefree.mongodb.options.read-concern=local
carefree.mongodb.options.read-preference=primary
carefree.mongodb.options.cursor-finalizer-enabled=true
carefree.mongodb.options.command-listeners[0]=com.xxx.CustomCommandListener
carefree.mongodb.options.cluster-listeners[0]=com.xxx.CustomClusterListener
carefree.mongodb.options.connection-pool-listeners[0]=com.xxx.CustomConnectionPoolListener
carefree.mongodb.options.server-listeners[0]=com.xxx.CustomServerListener
carefree.mongodb.options.server-monitor-listeners[0]=com.xxx.CustomServerMonitorListener
carefree.mongodb.options.type-key=_class
carefree.mongodb.options.grid-fs-template-name=gridFsTemplate
carefree.mongodb.options.grid-fs-database=test_db
carefree.mongodb.options.field-naming-strategy=com.xxx.CustomFieldNamingStrategy
carefree.mongodb.options.optioned-listeners[0]=com.xxx.CustomOptionedListener

多數據源

進行多數據源配置時，須要明確指定各數據源的 MongoTemplate Bean 名稱。如——

carefree:
  mongodb:
    enable: true
    options:
      primary: true
      uri: xxx
      
      masterTemplate:
        uri: xxx
        
      testTemplate:
        uri: yyy

以上配置表示 3 個數據源，將建立 mongoTemplate、masterTemplate、testTemplate 三個 Bean。其中 mongoTemplate 爲默認名稱，不須要顯示聲明，當不指定名稱時，將以此爲名建立並注入。即如下兩種配置等價——

carefree.mongodb.options.mongoTemplate.xxx=yyy

carefree.mongodb.options.xxx=yyy

配置說明

關於 MongoDB Java Driver 客戶端選項的詳細說明能夠參考 MongoDB 客戶端鏈接選項 一文。

注：因爲官方已對 socket-keep-alive 選項以及 MONGODB-CR 認證方式標註廢棄，所以 Carefree MongoDB 也不予支持。

如下將對一些由 Carefree MongoDB 特別處理的配置項進行說明——

• carefree.mongodb.enable - 用於指示是否開啓 Carefree MongoDB 的自動配置。該選項設爲 false 時將覆蓋 @EnableMongoCarefree 註解並關閉自動配置。默認爲 true。
• uri - MongoDB 的鏈接字符串，當配置了 uri 時，將忽略 addresses、database、username 等鏈接相關的配置項，而直接使用 uri 創建鏈接。
• auth - 服務端是否須要認證，默認爲 false，若是服務端須要認證，請將該選項設爲 true，不然即便配置了 username、password 等選項也會被忽略。
• authentication-mechanism - 服務端認證所採用的算法，可選值爲 PLAIN、GSSAPI、MONGODB-X509、SCRAM-SHA-1、SCRAM-SHA-256。注：因爲官方已對 MONGODB-CR 認證方式標註廢棄，所以 Carefree MongoDB 直接不予支持。
• server-selector - com.mongodb.selector.ServerSelector 接口實現類的全名。
• command-listeners - com.mongodb.event.CommandListener 接口實現類的全名，能夠指定多個。
• cluster-listeners - com.mongodb.event.ClusterListener 接口實現類的全名，能夠指定多個。
• connection-pool-listeners - com.mongodb.event.ConnectionPoolListener 接口實現類的全名，能夠指定多個。
• server-listeners - com.mongodb.event.ServerListener 接口實現類的全名，能夠指定多個。
• server-monitor-listeners - com.mongodb.event.ServerMonitorListener 接口實現類的全名，能夠指定多個。

• write-concern - 該選項接受的值形式以下——

  • w1、w2、w3 ... - 其中的數字可根據實際狀況指定。
  • majority、journal - 分別對應 WriteConcern.MAJORITY 和 WriteConcern.JOURNALED 兩種模式。
  • w2-10000-true、w2-10000-false - 其中 w2 表示寫入模式；10000 表示寫入超時時間，即 wtimeout，單位爲毫秒；true/false 表示是否須要 journalling。
• read-concern - 可選值爲 local、majority、linearizable、snapshot。

• read-preference - 該選項接受的值形式以下——

  • primary、primaryPreferred、secondary、secondaryPreferred、nearest - 分別表示主節點、首選主節點、從節點、首選從節點以及最近節點 5 種模式。
  • mode-tagSet-staleness - 這種配置方式在 非 primary 模式下能夠指定從哪些節點讀取（tagSet）以及容忍的最大延遲（staleness），其中 tagSet 能夠指定多個，staleness 單位爲毫秒。如 secondary-[{a=0,b=1},{c=3,d=4},{e=5}]-10000、secondary-[{a=0,b=1}]、secondary-10000。
• type-key - Java 對象存儲爲 MongoDB 的 Document 時，會同時以一個名爲 _class 的字段存儲類名。該選項用於指定這個字段的名稱，若是設爲 false 將不存儲這個字段；若爲 true 則以默認的 _class 存儲；其它值則以指定的值爲名存儲這個字段。
• field-naming-strategy - org.springframework.data.mapping.model.FieldNamingStrategy 接口實現類的全名。
• grid-fs-template-name - 指定該數據源 GridFsTemplate 的 Bean 名稱。若不指定則不建立該數據源的 GridFsTemplate。默認的（名爲 mongoTemplate）的數據源即便不指定該選項也會建立名爲 gridFsTemplate 的 Bean。
• grid-fs-database - GridFS 數據庫名稱。默認使用 database 的值。
• optioned-listeners - org.kweny.carefree.mongodb.MongoCarefreeOptionedListener 接口實現類的全名，能夠指定多個。這個監聽器於配置選項被加載解析完成後觸發，接受 org.kweny.carefree.mongodb.MongoCarefreeStructure 和 com.mongodb.MongoClientOptions.Builder 兩個實例參數，能夠在鏈接、工廠、template 等對象真正建立以前進行一些操做，如手動設置一些沒有（沒法）經過配置文件來指定的值等。

---

若是您喜歡個人文章，能夠在如下平臺關注我——

• 我的主頁：http://kweny.io
• GitHub：https://github.com/kweny
• 知乎：https://zhihu.com/people/kweny
• 思否：https://segmentfault.com/u/kweny
• 微博：https://weibo.com/kweny
• 公衆號：K棧IO（KwenyIO）