ฉันโคลนที่เก็บ glaforge/gemini-interactions-api-sdk ลงในสภาพแวดล้อมแซนด์บ็อกซ์และตรวจสอบฐานของโค้ด เลย์เอาต์โปรเจ็กต์ และไฟล์การกำหนดค่าเรียบร้อยแล้ว
ด้านล่างนี้คือการวิเคราะห์และรายละเอียดโครงสร้างไฟล์ pom.xml ของสถาปนิก รวมถึงวิธีที่โครงสร้างนี้รองรับวงจรการสร้าง การทดสอบ การแพ็กเกจ และการเผยแพร่ CI/CD ของโปรเจ็กต์
โปรเจ็กต์นี้มีโครงสร้างเป็นไลบรารี Java สมัยใหม่ที่ออกแบบมาเพื่อเชื่อมต่อกับ Google Gemini Interactions API โดยมีเป้าหมายเป็น Java 21 (LTS) และแสดงการกำหนดค่า Maven ที่ซับซ้อนสูงซึ่งอิงตามโปรไฟล์ที่จัดการทุกอย่างตั้งแต่การคอมไพล์หลักไปจนถึงการลงนาม การเผยแพร่ไปยัง Maven Central โดยอัตโนมัติ และการแพ็กเกจส่วนหน้าเวอร์ชันทดลองสำหรับการติดตั้งใช้งานแบบไร้เซิร์ฟเวอร์ใน Google Cloud Run
1. พิกัดและข้อมูลเมตาของโปรเจ็กต์
ที่ด้านบนของไฟล์ จะมีการกำหนดข้อมูลเมตาและพิกัดของโปรเจ็กต์ Maven พื้นฐานดังนี้
<groupId>io.github.glaforge</groupId>
<artifactId>gemini-interactions-api-sdk</artifactId>
<version>0.10.2-SNAPSHOT</version>
<name>Gemini Interactions API SDK</name>
<description>Google Gemini Interactions API SDK</description>
- JDK เป้าหมาย: พร็อพเพอร์ตี้จะระบุแหล่งที่มาและความเข้ากันได้ของเป้าหมายของ Java 21 ซึ่งช่วยให้ใช้ฟีเจอร์ Java สมัยใหม่ได้ (บันทึก การจับคู่รูปแบบ เธรดเสมือน ฯลฯ)
xml <properties> <maven.compiler.source>21</maven.compiler.source> <maven.compiler.target>21</maven.compiler.target> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> </properties> - การระบุแหล่งที่มา: ระบุใบอนุญาต Apache 2.0 และระบุแหล่งที่มาของโปรเจ็กต์ให้กับนักพัฒนาแอป Guillaume Laforge (
glaforge)
2. ทรัพยากร Dependency และการจัดการทรัพยากร Dependency
ตัวเลือกทรัพยากร Dependency แสดงให้เห็นถึงสแต็กที่มองไปข้างหน้าอย่างมาก โดยเลือกใช้ไลบรารียอดนิยมรุ่นถัดไป
ก. การย้ายข้อมูลการขึ้นต่อกันหลักและ Jackson 3.x
SDK ใช้ Jackson 3.0.0 สำหรับการประมวลผล JSON
```xml
* **Architectural Note:** Jackson is undergoing a major package rename for version 3.x, changing its Maven group ID fromcom.fasterxml.jacksontotools.jackson. This POM imports thejackson-bom(Bill of Materials) version3.0.0and utilizes the newtools.jackson.core:jackson-databind` ทำให้ SDK มีขนาดเล็กมากและล้ำหน้ากว่าใคร
ข. การทดสอบและการขึ้นต่อกันของยูทิลิตี
ในส่วน <scope>test</scope> โปรเจ็กต์จะดึงเครื่องมือสำหรับการตรวจสอบและเซิร์ฟเวอร์จำลองมาใช้ ดังนี้
1. JUnit 6:
xml
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>6.0.2</version>
<scope>test</scope>
</dependency>
ใช้ JUnit 6.0.2 ที่ทันสมัยที่สุดสำหรับการทดสอบหน่วยและการทดสอบการผสานรวม
2. MockWebServer:
xml
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>mockwebserver</artifactId>
<version>4.12.0</version>
<scope>test</scope>
</dependency>
ใช้เพื่อจำลองการตอบกลับ HTTP จาก Gemini API ระหว่างการทดสอบการผสานรวมในเครื่อง
3. Javelit:
xml
<dependency>
<groupId>io.javelit</groupId>
<artifactId>javelit</artifactId>
<version>0.86.0</version>
<scope>test</scope>
</dependency>
เฟรมเวิร์กที่มีน้ำหนักเบาและสง่างามซึ่งใช้ในโฟลเดอร์ทดสอบโดยเฉพาะเพื่อสร้าง UI บนเว็บ ("ฟรอนท์เอนด์ของ Research") สำหรับการโต้ตอบกับ SDK
3. โปรไฟล์: สถาปัตยกรรมวงจรของแอปที่ขับเคลื่อนด้วยโปรไฟล์
pom.xmlโปรไฟล์ Maven 4 รายการแต่ละรายการจะทำหน้าที่ในขั้นตอนสถาปัตยกรรมที่เฉพาะเจาะจง ดังนี้
โปรไฟล์ 1: deployment
ออกแบบมาเพื่อจัดแพ็กเกจ SDK รุ่นมาตรฐานพร้อมเอกสารประกอบและแหล่งที่มาของ API แบบเต็ม
* พื้นที่จัดเตรียม: กำหนดค่าไดเรกทอรีการจัดเตรียมในเครื่องที่ target/staging-deploy โดยใช้ <altDeploymentRepository>
* ปลั๊กอิน:
* maven-javadoc-plugin (v3.5.0): จัดแพ็กเกจ Javadoc
* maven-source-plugin (v3.3.0): จัดแพ็กเกจไฟล์ต้นฉบับ Java ดิบ
โปรไฟล์ 2: publication
โปรไฟล์นี้มีไว้สำหรับการเผยแพร่ไลบรารีไปยังรีจิสทรีสาธารณะ และใช้ JReleaser (v1.22.0) แทนกลไกการเผยแพร่ Maven แบบเดิมที่มีขนาดใหญ่
* GitHub Release: สร้างบันทึกการเปลี่ยนแปลงที่สวยงามและอัตโนมัติตาม Conventional Commits โดยจะลบล้างรีลีสที่มีอยู่หากจำเป็น
* การลงนาม PGP: กำหนดค่าให้ลงนามในอาร์ติแฟกต์การเผยแพร่ทั้งหมดโดยอัตโนมัติผ่าน PGP (<armored>true</armored>)
* การติดตั้งใช้งาน Maven Central: ติดตั้งใช้งานอาร์ติแฟกต์ที่ลงนามแล้วจากไดเรกทอรี target/staging-deploy ไปยัง Sonatype Central (https://central.sonatype.com/api/v1/publisher) โดยตรง
โปรไฟล์ 3: release
ทำหน้าที่เป็นผู้ประสานงานของขั้นตอนการเผยแพร่ โดยกำหนดค่า maven-release-plugin (v3.3.1) เพื่อทำให้งาน Git เป็นแบบอัตโนมัติ ดังนี้
* ขั้นตอนการทำงานอัตโนมัติ:
* เรียกใช้การยืนยัน clean verify
* เพิ่มเวอร์ชัน ยืนยันการเปลี่ยนแปลง และติดแท็กที่เก็บ (v@{project.version}) โดยใช้รูปแบบข้อความยืนยัน chore: Releasing version...
* เรียกใช้การเผยแพร่โดยการเรียกใช้ deploy jreleaser:full-release ด้วย -DskipTests ซึ่งจะเปิดใช้งานทั้งโปรไฟล์ deployment และ publication
โปรไฟล์ 4: deploy-frontend
โปรไฟล์อัจฉริยะที่ช่วยแก้ปัญหาที่ไม่เหมือนใคร นั่นคือการแพ็กเกจคลาสทดสอบแบบทดลองบนเว็บ (ResearchFrontend.java ซึ่งอยู่ใน src/test/java) และการนำไปใช้งานจริงเป็นคอนเทนเนอร์แบบไร้เซิร์ฟเวอร์
* ปลั๊กอินการประกอบ: ใช้ maven-assembly-plugin (v3.6.0) กับตัวอธิบายที่กำหนดเอง src/assembly/frontend-deployment.xml เพื่อผสานคลาสหลัก คลาสทดสอบ และการอ้างอิงทั้งหมดที่กำหนดขอบเขตการทดสอบ (รวมถึง Javelit และ OkHttp) ลงใน Uber-JAR ที่เรียกใช้ได้รายการเดียว
* คลาสเป้าหมาย: กำหนดค่ารายการ Manifest ของ Main-Class ให้ชี้ไปยัง io.github.glaforge.gemini.interactions.ResearchFrontend
* บริบทการนำไปใช้งาน: ระบบจะคัดลอกและนำ JAR ที่สร้างขึ้นนี้ไปใช้งานใน Google Cloud Run โดยตรงโดยใช้รูปภาพฐาน Java 25 (us-central1-docker.pkg.dev/serverless-runtimes/google-24/runtimes/java25) โดยไม่ต้องใช้ Dockerfile ตามที่ระบุไว้ใน researcher-deployment.md
4. การผสานรวมกับ GitHub Actions (CI/CD)
สถาปัตยกรรมโปรไฟล์จะมิเรอร์เวิร์กโฟลว์ GitHub ที่อยู่ใน .github/workflows/
build.yml(CI): เรียกใช้./mvnw verifyใน Pull Request หรือคอมมิตไปยัง Branchmainเพื่อให้มั่นใจว่าการคอมไพล์ การทดสอบ และทรัพยากร Dependency จะได้รับการแก้ไขอย่างราบรื่นrelease.yml(CD): เวิร์กโฟลว์นี้จะทำงานเมื่อทริกเกอร์ด้วยตนเอง (workflow_dispatch) โดยจะทำดังนี้bash ./mvnw -ntp -B -Prelease release:prepare release:performคำสั่งนี้ใช้โปรไฟล์releaseซึ่งจะอัปเดตเวอร์ชันโดยอัตโนมัติ พุชแท็ก Git สร้าง Javadoc และแหล่งที่มา ลงนามในอาร์ติแฟกต์ คอมไพล์โปรเจ็กต์ พุชรุ่นไปยัง Sonatype และร่างหมายเหตุรุ่นของ GitHub
สรุป
pom.xml ใน gemini-interactions-api-sdk เป็นตัวอย่างที่ยอดเยี่ยมของ Declarative DevOps โดยจะทำให้ไลบรารีหลักมีขนาดเล็กมาก (ใช้เฉพาะ Jackson 3.x) แต่ยังคงห่อหุ้มการแพ็กเกจ การลงนาม การสร้างเอกสาร และความสามารถในการติดตั้งใช้งานส่วนหน้าแบบ Cloud-Native ที่ซับซ้อนไว้ในโปรไฟล์ที่นำกลับมาใช้ใหม่ได้อย่างสะอาด