Skip to content
BranchesTags

Repository files navigation

🚀 UPLOAD API

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

📖 Sobre o Projeto

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

🛠 Tecnologias

Backend

  • 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

Autenticação & Segurança

  • JWT (jsonwebtoken) - Tokens de autenticação
  • Bcrypt - Hash de senhas
  • Yup - Validação de schemas

Upload & Storage

  • Busboy - Parser multipart/form-data
  • Multer - Middleware para upload de arquivos
  • File System - Armazenamento local de arquivos

Desenvolvimento

  • Nodemon - Hot reload em desenvolvimento
  • Sucrase - Transpilador ES6+
  • ESLint + Prettier - Linting e formatação de código

🏗 Arquitetura

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 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 │
└─────────────────┘

📁 Estrutura do Projeto

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

🚀 Requisitos

Sistema

  • Node.js v14.18.1 ou superior
  • MySQL 5.7+ ou 8.0+
  • Yarn ou npm

📦 Instalação

  1. Clone o repositório
git clone <repository-url>cd api-upload-nodejs
  1. Instale as dependências
yarn install
# ou
npm install
  1. Configure o banco de dados
# Crie o banco MySQL
mysql -u root -p
CREATE DATABASE nome_do_banco;
  1. Configure as variáveis de ambiente
cp .env-sample .env
# Edite o arquivo .env com suas configurações

⚙️ Configuração

Arquivo .env

Crie o arquivo .env na raiz do projeto com as seguintes variáveis:

# AplicaçãoAPP_PORT=3333APP_ENVIRONMENT=developmentDOC_URL=https://docs.example.com# Banco de DadosDATABASE_DIALECT=mysqlDATABASE_HOST=localhostDATABASE_USERNAME=rootDATABASE_PASSWORD=senhaDATABASE_NAME=upload_api# AutenticaçãoBCRYPT_SALT=10

Configuração do Banco de Dados

Execute 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:all

🚀 Execução

Desenvolvimento

yarn dev
# ou
npm run dev

Produção

  1. Gere o build
./node_modules/sucrase/bin/sucrase ./src -d ./dist --transforms imports
  1. Configure permissões
mkdir -p tmp/uploads
chmod 0777 tmp/ -R
  1. Execute em produção
yarn serve
# ou
npm run serve

A aplicação estará disponível em http://localhost:3333

📡 API Endpoints

🔐 Autenticação

POST /sessions - Login

{
"email": "user@example.com",
"password": "password123"
}

Resposta:

{
"user": {
"id": 1,
"name": "João Silva",
"email": "user@example.com",
"platforms": []
},
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

POST /token-verify - Verificar Token

{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

👥 Usuários

POST /users - Criar Usuário

{
"name": "João Silva",
"email": "joao@example.com",
"password": "password123"
}

GET /users - Listar Usuários

Headers:Authorization: Bearer {token}

Query Params:?page=0&limit=10

GET /users/:id - Buscar Usuário

PATCH /users/:id - Atualizar Usuário

🏢 Plataformas

GET /platforms - Listar Plataformas

POST /platforms - Criar Plataforma

GET /platforms/:id - Buscar Plataforma

PATCH /platforms/:id - Atualizar Plataforma

DELETE /platforms/:id - Deletar Plataforma

📁 Arquivos

GET /files - Listar Arquivos

Headers:Authorization: Bearer {token}

POST /files - Upload de Arquivo

Headers:

  • Authorization: Bearer {token}
  • Content-Type: multipart/form-data

Body (FormData):

  • file: Arquivo a ser enviado
  • platform_id: ID da plataforma

GET /files/:id - Buscar Arquivo

DELETE /files/:id - Deletar Arquivo

🗄 Modelos de Dados

User (Usuário)

{id: INTEGER(PK),name: STRING,email: STRING(UNIQUE),password_hash: STRING,created_at: DATE,updated_at: DATE,deleted_at: DATE}

Platform (Plataforma)

{id: INTEGER(PK),title: STRING,slug: STRING,created_at: DATE,updated_at: DATE,deleted_at: DATE}

File (Arquivo)

{id: INTEGER(PK),name: STRING,// Nome originalpath: STRING,// Nome no sistema de arquivosurl: STRING,// URL para acesso ao arquivouser_id: INTEGER(FK),platform_id: INTEGER(FK),created_at: DATE,updated_at: DATE,deleted_at: DATE}

Relacionamentos

  • UserbelongsToManyPlatform (through: user_platforms)
  • UserhasManyFile
  • PlatformbelongsToManyUser (through: user_platforms)
  • FilebelongsToUser
  • FilebelongsToPlatform

✨ Funcionalidades

📤 Upload com Progresso

O sistema oferece upload de arquivos com monitoramento em tempo real:

  1. WebSocket Connection: Cliente conecta via Socket.IO
  2. Stream Upload: Arquivo é enviado via busboy em chunks
  3. Progress Events: Progresso é emitido via WebSocket
  4. File Storage: Arquivo é salvo no diretório tmp/uploads/
  5. Database Record: Registro é criado no banco de dados

🔒 Sistema de Autenticação

  • JWT Tokens: Autenticação stateless
  • Bcrypt Hash: Senhas criptografadas
  • Middleware Protection: Rotas protegidas automaticamente
  • Token Verification: Endpoint para validar tokens

🏢 Multi-Platform

  • 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

📁 File Storage

  • 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

📝 Exemplos

Upload de Arquivo com JavaScript

// Conectar WebSocketconstsocket=io('http://localhost:3333');// Monitorar progressosocket.on('upload-progress',(data)=>{console.log(`Progresso: ${data.progress}%`);});socket.on('complete',()=>{console.log('Upload concluído!');});// Fazer uploadconstformData=newFormData();formData.append('file',file);formData.append('platform_id','1');fetch('/files',{method: 'POST',headers: {'Authorization': `Bearer ${token}`},body: formData});

Upload com cURL

curl -X POST \
http://localhost:3333/files \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "file=@/path/to/file.pdf" \
-F "platform_id=1"

Autenticação

# 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..."

🚨 Limites e Considerações

  • 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)

🔧 Troubleshooting

Problemas Comuns

  1. Erro de conexão com banco

    • Verifique as credenciais no .env
    • Confirme se o MySQL está rodando
    • Execute as migrações

  2. 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

  3. Token inválido

    • Verifique se o token não expirou (1 dia)
    • Confirme o secret do JWT no .env

📄 Licença

Este projeto está sob a licença MIT.

Feito com ♥ por Thiago F. Rosa 👋 Entre em contato!

About

API de upload via Stream

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages