El Projecte | Sobre nosaltres | Contribuir | Donacions | Llicència
HOME Els meus cursos Finalitzats
◄ Anterior
◄

Configuració del teu Entorn de Desenvolupament

Següent ►
►

Un entorn mal preparat és la causa número u de frustració quan es comença amb Spring Boot: errors de compilació que semblen del framework però són de versió de Java, dependències que no es descarreguen, o un IDE que marca en vermell un projecte perfectament vàlid. Aquesta lliçó et guia per deixar la màquina llesta de manera verificable: instal·lar i comprovar el JDK 21, entendre l'elecció de Maven i el seu wrapper, triar IDE, disposar d'eines per provar l'API i tenir Docker preparat per als mòduls avançats. Acabarem amb una llista de comprovació que pots executar tal qual.

Contingut

  1. El JDK 21: instal·lació i verificació
  2. Gestionar diverses versions de Java amb SDKMAN!
  3. Maven enfront de Gradle, i per què aquest curs fa servir Maven
  4. El wrapper de Maven (mvnw)
  5. Triar un IDE: IntelliJ IDEA, Eclipse/STS i VS Code
  6. Eines per provar l'API
  7. Docker: requisit per als mòduls posteriors
  8. Llista de comprovació final
  9. Errors Habituals i Consells
  10. Exercicis

  1. El JDK 21: instal·lació i verificació

Spring Boot 3 exigeix Java 17 o superior. Farem servir Java 21, la versió LTS (suport a llarg termini) més recent i àmpliament adoptada en producció.

Necessites un JDK (Java Development Kit), no només un JRE: el JDK inclou el compilador javac, sense el qual Maven no pot construir res.

Distribucions disponibles

Totes implementen el mateix estàndard; la diferència rau en el suport i l'empaquetat.

Distribució Proveïdor Notes
Eclipse Temurin Adoptium L'opció per defecte recomanada: gratuïta, sense registre, multiplataforma
Amazon Corretto AWS Bona si desplegues a AWS; suport llarg
Azul Zulu Azul Systems Àmplia cobertura de plataformes
Oracle JDK Oracle Llicència amb condicions; innecessari per aprendre
OpenJDK de la distribució Debian, Ubuntu, Fedora Còmode a Linux, versió lligada a la distribució

Linux

En distribucions basades en Debian o Ubuntu:

# Actualitzar índexs i instal·lar el JDK 21 des dels repositoris
sudo apt update
sudo apt install openjdk-21-jdk

# Comprovar la instal·lació
java -version
javac -version

A Fedora o derivades de Red Hat:

sudo dnf install java-21-openjdk-devel
java -version

macOS

Amb Homebrew:

brew install --cask temurin@21

# Comprovar
java -version

# Veure tots els JDK instal·lats al sistema
/usr/libexec/java_home -V

Windows

Descarrega l'instal·lador .msi d'Eclipse Temurin 21 des d'adoptium.net i, durant la instal·lació, marca l'opció "Set JAVA_HOME variable". Després, a PowerShell:

java -version
javac -version
echo $env:JAVA_HOME

Interpretar la sortida

Una instal·lació correcta produeix una cosa així:

$ java -version
openjdk version "21.0.5" 2024-10-15 LTS
OpenJDK Runtime Environment Temurin-21.0.5+11 (build 21.0.5+11-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.5+11 (build 21.0.5+11-LTS, mixed mode)

Fixa't en tres coses:

  • 21.0.5: la versió major és 21. És l'únic crític.
  • 64-Bit Server VM: és una JVM de 64 bits, la que vols.
  • javac -version ha d'existir i coincidir. Si java respon però javac diu "ordre no trobada", has instal·lat un JRE o falta el paquet -devel/-jdk.

La variable JAVA_HOME

Maven i molts IDE localitzen el JDK a través de JAVA_HOME. Per comprovar-la:

# Linux / macOS
echo $JAVA_HOME
# Hauria d'imprimir alguna cosa com /usr/lib/jvm/java-21-openjdk-amd64

# Si està buida, fixa-la al teu ~/.bashrc o ~/.zshrc
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export PATH="$JAVA_HOME/bin:$PATH"

  1. Gestionar diverses versions de Java amb SDKMAN!

És habitual mantenir projectes amb Java 8, 17 i 21 alhora. SDKMAN! permet canviar de versió amb una ordre, sense tocar variables del sistema. Funciona a Linux i macOS (a Windows, mitjançant WSL o Git Bash).

# Instal·lar SDKMAN!
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

# Veure les versions de Java disponibles
sdk list java

# Instal·lar Temurin 21
sdk install java 21.0.5-tem

# Fer servir aquesta versió només al terminal actual
sdk use java 21.0.5-tem

# Fixar-la com a predeterminada del sistema
sdk default java 21.0.5-tem

# Comprovar quina està activa
sdk current java

Un detall molt útil: SDKMAN! reconeix un fitxer .sdkmanrc a l'arrel del projecte.

# .sdkmanrc a l'arrel de ciclourbana
java=21.0.5-tem
maven=3.9.9

Amb sdk env dins d'aquesta carpeta, el terminal canvia automàticament a les versions declarades. És la manera més neta de garantir que tot l'equip compila amb el mateix.

SDKMAN! també instal·la Maven, Gradle i altres eines:

sdk install maven
sdk list maven

  1. Maven enfront de Gradle, i per què aquest curs fa servir Maven

Totes dues són eines de construcció: descarreguen dependències, compilen, executen proves i empaqueten. Spring Boot les admet totes dues amb la mateixa qualitat.

Criteri Maven Gradle
Fitxer de construcció pom.xml (XML declaratiu) build.gradle / build.gradle.kts (Groovy o Kotlin)
Corba d'aprenentatge Baixa: estructura rígida i predictible Mitjana-alta: és un llenguatge de programació
Verbositat Alta Baixa
Velocitat de compilació Bona Millor: memòria cau de tasques i compilació incremental
Flexibilitat Limitada, per convenció Molt alta, scripts arbitraris
Documentació i exemples Majoritària al món Spring Abundant, però menys freqüent als tutorials
Ús típic Aplicacions empresarials Android, projectes grans o multimòdul

Aquest curs fa servir Maven per tres raons pràctiques:

  1. El pom.xml és declaratiu i explícit: es llegeix de dalt a baix i no amaga lògica. Quan s'aprèn, això importa més que la velocitat.
  2. La immensa majoria de la documentació de Spring i de les respostes que trobaràs fan servir Maven.
  3. És l'opció per defecte de Spring Initializr, l'eina amb què crearàs el projecte a la lliçó 01-03.

Si la teva empresa fa servir Gradle, tot el que aprenguis aquí es trasllada gairebé literalment: canvien la sintaxi del fitxer de construcció i els noms de les tasques, no els conceptes.

Comprovar Maven

mvn -version

Sortida esperada:

Apache Maven 3.9.9
Maven home: /home/usuari/.sdkman/candidates/maven/current
Java version: 21.0.5, vendor: Eclipse Adoptium

Fixa't en l'última línia: Maven informa de quin JDK està fent servir. Si diu Java version: 17, Maven no està veient el teu JDK 21 encara que java -version sí que ho digui; revisa JAVA_HOME.

  1. El wrapper de Maven (mvnw)

Aquí ve una bona notícia: no necessites instal·lar Maven per seguir aquest curs.

Spring Initializr genera al projecte un wrapper: dos scripts (mvnw per a Linux/macOS i mvnw.cmd per a Windows) i una carpeta .mvn/wrapper amb la configuració. La primera vegada que l'executes, el wrapper descarrega la versió exacta de Maven que el projecte declara i la fa servir.

# En lloc de: mvn clean package
./mvnw clean package

# A Windows (PowerShell o CMD)
mvnw.cmd clean package

Avantatges, i són importants:

  • Reproductibilitat: tot l'equip i el servidor d'integració contínua fan servir la mateixa versió de Maven, sense coordinar-se.
  • Zero instal·lació: algú clona el repositori i construeix sense instal·lar res més que el JDK.
  • Versionat: la versió de Maven s'actualitza canviant un fitxer i es revisa com qualsevol altre canvi de codi.

La versió concreta viu aquí:

# .mvn/wrapper/maven-wrapper.properties
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip

En aquest curs sempre farem servir ./mvnw. Si tens Maven instal·lat, mvn funcionarà igual, però acostuma't al wrapper: és la convenció professional.

Un detall habitual a Linux/macOS: si en clonar un repositori ./mvnw diu "permís denegat", falta el bit d'execució.

chmod +x mvnw

  1. Triar un IDE: IntelliJ IDEA, Eclipse/STS i VS Code

Pots seguir el curs amb qualsevol dels tres. Això és el que aporta cadascun:

IDE Edició gratuïta Punts forts Inconvenients
IntelliJ IDEA Community (suficient per al curs) El millor autocompletat i refactorització de Java del mercat; excel·lent depurador El suport específic de Spring (navegació de beans, autocompletat d'application.properties) només és a Ultimate
Eclipse / Spring Tool Suite (STS) Sí, tot gratuït STS és Eclipse amb eines Spring ja incloses: plafó de beans, arrencada d'aplicacions Boot, edició assistida de propietats Interfície menys polida; consumeix força memòria
VS Code + Extension Pack for Java Sí Lleuger, arrenca ràpid, mateix editor per a frontend i backend; extensió "Spring Boot Extension Pack" molt completa Menys potent en refactoritzacions grans

Què instal·lar en cada cas

IntelliJ IDEA Community: descarrega'l de jetbrains.com o instal·la'l amb la Toolbox App. Reconeix projectes Maven automàticament en obrir la carpeta que conté el pom.xml.

Spring Tool Suite: descarrega STS 4 des de spring.io/tools. Es distribueix com un JAR autoexecutable que desplega l'IDE. Per importar el projecte: File → Import → Existing Maven Projects.

VS Code: instal·la aquestes dues extensions des del Marketplace.

# Des de la línia d'ordres, si tens l'ordre "code" disponible
code --install-extension vscjava.vscode-java-pack
code --install-extension vmware.vscode-boot-dev-pack
  • Extension Pack for Java: compilador, depurador, suport Maven, executor de proves.
  • Spring Boot Extension Pack: autocompletat a application.properties, plafó de Spring Boot Dashboard per arrencar i aturar aplicacions, navegació entre endpoints.

Configuració recomanada, sigui quin sigui l'IDE

  1. Comprova que l'IDE fa servir el JDK 21, no un d'intern més antic. A IntelliJ: File → Project Structure → SDK. A VS Code: la variable java.configuration.runtimes.
  2. Activa la construcció automàtica i el formatatge en desar.
  3. Configura la codificació en UTF-8 per a tot el projecte. Els noms de les estacions de Ribalta porten accents, i una codificació mal fixada produeix "Estació Nord".

  1. Eines per provar l'API

Construiràs una API REST, així que necessites alguna cosa amb què cridar-la. Val la pena conèixer diverses opcions:

curl

És pràcticament a qualsevol sistema i és el llenguatge comú de la documentació.

# Petició GET simple
curl http://localhost:8080/api/v1/estacions

# Veure també les capçaleres de resposta i el codi d'estat
curl -i http://localhost:8080/api/v1/estacions

# Petició POST amb cos JSON
curl -X POST http://localhost:8080/api/v1/estacions \
  -H "Content-Type: application/json" \
  -d '{"nom":"Plaça Major","capacitat":24}'

Les opcions que més faràs servir: -i (incloure capçaleres), -X (mètode HTTP), -H (capçalera), -d (cos), -s (silenciós).

HTTPie

Sintaxi més llegible i acolorit del JSON de sortida. Molt còmode per explorar.

# Instal·lació
sudo apt install httpie        # Debian/Ubuntu
brew install httpie            # macOS

# GET
http :8080/api/v1/estacions

# POST: els parells clau=valor es converteixen en JSON automàticament
http POST :8080/api/v1/estacions nom="Plaça Major" capacitat:=24

Detall important: nom="Plaça Major" genera una cadena, mentre que capacitat:=24 (amb :=) genera un nombre. És un error freqüent enviar "24" quan l'API espera un enter.

Postman

Aplicació gràfica. El seu valor rau a organitzar col·leccions de peticions desades, fer servir variables d'entorn ({{baseUrl}}), gestionar tokens d'autenticació i compartir-ho tot amb l'equip. Molt útil a partir del mòdul 5, quan apareguin els tokens JWT.

Fitxers .http

És la meva recomanació per a aquest curs. Són fitxers de text pla, versionables a Git, que IntelliJ (de manera nativa) i VS Code (extensió REST Client) executen directament des de l'editor.

### Llistar totes les estacions de Ribalta
GET http://localhost:8080/api/v1/estacions
Accept: application/json

### Consultar una estació concreta
GET http://localhost:8080/api/v1/estacions/1
Accept: application/json

### Donar d'alta una estació nova
POST http://localhost:8080/api/v1/estacions
Content-Type: application/json

{
  "nom": "Parc del Riu",
  "adreca": "Passeig Fluvial 12",
  "capacitat": 18
}

Cada bloc separat per ### és una petició independent amb el seu propi botó d'execució. Crea el fitxer api-ciclourbana.http a l'arrel del projecte i ves-hi afegint cada endpoint que construeixis: acabaràs amb documentació viva i executable de tota l'API.

  1. Docker: requisit per als mòduls posteriors

Als mòduls 1 a 3 no necessites Docker. A partir del mòdul 4 sí que convé tenir-lo, i és imprescindible als mòduls 6, 7 i 8:

  • Mòdul 4: aixecar un PostgreSQL real sense instal·lar-lo a la teva màquina.
  • Mòdul 6: Testcontainers arrenca bases de dades efímeres per a les proves d'integració.
  • Mòduls 7 i 8: empaquetar CicloUrbana com a imatge i desplegar-la.

Instal·lació

  • Linux: instal·la Docker Engine seguint la guia oficial de la teva distribució i afegeix el teu usuari al grup docker per no necessitar sudo.
  • macOS i Windows: instal·la Docker Desktop. A Windows, activa la integració amb WSL 2, que és on funcionarà millor.
# A Linux, després d'instal·lar
sudo usermod -aG docker $USER
# Tanca la sessió i torna a entrar perquè el canvi tingui efecte

Verificació

docker --version
docker compose version

# Prova real: descarrega i executa una imatge mínima
docker run --rm hello-world

Un assaig del que faràs al mòdul 4, només per comprovar que tot funciona:

# Arrencar un PostgreSQL temporal per a CicloUrbana
docker run --name ciclourbana-db \
  -e POSTGRES_DB=ciclourbana \
  -e POSTGRES_USER=ciclo \
  -e POSTGRES_PASSWORD=secret \
  -p 5432:5432 \
  -d postgres:16

# Comprovar que està en marxa
docker ps

# Aturar-lo i eliminar-lo quan acabis
docker stop ciclourbana-db && docker rm ciclourbana-db

  1. Llista de comprovació final

Desa aquest script com a verificar-entorn.sh i executa'l. Si totes les línies responen, el teu entorn està llest.

#!/usr/bin/env bash
echo "=== Verificació de l'entorn per a CicloUrbana ==="

echo "--- 1. JDK (s'espera 21) ---"
java -version 2>&1 | head -1
javac -version 2>&1

echo "--- 2. JAVA_HOME ---"
echo "JAVA_HOME=${JAVA_HOME:-NO DEFINIDA}"

echo "--- 3. Maven (opcional: farem servir ./mvnw) ---"
mvn -version 2>/dev/null | head -1 || echo "Maven no instal·lat (correcte si fas servir el wrapper)"

echo "--- 4. Eines HTTP ---"
curl --version 2>/dev/null | head -1 || echo "curl NO disponible"
http --version 2>/dev/null || echo "HTTPie no instal·lat (opcional)"

echo "--- 5. Docker (necessari des del mòdul 4) ---"
docker --version 2>/dev/null || echo "Docker no instal·lat (encara no és obligatori)"

echo "--- 6. Git ---"
git --version 2>/dev/null || echo "Git NO disponible"

echo "=== Fi de la verificació ==="

Execució:

chmod +x verificar-entorn.sh
./verificar-entorn.sh

Taula del que s'ha de complir abans de passar a la lliçó 01-03:

Requisit Com es comprova Obligatori ja?
JDK 21 instal·lat java -version mostra 21.x Sí
Compilador disponible javac -version mostra 21.x Sí
JAVA_HOME apuntant al JDK 21 echo $JAVA_HOME Sí
IDE instal·lat i fent servir el JDK 21 Configuració del projecte Sí
Client HTTP curl --version Sí
Connexió a internet Maven descarregarà dependències Sí
Git git --version Recomanat
Docker docker run --rm hello-world Des del mòdul 4

Errors Habituals i Consells

  • Tenir instal·lat un JRE en lloc d'un JDK. El símptoma és clar: java funciona però javac no existeix, i Maven falla amb "No compiler is provided in this environment". Instal·la el paquet amb sufix -jdk o -devel.
  • JAVA_HOME apuntant a una altra versió. java -version diu 21 però Maven compila amb 17. Fia't sempre de la línia Java version: que imprimeix mvn -version, perquè és la que realment fa servir la construcció.
  • Fer servir mvn en lloc de ./mvnw. Funciona, però introdueix una variable no controlada: la versió de Maven de la teva màquina. En equip, això acaba en un «a mi em compila».
  • Oblidar chmod +x mvnw després de clonar. Error molt freqüent a Linux i macOS.
  • La primera construcció triga moltíssim. És normal: Maven descarrega centenars d'artefactes a ~/.m2/repository. Les següents fan servir aquesta memòria cau local i són ràpides. No cancel·lis el procés a mitges, perquè pots deixar fitxers corromputs a la memòria cau.
  • Consell — treballar sense connexió. Si la memòria cau queda inconsistent, esborra la carpeta problemàtica dins de ~/.m2/repository i torna a construir. Esborrar tot ~/.m2 funciona, però obliga a descarregar-ho tot un altre cop.
  • Consell — codificació UTF-8. Fixa-la a l'IDE i al sistema. Ribalta té estacions com «Estació Nord» i veuràs els accents trencats al primer descuit.

Exercicis

Exercici 1

Prepara la teva màquina i documenta'n el resultat: instal·la el JDK 21, comprova java -version, javac -version i JAVA_HOME, i indica quina distribució has triat i per què.

Exercici 2

El teu equip manté un sistema antic amb Java 17 i vol començar CicloUrbana amb Java 21 al mateix portàtil. Explica com ho resoldries amb SDKMAN! i escriu les ordres concretes, incloent-hi com deixar fixada la versió per projecte sense canviar la del sistema.

Exercici 3

Crea un fitxer api-ciclourbana.http amb tres peticions a endpoints que encara no existeixen: llistar estacions, obtenir l'estació amb id 1 i crear l'estació "Estació Nord" amb capacitat 30. Escriu a més l'ordre curl equivalent a la tercera.

Solucions

Solució 1

En una màquina Ubuntu:

sudo apt update
sudo apt install openjdk-21-jdk

java -version
# openjdk version "21.0.5" 2024-10-15 LTS

javac -version
# javac 21.0.5

echo $JAVA_HOME
# (buit) → cal definir-la

# Esbrinar la ruta real del JDK
readlink -f $(which javac)
# /usr/lib/jvm/java-21-openjdk-amd64/bin/javac

# Afegir al ~/.bashrc
echo 'export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64' >> ~/.bashrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

echo $JAVA_HOME
# /usr/lib/jvm/java-21-openjdk-amd64

Elecció justificada: l'OpenJDK dels repositoris és còmode a Linux perquè s'actualitza amb el sistema. Si necessites una versió concreta i reproductible entre màquines, és preferible Temurin via SDKMAN!.

Solució 2

# 1. Instal·lar SDKMAN! si no el tens
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

# 2. Instal·lar les dues versions que necessita l'equip
sdk install java 17.0.13-tem
sdk install java 21.0.5-tem

# 3. Mantenir 17 com a versió per defecte del sistema (el projecte antic)
sdk default java 17.0.13-tem

Perquè CicloUrbana faci servir 21 sense canviar la versió global, es declara a l'arrel del projecte:

# ciclourbana/.sdkmanrc
java=21.0.5-tem
maven=3.9.9

I a cada sessió de terminal dins del projecte:

cd ciclourbana
sdk env          # activa les versions del .sdkmanrc
java -version    # 21.0.5
cd ..
java -version    # torna a 17.0.13 (la global)

El fitxer .sdkmanrc es versiona a Git, així que qualsevol membre de l'equip obté la mateixa configuració en clonar. Amb sdk env install s'instal·len de cop les versions que faltin.

Solució 3

### 1. Llistar totes les estacions de la xarxa de Ribalta
GET http://localhost:8080/api/v1/estacions
Accept: application/json

### 2. Detall de l'estació amb id 1
GET http://localhost:8080/api/v1/estacions/1
Accept: application/json

### 3. Alta de l'estació "Estació Nord"
POST http://localhost:8080/api/v1/estacions
Content-Type: application/json
Accept: application/json

{
  "nom": "Estació Nord",
  "adreca": "Avinguda Estació 3",
  "capacitat": 30
}

L'equivalent en curl de la tercera petició:

curl -i -X POST http://localhost:8080/api/v1/estacions \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "nom": "Estació Nord",
        "adreca": "Avinguda Estació 3",
        "capacitat": 30
      }'

Nota sobre les capçaleres: Content-Type descriu el que envies; Accept declara el que vols rebre. Confondre-les és una font clàssica de respostes 415 i 406, que veurem al mòdul 3.

Conclusió

Ja tens l'entorn preparat i, més important encara, verificat: JDK 21 amb JAVA_HOME correcte, un IDE que apunta a aquest JDK, un client HTTP per provar l'API i Docker llest per quan el necessitis. Has vist també per què el curs fa servir Maven i per què sempre invocarem ./mvnw en lloc de mvn: reproductibilitat per a tu i per a tot l'equip.

A la lliçó següent, Creant la teva Primera Aplicació Spring Boot, generaràs el projecte ciclourbana amb Spring Initializr, escriuràs el teu primer endpoint GET /api/v1/estacions amb les estacions de Ribalta, l'executaràs amb ./mvnw spring-boot:run i l'empaquetaràs en un JAR executable.

◄ Anterior
◄
Següent ►
►

Curs de Spring Boot

Mòdul 1: Introducció a Spring Boot

Mòdul 2: Conceptes bàsics de Spring Boot

Mòdul 3: Construint serveis web RESTful

Mòdul 4: Accés a dades amb Spring Boot

Mòdul 5: Seguretat a Spring Boot

Mòdul 6: Proves a Spring Boot

Mòdul 7: Funcions avançades de Spring Boot

Mòdul 8: Desplegament d'aplicacions Spring Boot

Mòdul 9: Rendiment i monitoratge

Mòdul 10: Millors pràctiques i consells

El Projecte | Sobre nosaltres | Contribuir | Donacions | Llicència
© Copyright 2026. Tots els drets reservats