Home
File settings.xml trong Maven dùng để làm gì?
Tags:

File settings.xml trong Maven dùng để làm gì?

August 15, 2021

Khi sử dụng Maven chúng ta đều giành hầu hết sự quan tâm đến file pom.xml, dùng để cấu hình cho một dự án cụ thể. Nhưng có thể chúng ta đã quên đi rằng Maven còn cung cấp file settings.xml cho phép chúng ta chỉ định local và remote repository mà nó sẽ sử dụng, chúng ta còn có thể sử dụng nó để lưu trữ các thông tin nhạy cảm mà chúng ta không muốn nó xuất hiện trong mã nguồn của dự án chẳng hạn username, password v.v.

Trong bài viết này chúng ta sẽ cùng nhau tìm hiểu cách sử dụng settings.xml trong maven một cách hiệu quả. 

Cấu hình

File settings.xml được tải cùng lúc với Maven. Nó tương tự như file pom.xml nhưng nó được dùng ở mức global. Nghĩa là các project sử dụng gói maven này đều có một cấu hình chung là settings.xml.

Hãy xem các phần tử trong file settings.xml mà chúng ta có thể cấu hình sau đây:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository/>
    <interactiveMode/>
    <offline/>
    <pluginGroups/>
    <servers/>
    <mirrors/>
    <proxies/>
    <profiles/>
    <activeProfiles/>
</settings>

Các giá trị cơ bản

Các phần tử nằm ở trên đầu chứa các giá trị cơ bản mà chúng ta cần phải chú ý đầu tiên.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <localRepository>${user.home}/.m2/repository</localRepository>
    <interactiveMode>true</interactiveMode>
    <offline>false</offline>
</settings>

Phần tử localRepository trỏ đến đường dẫn của kho lưu trữ nội bộ của hệ thống. Kho lưu trữ nội bộ này là nơi tất cả các dependency của các dự án của chúng tôi được lưu vào bộ nhớ đệm. Thư mục mặc định được sử dụng là ${user.home}/.m2/repository tuy nhiên chúng ta có thể thay đổi nó bằng chỉ định lại đường dẫn trong phần tử localRepository.

Phần tử interactiveMode cho phép maven tương tác với người dùng cho các yêu cầu nhập dữ liệu. Giá trị này mặc định là true.

Phần tử offline xác định xem build system có thể hoạt động ở chế độ ngoại tuyến hay không, mặc định là false. Chúng ta cần lưu ý khi chuyển giá trị thành true vì lúc này maven sẽ không connect đến remote để tải các dependency cần thiết mà chỉ tìm kiếm trong kho lưu trữ nội bộ. Nếu những dependency mới được thêm vào chưa có sẵn trong kho lưu trữ nội bộ thì quá trình build sẽ không thành công.

Plugin Groups

Phần tử pluginGroups chứa một danh sách các phần tử con, mỗi phần con mang một giá trị groupId duy nhất dùng để định danh cho tổ chức tạo ra các maven artifact cụ thể.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <pluginGroups>
        <pluginGroup>org.apache.tomcat.maven</pluginGroup>
    </pluginGroups>
</settings>

Maven sẽ tìm kiếm các plugin được sử dụng trong các project mà groupId không được chỉ định cụ thể. Danh sách này  tập giá trị mặc định là org.apache.maven.plugins và org.codehaus.mojo.

Proxies

Chúng tôi có cấu hình proxy cho một số hoặc tất cả các HTTP request của Maven. Phần tử proxies  cho phép chỉ định một danh sách các phần tử proxy con, nhưng chỉ một proxy có thể hoạt động tại một thời điểm.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <proxies>
    <proxy>
      <id>myproxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>proxy.somewhere.com</host>
      <port>8080</port>
      <username>proxyuser</username>
      <password>somepassword</password>
      <nonProxyHosts>*.google.com|ibiblio.org</nonProxyHosts>
    </proxy>
  </proxies>
  ...
</settings>

Chúng ta có thể kích hoạt một proxy bằng active flag. Với phần tử nonProxyHosts chúng ta có thể định các host không cần dùng proxy.

Mirrors

Với Repositories, chúng ta có thể chỉ định vị trí nào bạn muốn tải xuống các artifacts, chẳng hạn như dependency và maven-plugin. Tuy nhiên thay vì chỉ định nó trong file pom.xml như thế này

<project>
  ...
  <repositories>
    <repository>
      <id>my-internal-site</id>
      <url>https://myserver/repo</url>
    </repository>
  </repositories>
  ...
</project>

Thì chúng ta có thể sử dụng Mirrors để đạt được điều tương tự.s

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <mirrors>
    <mirror>
      <id>planetmirror.com</id>
      <name>PlanetMirror Australia</name>
      <url>http://downloads.planetmirror.com/pub/maven2</url>
      <mirrorOf>central</mirrorOf>
    </mirror>
  </mirrors>
  ...
</settings>

Servers

Định nghĩa repositories trong file pom.xml là một good practice. Tuy nhiên, chúng ta không nên đưa các cài đặt bảo mật, chẳng hạn như thông tin đăng nhập vào file pom.xml. Thay vào đó, chúng ta có thể chỉ định cá thông tin bảo mật này trong tệp settings.xml:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <servers>
    <server>
      <id>server001</id>
      <username>my_login</username>
      <password>my_password</password>
      <privateKey>${user.home}/.ssh/id_dsa</privateKey>
      <passphrase>some_passphrase</passphrase>
      <filePermissions>664</filePermissions>
      <directoryPermissions>775</directoryPermissions>
      <configuration></configuration>
    </server>
  </servers>
  ...
</settings>

Profiles

Phần tử profiles cho phép chúng ta tạo ra nhiều profile con được phân bởi ID. Phần profile trong settings.xml là phiên bản rút gọn của cùng một phần tử có sẵn trong pom.xml. 

Phần tử profiles chỉ có thể chứa 4 loại phần tử con là: activation, repositories, pluginRepositories, và properties. Những cấu hình trong các phần tử con này sẽ ảnh hưởng đến toàn bộ dự án chứ không chỉ riêng một dự án nào.

Điều quan trọng cần lưu ý là các giá trị từ active profile  trong settings.xml sẽ ghi đè mọi giá trị cấu hình tương đương trong tệp pom.xml hoặc profiles.xml. Profiles được khớp theo ID.

Activation

Chúng ta có thể sử dụng các profiles để chỉnh sửa các giá trị trong những trường hợp cụ thể, chúng ta cũng có thể đạt được điều tương tự thông qua activation. 

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <profiles>
    <profile>
      <id>test</id>
      <activation>
        <activeByDefault>false</activeByDefault>
        <jdk>1.5</jdk>
        <os>
          <name>Windows XP</name>
          <family>Windows</family>
          <arch>x86</arch>
          <version>5.1.2600</version>
        </os>
        <property>
          <name>mavenVersion</name>
          <value>2.0.3</value>
        </property>
        <file>
          <exists>${basedir}/file2.properties</exists>
          <missing>${basedir}/file1.properties</missing>
        </file>
      </activation>
      ...
    </profile>
  </profiles>
  ...
</settings>

Có bốn yếu tố để có thể kích hoạt activation: 

  • jdk: Kích hoạt profile dựa trên phiên bản JDK
  • os: Kích hoạt profile  dựa trên phiên bản hệ điều hành
  • property: Kích hoạt profile nếu Maven phát hiện một giá trị thuộc tính cụ thể
  • file: kích hoạt profile nếu tên một tệp nhất định tồn tại hoặc bị thiếu

Lưu ý chúng ta không cần chỉ định hết 4 thuộc tính trên. Để kiểm tra profile nào đang được active chúng ta có thể sử dụng lệnh sau

mvn help:active-profiles

Properties

Maven properties là các value placeholder, chúng ta có thể sử dụng các value placeholder thông qua cú pháp ${X} trong đó X là property. Chúng ta có đến 5 cách để có thể truy cập trong settings.xml như sau:

  1. env.X: Với tiền tố là “env.” sẽ trả về biến môi trường. Ví dụ, ${env.PATH} chứa biên môi trường $path(%PATH% trong Windows).
  2. project.x: Tiền tố project trả về các giá trị được đặt trong phần tử project. Ví dụ: <project><version>1.0</version></project> có thể truy cập thông qua ${project.version}.
  3. settings.x: Trả về các giá trị được cấu hình trong file settings.xml Ví dụ : <settings><offline>false</offline></settings> có thể truy cập thông qua ${settings.offline}.
  4. Java System Properties: Các thuộc tính có thể truy cập thông qua java.lang.System.getProperties() cũng có thể sử dụng như sau ${java.home}.
  5. x: Các giá trị được đặt trong <properties /> ví dụ như ${someVar}.
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <profiles>
    <profile>
      ...
      <properties>
        <user.install>${user.home}/our-project</user.install>
      </properties>
      ...
    </profile>
  </profiles>
  ...
</settings>

Repositories

Remote repositories chứa các maven artifacts mà maven sử dụng và lưu lại trên localrepository. Các remote repositories có thể chứa ở những nơi khác nhau, chúng ta có thể chỉ đinh rõ những nơi này khi một profile được active.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <profiles>
    <profile>
      ...
      <repositories>
        <repository>
          <id>codehausSnapshots</id>
          <name>Codehaus Snapshots</name>
          <releases>
            <enabled>false</enabled>
            <updatePolicy>always</updatePolicy>
            <checksumPolicy>warn</checksumPolicy>
          </releases>
          <snapshots>
            <enabled>true</enabled>
            <updatePolicy>never</updatePolicy>
            <checksumPolicy>fail</checksumPolicy>
          </snapshots>
          <url>http://snapshots.maven.codehaus.org/maven2</url>
          <layout>default</layout>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>myPluginRepo</id>
          <name>My Plugins repo</name>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
          <url>https://maven-central-eu....com/maven2/</url>
        </pluginRepository>
      </pluginRepositories>
      ...
    </profile>
  </profiles>
  ...
</settings>

 Plugin Repositories

Chúng ta có 2 kiểu Maven artifacts chính là dependency và plugin. Vì maven plugin là một artifact đặc biệt, chúng ta có thể tách các kho repository chứa plugin khỏi các repository khác:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <profiles>
        <profile>
            <id>adobe-public</id>
            <pluginRepositories>
               <pluginRepository>
                  <id>adobe-public-releases</id>
                  <name>Adobe Public Repository</name>
                  <url>https://repo.adobe.com/nexus/content/groups/public</url>
                  <releases>
                      <enabled>true</enabled>
                      <updatePolicy>never</updatePolicy>
                  </releases>
                  <snapshots>
                      <enabled>false</enabled>
                  </snapshots>
	        </pluginRepository>
	    </pluginRepositories>
        </profile>
    </profiles>
</settings>

Cấu trúc của phần tử pluginRepositories rất giống với phần tử repositories.

Active Profiles

Phần tử activeProfiles chứa danh sách các phần tử con chỉ định một ID cụ thể. Maven sẽ active bất cứ profile nào được chỉ định tại đây.

settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
  ...
  <activeProfiles>
    <activeProfile>env-test</activeProfile>
  </activeProfiles>
</settings>

Settings Level

File settings.xml thường sẽ được đặt tại 2 vị trí sau:

  • Global settings trong thư mục home của maven: ${maven.home}/conf/settings.xml
  • User settings trong thư mục home của user: ${user.home}/.m2/settings.xml

Nếu cả hai tệp  đều tồn tại, nội dung của chúng sẽ được hợp nhất. Cấu hình từ User Settings sẽ được ưu tiên.

Tìm kiếm settings.xml trong maven

Trong trường hợp chúng ta muốn tìm kiếm file settings.xml của cả maven và user nằm ở đâu thì có thể sử dụng lệnh sau:

$ mvn -X clean | grep "settings"

Các cấu hình hợp nhất

Chúng ta có thể sử dụng 

mvn help:effective-settings

Để xem các cấu hình được hợp nhất từ user setting và maven setting.

Tóm lược

Qua bài viết trên chúng ta đã tìm hiểu được sơ lược về cấu trúc của file settings.xml trong maven.

Nguồn tham khảo

https://maven.apache.org/guides/mini/guide-mirror-settings.html

https://www.baeldung.com/maven-settings-xml

https://maven.apache.org/settings.html

0 0 votes
Article Rating
Subscribe
Notify of
guest
0 Comments
Inline Feedbacks
View all comments
0
Would love your thoughts, please comment.x
()
x