Giới thiệu về cấu trúc thư mục của Apache Iceberg

Apache Iceberg là một định dạng bảng mã nguồn mở được thiết kế để phân tích các bộ dữ liệu lớn. Việc hiểu rõ cấu trúc thư mục của dự án là bước đầu tiên quan trọng để làm việc hiệu quả với nó. Dưới đây là cái nhìn chi tiết về cách tổ chức điển hình của một dự án Iceberg:

iceberg/
├── src/
│   ├── main/
│   │   ├── java/         # Mã nguồn Java chính của ứng dụng
│   │   └── resources/    # Các tài nguyên không phải mã nguồn (ví dụ: cấu hình, tệp mẫu)
│   └── test/
│       ├── java/         # Mã nguồn kiểm thử (unit tests, integration tests)
│       └── resources/    # Tài nguyên dành cho kiểm thử
├── build.gradle          # Tệp cấu hình chính của Gradle để định nghĩa các tác vụ xây dựng
├── gradlew               # Script wrapper Gradle cho hệ điều hành Unix/Linux/macOS
├── gradlew.bat           # Script wrapper Gradle cho hệ điều hành Windows
├── settings.gradle       # Tệp cấu hình Gradle cho các module và cấu trúc dự án đa-module
├── LICENSE               # Giấy phép sử dụng của dự án
├── NOTICE                # Thông báo bản quyền và các yêu cầu pháp lý khác
├── README.md             # Tệp mô tả dự án, hướng dẫn cài đặt và sử dụng cơ bản
└── CONTRIBUTING.md       # Hướng dẫn dành cho những người muốn đóng góp vào dự án

• src/main/java/: Đây là nơi chứa toàn bộ mã nguồn Java cốt lõi của ứng dụng.
• src/main/resources/: Các tệp tài nguyên, chẳng hạn như tệp cấu hình, tệp XML, hoặc các mẫu dữ liệu khác mà ứng dụng cần trong quá trình chạy, được đặt ở đây.
• src/test/java/: Chứa mã nguồn cho các bài kiểm thử, đảm bảo rằng các tính năng của dự án hoạt động đúng như mong đợi.
• src/test/resources/: Các tài nguyên đặc biệt được sử dụng riêng cho mục đích kiểm thử sẽ được lưu trữ tại đây.
• build.gradle: Tệp này là trái tim của hệ thống xây dựng dự án, nơi định nghĩa các phần phụ thuộc, plugin và các tác vụ xây dựng tùy chỉnh.
• gradlew và gradlew.bat: Các script này cho phép bạn chạy các lệnh Gradle mà không cần cài đặt Gradle toàn cục trên hệ thống. Chúng đảm bảo rằng mọi người trong nhóm đều sử dụng cùng một phiên bản Gradle.
• settings.gradle: Trong các dự án lớn hơn với nhiều module con, tệp này sẽ xác định cấu trúc module của dự án.
• LICENSE và NOTICE: Cung cấp thông tin về giấy phép và quyền sở hữu trí tuệ của dự án.
• README.md: Tệp này thường là điểm khởi đầu cho bất kỳ ai mới tiếp cận dự án, cung cấp tổng quan và hướng dẫn nhanh.
• CONTRIBUTING.md: Hướng dẫn chi tiết cho các nhà phát triển muốn đóng góp mã nguồn hoặc tài liệu.

Tệp thực thi và khởi động dự án

Trong một dự án Iceberg được quản lý bằng Gradle, các tệp chính để khởi động và thực thi các tác vụ xây dựng là build.gradle cùng với các script wrapper gradlew và gradlew.bat. Chúng đóng vai trò quan trọng trong việc chuẩn bị và chạy ứng dụng.

• build.gradle: Tệp này không phải là một tệp "thực thi" theo nghĩa truyền thống, mà là một tệp cấu hình mà Gradle đọc để hiểu cách xây dựng dự án. Nó chứa định nghĩa về các plugin, thư viện phụ thuộc, và các tác vụ (tasks) mà bạn có thể chạy. Ví dụ, để biên dịch mã nguồn, bạn sẽ chạy một tác vụ đã được định nghĩa trong tệp này.
• gradlew và gradlew.bat: Đây là các "Gradle Wrapper" script. Thay vì yêu cầu người dùng cài đặt Gradle thủ công, bạn có thể sử dụng các script này để tự động tải xuống và sử dụng phiên bản Gradle được chỉ định.
  • Trên các hệ thống Unix/Linux/macOS, bạn sẽ sử dụng ./gradlew [tác vụ] để thực thi các tác vụ Gradle (ví dụ: ./gradlew build để biên dịch và đóng gói dự án).
  • Trên Windows, bạn sẽ sử dụng gradlew.bat [tác vụ] (ví dụ: gradlew.bat test để chạy các bài kiểm thử).

Cấu hình chính của dự án

Các tệp cấu hình chủ yếu trong một dự án Apache Iceberg sử dụng Gradle là build.gradle và settings.gradle. Chúng điều khiển hầu hết các khía cạnh của quá trình xây dựng.

• build.gradle:

  Tệp này quy định các khía cạnh cơ bản của quá trình xây dựng, bao gồm việc áp dụng các plugin cần thiết (ví dụ: để hỗ trợ Java), nơi Gradle nên tìm kiếm các thư viện phụ thuộc, và danh sách các thư viện mà dự án cần. Dưới đây là một ví dụ minh họa:

  plugins {
      id 'java' // Áp dụng plugin Java cho dự án
  }
  
  repositories {
      mavenCentral() // Khai báo kho lưu trữ Maven Central để tải các thư viện
      // Có thể thêm các kho lưu trữ khác như mavenLocal() hoặc các kho tùy chỉnh
  }
  
  dependencies {
      // Khai báo các thư viện phụ thuộc của dự án
      implementation 'org.apache.iceberg:iceberg-core:1.x.x' // Phiên bản mới nhất của core Iceberg
      testImplementation 'org.junit.jupiter:junit-jupiter-api:5.11.0' // Ví dụ về thư viện kiểm thử
      // Thêm các thư viện khác tùy theo nhu cầu của dự án
  }
  
  // Các tác vụ tùy chỉnh có thể được định nghĩa tại đây
  task runApplication(type: JavaExec) {
      classpath sourceSets.main.runtimeClasspath
      mainClass = 'com.example.iceberg.MainApp' // Điểm vào chính của ứng dụng
  }
  

• settings.gradle:

  Đối với các dự án lớn, đặc biệt là những dự án được chia thành nhiều module con, tệp settings.gradle sẽ chịu trách nhiệm xác định tên dự án gốc và các module con đó. Nó giúp Gradle hiểu được cấu trúc tổng thể của không gian làm việc.

  rootProject.name = 'iceberg-project' // Đặt tên cho dự án gốc
  
  // Bao gồm các module con nếu dự án được chia thành nhiều phần
  include 'iceberg-client', 'iceberg-utils', 'iceberg-connector'