در این فصل چه یاد میگیری#
این فصل قلبِ ترم است. هیچ مفهومِ تازهای از API یاد نمیگیری؛ همهچیزی را که در فصلهای ۳ تا ۵ ساختی برمیداری و به یک ابزارِ واقعیِ کامل تبدیل میکنی: دستیارِ من. تفاوتِ یک تمرین با یک ابزارِ واقعی در مسیرهای بدِ کار است — وقتی کاربر دکمه را خالی میزند، وقتی اینترنت قطع است، وقتی کلید غلط است، وقتی جواب دارد میآید و هنوز نرسیده. ابزارِ خوب در هر کدام از این حالتها به کاربر میگوید چه خبر است، بهجای اینکه ساکت بماند یا بشکند.

آخر این فصل میتوانی:
- چهار حالتِ یک ابزار را بشناسی و مدیریت کنی: ورودیِ خالی، انتظار، جوابِ موفق، خطا
- دکمه را وقتِ کار غیرفعال کنی تا کاربر دو بار پشتِهم درخواست نفرستد
- با
try/catchو چکِres.okخطاها را به پیامِ دوستانه تبدیل کنی - کلِ اپِ
BYOKرا با هر سه فایلش سرِ هم و اجرا کنی
قبل از شروع#
- از فصل ۳: اپِ پایه — کلید، سؤال، دکمه، و نمایشِ جواب.
- از فصل ۴:
system_instructionدر بدنهٔ درخواست. - از ترم ۷ تاروپود (پیشنیاز):
try/catchبرای قطعیِ شبکه و چکِres.okبرای جوابِ ناسالمِ سرور.
مثلِ همیشه فقط یک مرورگر و کلیدِ رایگانِ خودت لازم داری. یادت باشد کلید از <input type="password"> خوانده میشود و هرگز داخلِ کدِ منتشرشده نمیرود.
۱. یک اپ فقط مسیرِ خوش نیست#
در فصلهای قبل کدِ ما فرض میکرد همهچیز درست پیش میرود: کلید هست، سؤال هست، اینترنت وصل است، سرور جواب میدهد. این «مسیرِ خوش» است. ولی کاربرِ واقعی گاهی دکمه را بدونِ نوشتنِ چیزی میزند؛ گاهی کلید را اشتباه میچسباند؛ گاهی وسطِ کار وایفای میپرد. اگر برنامه برای اینها آماده نباشد، یا هیچ واکنشی نشان نمیدهد و کاربر گیج میماند، یا با یک خطای قرمز در console میشکند که کاربر اصلاً نمیبیندش.
پس چهار حالت را جدا مدیریت میکنیم: ورودیِ خالی (چیزی نپرس، فقط بگو چه کم است)، انتظار (جواب در راه است، صبر کن)، موفق (این هم جوابت)، و خطا (مشکلی پیش آمد، اینطور دوباره امتحان کن). این چهار حالت همان چیزی است که یک تمرین را به یک ابزار تبدیل میکند.
۲. نگهبانِ ورودی، حالتِ انتظار، و دکمهٔ غیرفعال#
قبل از اینکه اصلاً درخواستی بفرستیم، دو چیز را چک میکنیم و دو حالت را روشن میکنیم:
answer.textContent = "";
if (key === "" || prompt === "") {
status.textContent = "کلید و سؤال را بگذار.";
return;
}
status.textContent = "در حالِ فکر کردن…";
askBtn.disabled = true;
اول جوابِ قبلی را پاک میکنیم تا کاربر جوابِ کهنه را اشتباه نگیرد. بعد اگر کلید یا سؤال خالی بود، یک پیامِ کوتاه میدهیم و با return همانجا میایستیم — بیفایده است که یک درخواستِ خالی به سرور بفرستیم. اگر همهچیز سرِ جایش بود، حالتِ انتظار را روشن میکنیم («در حالِ فکر کردن…») و دکمه را با askBtn.disabled = true غیرفعال میکنیم. این دومی مهم است: بدونش کاربرِ بیحوصله چند بار پشتِهم دکمه را میزند و چند درخواستِ موازی میفرستد که هم گیجکننده است و هم سهمیهات را زودتر تمام میکند.
💡 نکته: «در حالِ فکر کردن…» فقط ادب نیست؛ کاربردی است. بینِ زدنِ دکمه و رسیدنِ جواب یک لحظهٔ خالی هست، و اگر صفحه هیچ نشانهای ندهد، کاربر فکر میکند دکمه خراب است و دوباره میزند. یک خطِ کوتاه این را حل میکند.
۳. مسیرِ خطا: try/catch و res.ok#
حالا درخواست را داخلِ یک try میگذاریم تا اگر اینترنت قطع بود و fetch ترکید، بهجای شکستنِ برنامه به catch برویم. و وقتی جواب آمد، قبل از خواندنش سلامتش را میسنجیم:
if (res.status === 429) {
status.textContent = "سهمیهٔ الان تمام شد؛ کمی بعد دوباره امتحان کن.";
return;
}
if (!res.ok) {
status.textContent = "خطا از سرور: " + res.status;
return;
}
خطِ اولْ یک حالتِ خاص را میگیرد: کدِ 429، وقتی سرور موقتاً میگوید «الان زیادی پرسیدی، کمی صبر کن». فعلاً همینقدر بدان؛ چراییِ کامل و مدیریتِ سهمیه را فصل بعد باز میکنیم. خطِ دوم با res.ok — همان که در تاروپود دیدی — هر جوابِ ناسالمِ دیگر را میگیرد (مثلاً کلیدِ غلط) و بهجای ترکیدن، شمارهٔ خطا را نشان میدهد.
و در پایانِ کار، چه موفق چه ناموفق، دکمه را دوباره فعال میکنیم. جایش در finally است، چون finally در هر صورت اجرا میشود — حتی اگر وسطِ راه با return بیرون زده باشیم:
} catch (e) {
status.textContent = "در اینترنت یا کلیدت مشکلی هست؛ دوباره امتحان کن.";
} finally {
askBtn.disabled = false;
}
اگر دکمه را در finally فعال نکنی، یک اشتباهِ کوچک کلِ ابزار را از کار میاندازد: یکبار که اینترنت بپرد، دکمه برای همیشه غیرفعال میماند و کاربر مجبور میشود صفحه را از نو بارگذاری کند.
۴. اپِ کامل: هر سه فایل#
حالا همهچیز کنارِ هم. این script.jsِ نهایی است. یک فرق با فصل ۴ دارد: generationConfig را برداشتهایم، چون temperature روی مدلهای تازه نادیده گرفته میشود و ممکن است روزی با خطا رد شود، و اپی که قرار است بماند نباید به چنین چیزی تکیه کند:
// script.js
// modelِ رایگان — dar zaman-e khandan az mostanadat-e Gemini check kon:
const MODEL = "gemini-flash-latest";
const URL = "https://generativelanguage.googleapis.com/v1beta/models/" + MODEL + ":generateContent";
const askBtn = document.querySelector("#ask");
askBtn.addEventListener("click", async function () {
const key = document.querySelector("#key").value.trim();
const prompt = document.querySelector("#prompt").value.trim();
const status = document.querySelector("#status");
const answer = document.querySelector("#answer");
answer.textContent = "";
if (key === "" || prompt === "") {
status.textContent = "کلید و سؤال را بگذار.";
return;
}
status.textContent = "در حالِ فکر کردن…";
askBtn.disabled = true;
try {
const res = await fetch(URL + "?key=" + key, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
system_instruction: {
parts: [{ text: "تو یک دستیارِ فارسی، دقیق و کوتاهگو هستی." }]
},
contents: [{ parts: [{ text: prompt }] }]
})
});
if (res.status === 429) {
status.textContent = "سهمیهٔ الان تمام شد؛ کمی بعد دوباره امتحان کن.";
return;
}
if (!res.ok) {
status.textContent = "خطا از سرور: " + res.status;
return;
}
const data = await res.json();
const text = data.candidates[0].content.parts[0].text;
status.textContent = "";
answer.textContent = text;
} catch (e) {
status.textContent = "در اینترنت یا کلیدت مشکلی هست؛ دوباره امتحان کن.";
} finally {
askBtn.disabled = false;
}
});
این index.html:
<!DOCTYPE html>
<html lang="fa" dir="rtl">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>دستیارِ من</title>
<link rel="stylesheet" href="styles.css">
</head>
<body>
<main>
<h1>دستیارِ من</h1>
<p class="hint">کلیدِ Gemini خودت را بگذار، بعد بپرس.</p>
<input type="password" id="key" placeholder="کلیدِ API خودت — روی کامپیوترِ خودت میماند">
<textarea id="prompt" placeholder="سؤالت را اینجا بنویس"></textarea>
<button id="ask">بپرس</button>
<p id="status" class="status"></p>
<div id="answer" class="answer"></div>
</main>
<script src="script.js"></script>
</body>
</html>
و این styles.css:
/* styles.css */
body { font-family: Vazirmatn, Tahoma, sans-serif; background: #0f1413; color: #e9ede9; }
main { max-width: 640px; margin: 2rem auto; padding: 0 1rem; }
h1 { color: #2fc6ce; }
input, textarea { width: 100%; margin: 0.5rem 0; padding: 0.7rem; box-sizing: border-box;
background: #151b19; color: #e9ede9; border: 1px solid #253029; border-radius: 8px; }
textarea { min-height: 8rem; }
button { background: #2fc6ce; color: #06130b; border: 0; padding: 0.7rem 1.4rem;
border-radius: 8px; font-size: 1rem; cursor: pointer; }
button:disabled { opacity: 0.6; }
.status { color: #98a49e; }
.answer { white-space: pre-wrap; margin-top: 1rem; padding: 1rem;
background: #151b19; border-radius: 8px; min-height: 2rem; }
به دو تکهٔ کوچکِ استایل دقت کن که مستقیم به حالتها وصلاند: button:disabled { opacity: 0.6; } دکمهٔ غیرفعال را کمرنگ نشان میدهد تا کاربر ببیند الان نمیشود زد، و white-space: pre-wrap روی .answer باعث میشود خطشکنهای جوابِ مدل حفظ شوند.
✅ چک کن: هر چهار حالت را یکییکی امتحان کن. (۱) دکمه را با کادرِ خالی بزن → «کلید و سؤال را بگذار». (۲) کلید و سؤال بگذار و بزن → «در حالِ فکر کردن…» و بعد جواب. (۳) وسطِ کار به دکمهٔ غیرفعالِ کمرنگ نگاه کن. (۴) اینترنت را قطع کن و بزن → پیامِ دوستانهٔ
catch. اگر هر چهار درست بود، ابزارت واقعاً کامل است.
🔧 اگر جواب نگرفتی: اگر «خطا از سرور: 400» گرفتی، تقریباً همیشه یعنی کلید غلط است یا بدنهٔ
JSONخراب است — کلید را دوباره کپی کن و مطمئن شو ساختارِbodyرا دستنخورده گذاشتهای. اگر پیامِcatchرا بیدلیل میگیری، احتمالاً اینترنت یا فیلترِ شبکه جلوی درخواست را گرفته. جدولِ پایین بقیهٔ کدها را میگوید.
| چیزی که روی صفحه میبینی | معنایش |
|---|---|
خطا از سرور: 400 |
کلیدِ غلط یا بدنهٔ خراب |
خطا از سرور: 403 |
کلید اجازه ندارد؛ مثلاً لو رفته و مسدود شده. یک کلیدِ تازه بساز |
خطا از سرور: 404 |
نامِ مدل در ثابتِ MODEL دیگر معتبر نیست؛ فهرستِ مدلها را چک کن |
خطا از سرور: 503 |
سرویس موقتاً شلوغ است؛ کمی بعد دوباره بفرست |
یک نکته دربارهٔ پیامِ catch: با اینکه میگوید «اینترنت یا کلید»، کلیدِ غلط هرگز به آن نمیرسد، چون کدِ 400 همان !res.ok را فعال میکند. این پیام وقتی میآید که چیزی داخلِ try بترکد. یعنی یا اصلاً جوابی نیامده، یا جواب آمده ولی candidates[0].content.parts[0].text در آن نیست. حالتِ دوم نادر است، ولی واقعی است: مثلاً مدل بهخاطرِ قواعدِ ایمنی جواب نداده باشد. اگر میخواهی پیامت دقیقتر باشد، متنش را به «جوابی نرسید؛ اینترنت را چک کن و دوباره امتحان کن» عوض کن.
۵. یک ابزارِ صیقلی، هنوز یک ماشینِ حدس#
حالا اپت تر و تمیز بهنظر میرسد: پیامهای مرتب، دکمهٔ هوشمند، و جوابی که با اطمینان روی صفحه مینشیند. ولی مواظبِ یک تله باش: صیقلیبودنِ ظاهر، درستیِ محتوا را تضمین نمیکند. همان مدل با همان system_instruction، پشتِ این رابطِ تمیز، هنوز کلمهبهکلمه حدس میزند و میتواند مطمئن ولی غلط جواب بدهد.
✅ وارسی: یک رابطِ حرفهای به جوابِ مدل اعتبارِ ظاهری میدهد که لزوماً حقش نیست. برای هر جوابی که یک ادعای واقعی دارد، همان عادتِ همیشگی: با یک منبعِ مستقل بسنج، نه با خودِ ابزار. سه قانونِ ثابتِ این دوره: «اول خودت فکر کن» — «وارسی کن، خط به خط» — «مدل مطمئن است؛ دلیل نمیشود درست باشد».
⚠️ مواظب باش: این ابزار
BYOKاست — کلید از کادرِ رمز خوانده میشود و در کد نیست. همینطور نگهش دار: هیچوقت کلید را داخلِscript.jsننویس، وگرنه با انتشارِ صفحه هر بازدیدکنندهای میتواند بخواندش. و یادت باشد ردهٔ رایگان ممکن است پرامپت و جوابت را برای آموزش استفاده کند؛ پس دادهٔ خصوصی به این ابزار نده.
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
ابزارت کار میکند و در برابرِ خطاها محکم است. ولی یک خطِ کوچک در کد بود که رویش سریع گذشتیم — همان res.status === 429. فصل بعد سراغِ هزینه، سهمیه و مرزها میرویم: میفهمی چرا سرور گاهی میگوید «کمی صبر کن»، چطور با سهمیه مهربان باشی، و چرا اینکه کلید مالِ خودِ کاربر است، هم یک تصمیمِ اخلاقی است و هم یک تصمیمِ عملی دربارهٔ هزینه.
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.