قم بتحويل أي استجابة JSON إلى مخطط Zod بطلب POST واحد

لقد وصلت إلى واجهة برمجة تطبيقات تابعة لجهة خارجية، وحصلت على استجابة JSON، والآن تحتاج إلى مخطط Zod لذلك. العملية اليدوية: التحديق في الاستجابة، عد الحقول، ومعرفة الحقول التي لاغية، والتعامل مع الكائنات المتداخلة، اكتب خارجا z.object و z.string() لكل عقار. خطأ مطبعي واحد و الخاص بك التحقق من الصحة يمرر البيانات السيئة بصمت.

بالنسبة لجسم مسطح ذي خمسة مجالات، يستغرق هذا بضع دقائق. بالنسبة لنية الدفع الشريطية مع الرسوم المتداخلة، البيانات الوصفية، وأكثر من 30 حقلاً، يستغرق الأمر وقتًا طويلاً بما يكفي لبدء التشكيك في اختياراتك المهنية.

البوتوي /v1/schema/json-to-zod نقطة النهاية تلغي هذا. انشر أي JSON، واحصل على ملف كامل مخطط Zod مرة أخرى. طلب واحد، لا توجد واجهة سطر أوامر (CLI) للتثبيت، ولا توجد حزمة npm للتكوين.

استدعاء API

أرسل كائن JSON واسم مخطط اختياري:

حليقة

إجابة:

Node.js

بايثون

تقبل نقطة النهاية أي JSON صالحًا في ملف json مجال. الكائنات والمصفوفات متداخلة بعمق الهياكل. كل شيء يعمل. ال name الحقل اختياري والإعدادات الافتراضية هي "Root".

مثال حقيقي: نية الدفع الشريطية

هنا شريط واقعي payment_intent الاستجابة مع متداخلة metadata و charges أشياء. هذا هو نوع الحمولة التي يتم فيها كتابة مخططات Zod بخط اليد يصبح مؤلما بسرعة.

هيئة الطلب:

تقوم واجهة برمجة التطبيقات (API) بإرجاع مخطط Zod هذا:

يصبح كل كائن متداخل خاصًا به z.object. ال charges.data تنتج المصفوفة أ z.array مع شكل العنصر الصحيح. يتم الكشف عن القيم المنطقية والأرقام والسلاسل من القيم. انسخ هذا إلى قاعدة التعليمات البرمجية الخاصة بك، أضف import { "z" } from "zod"، ولديك الأنواع التي تم التحقق من صحتها في وقت التشغيل لاستجابات Stripe في أقل من 30 ثانية.

يعمل أيضًا مع واجهات TypeScript

إذا كنت بحاجة إلى أنواع TypeScript دون التحقق من صحة وقت التشغيل، فإن /v1/schema/json-to-typescript تقوم نقطة النهاية بإنشاء واجهات من نفس مدخلات JSON.

إجابة:

نفس تنسيق الإدخال، نفس name المعلمة. يستخدم json-to-zod عندما تحتاج التحقق من صحة وقت التشغيل (معالجات واجهة برمجة التطبيقات، وتحليل النماذج، وحمولات خطاف الويب). يستخدم json-to-typescript عندما تحتاج فقط إلى أمان نوع وقت الترجمة.

قم ببناء برنامج نصي Codegen لمشروعك

تظهر القوة الحقيقية عند أتمتة إنشاء المخطط. يجلب هذا البرنامج النصي استجابات واجهة برمجة التطبيقات المباشرة، يحول كل واحد إلى مخطط Zod، ويكتب الإخراج إلى ملفك src/schemas/ دليل.

#!/bin/bash
set -euo pipefail

API_BASE="https://api.botoi.com/v1"
OUTPUT_DIR="./src/schemas"

mkdir -p "\$OUTPUT_DIR"

generate_schema() {
  local name=\$1
  local url=\$2
  local output_file="\$OUTPUT_DIR/\$(echo "\$name" | tr '[:upper:]' '[:lower:]').ts"

  echo "Fetching \$url ..."
  local json_response
  json_response=\$(curl -s "\$url")

  echo "Generating Zod schema for \$name ..."
  local zod_response
  zod_response=\$(curl -s -X POST "\$API_BASE/schema/json-to-zod" \\
    -H "Content-Type: application/json" \\
    -d "{
      \\"json\\": \$json_response,
      \\"name\\": \\"\$name\\"
    }")

  local schema
  schema=\$(echo "\$zod_response" | jq -r '.data.zod')

  cat > "\$output_file" << SCHEMAEOF
import { z } from "zod";

\$schema

export type \$name = z.infer<typeof \${name}Schema>;
SCHEMAEOF

  echo "Wrote \$output_file"
}

# Add your API endpoints here
generate_schema "UserProfile" "https://api.example.com/users/1"
generate_schema "Order" "https://api.example.com/orders/latest"
generate_schema "Product" "https://api.example.com/products/42"

echo "Done. Generated \$(ls "\$OUTPUT_DIR"/*.ts | wc -l) schema files."

تشغيله:

Fetching https://api.example.com/users/1 ...
Generating Zod schema for UserProfile ...
Wrote ./src/schemas/userprofile.ts
Fetching https://api.example.com/orders/latest ...
Generating Zod schema for Order ...
Wrote ./src/schemas/order.ts
Fetching https://api.example.com/products/42 ...
Generating Zod schema for Product ...
Wrote ./src/schemas/product.ts
Done. Generated 3 schema files.

يبدو كل ملف تم إنشاؤه كما يلي:

أضف هذا البرنامج النصي إلى package.json مثل "codegen:schemas" وتشغيله كلما تغيرت واجهة برمجة التطبيقات الأولية. تظل مخططات Zod الخاصة بك متزامنة مع شكل الاستجابة الحقيقي، ويتم اشتقاق أنواع TypeScript من المخطط تلقائيًا.

عندما يكون هذا مفيدًا

• إعداد واجهة برمجة تطبيقات جديدة لجهة خارجية. اضغط على API مرة واحدة، وقم بتحويل الرد إلى Zod المخطط، وابدأ في الإنشاء باستخدام الأنواع التي تم التحقق من صحتها بدلاً من تخمين أسماء الحقول.
• ترحيل جافا سكريبت إلى TypeScript. إذا كان لديك استجابات API تتدفق من خلال كود غير مكتوب، قم بإنشاء مخططات من البيانات الحقيقية للحصول على تغطية الكتابة بسرعة.
• الحفاظ على مزامنة المخططات. قم بتشغيل البرنامج النصي codegen في CI وفقًا لجدول زمني للكشف عندما تغير واجهة برمجة التطبيقات الأولية شكل الاستجابة الخاصة بها.
• النماذج الأولية. عندما تحتاج إلى أنواع تم التحقق من صحتها لإثبات المفهوم ولا تريد ذلك لقضاء بعض الوقت في صياغة المخططات يدويًا لواجهات برمجة التطبيقات (API) التي قد تتجاهلها الأسبوع المقبل.