پیام خطا باید مشکل را توضیح دهد، راه اصلاح ورودی را نشان دهد و شناسه‌ای برای پیگیری داشته باشد. جزئیات داخلی، متن کوئری‌ها یا اطلاعات محرمانه نباید در پاسخ عمومی قرار بگیرند.An error response should explain the problem, help the caller correct input, and include a traceable identifier. Internal details, query text, and secrets should not appear in public responses.
نوشته‌هاWriting
یادداشت‌هایی درباره تصمیم‌های فنیNotes on engineering decisions
موضوع‌های کوتاه درباره API، داده و نگهداری نرم‌افزار؛ با تمرکز بر دلیل تصمیم و اثر آن روی پروژه.Short notes on APIs, data, and software maintenance, focused on why a decision matters and what it changes.
APIپاسخ خطای API باید چه اطلاعاتی داشته باشد؟What belongs in an API error response?+
DATAچرا قیمت زمان خرید را در سفارش ذخیره کنیم؟Why store the price at purchase time?+
قیمت فعلی محصول ممکن است تغییر کند، اما مبلغ سفارش قبلی باید ثابت بماند. بنابراین قیمت، تخفیف و اطلاعات لازم باید در ردیف سفارش ثبت شوند.A product’s current price can change, while a historical order should remain stable. Store the purchase-time price, discount, and necessary snapshot data on the order line.
DOCراهنمای اجرا هم بخشی از پروژه استSetup documentation is part of the project+
پروژه باید روی محیطی غیر از سیستم توسعه‌دهنده قابل راه‌اندازی باشد. پیش‌نیازها، متغیرهای محیطی و روش بررسی سلامت سیستم را مستند کنید.A project should be deployable outside the developer’s machine. Document prerequisites, environment variables, and a simple health-check procedure.
APIاول ورودی و خروجی را مشخص کنیدDefine inputs and outputs first+
قبل از پیاده‌سازی مسیر API، روش درخواست، آدرس، ورودی، پاسخ موفق و خطاهای مورد انتظار را مشخص کنید تا بک‌اند و رابط کاربری روی یک قرارداد مشترک کار کنند.Before implementing an endpoint, define the method, route, request, successful response, and expected errors so backend and frontend share the same contract.
DBقواعد مهم را در پایگاه داده هم اعمال کنیدEnforce important rules in the database too+
اعتبارسنجی رابط کاربری کافی نیست. یکتایی، ارتباط رکوردها و عملیات وابسته باید در سرور و پایگاه داده نیز کنترل شوند.UI validation is not enough. Uniqueness, record relationships, and dependent writes should also be enforced at the server and database layers.
LOGدر گزارش رویداد چه چیزهایی ثبت کنیم؟What should application logs contain?+
زمان، نوع رویداد، نتیجه و شناسه پیگیری مفیدند؛ رمز عبور، توکن و اطلاعات شخصی غیرضروری نه.Timestamp, event type, result, and trace ID are useful; passwords, tokens, and unnecessary personal data are not.