Guia 01 / 4
Glossário de Node.js
Compreender os conceitos de Node.js e o seu lugar no miniblogue.
Explicar cada noção ligando-a a uma operação do projeto.
01 · Situar-se no percurso confirmado
Retomamos o miniblogue «À table !» com mais estrutura e fronteiras explícitas entre servidor, ferramentas de compilação e navegador.
O projeto condutor e as competências visadas
Construir uma API HTTP local com os módulos nativos do Node.js: lista filtrável, ficha por identificador e adição validada; apresentar os seus dados no navegador e testar as respostas HTTP. Os dados de referência continuam a ser Soupe de carottes (20 min), Salade de tomates (10 min) e Tarte aux pommes (45 min).
Exemplo
01. Node.js : exposer et tester une API HTTP de recettes, puis la consommer depuis le navigateur.
02. SCSS : organiser la présentation du mini-blog en modules et compiler une feuille CSS.
03. TypeScript : modéliser les recettes et vérifier les réponses de l’API avant de les afficher.
Cada curso tem quatro guias: glossário, essenciais, oficina e recursos. Os ficheiros completos encontram-se no final da oficina.
Pré-requisitos e ambiente
Dominar as bases de JavaScript: funções, objetos, tabelas, condições, DOM e eventos. Utilizar o Node.js 24.x e o npm, um editor e um terminal. O servidor desta oficina não tem nenhuma dependência npm externa; não é necessária nenhuma framework para compreender os mecanismos HTTP.
Exemplo
mini-blog-node/
├── package.json
├── src/
│ ├── index.js
│ ├── server.js
│ └── recettes.js
├── public/
│ ├── index.html
│ ├── app.js
│ └── style.css
└── test/
└── api.test.js
Trabalhar num projeto mini-blog-node/ separado dos ficheiros do curso Technipédia. Guardar uma cópia de cada etapa funcional. Os caminhos dos exemplos partem da raiz deste projeto.
O método e os limites da oficina
Ler o vocabulário, reproduzir um pequeno exemplo, construir a oficina e verificar depois os seus resultados. As fichas curtas ilustram uma noção; apenas os ficheiros anunciados como completos constituem a aplicação a reproduzir.
Exemplo
Comprendre → reproduire → modifier → observer → expliquer
O ramo Node.js é uma nova implementação pedagógica: não reutiliza o servidor PHP/PDO do percurso para principiantes. O seu armazenamento inicial é em memória; o SCSS e o TypeScript prolongam este mesmo projeto Node.
02 · Compreender o ambiente Node.js
A linguagem continua a ser JavaScript; as API e o local de execução mudam.
Ambiente de execução e motor JavaScript
Um ambiente de execução fornece um contexto para executar uma linguagem. O Node.js permite executar JavaScript fora do navegador, com API de rede, de ficheiros e de processos.
Exemplo
node --version
node src/index.js
document e window não existem no lado do servidor. O ficheiro public/app.js, por seu lado, executa-se no navegador.
Processo e porta
O programa Node é um processo que pode escutar uma porta TCP. O navegador contacta um endereço composto por um protocolo, um anfitrião e uma porta.
Exemplo
http://127.0.0.1:3000
# HTTP, machine locale, port 3000
Dois servidores não podem geralmente escutar em simultâneo o mesmo endereço e a mesma porta.
Módulo ES e import/export
Um módulo expõe funções com export e carrega as de outro ficheiro com import. type: module em package.json escolhe este modo para os .js do projeto.
Exemplo
export function doubler(n) { return n * 2; }
// Dans un autre fichier :
import { doubler } from "./calcul.js";
Incluir a extensão .js nas importações relativas desta oficina.
Módulo nativo e pacote npm
Um módulo nativo vem com o Node.js, por exemplo node:http. Um pacote npm é instalado separadamente. O npm serve também para executar os scripts do projeto.
Exemplo
import { createServer } from "node:http";
// Aucun npm install nécessaire pour node:http.
package.json e ficheiro de bloqueio de dependências
package.json descreve o projeto, os seus scripts e as suas dependências. package-lock.json fixa as versões resolvidas após uma instalação npm para facilitar a reprodução.
Exemplo
npm run dev
npm test
A oficina Node sem dependências lança-se sem instalação. O SCSS e depois o TypeScript acrescentarão ferramentas de desenvolvimento e um ficheiro de bloqueio.
Ciclo de eventos e tratamento não bloqueante
O Node coordena os callbacks e as operações assíncronas. Esperar por uma leitura de ficheiro assíncrona permite ao processo tratar outros eventos; um cálculo JavaScript longo bloqueia sempre esse trabalho.
Exemplo
const contenu = await readFile(urlDuFichier);
async não torna automaticamente paralelo um cálculo pesado. Evitar as leituras síncronas no tratamento dos pedidos.
03 · Descrever uma API HTTP
O navegador e o servidor acordam endereços e dados.
Rota, método e recurso
Uma rota associa um método HTTP e um caminho a um tratamento. A coleção é /api/recettes; uma receita concreta é /api/recettes/1.
Exemplo
GET /api/recettes
GET /api/recettes/1
POST /api/recettes
Pedido, resposta e cabeçalho
O pedido transporta um método, um endereço, cabeçalhos e eventualmente um corpo. A resposta fornece um estado, cabeçalhos e um conteúdo.
Exemplo
Content-Type: application/json; charset=utf-8
Location: /api/recettes/4
Content-Type descreve o formato enviado; Location indica aqui o endereço do recurso criado.
JSON e contrato de dados
O JSON transporta objetos, tabelas e valores simples. O contrato do blogue escolhe números para a duração e as porções, e tabelas de cadeias para os ingredientes e os passos.
Exemplo
{"donnees":[{"id":1,"titre":"Soupe de carottes","duree_minutes":20,"portions":2,"categorie":"Plat","ingredients":["4 carottes"],"etapes":["Cuire."]}],"total":1}
Nos cursos de PHP/MySQL, os ingredientes e os passos eram texto de várias linhas. Uma futura ligação SQL a esta API terá de converter explicitamente esse texto em tabelas.
Estados HTTP úteis
200 indica uma leitura bem-sucedida, 201 uma criação. 400 assinala um pedido mal formado, 404 uma ausência, 405 um método recusado, 413 um corpo demasiado volumoso, 415 um formato recusado e 422 campos incoerentes.
Exemplo
JSON mal formé → 400
Durée négative dans un JSON valide → 422
Recette ajoutée → 201
Promessa, async e await
Uma promessa representa um resultado futuro ou uma falha. async permite utilizar await para esperar esse resultado na função; try/catch trata as falhas.
Exemplo
async function lireRecettes() {
const reponse = await fetch("http://127.0.0.1:3000/api/recettes");
if (!reponse.ok) throw new Error(`HTTP ${reponse.status}`);
return reponse.json();
}
fetch não rejeita automaticamente as respostas 404 ou 500: verificar reponse.ok.
Origem e CORS
A origem compreende protocolo, anfitrião e porta. O servidor da oficina serve a página e a API na mesma origem: nenhuma definição CORS é necessária.
Exemplo
Page : http://127.0.0.1:3000/
API : http://127.0.0.1:3000/api/recettes
Abrir a página a partir de outra porta ou de file:// altera esta situação; utilizar o URL servido pelo Node.