API robusta para upload de arquivos com suporte a arquivos grandes (até 4GB), monitoramento de progresso em tempo real via WebSocket e armazenamento local de arquivos.
Sobre | Tecnologias | Arquitetura | Estrutura | Requisitos | Instalação | Configuração | Execução | API | Modelos | Funcionalidades | Exemplos
Esta API foi desenvolvida para gerenciar uploads de arquivos grandes com as seguintes características principais:
- Upload Assíncrono: Suporte a arquivos até 4GB com monitoramento de progresso
- WebSocket: Comunicação em tempo real para acompanhar o progresso do upload
- Storage Local: Armazenamento seguro de arquivos no servidor
- Autenticação JWT: Sistema completo de autenticação e autorização
- Multi-Platform: Sistema de plataformas para organização de usuários e arquivos
- Paginação: Listagens otimizadas com paginação automática
- Node.js (v14.18+) - Runtime JavaScript
- Express.js - Framework web minimalista
- Socket.IO - Comunicação WebSocket em tempo real
- Sequelize - ORM para banco de dados
- MySQL - Banco de dados relacional
- JWT (jsonwebtoken) - Tokens de autenticação
- Bcrypt - Hash de senhas
- Yup - Validação de schemas
- Busboy - Parser multipart/form-data
- Multer - Middleware para upload de arquivos
- File System - Armazenamento local de arquivos
- Nodemon - Hot reload em desenvolvimento
- Sucrase - Transpilador ES6+
- ESLint + Prettier - Linting e formatação de código
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend │ │ Upload API │ │ File System │
│ │ │ │ │ │
│ - Interface │◄──►│ - Express.js │◄──►│ - Local Store │
│ - WebSocket │ │ - Socket.IO │ │ - tmp/uploads/ │
│ - Progress │ │ - JWT Auth │ │ - Static Files │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ MySQL │
│ │
│ - Users │
│ - Platforms │
│ - Files │
│ - Relations │
└─────────────────┘
api-upload-nodejs/
├── src/
│ ├── app/
│ │ ├── controllers/ # Controladores da aplicação
│ │ │ ├── FileController.js
│ │ │ ├── PlatformController.js
│ │ │ ├── SessionController.js
│ │ │ ├── UploadController.js
│ │ │ └── UserController.js
│ │ ├── middlewares/ # Middlewares customizados
│ │ │ ├── auth.js # Autenticação JWT
│ │ │ ├── Pagination.js # Paginação automática
│ │ │ └── PlatformUserVerification.js
│ │ └── models/ # Modelos do banco de dados
│ │ ├── File.js
│ │ ├── Platform.js
│ │ └── User.js
│ ├── config/ # Configurações
│ │ ├── auth.js # Config JWT
│ │ └── database.js # Config MySQL
│ ├── database/ # Migrações e seeders
│ │ ├── migrations/
│ │ └── seeders/
│ ├── services/ # Serviços externos
│ │ └── StorageService.js # Serviço de arquivos
│ ├── app.js # Configuração da aplicação
│ ├── routes.js # Definição de rotas
│ └── server.js # Servidor principal
├── tmp/
│ └── uploads/ # Uploads temporários
├── package.json
└── README.md
- Node.js v14.18.1 ou superior
- MySQL 5.7+ ou 8.0+
- Yarn ou npm
- Clone o repositório
git clone <repository-url>
cd api-upload-nodejs- Instale as dependências
yarn install
# ou
npm install- Configure o banco de dados
# Crie o banco MySQL
mysql -u root -p
CREATE DATABASE nome_do_banco;- Configure as variáveis de ambiente
cp .env-sample .env
# Edite o arquivo .env com suas configuraçõesCrie o arquivo .env na raiz do projeto com as seguintes variáveis:
# Aplicação
APP_PORT=3333
APP_ENVIRONMENT=development
DOC_URL=https://docs.example.com
# Banco de Dados
DATABASE_DIALECT=mysql
DATABASE_HOST=localhost
DATABASE_USERNAME=root
DATABASE_PASSWORD=senha
DATABASE_NAME=upload_api
# Autenticação
BCRYPT_SALT=10Execute as migrações para criar as tabelas:
# Rode as migrações
npx sequelize-cli db:migrate
# (Opcional) Execute os seeders para dados iniciais
npx sequelize-cli db:seed:allyarn dev
# ou
npm run dev- Gere o build
./node_modules/sucrase/bin/sucrase ./src -d ./dist --transforms imports- Configure permissões
mkdir -p tmp/uploads
chmod 0777 tmp/ -R- Execute em produção
yarn serve
# ou
npm run serveA aplicação estará disponível em http://localhost:3333
{
"email": "user@example.com",
"password": "password123"
}Resposta:
{
"user": {
"id": 1,
"name": "João Silva",
"email": "user@example.com",
"platforms": []
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}{
"name": "João Silva",
"email": "joao@example.com",
"password": "password123"
}Headers: Authorization: Bearer {token}
Query Params: ?page=0&limit=10
Headers: Authorization: Bearer {token}
Headers:
Authorization: Bearer {token}Content-Type: multipart/form-data
Body (FormData):
file: Arquivo a ser enviadoplatform_id: ID da plataforma
{
id: INTEGER (PK),
name: STRING,
email: STRING (UNIQUE),
password_hash: STRING,
created_at: DATE,
updated_at: DATE,
deleted_at: DATE
}{
id: INTEGER (PK),
title: STRING,
slug: STRING,
created_at: DATE,
updated_at: DATE,
deleted_at: DATE
}{
id: INTEGER (PK),
name: STRING, // Nome original
path: STRING, // Nome no sistema de arquivos
url: STRING, // URL para acesso ao arquivo
user_id: INTEGER (FK),
platform_id: INTEGER (FK),
created_at: DATE,
updated_at: DATE,
deleted_at: DATE
}- User
belongsToManyPlatform (through: user_platforms) - User
hasManyFile - Platform
belongsToManyUser (through: user_platforms) - File
belongsToUser - File
belongsToPlatform
O sistema oferece upload de arquivos com monitoramento em tempo real:
- WebSocket Connection: Cliente conecta via Socket.IO
- Stream Upload: Arquivo é enviado via busboy em chunks
- Progress Events: Progresso é emitido via WebSocket
- File Storage: Arquivo é salvo no diretório tmp/uploads/
- Database Record: Registro é criado no banco de dados
- JWT Tokens: Autenticação stateless
- Bcrypt Hash: Senhas criptografadas
- Middleware Protection: Rotas protegidas automaticamente
- Token Verification: Endpoint para validar tokens
- Platform Management: Criação e gestão de plataformas
- User-Platform Association: Usuários podem pertencer a múltiplas plataformas
- Platform Verification: Middleware para verificar acesso
- Local Storage: Armazenamento seguro em tmp/uploads/
- Static File Serving: URLs diretas para acesso aos arquivos
- File Management: Upload e deleção de arquivos locais
// Conectar WebSocket
const socket = io('http://localhost:3333');
// Monitorar progresso
socket.on('upload-progress', (data) => {
console.log(`Progresso: ${data.progress}%`);
});
socket.on('complete', () => {
console.log('Upload concluído!');
});
// Fazer upload
const formData = new FormData();
formData.append('file', file);
formData.append('platform_id', '1');
fetch('/files', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`
},
body: formData
});curl -X POST \
http://localhost:3333/files \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file=@/path/to/file.pdf" \
-F "platform_id=1"# Login
curl -X POST \
http://localhost:3333/sessions \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "password123"
}'
# Usar token nas requisições
curl -X GET \
http://localhost:3333/files \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."- Tamanho Máximo: 4GB por arquivo
- Formatos: Todos os formatos são suportados
- Concurrent Uploads: Suporte a múltiplos uploads simultâneos
- Storage: Armazenamento local em tmp/uploads/ (configure permissões adequadas para produção)
-
Erro de conexão com banco
- Verifique as credenciais no
.env - Confirme se o MySQL está rodando
- Execute as migrações
- Verifique as credenciais no
-
Upload falhando
- Verifique as permissões da pasta
tmp/uploads/ - Confirme se o diretório tmp/uploads/ existe
- Verifique o tamanho do arquivo (máx 4GB)
- Verifique o espaço em disco disponível
- Verifique as permissões da pasta
-
Token inválido
- Verifique se o token não expirou (1 dia)
- Confirme o secret do JWT no
.env
Este projeto está sob a licença MIT.
Feito com ♥ por Thiago F. Rosa 👋 Entre em contato!