Spring AI · Spring AI ilə ilk addımlar · Dərs 2

Yeni Spring layihəsinin yaradılması

Spring AI ilə tanış ol, yeni Spring layihəsi yarat və kurs boyunca inkişaf etdirəcəyin tətbiqin əsasını qur.

Yeni Spring layihəsinin yaradılması

study-coach layihəsini adi Java veb tətbiqi kimi başlat. Bu dərsdə uzaq modeldən asılılıq yaratmazdan əvvəl build-in, HTTP endpoint-in və test quruluşunun işlədiyini yoxlayacağıq. Hələ provayder hesabı və ya açarı lazım deyil.

1. Dərs üçün versiyaları seç və yoxla

Bu məşqdə JDK 21 və Maven 3.9.11 istifadə et. POM-da Spring Boot 3.5.9, Spring AI BOM isə 1.1.8 versiyasına sabitlənib. Bunlar dərs üçün seçilmiş konkret versiyalardır; ən yeni buraxılış olduqları iddia edilmir. Spring AI 1.1 sənədləri Spring Boot 3.4.x və 3.5.x versiyalarını dəstəkləyir. Miqrasiya və uyğunluq tələblərini araşdırmadan Boot 4 və ya Spring AI 2 ilə əvəz etmə. Spring AI quraşdırılması

Ayrıca məşq qovluğu yarat. Əmrlər macOS/Linux üçün POSIX shell ilə yazılıb; Windows-da WSL istifadə et və ya fayl əmrlərini uyğunlaşdır. Maven əvvəlcədən quraşdırılmalıdır. mvn -version nəticəsində gözlənilən Maven versiyası ilə yanaşı Java 21-in də göstərildiyini yoxla; Maven redaktordan fərqli JDK istifadə edə bilər.

sh
mkdir study-coach
cd study-coach
mkdir -p src/main/java/academy/study src/main/resources
mkdir -p src/test/java/academy/study
java -version
mvn -version

Spring Initializr vasitəsilə də Maven/Java/Jar layihəsi yarada bilərsən: group academy, artifact study-coach, package isə academy.study olsun. Generatorun seçimləri zamanla dəyişdiyi üçün bu məşqin dəqiq quruluşunu aşağıdakı tam fayllar müəyyən edir. Generator wrapper yaradıbsa, onu saxla, amma nəticələri müqayisə edəndə eyni Maven versiyasından istifadə et.

2. Asılılıqları müəyyən et

Bu tam pom.xml faylını layihənin kökündə saxla:

xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.5.9</version>
    <relativePath/>
  </parent>
  <groupId>academy</groupId>
  <artifactId>study-coach</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <properties>
    <java.version>21</java.version>
    <spring-ai.version>1.1.8</spring-ai.version>
  </properties>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-bom</artifactId>
        <version>${spring-ai.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

Boot parent asılılıq və plugin versiyalarını idarə edir. AI BOM Spring AI asılılıqlarının versiyalarını uyğunlaşdırır; onu import etmək model kitabxanası əlavə etmir və provayderə şəbəkə çağırışı etmir. Web starter Spring MVC-ni və daxili serveri əlavə edir. Validation starter növbəti dərsdə sorğu məhdudiyyətlərini yoxlayacaq. Test asılılıqları test scope-da qalır.

Model starter-ini tətbiq dərsində ayrıca əlavə edəcəyik. Bu mərhələdə OpenAI üçün konfiqurasiya yoxdur. Maven keşdə olmayan asılılıqlar üçün yenə artefakt repozitoriyasına çıxış tələb edir. İlk Spring Boot tətbiqi

3. Tətbiqin giriş nöqtəsini əlavə et

src/main/java/academy/study/StudyCoachApplication.java faylını saxla:

Java
package academy.study;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class StudyCoachApplication {
    public static void main(String[] args) {
        SpringApplication.run(StudyCoachApplication.class, args);
    }
}

Tətbiq siniflərini academy.study paketində və ya onun alt paketlərində saxla ki, tətbiq annotasiyasının standart komponent axtarışı onları tapsın. main metodu Spring tətbiq kontekstini, web starter olduqda isə daxili serveri başladır.

src/main/java/academy/study/StatusController.java faylını saxla:

Java
package academy.study;

import java.util.Map;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class StatusController {
    @GetMapping("/api/status")
    public Map<String, String> status() {
        return Map.of("status", "ready");
    }
}

Bu endpoint yalnız lokal tətbiqin həmin sorğuya cavab verə bildiyini göstərir. O, verilənlər bazasının vəziyyətini və ya model provayderinin hazır olub-olmadığını yoxlamır. Sonradan model provayderi əlçatmaz olsa belə, status sorğusu uğurlu ola bilər.

4. Lokal icra mühitini açıq göstər

src/main/resources/application.yml faylını saxla:

yaml
server:
  address: 127.0.0.1
  port: 8080
spring:
  application:
    name: study-coach

Loopback ünvanına bağlanmaq autentifikasiyası olmayan bu məşqi lokal kompüterdə saxlayır. 8080 portu artıq tutulubsa, sənə aid digər prosesi dayandır və ya başqa port seçib curl əmrlərini yenilə. Lokal port ziddiyyətini aradan qaldırmaq üçün tətbiqi internetə açma.

Bu məşqdə yalnız bir tətbiq konfiqurasiya formatı istifadə et. YAML ilə yanaşı köhnə application.properties faylını saxlamaq parametrlərin üstünlük sırasını araşdırmağı çətinləşdirə bilər. Adi icra konfiqurasiyası versiya nəzarətində saxlanıla bilər; provayderin məxfi açarları isə saxlanılmamalıdır.

5. HTTP davranışını və paketləməni yoxla

src/test/java/academy/study/StatusControllerTest.java faylını saxla:

Java
package academy.study;

import org.junit.jupiter.api.Test;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

class StatusControllerTest {
    @Test
    void reportsApplicationStatus() throws Exception {
        var mvc = MockMvcBuilders.standaloneSetup(new StatusController()).build();
        mvc.perform(get("/api/status"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.status").value("ready"));
    }
}

Bu, ayrıca işləyən Spring MVC testidir. Serveri və bütöv tətbiq kontekstini başlatmadan sorğunun metoda yönləndirilməsini və JSON serializasiyasını yoxlayır. Buna görə növbəti dərsdə Spring AI əlavə ediləndən sonra da provayder açarı olmadan işləyə biləcək.

Layihənin kökündən icra et:

sh
mvn clean verify
java -jar target/study-coach-0.0.1-SNAPSHOT.jar

verify testləri işlədir və tətbiqi paketləyir. Boot plugin JAR-ı java -jar ilə başlana bilən formaya salır. Server işlək qalsın, ikinci terminalda bu əmri icra et:

sh
curl --fail-with-body http://127.0.0.1:8080/api/status

Cavabın gövdəsi belədir:

json
{"status":"ready"}

Test və real HTTP sorğusu fərqli hissələri yoxlayır: birincisi MVC davranışını ayrıca sınaqdan keçirir; ikincisi paketlənmiş tətbiqin başlamasını və socket-ə bağlanmasını da yoxlayır. İşin bitəndə serveri Ctrl+C ilə dayandır.

6. Nəticəni izah et və bir dəyişiklik sına

Tapşırıq: konfiqurasiyada portu 8081 et, yenidən build et, JAR-ı başlat və yeni portda status endpoint-inə sorğu göndər. Sonra 8080-i bərpa et ki, növbəti dərsin əmrləri uyğun gəlsin. Ayrıca MVC testində portu niyə dəyişməyin lazım olmadığını izah et.

Cavabın yoxlanması: MockMvc sorğuları test prosesinin daxilində yönləndirir, ona görə konfiqurasiya edilmiş TCP portunu dinləmir. JAR isə həmin portu dinləyir. Tətbiq ready qaytarmalı, build nəticəsində bir testin keçdiyi görünməlidir. Bu nəticələrin heç biri model inteqrasiyasının işlədiyini sübut etmir; dərsdə hələ belə inteqrasiya əlavə edilməyib.

Kompilyasiya dəstəklənməyən release xətası verirsə, Java 21 parametrini silmək əvəzinə Maven-in JDK-sını yoxla. JAR icra olunmursa, Boot parent/plugin hissəsini və verify əmrini işlətdiyini yoxla. Status endpoint-i və testi də daxil olmaqla eyni qovluqla növbəti dərsə davam et.