Apostila — Microserviços Acadêmicos (VS Code + Terminal)

1. Estrutura do Projeto

microservices-academico-vscode/
├─ requirements.txt
├─ run_all.py
├─ requests.http
├─ services/
│  ├─ academico.py
│  ├─ salas.py
│  ├─ turmas.py
│  └─ notas.py
└─ tests/
   └─ test_e2e.py

Sempre execute comandos na pasta raiz, onde ficam requirements.txt e run_all.py.

2. Preparando o Ambiente (Terminal do VS Code)

2.1 Abrir o Terminal

1. No VS Code: View → Terminal (atalho: Ctrl + `).
2. Garanta que o caminho atual é a pasta raiz do projeto.

2.2 Criar e ativar o ambiente virtual

Windows:

python -m venv .venv
.venv\Scripts\activate

Linux/Mac:

python3 -m venv .venv
source .venv/bin/activate

2.3 Instalar dependências

pip install -r requirements.txt

3. Subir os Serviços

3.1 Todos de uma vez

python run_all.py

Saída esperada (exemplo):

Services up: academico:8000, salas:8001, turmas:8002, notas:8003
Uvicorn running on http://127.0.0.1:8000
Uvicorn running on http://127.0.0.1:8001
Uvicorn running on http://127.0.0.1:8002
Uvicorn running on http://127.0.0.1:8003

3.2 Porta ocupada (Windows)

Se der erro ao “bindar” a 8000:

netstat -aon | findstr :8000
taskkill /PID <PID> /F

Ou altere a porta do acadêmico no run_all.py para 8010 e use http://127.0.0.1:8010.

3.3 Subir um serviço individual (opcional)

uvicorn services.academico:app --port 8000
uvicorn services.salas:app     --port 8001
uvicorn services.turmas:app    --port 8002
uvicorn services.notas:app     --port 8003

4. Testes pelo Terminal (curl)

Abra outro terminal (ícone + na aba do Terminal) e ative o .venv novamente.

4.1 Health checks

curl 127.0.0.1:8000/health
curl 127.0.0.1:8001/health
curl 127.0.0.1:8002/health
curl 127.0.0.1:8003/health

4.2 Fluxo completo

1) Criar turma e 2) matricular aluno:

curl -X POST 127.0.0.1:8002/turmas -H "Content-Type: application/json" -d "{\"turma_id\":\"ADS101\",\"professor\":\"simone\"}"
curl -X POST 127.0.0.1:8002/matriculas -H "Content-Type: application/json" -d "{\"turma_id\":\"ADS101\",\"aluno_id\":\"A1\"}"

3) Agendar aula (via orquestrador):

curl -X POST 127.0.0.1:8000/agendar-aula -H "Content-Type: application/json" -d "{\"turma_id\":\"ADS101\",\"sala\":\"LAB-01\",\"inicio\":\"2025-11-05T19:00\",\"fim\":\"2025-11-05T21:00\"}"

4) Lançar nota (via orquestrador) e 5) consultar:

curl -X POST 127.0.0.1:8000/lancar-nota -H "Content-Type: application/json" -d "{\"turma_id\":\"ADS101\",\"aluno_id\":\"A1\",\"avaliacao\":\"P1\",\"nota\":8.5}"
curl 127.0.0.1:8003/nota/ADS101/A1

5. Testes no VS Code (REST Client)

1. Instale a extensão REST Client.
2. Abra o arquivo requests.http.
3. Clique em Send Request em cada bloco para executar as requisições.

6. Menu Interativo (CLI)

Baixe o arquivo menu_cli_academico.py e rode em um segundo terminal (com o venv ativo):

python menu_cli_academico.py

Opções do menu:

• Health (todos)
• Criar turma
• Matricular aluno
• Listar alunos da turma
• Agendar aula (orquestrador)
• Lançar nota (orquestrador)
• Consultar notas de um aluno

7. Tabela de Endpoints

8. Solução de Problemas (FAQ)

Erro: Could not open requirements file

Você está na pasta services. Suba um nível: cd .. e rode o comando na raiz.

Error: Got unexpected extra arguments (on http://127.0.0.1:8000)

Você colou o endereço após uvicorn. Use o formato correto: uvicorn services.academico:app --port 8000 ou simplesmente python run_all.py.

[Errno 13] ... proibida pelas permissões de acesso (porta 8000)

Outro processo está usando a porta. Encontre o PID: netstat -aon | findstr :8000 e mate com taskkill /PID <PID> /F, ou troque a porta para 8010 no run_all.py.

Pip desatualizado

Opcional: python -m pip install --upgrade pip.

9. Próximos Passos (Extensões didáticas)

• Cancelar/Reagendar aula (liberar reserva em salas + atualizar turmas).
• Timeout/Retry no academico ao chamar serviços dependentes.
• Persistência com SQLite por serviço.
• Contract tests entre academico e os demais.