A qui va dirigit
Aquesta guia va dirigida a tots aquells usuaris que vulguin actualitzar a Canigó 3.10 la seva aplicació Canigó 3.8.
Versió de Canigó
Els passos descrits en aquest document apliquen a la versió 3.10 del Framework Canigó.
Introducció
Aquesta versió és una versió LTS i es recomana actualitzar les aplicacions Canigó a aquesta versió per tal de tenir un suport continuat, així com la màxima estabilitat que proporciona una versió LTS.
L’objectiu d’aquesta guia és mostrar els procediments necessaris per a actualitzar una aplicació realitzada amb Canigó 3.8 a Canigó 3.10. El punt de partida d’aquesta guia és una aplicació creada amb l’arquetipus maven de Canigó 3.8.
Principals canvis entre Canigó 3.8 i Canigó 3.10
Les principals actualitzacions realitzades en la versió 3.10 respecte la versió 3.8 són les següents:
| Tecnologia / Dependència | Canigó 3.8 | Canigó 3.10 |
|---|---|---|
| Java (OpenJDK) | 17 | 21 |
| Spring Framework | 6.1.1 | 6.2.15 |
| Spring Boot | 3.1.4 | 3.5.9 |
| Spring Security | 6.1.3 | 6.5.7 |
| Spring Data | 3.1.4 | 3.5.9 |
| JUnit Jupiter | 5.10.1 | 5.14.2 |
| Hibernate | 5.6.7.Final | 6.6.39.Final |
| Jackson | 2.13.2 | 2.21.0 |
| Mockito | 5.7.0 | 5.21.0 |
| Log4j | 2.22.2 | 2.25.3 |
| SLF4J | 2.0.9 | 2.0.17 |
| QueryDSL | 5.0.0 | 6.11 |
| Swagger/OpenAPI | 3.0.0 | 2.8.4 (springdoc) |
| MongoDB Driver | 5.0.0 | 5.5.2 |
| Hamcrest | 2.2 | 3.0 |
Configuració prèvia
A la Matriu de Compatibilitats podeu consultar les versions dels mòduls i components de Canigó de les versions 3.8.x i 3.10.x.
Passes a realitzar
Un cop actualitzades les versions dels mòduls, segons s’indica a la secció anterior, serà necessari realitzar els següents passos:
1. Actualitzar la versió de Java de 17 a 21.
Assegureu-vos que el vostre entorn de desenvolupament i els servidors d’execució utilitzen OpenJDK 21. Actualitzeu el pom.xml:
<maven.compiler.source>21</maven.compiler.source>
<maven.compiler.target>21</maven.compiler.target>
2. Actualitzar Hibernate de 5.x a 6.x.
Canigó 3.10 utilitza Hibernate 6.6.39.Final. Això implica diversos canvis importants:
- Les classes de
org.hibernatehan canviat de paquet en alguns casos. - El dialecte de la base de dades s’ha d’actualitzar. Per exemple:
org.hibernate.dialect.MySQL8Dialectpassa aorg.hibernate.dialect.MySQLDialectorg.hibernate.dialect.PostgreSQLDialectes manté.org.hibernate.dialect.Oracle12cDialectpassa aorg.hibernate.dialect.OracleDialect
Exemple de configuració actualitzada al fitxer application.yml:
spring:
jpa:
properties:
hibernate:
dialect: org.hibernate.dialect.MySQLDialect
- Si s’utilitzen
@Typede Hibernate, cal migrar a la nova API deorg.hibernate.type.
3. Actualitzar QueryDSL de 5.x a 6.x.
Si el projecte utilitza QueryDSL, cal actualitzar les dependències a la versió 6.11 i verificar que la generació de codi Q-classes segueix funcionant correctament. Reviseu el plugin de maven apt-maven-plugin o querydsl-apt per assegurar la compatibilitat amb la nova versió.
<dependency>
<groupId>io.github.openfeign.queryds</groupId>
<artifactId>querydsl-jpa</artifactId>
<version>6.11</version>
</dependency>
4. Actualitzar la configuració de Swagger/OpenAPI: migració de Springfox a SpringDoc.
Canigó 3.8 utilitzava springfox-swagger2 3.0.0, mentre que Canigó 3.10 utilitza springdoc-openapi-starter-webmvc-ui 2.8.4. Això requereix diversos canvis importants:
4.1 Reemplaçar la dependència al pom.xml:
Eliminar:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
Afegir:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.8.4</version>
</dependency>
4.2 Eliminar la classe de configuració de Springfox (SwaggerConfig o similar) i reemplaçar-la amb la configuració de SpringDoc.
Eliminar la configuració basada en Docket:
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.OAS_30)
.select()
.apis(RequestHandlerSelectors.basePackage("cat.gencat.ctti"))
.paths(PathSelectors.any())
.build();
}
}
Reemplaçar per la configuració de SpringDoc amb OpenAPI i GroupedOpenApi:
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration
public class OpenApiConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info()
.title("API de l'aplicació")
.version("1.0")
.description("Documentació de l'API"));
}
@Bean
public GroupedOpenApi publicApi() {
return GroupedOpenApi.builder()
.group("public")
.pathsToMatch("/api/**")
.build();
}
}
4.3 Reemplaçar les anotacions de Swagger 2 (io.swagger.annotations) per les anotacions d’OpenAPI 3 (io.swagger.v3.oas.annotations) en tots els controladors i models.
| Anotació Springfox (Swagger 2) | Anotació SpringDoc (OpenAPI 3) |
|---|---|
@Api(value = "...") |
@Tag(name = "...") |
@ApiOperation(value = "...") |
@Operation(summary = "...") |
@ApiParam(value = "...") |
@Parameter(description = "...") |
@ApiResponse(code = 200, message = "") |
@ApiResponse(responseCode = "200", description = "") |
@ApiModel |
@Schema |
@ApiModelProperty |
@Schema |
@ApiIgnore |
@Hidden |
Exemple de migració d’un controlador:
Abans (Springfox / Swagger 2):
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
@RestController
@RequestMapping("/api/equipaments")
@Api(value = "Equipaments", tags = {"Equipaments"})
public class EquipamentController {
@GetMapping("/{id}")
@ApiOperation(value = "Obté un equipament per ID")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Equipament trobat"),
@ApiResponse(code = 404, message = "Equipament no trobat")
})
public ResponseEntity<Equipament> getById(
@ApiParam(value = "ID de l'equipament", required = true)
@PathVariable Long id) {
// ...
}
}
Després (SpringDoc / OpenAPI 3):
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
@RestController
@RequestMapping("/api/equipaments")
@Tag(name = "Equipaments", description = "Operacions sobre equipaments")
public class EquipamentController {
@GetMapping("/{id}")
@Operation(summary = "Obté un equipament per ID")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "Equipament trobat"),
@ApiResponse(responseCode = "404", description = "Equipament no trobat")
})
public ResponseEntity<Equipament> getById(
@Parameter(description = "ID de l'equipament", required = true)
@PathVariable Long id) {
// ...
}
}
Exemple de migració d’un model:
Abans (Springfox / Swagger 2):
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel(description = "Entitat Equipament")
public class Equipament {
@ApiModelProperty(value = "Identificador", example = "1")
private Long id;
@ApiModelProperty(value = "Nom de l'equipament", example = "Equipament 1")
private String nom;
}
Després (SpringDoc / OpenAPI 3):
import io.swagger.v3.oas.annotations.media.Schema;
@Schema(description = "Entitat Equipament")
public class Equipament {
@Schema(description = "Identificador", example = "1")
private Long id;
@Schema(description = "Nom de l'equipament", example = "Equipament 1")
private String nom;
}
4.4 Configuració al fitxer application.yml (opcional):
springdoc:
api-docs:
path: /api/v3/api-docs
swagger-ui:
path: /api/swagger-ui.html
operationsSorter: method
tagsSorter: alpha
4.5 Eliminar l’anotació @EnableSwagger2 o @EnableOpenApi si s’utilitza. SpringDoc no requereix cap anotació d’habilitació, ja que es configura automàticament mitjançant Spring Boot autoconfiguration.
La URL d’accés a Swagger segueix sent: http://localhost:8080/api/swagger-ui/index.html
5. Revisar canvis en Spring Boot 3.5.x respecte 3.1.x.
Algunes de les diferències a tenir en compte:
- Autoconfiguration: Spring Boot 3.5 pot introduir noves autoconfigurations. Reviseu que les propietats de
application.ymlsiguin compatibles. - Spring Security 6.5: Es recomana revisar la configuració de seguretat, ja que hi pot haver canvis en el
SecurityFilterChaini la gestió de CSRF. - Deprecations: Reviseu les classes i mètodes obsolets que puguin haver estat eliminats.
6. Revisar dependències de MongoDB.
Si la vostra aplicació utilitza MongoDB, actualitzeu les dependències del driver:
<dependency>
<groupId>org.mongodb</groupId>
<artifactId>mongodb-driver-sync</artifactId>
<version>5.5.2</version>
</dependency>
Per a reactiu:
<dependency>
<groupId>org.mongodb</groupId>
<artifactId>mongodb-driver-reactivestreams</artifactId>
<version>5.5.2</version>
</dependency>
Informació sobre mòduls migrats
S’indica el llistat de mòduls que han estat migrats de la versió 3.8 a la 3.10. Per cada mòdul cal modificar els intervals de les versions.
- canigo.root
- canigo.core
- canigo.persistence.core
- canigo.persistence.jpa
- canigo.persistence.mongodb
- canigo.security
- canigo.web.core
- canigo.web.rs
- canigo.support.mailing
- canigo.operation.logging
- canigo.test
- canigo.support.sftp
- canigo.integration.antivirus
- canigo.integration.notificacions.electroniques
- canigo.integration.pica
- canigo.integration.psgd
- canigo.integration.sarcat.pica
- canigo.integration.psis
canigo.root
No aplica realitzar accions addicionals relacionades amb la migració de 3.8 a 3.10.
canigo.core
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.core | [5.1.0, 5.2.0) | [5.4.0, 5.5.0) |
Hi ha uns certs aspectes a tenir en compte també per al connector core:
- La configuració del inicializador de propietats Yaml i propietats del mòdul configurador.
- Configuració del mòdul de logging.
- Configuració del mòdul de internacionalització.
canigo.persistence.core
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.persistence.core | [3.1.0, 3.2.0) | [3.4.0, 3.5.0) |
canigo.persistence.jpa
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.persistence.jpa | [3.1.0, 3.2.0) | [3.4.0, 3.5.0) |
-
S’ha actualitzat Hibernate de la versió 5.6.7.Final a la 6.6.39.Final. Això pot implicar canvis en els dialectes i en algunes APIs de mapping.
-
S’ha actualitzat jackson-databind de la 2.13.2 a la versió 2.21.0.
-
S’ha actualitzat mockito-core de la 5.7.0 a la versió 5.21.0.
-
Es pot consultar la documentació detallada d’aquest connector en el següent enllaç.
canigo.persistence.mongodb
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.persistence.mongodb | [3.1.0, 3.2.0) | [3.4.0, 3.5.0) |
- S’ha actualitzat mongo-java-driver de la 5.0.0 a la versió 5.5.2.
- S’ha actualitzat mongodb-driver-sync de la 4.6.0 a la versió 5.5.2.
- S’ha actualitzat mongodb-driver-reactivestreams de la 4.6.0 a la versió 5.5.2.
Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.
canigo.security
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.security | [3.1.0, 3.2.0) | [3.4.0, 3.5.0) |
- S’ha actualitzat Spring Security de la versió 6.1.3 a la 6.5.7. Reviseu la configuració de seguretat per possibles canvis en la API.
Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.
canigo.web.core
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.web.core | [3.1.0, 3.2.0) | [3.4.0, 3.5.0) |
canigo.web.rs
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.web.rs | [3.1.0, 3.2.0) | [3.4.0, 3.5.0) |
canigo.support.mailing
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.support.mailing | [3.1.0, 3.2.0) | [3.4.0, 3.5.0) |
Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.
canigo.operation.logging
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.operation.logging | [3.1.0, 3.2.0) | [3.4.0, 3.5.0) |
- S’ha actualitzat Log4j de la versió 2.22.2 a la 2.25.3.
Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.
canigo.test
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.test | [3.1.0, 3.2.0) | [3.4.0, 3.5.0) |
- S’ha actualitzat JUnit Jupiter de la versió 5.10.1 a la 5.14.2.
- S’ha actualitzat mockito-core de la versió 5.7.0 a la 5.21.0.
- S’ha actualitzat Hamcrest de la versió 2.2 a la 3.0.
canigo.support.sftp
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.support.sftp | [3.1.0, 3.2.0) | [3.4.0, 3.5.0) |
Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.
canigo.integration.antivirus
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.integration.antivirus | [3.1.0, 3.2.0) | [3.4.0, 3.5.0) |
Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.
canigo.integration.notificacions.electroniques
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.integration.notificacions.electroniques | [3.1.0, 3.2.0) | [3.4.0, 3.5.0) |
Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.
canigo.integration.pica
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.integration.pica | [3.1.2, 3.2.0) | [3.4.0, 3.5.0) |
Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.
canigo.integration.psgd
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.integration.psgd | [3.1.0, 3.2.0) | [3.4.0, 3.5.0) |
Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.
canigo.integration.sarcat.pica
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.integration.sarcat.pica | [3.1.4, 3.2.0) | [3.4.0, 3.5.0) |
Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.
canigo.integration.psis
- Actualitzar en el fitxer pom.xml els intervals de les dependències del mòdul:
| Mòdul | Interval de versions 3.8 | Interval de versions 3.10 |
|---|---|---|
| canigo.integration.psgd | [3.1.4, 3.2.0) | [3.4.0, 3.5.0) |
Per a més informació d’aquest connector i com configurar-lo, consultar la seva secció corresponent.