توقف عن كتابة واجهات TypeScript يدويًا: قم بإنشائها تلقائيًا من JSON

في كل مرة تقوم فيها بدمج واجهة برمجة تطبيقات جديدة، ينتهي بك الأمر إلى التحديق في استجابة JSON وكتابة الواجهة يدويًا. حقلاً تلو الآخر. تخمين القيم التي هي اختيارية. نسيان ذلك created_at هي سلسلة، وليس تاريخ. النسخ واللصق من المستندات التي قد تتطابق أو لا تتطابق مع الاستجابة الحقيقية.

وهذا أمر ممل، وبطيء، ومصدر موثوق للأخطاء. يحتوي JSON بالفعل على كل نوع تحتاجه. يمكن لاستدعاء API واحد استخراجها.

طلب POST واحد، وواجهة TypeScript واحدة

أرسل أي كائن JSON إلى Botoi json-to-typescript نقطة النهاية باسم الواجهة الجذرية. تقوم واجهة برمجة التطبيقات (API) بإرجاع واجهة TypeScript الكاملة كسلسلة.

curl -X POST https://api.botoi.com/v1/schema/json-to-typescript \\
  -H "Content-Type: application/json" \\
  -d '{
    "json": {
      "id": 1,
      "name": "Acme Corp",
      "active": true,
      "tags": ["saas", "b2b"]
    },
    "name": "Company"
  }'

إجابة:

{
  "success": true,
  "data": {
    "typescript": "interface Company {\\n  id: number;\\n  name: string;\\n  active: boolean;\\n  tags: string[];\\n}",
    "name": "Company"
  }
}

الواجهة التي تم إنشاؤها، منسقة:

interface Company {
  id: number;
  name: string;
  active: boolean;
  tags: string[];
}

يستنتج API number, string, boolean، و string[] من القيم. لا يوجد تعليق توضيحي يدوي. لا التخمين.

أنشئ برنامجًا نصيًا للأنواع من واجهة برمجة التطبيقات لمشروعك

تعد واجهات الكتابة يدويًا بمثابة إصلاح لمرة واحدة. النهج الأفضل: برنامج نصي يجلب استجابات واجهة برمجة التطبيقات المباشرة ويقوم بإنشاء ملفات الكتابة التي يمكنك الالتزام بها في الريبو الخاص بك.

فيما يلي نص برمجي bash يقوم بإنشاء أنواع TypeScript من أي عنوان URL:

#!/bin/bash
set -euo pipefail

API="https://api.botoi.com/v1/schema/json-to-typescript"
OUT_DIR="./src/types/generated"
mkdir -p "\$OUT_DIR"

generate_type() {
  local url="\$1"
  local name="\$2"
  local file="\$3"

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

  echo "Generating \$name interface..."
  local result
  result=\$(curl -s -X POST "\$API" \\
    -H "Content-Type: application/json" \\
    -d "{\"json\": \$json, \"name\": \"\$name\"}")

  echo "\$result" | jq -r '.data.typescript' > "\$OUT_DIR/\$file"
  echo "Wrote \$OUT_DIR/\$file"
}

generate_type "https://api.github.com/users/octocat" "GitHubUser" "github-user.ts"
generate_type "https://jsonplaceholder.typicode.com/posts/1" "BlogPost" "blog-post.ts"

echo "Done. All types written to \$OUT_DIR/"

قم بتشغيل هذا البرنامج النصي أثناء التطوير أو كربط مسبق. عندما تتغير واجهة برمجة التطبيقات الأولية، أعد تشغيل البرنامج النصي وستظل أنواعك دقيقة.

إذا كنت تفضل Node.js على bash:

import { writeFileSync, mkdirSync } from "fs";

const API = "https://api.botoi.com/v1/schema/json-to-typescript";

async function generateType(json: unknown, name: string): Promise<string> {
  const res = await fetch(API, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ json, name }),
  });
  const data = await res.json();
  return data.data.typescript;
}

async function main() {
  const userRes = await fetch("https://api.github.com/users/octocat");
  const userJson = await userRes.json();

  const typescript = await generateType(userJson, "GitHubUser");

  mkdirSync("./src/types/generated", { recursive: true });
  writeFileSync("./src/types/generated/github-user.ts", typescript);
  console.log("Wrote ./src/types/generated/github-user.ts");
}

main();

مثال حقيقي: إنشاء أنواع لاستجابة مستخدم GitHub API

جيثب /users/:username تقوم نقطة النهاية بإرجاع أكثر من 30 حقلاً. كتابة تلك الواجهة باليد يستغرق دقائق ويدعو الأخطاء المطبعية. هنا هو النهج المكون من خطوتين:

# Fetch the GitHub user JSON
GITHUB_JSON=\$(curl -s https://api.github.com/users/octocat)

# Send it to the Botoi API
curl -s -X POST https://api.botoi.com/v1/schema/json-to-typescript \\
  -H "Content-Type: application/json" \\
  -d "{\"json\": \$GITHUB_JSON, \"name\": \"GitHubUser\"}" \\
  | jq -r '.data.typescript'

الإخراج:

interface GitHubUser {
  login: string;
  id: number;
  node_id: string;
  avatar_url: string;
  gravatar_id: string;
  url: string;
  html_url: string;
  followers_url: string;
  following_url: string;
  gists_url: string;
  starred_url: string;
  subscriptions_url: string;
  organizations_url: string;
  repos_url: string;
  events_url: string;
  received_events_url: string;
  type: string;
  site_admin: boolean;
  name: string;
  company: string;
  blog: string;
  location: string;
  bio: string;
  twitter_username: string;
  public_repos: number;
  public_gists: number;
  followers: number;
  following: number;
  created_at: string;
  updated_at: string;
}

وهذا يعني 32 حقلاً، مكتوبة بشكل صحيح، في أقل من ثانية. قم بتوجيه الإخراج إلى ملف ولديك تعريف النوع الجاهز للإنتاج.

قم بإنشاء مخططات Zod بدلاً من ذلك

تمنحك واجهات TypeScript الأمان أثناء الترجمة، ولكنها تختفي في وقت التشغيل. إذا كنت بحاجة إلى التحقق من صحة وقت التشغيل، ال json-to-zod تقوم نقطة النهاية بإنشاء مخطط Zod من نفس إدخال JSON.

curl -s -X POST https://api.botoi.com/v1/schema/json-to-zod \\
  -H "Content-Type: application/json" \\
  -d '{
    "json": {
      "id": 1,
      "name": "Acme Corp",
      "active": true,
      "tags": ["saas", "b2b"]
    },
    "name": "Company"
  }' | jq -r '.data.zod'

الإخراج:

import { z } from "zod";

const Company = z.object({
  id: z.number(),
  name: z.string(),
  active: z.boolean(),
  tags: z.array(z.string()),
});

قم بإسقاط المخطط الذي تم إنشاؤه في قاعدة التعليمات البرمجية الخاصة بك وستحصل على التحقق من صحة وقت التشغيل واستدلال النوع:

import { z } from "zod";

const Company = z.object({
  id: z.number(),
  name: z.string(),
  active: z.boolean(),
  tags: z.array(z.string()),
});

type Company = z.infer<typeof Company>;

const parsed = Company.parse(apiResponse);
// parsed is fully typed and validated at runtime

مع Zod، يتم طرح البيانات غير الصالحة على الحدود بدلاً من التسبب في أخطاء صامتة عميقة في منطق التطبيق الخاص بك.

متى يتم استخدام كل نقطة نهاية

سيناريو	نقطة النهاية	لماذا
استجابات واجهة برمجة التطبيقات الداخلية التي تثق بها	json-to-typescript	خفيف الوزن؛ لا توجد تكلفة وقت التشغيل
استجابات واجهة برمجة التطبيقات الخارجية	json-to-zod	التحقق من صحة البيانات على الحدود
مدخلات النموذج أو البيانات المقدمة من المستخدم	json-to-zod	تحليل، لا التحقق من صحة
النماذج الأولية السريعة	json-to-typescript	أسرع مسار للكود المكتوب
توليد نوع خط أنابيب CI	أيضاً	كلاهما ينتج مخرجات حتمية

النقاط الرئيسية

• طلب واحد يحل محل الكتابة اليدوية. أرسل JSON واحصل على واجهة TypeScript أو مخطط Zod مرة أخرى.
• أتمتة ذلك. أضف برنامجًا نصيًا إلى مشروعك يقوم بإعادة إنشاء الأنواع كلما تغيرت واجهات برمجة التطبيقات الأولية.
• لا يوجد حساب مطلوب. تسمح الطبقة المجانية بـ 5 طلبات في الدقيقة بدون تسجيل.
• يعمل مع أي مصدر JSON. واجهات برمجة تطبيقات REST، وملفات التكوين، وصادرات قاعدة البيانات، وحمولات خطاف الويب.

ال مستندات API الكاملة غطاء نقاط نهاية المخطط الإضافية، بما في ذلك json-to-jsonschema لإخراج مخطط JSON.