Przejdź do głównej treści
Polski— Wybierz język
Menu

Zod z JavaScriptem

Lekcja 7 z 12 Zaktualizowano 30 lipca 2026 Programista
Na tej stronie
  1. Strukturalne dane wyjściowe w JavaScript
  2. Instalacja
  3. Konfiguracja klienta
  4. Definiowanie schematu za pomocą Zod
  5. Mapowanie typów
  6. Kompletny przykład
  7. Zagnieżdżone schematy
  8. Pola opcjonalne z wartością nullable
  9. Walidacja po stronie klienta
  10. Kluczowe wnioski

Strukturalne dane wyjściowe w JavaScript

Jeśli programujesz w JavaScript lub TypeScript, Zod jest odpowiednikiem Pydantic. Ta biblioteka do walidacji schematów bezproblemowo integruje się z API Grok, umożliwiając generowanie typowanych danych strukturalnych.

Instalacja

npm install zod openai

SDK OpenAI dla JavaScript działa bezpośrednio z API Grok – wystarczy wskazać właściwy punkt końcowy.

Konfiguracja klienta

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "your-xai-key",
  baseURL: "https://api.x.ai/v1"
});

Definiowanie schematu za pomocą Zod

Zod wykorzystuje płynne API (fluent API) do definiowania schematów. Każda metoda odpowiada typowi JSON:

import { z } from "zod";

const MovieReview = z.object({
  title: z.string(),
  rating: z.number(),
  summary: z.string(),
  recommend: z.boolean()
});

Mapowanie typów

ZodSchemat JSONPydantic (Python)
z.string()"type": "string"str
z.number()"type": "number"float
z.boolean()"type": "boolean"bool
z.array(z.string())tablica ciągów znaków (array of strings)list[str]
z.object({...})"type": "object"BaseModel
z.enum([...])wyliczenie (enum)Literal[...]
z.union([...])anyOfTypy unii
z.nullable()anyOf z wartością nullstr | None

Kompletny przykład

import OpenAI from "openai";
import { z } from "zod";

const client = new OpenAI({
  apiKey: "your-xai-key",
  baseURL: "https://api.x.ai/v1"
});

const Analyse = z.object({
  titre: z.string(),
  resume: z.string(),
  sentiment: z.enum(["positif", "negatif", "neutre"]),
  score: z.number(),
  mots_cles: z.array(z.string()),
  recommandation: z.boolean()
});

const response = await client.chat.completions.create({
  model: "grok-4.20-0309-reasoning",
  messages: [{
    role: "user",
    content: "Analyze the following text: Sales increased by 25% this quarter."
  }],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "analyse",
      schema: Analyse
    }
  }
});

const data = JSON.parse(response.choices[0].message.content);
console.log(data.sentiment);  // "positive"
console.log(data.score);      // 0.92

Zagnieżdżone schematy

Podobnie jak Pydantic, Zod naturalnie obsługuje zagnieżdżanie:

const Adresse = z.object({
  rue: z.string(),
  ville: z.string(),
  code_postal: z.string(),
  pays: z.string()
});

const Contact = z.object({
  nom: z.string(),
  email: z.string(),
  telephone: z.string().nullable(),
  adresse: Adresse,
  tags: z.array(z.string())
});

Pola opcjonalne z wartością nullable

Aby pole było opcjonalne (mogło przyjmować wartość null), użyj metody .nullable():

const Produit = z.object({
  nom: z.string(),
  prix: z.number(),
  description: z.string().nullable(),
  promotion: z.number().nullable()
});

Walidacja po stronie klienta

Jedną z zalet Zod jest możliwość walidacji danych po stronie klienta przy użyciu tego samego schematu:

const rawData = JSON.parse(response.choices[0].message.content);

// Walidacja za pomocą Zod
const result = Analyse.safeParse(rawData);

if (result.success) {
  console.log(result.data.titre);
} else {
  console.error("Błąd walidacji:", result.error);
}

W praktyce walidacja zawsze się powiedzie, ponieważ API gwarantuje zgodność ze schematem. Jednak ta dodatkowa warstwa jest przydatna dla zwiększenia odporności systemu w środowisku produkcyjnym.

Kluczowe wnioski

  • Zod to odpowiednik Pydantic dla JavaScript/TypeScript
  • Składnia jest płynna: z.string(), z.number(), z.object({...})
  • .nullable() sprawia, że pole jest opcjonalne (może być null)
  • Przekaż schematy Zod w response_format.json_schema.schema
  • safeParse() umożliwia defensywną walidację po stronie klienta
  • SDK OpenAI dla JavaScript działa bezpośrednio z API Grok