Le but de ce tutoriel est de montrer comment, en moins de 15 minutes, on peut écrire un micro-service Spring capable de stocker et récupérer des fichiers dans Alibaba Cloud Object Storage Service (OSS) en s’appuyant sur Spring AI pour générer automatiquement la plupart du code.

1. Prérequis

• Un compte Alibaba Cloud actif et un bucket OSS créé (région cn-beijing conseillée).
• Des variables d’environnement ALI_KEY et ALI_SECRET définies localement.
• JDK 11 ou 17.

2. Génération du squelette Spring Boot via Spring AI

Utilisez la CLI spring ai generate (ou l’IDE intégré InsCode) avec la requête suivante :

Crée un projet Spring Boot 3.2 minimal exposant deux endpoints REST :
POST /fichiers pour l’upload
GET /fichiers/{nom} pour le téléchargement
Utilise Alibaba Cloud OSS SDK 3.17+ et Spring AI pour commenter le code en français.

Le générateur produit automatiquement :

• pom.xml avec les bonnes dépendances
• application.yml pré-configuré
• les classes de service et contrôleur annotées

3. Configuration simplifiée

alibaba:
  cloud:
    oss:
      endpoint: https://oss-cn-beijing.aliyuncs.com
      access-key: ${ALI_KEY}
      secret-key: ${ALI_SECRET}
      bucket: ${BUCKET_NAME}

4. Service de stockage OSS

@Service
public class StockageCloud {

    private final OSS client;
    private final String bucket;

    public StockageCloud(OssProperties props) {
        this.bucket = props.bucket();
        this.client = new OSSClientBuilder()
                .build(props.endpoint(), props.accessKey(), props.secretKey());
    }

    public String deposer(MultipartFile fichier) throws IOException {
        String nom = UUID.randomUUID() + "-" + fichier.getOriginalFilename();
        ObjectMetadata meta = new ObjectMetadata();
        meta.setContentType(fichier.getContentType());
        client.putObject(bucket, nom, fichier.getInputStream(), meta);
        return nom;
    }

    public void recuperer(String nom, HttpServletResponse resp) throws IOException {
        OSSObject obj = client.getObject(bucket, nom);
        resp.setContentType(obj.getObjectMetadata().getContentType());
        IOUtils.copy(obj.getObjectContent(), resp.getOutputStream());
    }
}

5. Contrôleur REST

@RestController
@RequestMapping("/fichiers")
public class FichierCtrl {

    private final StockageCloud service;

    public FichierCtrl(StockageCloud service) { this.service = service; }

    @PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public Map<String,String> upload(@RequestPart MultipartFile file) throws IOException {
        String id = service.deposer(file);
        return Map.of("id", id, "url", "/fichiers/" + id);
    }

    @GetMapping("/{id}")
    public void download(@PathVariable String id, HttpServletResponse resp) throws IOException {
        service.recuperer(id, resp);
    }
}

6. Gestion d’erreurs

Ajoutez un @ControllerAdvice pour transformer les exceptions OSS en réponses JSON lisibles :

@ExceptionHandler(OSSException.class)
public ResponseEntity<?> handle(OSSException ex) {
    return ResponseEntity.status(ex.getStatusCode())
                         .body(Map.of("erreur", ex.getErrorMessage()));
}

7. Test rapide avec curl

# Upload
curl -F fichier=@photo.jpg http://localhost:8080/fichiers

# Download
curl -O http://localhost:8080/fichiers/123e4567-photo.jpg

8. Optimisations possibles

• Upload multipart côté client pour les gros fichiers.
• Signature d’URL côté serveur pour éviter de passer par le backend.
• Cache HTTP + ETag pour les téléchargements fréquents.
• Retry automatique avec Spring Retry.

L’ensemble du projet est prêt à être déployé sur InsCode : un clic suffit pour lancer le conteneur et exposer l’URL publique.