در برنامه‌های React، مدیریت پاسخ‌های API می‌تواند به مسئله‌ای چالش‌برانگیز تبدیل شود. گاهی داده‌هایی دریافت می‌کنیم که فیلدهای ضروری را ندارند، ساختارشان غیرمنتظره است یا با قالب مورد انتظار مطابقت ندارند. وقتی توسعه‌دهنده با داده‌های ناسازگار روبه‌رو می‌شود، احتمال بروز خطا افزایش می‌یابد و مدیریت داده‌ها برای او دشوارتر می‌شود. در این شرایط، استفاده از Zod در React به عنوان راهکاری مؤثر مطرح می‌شود. این کتابخانه سبک و قدرتمند، امکان اعتبارسنجی دقیق پاسخ‌های API را فراهم می‌کند و از بروز خطاهای ناشی از داده‌های نامعتبر جلوگیری می‌نماید.

در پایان این آموزش، یاد خواهیم گرفت که چگونه:

• Zod را برای اعتبارسنجی پاسخ‌های API در React راه‌اندازی و استفاده کنیم.

• اسکیمایی تعریف کنیم که داده‌های ورودی را اعتبارسنجی و تبدیل کند.

• با ادغام Zod در فراخوانی‌های API، مدیریت داده‌ها را بهبود ببخشیم و جلوی کرش‌های رابط کاربری را بگیریم.

Zod چیست و چرا باید در فراخوانی‌های API React از آن استفاده کرد؟

Zod یک کتابخانه قدرتمند مبتنی بر تایپ اسکریپت است که فرآیند اعتبارسنجی داده‌ها را ساده می‌سازد. این ابزار به ما این امکان را می‌دهد تا قوانین روشنی (اسکیماها) برای قالب داده‌های مورد انتظار خود تعریف نماییم.

همچنین، Zod می‌تواند داده‌های ورودی (که اغلب از پاسخ‌های API هستند) را اعتبارسنجی کند تا اطمینان حاصل شود که با این قوانین تطابق دارند. این فرآیند اعتبارسنجی تضمین می‌کند که داده‌ها از قالب تعریف‌شده تبعیت می‌کنند و در نتیجه، قابلیت اطمینان و یکپارچگی برنامه ما افزایش می‌یابد.

دلایل درخشش Zod در اعتبارسنجی API در React عبارت‌اند از:

• اسکیماهای واضح: Zod به ما این امکان را می‌دهد تا الگوهای دقیق و خوانایی برای پاسخ‌های API تعریف کنیم که موجب افزایش قابلیت نگه‌داری کد می‌شود.
• اعتبارسنجی داده‌ها: این کتابخانه متدهای قدرتمندی برای انواع داده‌ها ارائه می‌دهد که قوانینی مانند فیلدهای اجباری یا فرمت‌های خاص را enforce می‌کند.
• شناسایی زودهنگام خطاها: با کمک Zod می‌توانیم ناسازگاری‌های داده را هنگام فراخوانی API شناسایی کنیم و از بروز خطاهای غیرمنتظره در مراحل بعدی برنامه جلوگیری کنیم.
• تجربه بهتر برای توسعه‌دهنده: با حمایت از کدنویسی type safe، فرآیند توسعه را بدون نیاز به بررسی دستی نوع داده‌ها سریع‌تر می‌کند.
• منبع یکتا برای تعریف مدل داده‌ها: در نهایت، ما با استفاده از Zod، مدل‌های داده را به صورت متمرکز در سراسر برنامه React تعریف می‌کنیم. این رویکرد به حفظ انسجام ساختار داده‌ها کمک می‌کند و احتمال بروز خطا را کاهش می‌دهد.

با استفاده از Zod می‌توانیم پاسخ‌های غیرقابل پیش‌بینی API را به داده‌هایی تمیز و ساختارمند تبدیل کنیم و مسیر توسعه در React را برای خود هموارتر و مؤثرتر سازیم.

چگونه یک پروژه React با تایپ اسکریپت ایجاد کنیم؟

ایجاد یک پروژه جدید React با پشتیبانی از تایپ اسکریپت بسیار ساده است. کافیست دستور زیر را در ترمینال اجرا کنیم:

npm create vite@latest my-react-app -- --template react-ts

پس از ایجاد پروژه، وارد پوشه آن می‌شویم و دستورات زیر را اجرا می‌کنیم:

cd my-react-app
npm install
npm run dev

اکنون می‌توانیم از پروژه React خود با پشتیبانی از تایپ اسکریپت استفاده کنیم. برای نصب کتابخانه Zod، دستور زیر را اجرا می‌کنیم:

npm install zod

بررسی مفاهیم اصلی کتابخانه Zod 

Zod با استفاده از اسکیمای داده‌ها به ما کمک می‌کند تا انتظارات روشنی برای پاسخ‌های API خود تعریف کنیم. این اسکیماها مانند نقشه‌هایی هستند که نوع داده‌هایی که انتظار دریافت آن‌ها را داریم، مشخص می‌کنند.

چگونه اسکیما بسازیم؟

Zod توابع سازنده‌ای مانند

import { z } from 'zod';
// Define basic data types
const userName = z.string().min(5).max(10); // String with min 5 and max 10 characters
const userAge = z.number().positive().int();  // Positive integer
const userEmail = z.string().email();        // Ensures a valid email format

console.log(userName.parse('John Doe'));       // Output: John Doe (valid)
console.log(userAge.parse(30));              // Output: 30 (valid)
console.log(userEmail.parse("johnDoe@gmail.com")); // Output: johnDoe@gmail.com (valid)

کد بالا سه نوع داده بیسیک را تعریف می‌کند:

• userName
  userName: رشته‌ای با حداقل ۵ و حداکثر ۱۰ کاراکتر
• userAge
  userAge: عدد صحیح مثبت
• userEmail
  userEmail: قالب معتبر ایمیل

چگونه قوانین اعتبارسنجی را اضافه کنیم؟

Zod به ما این امکان را می‌دهد تا با زنجیره‌سازی متدهایی مانند min، max، positive، int و email، قوانین خاصی را بر روی این نوع داده‌ها اعمال نماییم.

در ادامه، نمونه‌ای از رشته‌ای را می‌بینیم که از حداکثر تعداد کاراکتر مجاز عبور کرده است:

console.log(userName.parse("Hello there, My Name is John Doe")); // Throws ZodError

کد فوق به دلیل تجاوز از حداکثر طول ۱۰ کاراکتر، یک

اعتبارسنجی و تجزیه داده‌ها

Zod دو روش برای بررسی داده‌ها با استفاده از اسکیما ارائه می‌دهد:

• schema.parse(data)
  schema.parse(data): این متد تلاش می‌کند داده را مطابق اسکیما تجزیه کند. اما اگر خطای اعتبارسنجی وجود داشته باشد، یک خطا 
  ZodError
  ZodError ایجاد می‌کند. همان‌طور که در مثال قبلی دیدیم، این موضوع می‌تواند باعث اختلال در جریان اجرای برنامه شود.
• schema.safeParse(data)
  schema.safeParse(data): توسعه‌دهنگان این روش را توصیه می‌کنند. این متد، داده را تجزیه کرده و یک آبجکت از نوع
  ZodResult object
  ZodResult object بازمی‌گرداند که شامل ویژگی‌های کلیدی زیر است:
  • success
    success: این مقدار بولین مشخص می‌کند که آیا عملیات تجزیه با موفقیت انجام شده است یا خیر.
  • data
    data: داده تجزیه شده، در صورتی که
    success
    success برابر
    true
    true باشد.
  • error
    error: پیام خطا در صورتی که
    success
    success برابر
    false
    false باشد.

مثال‌هایی برای استفاده از safeParse با داده‌های معتبر و نامعتبر

مثال اول: استفاده از safeParse با داده‌های معتبر

const userSchema = z.object({
  name: userName,
  age: userAge,
  email: userEmail,
});

const userData = {
  name: "John Doe",
  age: 24,
  email: "johndoe@gmail.com"
};

const result = userSchema.safeParse(userData);

console.log(result); // ZodObject containing data and success status

در این مثال، یک اسکیمای کاربر با ویژگی‌های

مثال دوم: استفاده از safeParse با داده‌های نامعتبر

const userSchema = z.object({
  name: userName,
  age: userAge,
  email: userEmail,
});

const userData = {
  name: "John Doe",
  age: 24,
  email: "johndoe.com" // invalid email
};

const result = userSchema.safeParse(userData);

console.log(result); // ZodObject containing error and success status

در این مثال هم اسکیما مشابهی تعریف کرده‌ایم؛ اما این‌بار، عمداً داده‌ای نامعتبر (با فرمت نادرست ایمیل) را به تابع safeParse ارسال کرده‌ایم. بر خلاف متد

ساخت اسکیماهای Zod برای پاسخ‌های API

اکنون، با استفاده از مفاهیم اصلی Zod، اسکیماهایی طراحی می‌کنیم که به‌طور خاص برای داده‌های دریافتی از API کاربرد دارند. در اینجا از داده‌های سایت JSONPlaceholder استفاده می‌کنیم که اطلاعات مربوط به پست‌ها را در اختیارمان قرار می‌دهد.

نمونه‌ای از پاسخ JSON برای یک پست:

{
  "userId": 1,
  "id": 3,
  "title": "ea molestias quasi exercitationem repellat qui ipsa sit aut",
  "body": "et iusto sed quo iure\nvoluptatem occaecati omnis eligendi aut"
}

ساخت یک کامپوننت React برای نمایش کاربرد Zod در اعتبارسنجی داده‌های API

برای اینکه نحوه استفاده از Zod در کنار API را نشان بدهیم، می‌توانیم یک کامپوننت React بسازیم. اسم کامپوننت را می‌توانیم مطابق ساختار پروژه خود انتخاب نماییم، اما در این مقاله، برای سادگی از اسم

 import { z } from 'zod';

  const postSchema = z.object({
  userId: z.number().positive().int(),
  id: z.number().positive().int(),
  title: z.string(),
  body: z.string()
});

const postSchemaArray = z.array(postSchema); // Schema for array of posts

در این قطعه کد:

• postSchema
  postSchema ساختار مورد انتظار برای یک پست را مشخص می‌کند.
• postSchemaArray
  postSchemaArray اسکیمایی برای یک آرایه از پست‌ها می‌باشد.

نحوه اتصال Zod به API در React

اکنون می‌خواهیم اسکیماهایی که ساختیم را به داده‌های واقعی از API متصل کنیم و آن‌ها را اعتبارسنجی نماییم. برای این کار کدی که در بخش قبل نوشتیم را باید به‌روزرسانی کنیم:

import { z } from 'zod';
import { useEffect } from 'react';

const postSchema = z.object({
  userId: z.number().positive().int(),
  id: z.number().positive().int(),
  title: z.string(),
  body: z.string()
});

const postSchemaArray = z.array(postSchema); // schema for an array of posts

type Posts = z.infer<typeof postSchemaArray>; // type of the posts

const ZodApi = () => {
  useEffect(() => {
    fetch("https://jsonplaceholder.typicode.com/posts")
      .then((response) => response.json())
      .then((posts: Posts) => {
        const validatedPosts = postSchemaArray.safeParse(posts); // remember to use safeParse instead of parse

        if (validatedPosts.success === false) {
          console.log("Validation Error:"validatedPosts.error);
          return;
        }

        // we can now safely use the posts
        console.log(validatedPosts.data);
      });
  }, []);
  return <div>ZodApi</div>;
};

export default ZodApi;

کامپوننت

• دریافت داده‌ها: از هوک
  useEffect
  useEffect و
  fetch
  fetch برای گرفتن اطلاعات از API استفاده می‌کنیم.
• ایمنی تایپ: با استفاده از
  type Posts = z.infer<typeof postSchemaArray>;
  type Posts = z.infer<typeof postSchemaArray>;،
  Posts type
  Posts type به صورت خودکار از اسکیما
  postSchemaArray
  postSchemaArray استخراج می‌شود که باعث ایمنی و دقت بیشتر می‌گردد.
• اعتبارسنجی با Zod: داده‌های دریافتی از
  postSchemaArray
  postSchemaArray با استفاده از
  safeParse
  safeParse و اسکیما بررسی می‌شوند.
• مدیریت
  success
  success: در صورتی که اعتبارسنجی موفقیت‌آمیز باشد، داده معتبر در
  validatedPosts.data
  validatedPosts.data قرار می‌گیرد و می‌تواند در رابط کاربری یا state مورد استفاده قرار بگیرد.
• مدیریت خطا: با بررسی
  validatedPosts.success === false
  validatedPosts.success === false، خطاهای اعتبارسنجی به صورت ساده در کنسول لاگ می‌شوند.

نحوه رندر رابط کاربری و مدیریت خطا در React

در این بخش، یاد می‌گیریم چگونه داده‌های اعتبارسنجی‌شده را در رابط کاربری نمایش دهیم و با استفاده از stateهای React، مکانیزم مدیریت خطا را پیاده‌سازی کنیم.

import { z } from "zod";
import { useEffect, useState } from "react";

const postSchema = z.object({
  userId: z.number().positive().int(),
  id: z.number().positive().int(),
  title: z.string(),
  body: z.string(),
});

const postSchemaArray = z.array(postSchema); // schema for an array of posts

type Posts = z.infer<typeof postSchemaArray>; // type of the posts

const ZodApi = () => {
  const [posts, setPosts] = useState<Posts>([]); // State to store validated posts
  const [error, setError] = useState(""); // State to store any errors
  useEffect(() => {
    fetch("https://jsonplaceholder.typicode.com/posts")
      .then((response) => response.json())
      .then((posts: Posts) => {
        const validatedPosts = postSchemaArray.safeParse(posts); // remember to use safeParse instead of parse

        if (validatedPosts.success === false) {
          console.log(validatedPosts.error.name);
          setError(validatedPosts.error.message); // set error state
          return;
        }

        // we can now safely use the validatedPosts 
        console.log(validatedPosts.data);
        setPosts(validatedPosts.data)
      });
  }, []);

  // Handle loading state (optional)
  if (!posts.length && !error) {
    return <div>Loading posts...</div>;
  }

  // Handle error state
  if (error) {
    return <div>Error fetching Data</div>; // Display user-friendly error message
  }

  return (
    <div>
      <h1>Posts</h1>
      <ol>
        {posts.map((post) => (
          <li key={post.id}>
            {post.title}
          </li>
        ))}
      </ol>
    </div>
  );
};

export default ZodApi;

کدی که در اختیار داریم، مربوط به کامپوننت

• تعریف state‌ها: دو state به نام‌های
  posts
  posts و
  error
  error تعریف شده‌اند.
  posts
  posts برای نگه‌داری داده‌های دریافتی از API و
  error
  error برای ذخیره‌ پیام‌های خطا استفاده می‌شود.
• مدیریت state دریافت داده: در صورتی که هنوز داده‌ای دریافت نشده باشد و خطایی نیز رخ نداده باشد، پیام «در حال دریافت پست‌ها…» به کاربر نمایش داده می‌شود. اگر خطایی وجود داشته باشد، سیستم یک پیام مناسب برای کاربر نمایش می‌دهد.
• نمایش پست‌ها: پس از دریافت موفق داده‌ها، پست‌ها با استفاده از متد
  map
  map در رابط کاربری رندر می‌شوند.

در نهایت، زمانی که فرآیند بارگذاری با موفقیت انجام شود، کاربران باید بتوانند ۱۰۰ پست را روی صفحه مشاهده کنند. اگر همه مراحل را به‌درستی طی کرده باشیم، این تعداد پست قابل نمایش خواهد بود. در غیر این صورت، لازم است بررسی کنیم که درخواست

جمع‌بندی

با اضافه کردن Zod به روند توسعه React، می‌توانیم برنامه‌هایی مقاوم‌تر و قابل‌اعتمادتر بسازیم.

Zod این امکان را فراهم می‌کند تا ما در همان مراحل اولیه، ناسازگاری‌های داده‌ای را شناسایی کنیم و جلوی خطاهای پیچیده را بگیریم. این ویژگی موجب صرفه‌جویی در زمان اشکال‌زدایی و افزایش کیفیت کد خواهد شد.

همچنین، پیام‌های خطای قابل‌فهم و کاربرپسند Zod، تجربه کاربری را بهبود می‌بخشند و توسعه‌دهندگان را در شناسایی سریع‌تر مشکلات یاری می‌دهند.