Carregando agora
Desenvolvimento de Software Node.js Tutoriais Técnicos , , , , ,

Documentação Automática no Node.js com Fastify e Zod: Um Guia Prático

Você é do time que ama organizar o caos ou, pelo menos, fingir que consegue? Bora falar de um backend bonitinho e organizadinho, porque hoje a gente vai criar um backend tipado com Fastify e Zod. Tudo isso com muito amor, carinho, e claro, aquela dose de caos programático que todo dev adora (ou finge que não odeia).

Preparando o Terreno

Antes de colocar a mão na massa, vamos configurar nosso projeto do zero absoluto. Abra seu terminal favorito (ou o que menos trava) e digite:

pnpm init

Depois disso, vamos instalar os pacotes que serão nossos melhores amigos nessa jornada:

pnpm add fastify @fastify/swagger @fastify/swagger-ui @fastify/cors fastify-type-provider-zod zod
pnpm add -D typescript tsx @types/node

É isso mesmo: instalamos o Fastify, o Zod e outros pacotinhos mágicos. A ideia é que nosso backend valide as requisições, documente as rotas, e ainda faça café (ok, essa parte ainda não é possível).

Configurando o Ambiente

Crie o arquivo tsconfig.json para configurar o TypeScript com o comando:

tsc --init

E substitua o conteúdo pelo padrão de configuração do Node.js 20. O repositório tsconfig-bases da Microsoft tem um modelo que você pode copiar direto para lá:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true
  }
}

Agora, no arquivo package.json, vamos adicionar um script para facilitar a execução do servidor:

"scripts": {
  "start": "tsx src/server.ts"
}

Perfeito! Estamos prontos para codar. Crie a pasta src e, dentro dela, o arquivo server.ts.

O Primeiro Olá Mundo

No arquivo server.ts, começamos com as importações básicas:

import Fastify from "fastify";
import { fastifySwagger } from "@fastify/swagger";
import { fastifySwaggerUi } from "@fastify/swagger-ui";
import { ZodTypeProvider } from "fastify-type-provider-zod";

const app = Fastify().withTypeProvider<ZodTypeProvider>();

app.register(fastifySwagger, {
  openapi: {
    info: {
      title: "Typed API",
      version: "1.0.0"
    }
  }
});

app.register(fastifySwaggerUi, {
  routePrefix: "/docs",
  staticCSP: true
});

app.get("/", async () => {
  return { message: "Olá, Mundo!" };
});

app.listen({ port: 3333 }, () => {
  console.log("HTTP server running on http://localhost:3333/docs");
});

Execute o servidor:

pnpm start

Abra o navegador em http://localhost:3333/docs e admire a magia do Swagger. Parabéns, você tem uma API funcional com documentação automática!

Validando Dados com Zod

Agora é hora de dar poder ao nosso backend. Vamos criar rotas que validam entradas e saídas usando o Zod. No arquivo src/routes.ts, adicione:

import { FastifyInstance } from "fastify";
import { z } from "zod";

export async function userRoutes(app: FastifyInstance) {
  const UserSchema = z.object({
    name: z.string().min(1, "Name is required"),
    email: z.string().email("Invalid email")
  });

  app.post("/users", {
    schema: {
      body: UserSchema,
      response: {
        201: z.null()
      },
      tags: ["Users"],
      description: "Create a new user"
    }
  }, async (request, reply) => {
    const { name, email } = request.body;
    console.log(`New user: ${name}, ${email}`);
    reply.code(201).send();
  });
}

No arquivo server.ts, registre as rotas:

import { userRoutes } from "./routes";

app.register(userRoutes);

Agora, teste no Swagger. Quando você criar um usuário, ele vai validar os campos com as regras que definimos no Zod.

Documentando Tudo

Quer uma documentação ainda mais robusta? Adicione exemplos e descrições:

app.post("/users", {
  schema: {
    body: UserSchema,
    response: {
      201: z.null().describe("User created successfully")
    },
    tags: ["Users"],
    description: "Create a new user",
    example: {
      name: "John Doe",
      email: "john.doe@example.com"
    }
  }
}, async (request, reply) => {
  // Implementação
});

Com isso, sua API fica ainda mais amigável para os devs que vão usá-la (ou seja, você mesmo no futuro, depois de esquecer como funciona).

Maninho, talvez você curta?

Conclusão

Aí está! Um backend moderno, tipado e com documentação automatizada, pronto para brilhar em qualquer projeto. Agora é só colocar sua criatividade para rodar e construir APIs fantásticas com Fastify e Zod.

E lembre-se: nada é tão satisfatório quanto um backend redondinho. Se você curtiu, compartilhe com seus amigos devs e não esqueça de deixar nos comentários quais outras ideias de projetos ou tutoriais você gostaria de ver.

Abraços e até a próxima!

Angular performance Angular Signals Apps Multiplataforma automação de tarefas Backend Boas Práticas boas práticas Git controle de versão desenvolvedores desenvolvimento backend Desenvolvimento de Software Desenvolvimento Frontend Desenvolvimento Mobile Desenvolvimento Web desenvolvimento ágil devops dicas para devs escalabilidade ferramentas de Git ferramentas de programação Front-end Git Hooks integração contínua inteligência artificial JavaScript Linguagens de Programação Media Queries mercado de tecnologia Mercado de Trabalho Tech Node.js produtividade dev Programação Programação Orientada a Objetos programação para iniciantes programação reativa Python React React Suspense Rust Tecnologia Trunk-Based Development web development workflow Git workflows Git

Tag

Related Posts

Publicar comentário

O que temos aqui?