ساخت پروژه و اولین Controller

.NET 10 | Project Structure و Controller-based API

ساختار اولیه پروژه باید Bootstrapping، ثبت Serviceها، Middlewareها و Endpointها را از هم قابل تشخیص نگه دارد. در سبک Controller-based، Controllerها قرارداد HTTP را تعریف می‌کنند و Program.cs نقطه Composition برنامه است.

این فصل با تمرکز بر قراردادهای قابل اتکا، مرزبندی مسئولیت‌ها و رفتار قابل پیش‌بینی در محیط واقعی تنظیم شده است. مثال‌ها بر پایه ASP.NET Core و .NET 10 نوشته شده‌اند.

1. چارچوب موضوع و مفاهیم اصلی

ساختار اولیه پروژه باید Bootstrapping، ثبت Serviceها، Middlewareها و Endpointها را از هم قابل تشخیص نگه دارد. در سبک Controller-based، Controllerها قرارداد HTTP را تعریف می‌کنند و Program.cs نقطه Composition برنامه است.

واژگان و قراردادهای این بخش باید در سراسر پروژه یکدست بمانند؛ تفاوت میان لایه HTTP، منطق برنامه و زیرساخت زمانی روشن می‌ماند که مسئولیت هر جزء به‌صورت صریح تعریف شود.

2. ساختار پیشنهادی در پروژه

پروژه با Template webapi و گزینه --use-controllers ایجاد می‌شود. سپس AddControllers در Container ثبت و MapControllers در Pipeline فراخوانی می‌شود. Controllerها در پوشه یا ماژول مشخص نگهداری می‌شوند.

dotnet new webapi -n ProductApi --use-controllers
cd ProductApi
dotnet run

3. سناریوی اجرایی

یک ProductsController ساده ساخته می‌شود که مسیر ثابت api/products را پاسخ می‌دهد. Action فقط وظیفه تبدیل Request به Response را بر عهده دارد و منطق دامنه در فصل‌های بعد از آن جدا می‌شود.

در این سناریو، قرارداد ورودی و خروجی، مسیر شکست و رفتار قابل مشاهده سرویس باید پیش از جزئیات پیاده‌سازی مشخص شود. این رویکرد باعث می‌شود تغییرات بعدی بدون وابستگی پنهان و با امکان تست دقیق انجام شوند.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();
app.UseHttpsRedirection();
app.MapControllers();
app.Run();

4. اصول طراحی و نگهداری

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

• Program.cs کوتاه و نقش آن محدود به Composition باقی بماند.
• Controllerها sealed و وابستگی‌ها از Constructor دریافت شوند.
• Routeها صریح و قابل پیش‌بینی باشند.
• کد محیط Development از Production جدا شود.

5. خطاهای رایج و کنترل آن‌ها

بخش مهمی از کیفیت یک API در نحوه جلوگیری از خطاهای تکرارشونده مشخص می‌شود. موارد زیر باید در بازبینی کد و تست‌های قبل از انتشار کنترل شوند.

• فراموش کردن MapControllers و دریافت 404 برای همه Actionها.
• قرار دادن Query دیتابیس مستقیماً در Program.cs.
• استفاده از Controller به‌عنوان Service یا Repository.
• وابستگی به URLهای تصادفی محیط محلی در کد.

6. چک‌لیست نهایی فصل

• SDK و Template صحیح شناسایی شده‌اند.
• پروژه Build و Run می‌شود.
• Controller اولیه با GET پاسخ می‌دهد.
• ساختار Program.cs خوانا و حداقلی است.

7. جمع‌بندی

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