En l'ecosistema digital actual, la gestió de fitxers és un component crític de quasi qualsevol aplicació web moderna. Ja sigui per pujar imatges de perfil, documents PDF, factures o fitxers multimèdia, necessitem una solució que sigui escalable, segura i eficient. Emmagatzemar aquests fitxers directament al servidor de l'aplicació pot generar colls d'ampolla, costos impredictibles i riscos de pèrdua de dades. Aquí és on entra Amazon S3 (Simple Storage Service), un servei d'emmagatzematge d'objectes ofert per AWS que proporciona una durabilitat del 99.999999999% i una escalabilitat pràcticament il·limitada.
En aquest article et mostrarem com construir una API REST senzilla però robusta per pujar fitxers directament a un bucket d'Amazon S3 utilitzant Node.js, Express, Multer i AWS SDK v3. A més, explorarem bones pràctiques de seguretat, integració amb serveis cloud i com empreses com Q2BSTUDIO implementen solucions d'aquest tipus en projectes d'aplicacions a mida per als seus clients.
Aquest tutorial està pensat tant per a desenvolupadors que s'inicien a AWS com per a aquells que busquen optimitzar els seus processos de pujada de fitxers. Al llarg del text farem referències a conceptes com la ciberseguretat, la intel·ligència artificial (IA), els agents IA i la Business Intelligence (BI) amb Power BI, tots ells serveis que a Q2BSTUDIO integrem de forma natural en els nostres desenvolupaments.
Abans de començar, assegura't de tenir Node.js 18 o superior, un compte d'AWS actiu, un bucket de S3 creat i un usuari IAM amb accés programàtic (Access Key ID i Secret Access Key). Si encara no tens experiència amb AWS, no et preocupis: et guiarem pas a pas.
Pas 1: Creació del projecte
Obre la teva terminal i executa les ordres següents per crear un projecte nou i instal·lar les dependències necessàries:
mkdir s3-upload-apicd s3-upload-apinpm init -ynpm install express multer dotenv uuid @aws-sdk/client-s3
Els paquets instal·lats són: Express com a framework web, Multer per gestionar la càrrega de fitxers (en memòria), dotenv per a variables d'entorn, uuid per generar noms únics i el SDK v3 d'AWS per interactuar amb S3.
Pas 2: Variables d'entorn
Crearem un fitxer .env amb la configuració del nostre compte AWS i el bucket. Recorda substituir els valors amb les teves pròpies credencials. És fonamental no pujar aquest fitxer a repositoris públics; per això crearem també un .gitignore que exclogui node_modules i .env.
AWS_REGION=us-east-1AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXEMPLEAWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXEMPLEAWS_BUCKET_NAME=el-meu-bucket-uploadsPORT=3000
A Q2BSTUDIO sempre recomanem gestionar les credencials de manera segura, utilitzant serveis com AWS Secrets Manager o Azure Key Vault quan es passa a producció. Això forma part de les nostres pràctiques de ciberseguretat.
Pas 3: Configurar el client S3
Al fitxer principal de l'aplicació (per exemple index.js), importem el mòdul S3Client i l'inicialitzem amb les credencials:
import { S3Client } from '@aws-sdk/client-s3';const s3 = new S3Client({ region: process.env.AWS_REGION, credentials: { accessKeyId: process.env.AWS_ACCESS_KEY_ID, secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY, },});
Aquesta configuració és vàlida tant per a buckets a AWS com per a entorns multicloud (Azure/AWS) que gestionem a Q2BSTUDIO, on aprofitem les fortaleses de cada plataforma.
Pas 4: Configurar Multer amb emmagatzematge en memòria
Multer és un middleware de Node.js per gestionar la pujada de fitxers. Utilitzarem memoryStorage() perquè el fitxer es carregui en un buffer i el puguem enviar directament a S3 sense emmagatzemar-lo temporalment al disc del servidor:
import multer from 'multer';const upload = multer({ storage: multer.memoryStorage() });
Aquest enfocament és ideal per a API escalables, ja que evita escriptures locals i redueix la latència. A més, és compatible amb arquitectures serverless com AWS Lambda o Azure Functions, serveis que oferim com a part de les nostres solucions cloud.
Pas 5: Crear l'endpoint de pujada
Ara definirem una ruta POST que rebi un fitxer, generi un nom únic amb UUID i el pugi al bucket utilitzant l'ordre PutObject:
import { PutObjectCommand } from '@aws-sdk/client-s3';import { v4 as uuid } from 'uuid';
app.post('/upload', upload.single('file'), async (req, res) => { try { const filename = `${uuid()}-${req.file.originalname}`; await s3.send(new PutObjectCommand({ Bucket: process.env.AWS_BUCKET_NAME, Key: filename, Body: req.file.buffer, ContentType: req.file.mimetype, })); res.json({ success: true, filename }); } catch (error) { console.error(error); res.status(500).json({ success: false, message: 'Upload failed' }); }});
Aquest codi gestiona errors bàsics, però en un entorn de producció hauríem d'afegir validacions de tipus de fitxer, mida màxima i autenticació. A Q2BSTUDIO, quan desenvolupem aplicacions a mida, incloem capes de seguretat addicionals com autenticació JWT i polítiques d'accés basades en rols.
Pas 6: Iniciar el servidor
Afegeix el codi següent per engegar Express al port configurat:
const express = require('express');const app = express();const PORT = process.env.PORT || 3000;app.listen(PORT, () => console.log(`Server running on port ${PORT}`));
Executa npm start i la teva API estarà llesta a https://localhost:3000.
Pas 7: Provar amb Postman
Obre Postman i introdueix una sol·licitud POST a https://localhost:3000/upload. A Body, selecciona form-data, afegeix una clau anomenada file de tipus File i tria qualsevol imatge o document. En enviar, obtindràs una resposta com:
{ 'success': true, 'filename': '4c6ddcf2-profile.png' }
Verifica a la teva consola d'AWS S3 que el fitxer apareix al bucket.
Errors comuns i solucions
Durant el desenvolupament poden aparèixer errors com AccessDenied: significa que el teu usuari IAM no té permís per pujar objectes. Assegura't d'adjuntar una política que inclogui s3:PutObject. Un altre error típic és NoSuchBucket: revisa el nom del bucket i la regió. I si veus InvalidAccessKeyId, verifica les teves credencials. Aquestes pràctiques de gestió d'identitat són part de la ciberseguretat que implementem a Q2BSTUDIO per protegir les dades dels nostres clients.
Millores i propers passos
Un cop la pujada bàsica funciona, pots ampliar l'API amb funcionalitats addicionals:
Pujada múltiple de fitxers
Modifica Multer per acceptar diversos fitxers amb upload.array('files', maxCount) i processa cada un en un bucle.
URLs prefirmades (Pre-signed URLs)
Genera URL temporals perquè els usuaris puguin pujar fitxers directament des del frontend sense exposar les teves credencials. Això és útil en aplicacions amb React o Angular, i ho combinem amb serveis d'IA per classificar automàticament els documents pujats.
Validació de tipus i mida
Implementa un middleware personalitzat que rebutgi fitxers amb extensions perilloses o que excedeixin un límit (per exemple, 10 MB). Això és essencial per a la ciberseguretat i per evitar sobrecostos a S3.
Integració amb frontend
Connecta aquesta API a una aplicació React usant fetch o Axios. A Q2BSTUDIO desenvolupem aplicacions a mida amb stacks moderns com React, Vue o Angular, sempre sincronitzats amb el backend.
Ús de CloudFront per a distribució global
Per accelerar el lliurament de fitxers estàtics, pots col·locar CloudFront davant del teu bucket S3. Això redueix la latència i millora l'experiència de l'usuari, especialment si la teva audiència està distribuïda geogràficament.
Organització en carpetes
Pots estructurar els objectes a S3 utilitzant prefixos (per exemple, usuaris/{id}/imatges/) per facilitar la gestió i les polítiques de cicle de vida.
Casos d'ús empresarial i el valor de Q2BSTUDIO
A Q2BSTUDIO hem ajudat nombroses empreses a implementar sistemes de gestió documental basats en S3, combinats amb Business Intelligence amb Power BI per analitzar patrons d'ús, i amb agents IA que processen automàticament els fitxers pujats (extracció de dades, classificació, etc.). Per exemple, una asseguradora pot pujar parts d'accidents, i un agent IA extreu la informació clau i l'envia a un dashboard de Power BI per a la seva anàlisi.
El nostre equip d'experts en cloud (AWS i Azure) dissenya arquitectures escalables i segures, adaptades a les necessitats específiques de cada projecte. Ja sigui que necessitis una API simple de pujada de fitxers o un sistema complex de processament amb intel·ligència artificial, a Q2BSTUDIO oferim serveis de desenvolupament de programari a mida que integren aquestes tecnologies de manera natural.
Conclusió
Construir una API de pujada de fitxers amb Node.js i Amazon S3 és un procés directe un cop comprens el flux bàsic: el client envia el fitxer, Multer el captura en memòria, i el SDK d'AWS el transfereix al bucket. Aquest enfocament és escalable, segur i et prepara per integrar funcionalitats avançades com pre-signed URLs, validacions i automatitzacions amb IA.
La clau està a no limitar-se a la pujada simple: pensa com la teva aplicació gestionarà els fitxers després de pujar-los. La intel·ligència artificial i l'automatització poden transformar un simple repositori en un motor de negoci. A Q2BSTUDIO estem llestos per ajudar-te a fer aquest salt. Parlem del teu proper projecte?
