Node.js — Os fundamentos

Guia 01 / 4

Glossário de Node.js

Compreender os conceitos de Node.js e o seu lugar no miniblogue.

Resultado esperado :

Explicar cada noção ligando-a a uma operação do projeto.

Leitura
0%

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

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.
A reter :

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.

mini-blog-node/
├── package.json
├── src/
│   ├── index.js
│   ├── server.js
│   └── recettes.js
├── public/
│   ├── index.html
│   ├── app.js
│   └── style.css
└── test/
    └── api.test.js
A reter :

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.

Comprendre → reproduire → modifier → observer → expliquer
A reter :

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.

node --version
node src/index.js
A reter :

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.

http://127.0.0.1:3000
# HTTP, machine locale, port 3000
A reter :

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.

export function doubler(n) { return n * 2; }
// Dans un autre fichier :
import { doubler } from "./calcul.js";
A reter :

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.

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.

npm run dev
npm test
A reter :

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.

const contenu = await readFile(urlDuFichier);
A reter :

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.

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.

Content-Type: application/json; charset=utf-8
Location: /api/recettes/4
A reter :

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.

{"donnees":[{"id":1,"titre":"Soupe de carottes","duree_minutes":20,"portions":2,"categorie":"Plat","ingredients":["4 carottes"],"etapes":["Cuire."]}],"total":1}
A reter :

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.

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.

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();
}
A reter :

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.

Page : http://127.0.0.1:3000/
API : http://127.0.0.1:3000/api/recettes
A reter :

Abrir a página a partir de outra porta ou de file:// altera esta situação; utilizar o URL servido pelo Node.