ایجاد یک میکروسرویس CRUD مبتنی بر داده قسمت دوم

رشته اتصال DB و متغیرهای محیطی که توسط کانتینرهای Docker استفاده می شود

می‌توانید از تنظیمات ASP.NET Core استفاده کنید و یک ویژگی ConnectionString به فایل settings.json خود اضافه کنید، همانطور که در مثال زیر نشان داده شده است:

{

"ConnectionString": "Server=tcp:127.0.0.1,5433;Initial Catalog=Microsoft.eShopOnContainers.Services.CatalogDb;User Id=sa;Password=[PLACEHOLDER]",

"ExternalCatalogBaseUrl": "http://host.docker.internal:5101",

"Logging": {

"IncludeScopes": false,

"LogLevel": {

"Default": "Debug",

"System": "Information",

"Microsoft": "Information"

}

}

}

فایل settings.json می‌تواند مقادیر پیش‌فرض برای ویژگی ConnectionString یا هر ویژگی دیگری داشته باشد. با این حال، این ویژگی‌ها با مقادیر متغیرهای محیطی که در فایل docker-compose.override.yml مشخص می‌کنید، هنگام استفاده از Docker لغو می‌شوند.

از فایل‌های docker-compose.yml یا docker-compose.override.yml خود، می‌توانید آن متغیرهای محیطی را مقداردهی اولیه کنید تا Docker آنها را به عنوان متغیرهای محیط سیستم عامل برای شما تنظیم کند، همانطور که در فایل docker-compose.override.yml زیر نشان داده شده است. (رشته اتصال و خطوط دیگر در این مثال پیچیده می شود، اما در فایل خود شما قرار نمی گیرد).

# docker-compose.override.yml

#

catalog-api:

environment:

- ConnectionString=Server=sqldata;Database=Microsoft.eShopOnContainers.Services.CatalogDb;User Id=sa;Password=[PLACEHOLDER]

# Additional environment variables for this service

ports:

- "5101:80"

فایل‌های docker-compose.yml در سطح راه‌حل نه تنها نسبت به فایل‌های پیکربندی در سطح پروژه یا میکروسرویس انعطاف‌پذیرتر هستند، بلکه اگر متغیرهای محیطی اعلام‌شده در فایل‌های docker-compose را با مقادیر تنظیم‌شده از ابزارهای استقرار خود لغو کنید، امنیت بیشتری نیز دارند. ، مانند وظایف استقرار Azure DevOps Services Docker.

در نهایت، همانطور که در روش ConfigureServices در نمونه کد قبلی نشان داده شده است، می توانید با استفاده از Configuration["ConnectionString"] آن مقدار را از کد خود دریافت کنید.

با این حال، برای محیط های تولید، ممکن است بخواهید راه های دیگری را در مورد نحوه ذخیره اسرار مانند رشته های اتصال کشف کنید. یک راه عالی برای مدیریت اسرار برنامه استفاده از Azure Key Vault است.

Azure Key Vault به ذخیره و محافظت از کلیدهای رمزنگاری و اسرار مورد استفاده توسط برنامه‌ها و سرویس‌های ابری شما کمک می‌کند. یک راز هر چیزی است که می‌خواهید کنترل دقیقی روی آن داشته باشید، مانند کلیدهای API، رشته‌های اتصال، گذرواژه‌ها و غیره و کنترل دقیق شامل ثبت استفاده، تنظیم انقضا، مدیریت دسترسی و غیره است.

Azure Key Vault اجازه می دهد تا سطح کنترل دقیق استفاده از اسرار برنامه را بدون نیاز به اطلاع دیگران از آنها انجام دهید. رازها حتی می توانند برای افزایش امنیت بدون ایجاد اختلال در توسعه یا عملیات چرخانده شوند.

برنامه ها باید در اکتیو دایرکتوری سازمان ثبت شوند تا بتوانند از Key Vault استفاده کنند.

پیاده سازی نسخه سازی در ASP.NET Web API

با تغییر نیازهای کسب و کار، ممکن است مجموعه های جدیدی از منابع اضافه شود، روابط بین منابع ممکن است تغییر کند و ساختار داده ها در منابع ممکن است اصلاح شود. به روز رسانی Web API برای رسیدگی به نیازهای جدید یک فرآیند نسبتاً ساده است، اما باید تأثیراتی را که چنین تغییراتی بر برنامه های مشتری مصرف کننده Web API خواهند داشت، در نظر بگیرید. اگرچه توسعه‌دهنده‌ای که یک Web API را طراحی و اجرا می‌کند، کنترل کاملی بر آن API دارد، توسعه‌دهنده آن درجه از کنترل روی برنامه‌های کلاینت را ندارد که ممکن است توسط سازمان‌های شخص ثالث که از راه دور کار می‌کنند ساخته شوند.

نسخه‌سازی Web API را قادر می‌سازد تا ویژگی‌ها و منابعی را که در معرض نمایش قرار می‌دهد را نشان دهد. سپس یک برنامه مشتری می تواند درخواست هایی را به نسخه خاصی از یک ویژگی یا منبع ارسال کند. چندین رویکرد برای پیاده سازی نسخه سازی وجود دارد:

• نسخه URI
• نسخه سازی رشته پرس و جو
• نسخه هدر

رشته کوئری و نسخه‌سازی URI ساده‌ترین روش‌ها برای پیاده‌سازی هستند. نسخه نویسی هدر رویکرد خوبی است. با این حال، نسخه‌سازی هدر به اندازه نسخه‌سازی URI صریح و ساده نیست. از آنجا که نسخه‌سازی URL ساده‌ترین و واضح‌ترین است، برنامه نمونه eShopOnContainers از نسخه‌سازی URI استفاده می‌کند.

با نسخه‌سازی URI، مانند برنامه نمونه eShopOnContainers، هر بار که Web API را تغییر می‌دهید یا طرح منابع را تغییر می‌دهید، برای هر منبع یک شماره نسخه به URI اضافه می‌کنید. URI های موجود باید مانند قبل به کار خود ادامه دهند و منابعی را برگردانند که با طرحی مطابق با نسخه درخواستی مطابقت دارند.

همانطور که در مثال کد زیر نشان داده شده است، نسخه را می توان با استفاده از ویژگی Route در کنترلر Web API تنظیم کرد، که نسخه را در URI واضح می کند (در این مورد v1).

[Route("api/v1/[controller]")]

public class CatalogController : ControllerBase

{

// Implementation ...

این مکانیسم نسخه سازی ساده است و بستگی به این دارد که سرور درخواست را به نقطه پایانی مناسب هدایت کند. با این حال، برای نسخه‌سازی پیچیده‌تر و بهترین روش در هنگام استفاده از REST، باید از هایپر مدیا استفاده کنید و HATEOAS (فوق متن به عنوان موتور حالت برنامه) را پیاده‌سازی کنید.

ایجاد ابرداده توضیحات Swagger از ASP.NET Core Web API

Swagger یک چارچوب متن باز پر استفاده است که توسط اکوسیستم بزرگی از ابزارها پشتیبانی می شود که به شما کمک می کند API های RESTful خود را طراحی، ساخت، مستندسازی و مصرف کنید. این در حال تبدیل شدن به استانداردی برای دامنه فراداده توصیف APIها است. شما باید ابرداده توضیحات Swagger را با هر نوع میکروسرویس، اعم از میکروسرویس‌های مبتنی بر داده یا میکروسرویس‌های پیشرفته‌تر مبتنی بر دامنه اضافه کنید.

قلب Swagger مشخصات Swagger است، که ابرداده توضیحات API در یک فایل JSON یا YAML است. این مشخصات قرارداد RESTful را برای API شما ایجاد می‌کند و تمام منابع و عملیات آن را در قالبی قابل خواندن توسط انسان و ماشین برای توسعه، کشف و ادغام آسان توضیح می‌دهد.

این مشخصات اساس مشخصات OpenAPI (OAS) است و در یک جامعه باز، شفاف و مشارکتی برای استانداردسازی روش تعریف رابط های RESTful توسعه یافته است.

چرا از Swagger استفاده کنیم؟

دلایل اصلی برای ایجاد ابرداده Swagger برای API های شما موارد زیر است.

توانایی سایر محصولات برای مصرف خودکار و ادغام API های شما. ده ها محصول و ابزار تجاری و بسیاری از کتابخانه ها و چارچوب ها از Swagger پشتیبانی می کنند. مایکروسافت محصولات و ابزارهای سطح بالایی دارد که می توانند به طور خودکار API های مبتنی بر Swagger را مصرف کنند، مانند موارد زیر:

• استراحت خودکار. می توانید به طور خودکار کلاس های کلاینت دات نت را برای فراخوانی Swagger ایجاد کنید. این ابزار را می توان از CLI استفاده کرد و همچنین برای استفاده آسان از طریق رابط کاربری گرافیکی با ویژوال استودیو ادغام می شود.

• مایکروسافت فلو. می‌توانید به‌طور خودکار از API خود استفاده کرده و در یک جریان کاری سطح بالا Microsoft Flow، بدون نیاز به مهارت‌های برنامه‌نویسی، ادغام کنید.

• Microsoft Power Apps. می‌توانید به‌طور خودکار API خود را از برنامه‌های تلفن همراه PowerApps که با PowerApps Studio ساخته شده‌اند، بدون نیاز به مهارت برنامه‌نویسی مصرف کنید.

• Azure App Service Logic Apps. می‌توانید بدون نیاز به مهارت برنامه‌نویسی، به‌طور خودکار از API خود در یک برنامه منطقی سرویس Azure App استفاده کرده و ادغام کنید.

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

ابرداده Swagger همان چیزی است که Microsoft Flow، PowerApps و Azure Logic Apps برای درک نحوه استفاده از APIها و اتصال به آنها استفاده می کنند.

چندین گزینه برای خودکارسازی تولید ابرداده Swagger برای برنامه‌های ASP.NET Core REST API، در قالب صفحات راهنمای کاربردی API، بر اساس swagger-ui وجود دارد.

احتمالاً بهترین دانش Swashbuckle است که در حال حاضر در eShopOnContainers استفاده می شود و ما در این راهنما به جزئیات خواهیم پرداخت، اما گزینه ای برای استفاده از NSwag نیز وجود دارد که می تواند کلاینت های Typescript و C# API و همچنین کنترلرهای C# را از یک مشخصات Swagger یا OpenAPI و حتی با اسکن .dll حاوی کنترلرها، با استفاده از NSwagStudio.

چگونه با بسته Swashbuckle NuGet تولید ابرداده API Swagger را خودکار کنیم

ایجاد ابرداده Swagger به صورت دستی (در یک فایل JSON یا YAML) می تواند کار خسته کننده ای باشد. با این حال، می توانید با استفاده از بسته Swashbuckle NuGet برای تولید متاداده Swagger API به صورت پویا، کشف API سرویس های ASP.NET Web API را خودکار کنید.

Swashbuckle به طور خودکار ابرداده Swagger را برای پروژه های ASP.NET Web API شما تولید می کند. این برنامه از پروژه های ASP.NET Core Web API و ASP.NET Web API سنتی و هر طعم دیگری مانند Azure API App، Azure Mobile App، میکروسرویس های Azure Service Fabric مبتنی بر ASP.NET پشتیبانی می کند. همچنین از Web API ساده مستقر در کانتینرها، مانند برنامه مرجع، پشتیبانی می کند.

Swashbuckle API Explorer و Swagger یا swagger-ui را با هم ترکیب می‌کند تا تجربه‌ای غنی از کشف و مستندسازی را برای مصرف‌کنندگان API شما فراهم کند. Swashbuckle علاوه بر موتور مولد ابرداده Swagger، دارای یک نسخه جاسازی شده از swagger-ui نیز می باشد که پس از نصب Swashbuckle به طور خودکار به کار می رود.

این بدان معناست که می‌توانید API خود را با یک رابط کاربری جدید برای کمک به توسعه‌دهندگان در استفاده از API خود تکمیل کنید. به مقدار کمی کد و نگهداری نیاز دارد زیرا به طور خودکار تولید می شود و به شما امکان می دهد بر روی ساخت API خود تمرکز کنید. نتیجه API Explorer مانند شکل 6-8 است.

اسناد API Swagger UI ایجاد شده توسط Swashbuckle شامل تمام اقدامات منتشر شده است. کاوشگر API مهمترین چیز در اینجا نیست. هنگامی که یک Web API دارید که می تواند خود را در ابرداده Swagger توصیف کند، API شما می تواند به طور یکپارچه از ابزارهای مبتنی بر Swagger استفاده شود، از جمله تولیدکنندگان کد کلاس پروکسی مشتری که می توانند پلتفرم های زیادی را هدف قرار دهند. به عنوان مثال، همانطور که گفته شد، AutoRest به طور خودکار کلاس های کلاینت دات نت را تولید می کند. اما ابزارهای اضافی مانند swagger-codegen نیز در دسترس هستند که امکان تولید کد کتابخانه های سرویس گیرنده API، خرد سرور و مستندات را به صورت خودکار فراهم می کند.

در حال حاضر، Swashbuckle از پنج بسته داخلی NuGet تحت متا بسته بندی سطح بالا Swashbuckle.AspNetCore برای برنامه های ASP.NET Core تشکیل شده است.

بعد از اینکه این بسته های NuGet را در پروژه Web API خود نصب کردید، باید Swagger را در کلاس Startup پیکربندی کنید، مانند کد ساده شده زیر:

public class Startup

{

public IConfigurationRoot Configuration { get; }

// Other startup code...

public void ConfigureServices(IServiceCollection services)

{

// Other ConfigureServices() code...

// Add framework services.

services.AddSwaggerGen(options =>

{

options.DescribeAllEnumsAsStrings();

options.SwaggerDoc("v1", new OpenApiInfo

{

Title = "eShopOnContainers - Catalog HTTP API",

Version = "v1",

Description = "The Catalog Microservice HTTP API. This is a Data-Driven/CRUD microservice sample"

});

});

// Other ConfigureServices() code...

}

public void Configure(IApplicationBuilder app,

IHostingEnvironment env,

ILoggerFactory loggerFactory)

{

// Other Configure() code...

// ...

app.UseSwagger()

.UseSwaggerUI(c =>

{

c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

});

}

}

پس از انجام این کار، می توانید برنامه خود را راه اندازی کنید و با استفاده از URL هایی مانند این، نقاط پایانی Swagger JSON و UI زیر را مرور کنید:

http://<your-root-url>/swagger/v1/swagger.json

http://<your-root-url>/swagger/

شما قبلاً رابط کاربری ایجاد شده توسط Swashbuckle را برای نشانی اینترنتی مانند http://<your-root-url>/swagger مشاهده کرده‌اید. در شکل 6-9، همچنین می توانید ببینید که چگونه می توانید هر روش API را آزمایش کنید.

جزئیات API UI Swagger نمونه ای از پاسخ را نشان می دهد و می توان از آن برای اجرای API واقعی استفاده کرد که برای کشف توسعه دهندگان عالی است. شکل 6-10 ابرداده JSON Swagger را نشان می‌دهد که از ریزسرویس eShopOnContainers (که ابزارها در زیر آن استفاده می‌کنند) هنگامی که شما http://<your-root-url>/swagger/v1/swagger.json را با استفاده از Postman درخواست می‌کنید، نشان می‌دهد.

به همین سادگی است. و از آنجایی که به طور خودکار تولید می شود، زمانی که عملکرد بیشتری به API خود اضافه کنید، ابرداده Swagger رشد خواهد کرد.