elsabro 2.1.0 → 2.3.0

package/skills/api-microservice.md

@@ -0,0 +1,765 @@
+---
+name: api-microservice
+description: Crear microservicio API con Node.js, Fastify, OpenAPI/Swagger, Docker, Prisma, rate limiting y health checks.
+tags: [api, microservice, fastify, docker, openapi, swagger, nodejs, prisma]
+difficulty: intermediate
+estimated_time: 40min
+---
+
+# Skill: API Microservice
+
+<when_to_use>
+Usar cuando el usuario menciona:
+- "crear API"
+- "microservicio"
+- "backend API"
+- "REST API"
+- "API con documentacion"
+</when_to_use>
+
+<pre_requisites>
+## Pre-requisitos
+
+- Node.js 20+
+- Docker Desktop (opcional, para containerization)
+- PostgreSQL (local o Neon/Supabase)
+</pre_requisites>
+
+<project_structure>
+## Estructura de Proyecto
+
+```
+my-api/
+├── src/
+│   ├── routes/
+│   │   ├── health.ts          # Health check endpoints
+│   │   ├── users.ts           # User CRUD
+│   │   └── index.ts           # Route registration
+│   ├── schemas/
+│   │   └── user.ts            # Zod schemas
+│   ├── services/
+│   │   └── userService.ts     # Business logic
+│   ├── middleware/
+│   │   ├── auth.ts            # JWT auth
+│   │   └── error-handler.ts   # Global error handler
+│   ├── plugins/
+│   │   ├── prisma.ts          # Prisma plugin
+│   │   └── swagger.ts         # Swagger plugin
+│   ├── config/
+│   │   └── env.ts             # Environment validation
+│   ├── app.ts                 # Fastify app builder
+│   └── index.ts               # Entry point
+├── prisma/
+│   └── schema.prisma
+├── tests/
+│   └── routes/
+│       └── users.test.ts
+├── Dockerfile
+├── docker-compose.yml
+├── .env
+├── .env.example
+├── tsconfig.json
+└── package.json
+```
+</project_structure>
+
+<setup_steps>
+## Pasos de Setup
+
+### Paso 1: Inicializar proyecto
+
+```bash
+mkdir my-api && cd my-api
+npm init -y
+```
+
+### Paso 2: Instalar dependencias
+
+```bash
+npm install fastify @fastify/cors @fastify/helmet @fastify/rate-limit @fastify/swagger @fastify/swagger-ui @fastify/jwt
+npm install prisma @prisma/client zod dotenv
+npm install -D typescript tsx @types/node vitest
+```
+
+### Paso 3: Configurar TypeScript
+
+Crear `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### Paso 4: Configurar variables de entorno
+
+Crear `src/config/env.ts`:
+
+```typescript
+import { z } from "zod";
+import "dotenv/config";
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
+  PORT: z.coerce.number().default(3000),
+  HOST: z.string().default("0.0.0.0"),
+  DATABASE_URL: z.string(),
+  JWT_SECRET: z.string().min(32),
+  RATE_LIMIT_MAX: z.coerce.number().default(100),
+});
+
+export const env = envSchema.parse(process.env);
+```
+
+Crear `.env`:
+
+```env
+NODE_ENV=development
+PORT=3000
+HOST=0.0.0.0
+DATABASE_URL=postgresql://user:password@localhost:5432/myapi
+JWT_SECRET=your-super-secret-key-at-least-32-characters
+RATE_LIMIT_MAX=100
+```
+
+### Paso 5: Configurar Prisma
+
+```bash
+npx prisma init
+```
+
+Editar `prisma/schema.prisma`:
+
+```prisma
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  name      String?
+  password  String
+  role      Role     @default(USER)
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}
+
+enum Role {
+  USER
+  ADMIN
+}
+```
+
+### Paso 6: Crear plugin de Prisma
+
+Crear `src/plugins/prisma.ts`:
+
+```typescript
+import { FastifyPluginAsync } from "fastify";
+import fp from "fastify-plugin";
+import { PrismaClient } from "@prisma/client";
+
+declare module "fastify" {
+  interface FastifyInstance {
+    prisma: PrismaClient;
+  }
+}
+
+const prismaPlugin: FastifyPluginAsync = async (fastify) => {
+  const prisma = new PrismaClient({
+    log: fastify.log.level === "debug" ? ["query", "error", "warn"] : ["error"],
+  });
+
+  await prisma.$connect();
+
+  fastify.decorate("prisma", prisma);
+
+  fastify.addHook("onClose", async (server) => {
+    await server.prisma.$disconnect();
+  });
+};
+
+export default fp(prismaPlugin, { name: "prisma" });
+```
+
+### Paso 7: Crear plugin de Swagger
+
+Crear `src/plugins/swagger.ts`:
+
+```typescript
+import { FastifyPluginAsync } from "fastify";
+import fp from "fastify-plugin";
+import swagger from "@fastify/swagger";
+import swaggerUi from "@fastify/swagger-ui";
+
+const swaggerPlugin: FastifyPluginAsync = async (fastify) => {
+  await fastify.register(swagger, {
+    openapi: {
+      info: {
+        title: "My API",
+        description: "API documentation",
+        version: "1.0.0",
+      },
+      servers: [
+        {
+          url: "http://localhost:3000",
+          description: "Development server",
+        },
+      ],
+      components: {
+        securitySchemes: {
+          bearerAuth: {
+            type: "http",
+            scheme: "bearer",
+            bearerFormat: "JWT",
+          },
+        },
+      },
+    },
+  });
+
+  await fastify.register(swaggerUi, {
+    routePrefix: "/docs",
+    uiConfig: {
+      docExpansion: "list",
+      deepLinking: false,
+    },
+  });
+};
+
+export default fp(swaggerPlugin, { name: "swagger" });
+```
+
+### Paso 8: Crear schemas con Zod
+
+Crear `src/schemas/user.ts`:
+
+```typescript
+import { z } from "zod";
+
+export const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).optional(),
+  password: z.string().min(8),
+});
+
+export const updateUserSchema = z.object({
+  name: z.string().min(2).optional(),
+  email: z.string().email().optional(),
+});
+
+export const userResponseSchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  name: z.string().nullable(),
+  role: z.enum(["USER", "ADMIN"]),
+  createdAt: z.date(),
+});
+
+export type CreateUserInput = z.infer<typeof createUserSchema>;
+export type UpdateUserInput = z.infer<typeof updateUserSchema>;
+export type UserResponse = z.infer<typeof userResponseSchema>;
+```
+
+### Paso 9: Crear rutas de health
+
+Crear `src/routes/health.ts`:
+
+```typescript
+import { FastifyPluginAsync } from "fastify";
+
+export const healthRoutes: FastifyPluginAsync = async (fastify) => {
+  fastify.get(
+    "/health",
+    {
+      schema: {
+        description: "Health check endpoint",
+        tags: ["Health"],
+        response: {
+          200: {
+            type: "object",
+            properties: {
+              status: { type: "string" },
+              timestamp: { type: "string" },
+              uptime: { type: "number" },
+            },
+          },
+        },
+      },
+    },
+    async () => {
+      return {
+        status: "healthy",
+        timestamp: new Date().toISOString(),
+        uptime: process.uptime(),
+      };
+    }
+  );
+
+  fastify.get(
+    "/health/ready",
+    {
+      schema: {
+        description: "Readiness probe",
+        tags: ["Health"],
+        response: {
+          200: {
+            type: "object",
+            properties: {
+              status: { type: "string" },
+              database: { type: "string" },
+            },
+          },
+        },
+      },
+    },
+    async () => {
+      try {
+        await fastify.prisma.$queryRaw`SELECT 1`;
+        return { status: "ready", database: "connected" };
+      } catch {
+        return { status: "not ready", database: "disconnected" };
+      }
+    }
+  );
+};
+```
+
+### Paso 10: Crear rutas de usuarios
+
+Crear `src/routes/users.ts`:
+
+```typescript
+import { FastifyPluginAsync } from "fastify";
+import { createUserSchema, updateUserSchema } from "../schemas/user";
+import bcrypt from "bcryptjs";
+
+export const userRoutes: FastifyPluginAsync = async (fastify) => {
+  // GET /users
+  fastify.get(
+    "/",
+    {
+      schema: {
+        description: "List all users",
+        tags: ["Users"],
+        response: {
+          200: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                id: { type: "string" },
+                email: { type: "string" },
+                name: { type: "string" },
+                role: { type: "string" },
+              },
+            },
+          },
+        },
+      },
+    },
+    async () => {
+      const users = await fastify.prisma.user.findMany({
+        select: { id: true, email: true, name: true, role: true },
+      });
+      return users;
+    }
+  );
+
+  // GET /users/:id
+  fastify.get<{ Params: { id: string } }>(
+    "/:id",
+    {
+      schema: {
+        description: "Get user by ID",
+        tags: ["Users"],
+        params: {
+          type: "object",
+          properties: {
+            id: { type: "string" },
+          },
+          required: ["id"],
+        },
+        response: {
+          200: {
+            type: "object",
+            properties: {
+              id: { type: "string" },
+              email: { type: "string" },
+              name: { type: "string" },
+              role: { type: "string" },
+            },
+          },
+          404: {
+            type: "object",
+            properties: {
+              error: { type: "string" },
+            },
+          },
+        },
+      },
+    },
+    async (request, reply) => {
+      const { id } = request.params;
+      const user = await fastify.prisma.user.findUnique({
+        where: { id },
+        select: { id: true, email: true, name: true, role: true },
+      });
+
+      if (!user) {
+        return reply.code(404).send({ error: "User not found" });
+      }
+
+      return user;
+    }
+  );
+
+  // POST /users
+  fastify.post<{ Body: { email: string; name?: string; password: string } }>(
+    "/",
+    {
+      schema: {
+        description: "Create a new user",
+        tags: ["Users"],
+        body: {
+          type: "object",
+          properties: {
+            email: { type: "string", format: "email" },
+            name: { type: "string" },
+            password: { type: "string", minLength: 8 },
+          },
+          required: ["email", "password"],
+        },
+        response: {
+          201: {
+            type: "object",
+            properties: {
+              id: { type: "string" },
+              email: { type: "string" },
+              name: { type: "string" },
+            },
+          },
+        },
+      },
+    },
+    async (request, reply) => {
+      const input = createUserSchema.parse(request.body);
+      const hashedPassword = await bcrypt.hash(input.password, 10);
+
+      const user = await fastify.prisma.user.create({
+        data: {
+          ...input,
+          password: hashedPassword,
+        },
+        select: { id: true, email: true, name: true },
+      });
+
+      return reply.code(201).send(user);
+    }
+  );
+
+  // PATCH /users/:id
+  fastify.patch<{ Params: { id: string }; Body: { name?: string; email?: string } }>(
+    "/:id",
+    {
+      schema: {
+        description: "Update user",
+        tags: ["Users"],
+        params: {
+          type: "object",
+          properties: {
+            id: { type: "string" },
+          },
+          required: ["id"],
+        },
+        body: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            email: { type: "string", format: "email" },
+          },
+        },
+      },
+    },
+    async (request, reply) => {
+      const { id } = request.params;
+      const input = updateUserSchema.parse(request.body);
+
+      const user = await fastify.prisma.user.update({
+        where: { id },
+        data: input,
+        select: { id: true, email: true, name: true },
+      });
+
+      return user;
+    }
+  );
+
+  // DELETE /users/:id
+  fastify.delete<{ Params: { id: string } }>(
+    "/:id",
+    {
+      schema: {
+        description: "Delete user",
+        tags: ["Users"],
+        params: {
+          type: "object",
+          properties: {
+            id: { type: "string" },
+          },
+          required: ["id"],
+        },
+        response: {
+          204: { type: "null" },
+        },
+      },
+    },
+    async (request, reply) => {
+      const { id } = request.params;
+      await fastify.prisma.user.delete({ where: { id } });
+      return reply.code(204).send();
+    }
+  );
+};
+```
+
+### Paso 11: Crear app builder
+
+Crear `src/app.ts`:
+
+```typescript
+import Fastify, { FastifyInstance } from "fastify";
+import cors from "@fastify/cors";
+import helmet from "@fastify/helmet";
+import rateLimit from "@fastify/rate-limit";
+import prismaPlugin from "./plugins/prisma";
+import swaggerPlugin from "./plugins/swagger";
+import { healthRoutes } from "./routes/health";
+import { userRoutes } from "./routes/users";
+import { env } from "./config/env";
+
+export async function buildApp(): Promise<FastifyInstance> {
+  const app = Fastify({
+    logger: {
+      level: env.NODE_ENV === "production" ? "info" : "debug",
+    },
+  });
+
+  // Plugins de seguridad
+  await app.register(cors, {
+    origin: env.NODE_ENV === "production" ? "https://yourapp.com" : true,
+  });
+  await app.register(helmet);
+  await app.register(rateLimit, {
+    max: env.RATE_LIMIT_MAX,
+    timeWindow: "1 minute",
+  });
+
+  // Database
+  await app.register(prismaPlugin);
+
+  // Documentation
+  await app.register(swaggerPlugin);
+
+  // Routes
+  await app.register(healthRoutes);
+  await app.register(userRoutes, { prefix: "/users" });
+
+  return app;
+}
+```
+
+### Paso 12: Crear entry point
+
+Crear `src/index.ts`:
+
+```typescript
+import { buildApp } from "./app";
+import { env } from "./config/env";
+
+async function main() {
+  const app = await buildApp();
+
+  try {
+    await app.listen({ port: env.PORT, host: env.HOST });
+    console.log(`Server running at http://${env.HOST}:${env.PORT}`);
+    console.log(`Docs at http://${env.HOST}:${env.PORT}/docs`);
+  } catch (err) {
+    app.log.error(err);
+    process.exit(1);
+  }
+}
+
+main();
+```
+
+### Paso 13: Configurar Docker
+
+Crear `Dockerfile`:
+
+```dockerfile
+FROM node:20-alpine AS base
+WORKDIR /app
+
+# Dependencies
+FROM base AS deps
+COPY package*.json ./
+RUN npm ci --only=production
+
+# Build
+FROM base AS build
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npx prisma generate
+RUN npm run build
+
+# Production
+FROM base AS production
+ENV NODE_ENV=production
+
+COPY --from=deps /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules/.prisma ./node_modules/.prisma
+COPY prisma ./prisma
+
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+
+CMD ["node", "dist/index.js"]
+```
+
+Crear `docker-compose.yml`:
+
+```yaml
+version: "3.8"
+
+services:
+  api:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - DATABASE_URL=postgresql://postgres:password@db:5432/myapi
+      - JWT_SECRET=your-secret-key-at-least-32-characters
+    depends_on:
+      db:
+        condition: service_healthy
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      - POSTGRES_USER=postgres
+      - POSTGRES_PASSWORD=password
+      - POSTGRES_DB=myapi
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data:
+```
+
+### Paso 14: Scripts de package.json
+
+```json
+{
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest",
+    "db:migrate": "prisma migrate dev",
+    "db:push": "prisma db push",
+    "db:studio": "prisma studio",
+    "docker:build": "docker build -t my-api .",
+    "docker:run": "docker-compose up -d"
+  }
+}
+```
+</setup_steps>
+
+<verification>
+## Verificacion
+
+### 1. Ejecutar migraciones
+```bash
+npx prisma migrate dev --name init
+```
+
+### 2. Iniciar servidor
+```bash
+npm run dev
+```
+
+### 3. Verificar health check
+```bash
+curl http://localhost:3000/health
+```
+
+### 4. Ver documentacion
+Abrir http://localhost:3000/docs
+
+### 5. Probar CRUD
+```bash
+# Crear usuario
+curl -X POST http://localhost:3000/users \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","password":"password123"}'
+
+# Listar usuarios
+curl http://localhost:3000/users
+
+# Obtener usuario
+curl http://localhost:3000/users/{id}
+```
+
+### 6. Probar Docker
+```bash
+docker-compose up -d
+curl http://localhost:3000/health
+```
+</verification>
+
+<common_issues>
+## Problemas Comunes
+
+### "Cannot find module"
+- Verificar tsconfig paths
+- Ejecutar `npx prisma generate`
+
+### "Database connection failed"
+- Verificar DATABASE_URL
+- Verificar que PostgreSQL esta corriendo
+
+### "Rate limit exceeded"
+- Ajustar RATE_LIMIT_MAX en .env
+</common_issues>