بهترین روش ها برای طراحی و توسعه پروکسی API

شما در حال مشاهده مستندات Apigee Edge هستید.
به مستندات Apigee X مراجعه کنید . اطلاعات

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

علاوه بر دستورالعمل‌های اینجا، ممکن است پست انجمن Apigee Edge Antipatterns نیز برای شما مفید باشد.

استانداردهای توسعه

نظرات و مستندات

  • در پیکربندی‌های ProxyEndpoint و TargetEndpoint، کامنت‌های درون‌خطی ارائه دهید. کامنت‌ها خوانایی یک Flow را افزایش می‌دهند، به‌ویژه در مواردی که نام فایل‌های Policy به اندازه کافی توصیفی نیستند تا عملکرد اساسی Flow را بیان کنند.
  • نظرات را مفید بنویسید. از نظرات واضح خودداری کنید.
  • از تورفتگی، فاصله‌گذاری، تراز عمودی و غیره به طور منظم استفاده کنید.

کدنویسی به سبک فریم‌ورک

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

  • برای فعال کردن DRY ("خودتان را تکرار نکنید")، در صورت امکان، پیکربندی‌ها و اسکریپت‌های سیاست باید توابع تخصصی و قابل استفاده مجدد را پیاده‌سازی کنند. به عنوان مثال، یک سیاست اختصاصی برای استخراج پارامترهای پرس‌وجو از پیام‌های درخواست می‌تواند ExtractVariables.ExtractRequestParameters نامیده شود. یک سیاست اختصاصی برای تزریق هدرهای CORS می‌تواند AssignMessage.SetCORSHeaders نامیده شود. سپس این سیاست‌ها می‌توانند در سیستم کنترل منبع شما ذخیره شوند و به هر پروکسی API که نیاز به استخراج پارامترها یا تنظیم هدرهای CORS دارد، اضافه شوند، بدون اینکه شما را ملزم به ایجاد پیکربندی‌های اضافی (و در نتیجه کمتر قابل مدیریت) کنند.
  • سیاست‌ها و منابع بلااستفاده (جاوااسکریپت، جاوا، XSLT و غیره) را از پروکسی‌های API، به ویژه منابع بزرگی که پتانسیل کند کردن رویه‌های واردات و استقرار را دارند، پاک کنید.

قراردادهای نامگذاری

  • ویژگی name سیاست و نام فایل سیاست XML باید یکسان باشند.
  • ویژگی name سیاست Script و ServiceCallout و نام فایل منبع باید یکسان باشند.
  • DisplayName باید عملکرد خط‌مشی را برای کسی که قبلاً هرگز با آن پروکسی API کار نکرده است، به طور دقیق توصیف کند.
  • سیاست‌ها را بر اساس عملکردشان نامگذاری کنید. Apigee توصیه می‌کند که یک قرارداد نامگذاری ثابت برای سیاست‌های خود ایجاد کنید. برای مثال، از پیشوندهای کوتاه و به دنبال آن دنباله‌ای از کلمات توصیفی که با خط تیره از هم جدا شده‌اند استفاده کنید. به عنوان مثال، AM-xxx برای سیاست‌های AssignMessage. همچنین به ابزار apigeelint مراجعه کنید.
  • از پسوندهای مناسب برای فایل‌های منبع، .js برای جاوا اسکریپت، .py برای پایتون و .jar برای فایل‌های JAR جاوا استفاده کنید.
  • نام متغیرها باید ثابت باشد. اگر سبکی مانند camelCase یا under_score انتخاب می‌کنید، آن را در سراسر پروکسی API استفاده کنید.
  • در صورت امکان، از پیشوندهای متغیر برای سازماندهی متغیرها بر اساس هدف آنها استفاده کنید، برای مثال، Consumer.username و Consumer.password .

توسعه پروکسی API

ملاحظات اولیه طراحی

  • برای راهنمایی در مورد طراحی RESTful API، کتاب الکترونیکی Web API Design: The Missing Link را دانلود کنید.
  • از سیاست‌ها و قابلیت‌های Apigee Edge در هر کجا که ممکن است برای ساخت پروکسی‌های API استفاده کنید. از کدنویسی تمام منطق پروکسی در منابع جاوا اسکریپت، جاوا یا پایتون خودداری کنید.
  • جریان‌ها را به شیوه‌ای سازمان‌یافته بسازید. جریان‌های چندگانه، که هر کدام یک شرط واحد دارند، نسبت به پیوست‌های شرطی متعدد به همان پیش‌جریان و پس‌جریان ارجحیت دارند.
  • به عنوان یک «ایمن»، یک پروکسی API پیش‌فرض با ProxyEndpoint BasePath برابر با / ایجاد کنید. این می‌تواند برای هدایت درخواست‌های API پایه به سایت توسعه‌دهنده، بازگرداندن یک پاسخ سفارشی یا انجام اقدام دیگری مفیدتر از بازگرداندن messaging.adaptors.http.flow.ApplicationNotFound پیش‌فرض استفاده شود.
  • از منابع TargetServer برای جدا کردن پیکربندی‌های TargetEndpoint از URLهای مشخص استفاده کنید و از ارتقاء در محیط‌های مختلف پشتیبانی کنید.
    به بخش متعادل‌سازی بار در سرورهای backend مراجعه کنید.
  • اگر چندین RouteRule دارید، یکی را به عنوان «پیش‌فرض» ایجاد کنید، یعنی به عنوان یک RouteRule بدون شرط. مطمئن شوید که RouteRule پیش‌فرض در آخرین مرحله از لیست مسیرهای مشروط تعریف شده باشد. RouteRuleها در ProxyEndpoint از بالا به پایین ارزیابی می‌شوند.
    به مرجع پیکربندی پروکسی API مراجعه کنید.
  • اندازه بسته پروکسی API: بسته‌های پروکسی API نمی‌توانند بزرگتر از ۱۵ مگابایت باشند. در Apigee Edge برای Private Cloud، می‌توانید محدودیت اندازه را با تغییر ویژگی thrift_framed_transport_size_in_mb در مکان‌های زیر تغییر دهید: cassandra.yaml (در Cassandra) و conf/apigee/management-server/repository.properties.
  • نسخه‌بندی API: برای نظرات و توصیه‌های Apigee در مورد نسخه‌بندی API، به بخش نسخه‌بندی در کتاب الکترونیکی طراحی API وب: حلقه گمشده مراجعه کنید.

فعال کردن CORS

قبل از انتشار APIهای خود، باید CORS را روی پروکسی‌های API خود فعال کنید تا از درخواست‌های بین‌منبعی سمت کلاینت پشتیبانی شود.

CORS (اشتراک‌گذاری منابع بین‌منبعی) یک مکانیزم استاندارد است که به فراخوانی‌های جاوا اسکریپت XMLHttpRequest (XHR) که در یک صفحه وب اجرا می‌شوند، اجازه می‌دهد تا با منابع دامنه‌های غیرمبدأی تعامل داشته باشند. CORS یک راه‌حل رایج برای سیاست مبدأ یکسان است که توسط همه مرورگرها اجرا می‌شود. به عنوان مثال، اگر از طریق اجرای کد جاوا اسکریپت در مرورگر خود، یک فراخوانی XHR به API توییتر انجام دهید، فراخوانی با شکست مواجه خواهد شد. دلیل این امر این است که دامنه‌ای که صفحه را به مرورگر شما ارائه می‌دهد، همان دامنه‌ای نیست که API توییتر را ارائه می‌دهد. CORS با اجازه دادن به سرورها برای "انتخاب" در صورت تمایل به ارائه اشتراک‌گذاری منابع بین‌منبعی، راه‌حلی برای این مشکل ارائه می‌دهد.

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

اندازه بار پیام

برای جلوگیری از مشکلات حافظه در Edge، اندازه بار پیام به 10 مگابایت محدود شده است. تجاوز از این اندازه‌ها منجر به خطای protocol.http.TooBigBody می‌شود.

این موضوع همچنین در این پست انجمن Apigee مورد بحث قرار گرفته است.

در ادامه استراتژی‌های پیشنهادی برای مدیریت حجم بالای پیام‌ها در Edge آمده است:

  • درخواست‌ها و پاسخ‌های استریم. توجه داشته باشید که وقتی استریم می‌کنید، سیاست‌ها دیگر به محتوای پیام دسترسی ندارند. به درخواست‌ها و پاسخ‌های استریم مراجعه کنید.
  • در نسخه ۴.۱۵.۰۷ و قبل از آن از مرورگر Edge برای فضای ابری خصوصی، فایل http.properties پردازشگر پیام را ویرایش کنید تا محدودیت پارامتر HTTPResponse.body.buffer.limit افزایش یابد. قبل از اعمال تغییر در محیط عملیاتی، حتماً آن را آزمایش کنید.
  • در نسخه ۴.۱۶.۰۱ و بالاتر Edge برای Private Cloud، درخواست‌هایی که دارای بار داده (payload) هستند باید شامل هدر Content-Length یا در صورت پخش جریانی، هدر "Transfer-Encoding: chunked" باشند. برای ارسال POST به یک پروکسی API با بار داده خالی، باید مقدار Content-Length را ۰ قرار دهید.
  • در نسخه ۴.۱۶.۰۱ و بالاتر مرورگر اج برای فضای ابری خصوصی، برای تغییر محدودیت‌ها، ویژگی‌های زیر را در /opt/apigee/router.properties یا message-processor.properties تنظیم کنید. برای اطلاعات بیشتر به بخش «تنظیم محدودیت اندازه پیام روی روتر یا پردازنده پیام» مراجعه کنید.

    هر دو ویژگی مقدار پیش‌فرض "10m" معادل 10 مگابایت دارند:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

مدیریت خطا

  • از FaultRules برای مدیریت تمام خطاهای مربوط به پردازش استفاده کنید. (سیاست‌های RaiseFault برای متوقف کردن جریان پیام و ارسال پردازش به FaultRules Flow استفاده می‌شوند.)
  • در جریان FaultRules، از سیاست‌های AssignMessage برای ساخت پاسخ خطا استفاده کنید، نه از سیاست‌های RaiseFault. سیاست‌های AssignMessage را بر اساس نوع خطایی که رخ می‌دهد، به صورت مشروط اجرا کنید.
  • همیشه شامل یک مدیریت‌کننده‌ی خطای پیش‌فرض «catch-all» است تا خطاهای ایجاد شده توسط سیستم بتوانند به قالب‌های پاسخ خطای تعریف شده توسط مشتری نگاشت شوند.
  • در صورت امکان، همیشه پاسخ‌های مربوط به خطاها را با فرمت‌های استاندارد موجود در شرکت یا پروژه خود مطابقت دهید.
  • از پیام‌های خطای معنادار و قابل خواندن توسط انسان استفاده کنید که راه‌حلی برای شرایط خطا ارائه می‌دهند.

به بخش مدیریت خطاها مراجعه کنید.

برای بهترین شیوه‌های صنعتی، به طراحی پاسخ خطای RESTful مراجعه کنید.

پشتکار

نقشه‌های کلید/مقدار

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

به سیاست عملیات نقشه ارزش کلیدی مراجعه کنید.

ذخیره سازی پاسخ

  • اگر پاسخ موفقیت‌آمیز نبود یا اگر درخواست از نوع GET نبود، حافظه پنهان پاسخ را پر نکنید. ایجاد، به‌روزرسانی و حذف نباید ذخیره شوند. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • حافظه پنهان را با یک نوع محتوای ثابت (مثلاً XML یا JSON) پر کنید. پس از بازیابی ورودی responseCache، آن را با JSONtoXML یا XMLToJSON به نوع محتوای مورد نیاز تبدیل کنید. این کار از ذخیره داده‌های مضاعف، سه‌گانه یا بیشتر جلوگیری می‌کند.
  • مطمئن شوید که کلید کش برای الزامات ذخیره‌سازی کافی است. در بسیاری از موارد، request.querystring می‌تواند به عنوان شناسه منحصر به فرد استفاده شود.
  • کلید API ( client_id ) را در کلید حافظه پنهان قرار ندهید، مگر اینکه صریحاً لازم باشد. اغلب، APIهایی که فقط توسط یک کلید ایمن شده‌اند، برای یک درخواست معین، داده‌های یکسانی را به همه کلاینت‌ها برمی‌گردانند. ذخیره کردن مقدار یکسان برای تعدادی از ورودی‌ها بر اساس کلید API ناکارآمد است.
  • برای جلوگیری از خواندن‌های کثیف، فواصل انقضای حافظه پنهان مناسبی تنظیم کنید.
  • هر زمان که ممکن است، سعی کنید سیاست حافظه پنهان پاسخ که حافظه پنهان را پر می‌کند، تا حد امکان در پاسخ ProxyEndpoint PostFlow اجرا شود. به عبارت دیگر، آن را پس از مراحل ترجمه و میانجیگری، از جمله میانجیگری مبتنی بر جاوا اسکریپت و تبدیل بین JSON و XML، اجرا کنید. با ذخیره داده‌های میانجی، از هزینه عملکرد اجرای مرحله میانجیگری هر بار که داده‌های ذخیره شده را بازیابی می‌کنید، جلوگیری می‌کنید.

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

  • سیاست کش پاسخ برای جستجوی ورودی کش باید در PreFlow درخواست ProxyEndpoint رخ دهد. از پیاده‌سازی منطق بیش از حد، به غیر از تولید کلید کش، قبل از بازگرداندن ورودی کش خودداری کنید. در غیر این صورت، مزایای کش به حداقل می‌رسد.
  • به طور کلی، شما همیشه باید جستجوی پاسخ در حافظه پنهان را تا حد امکان نزدیک به درخواست کلاینت نگه دارید. برعکس، شما باید جمعیت پاسخ در حافظه پنهان را تا حد امکان نزدیک به پاسخ کلاینت نگه دارید.
  • هنگام استفاده از چندین سیاست ذخیره‌سازی پاسخ مختلف در یک پروکسی، برای اطمینان از رفتار مجزا برای هر یک، این دستورالعمل‌ها را دنبال کنید:
    • هر سیاست را بر اساس شرایط متقابلاً ناسازگار اجرا کنید. این به تضمین این امر کمک می‌کند که فقط یکی از چندین سیاست ذخیره‌سازی پاسخ اجرا شود.
    • منابع کش متفاوتی را برای هر سیاست کش پاسخ تعریف کنید. منبع کش را در عنصر <CacheResource> سیاست مشخص می‌کنید.

به سیاست حافظه پنهان پاسخ مراجعه کنید.

سیاست و کد سفارشی

سیاست یا کد سفارشی؟

  • در درجه اول و مهم‌تر از همه (در صورت امکان) از سیاست‌های داخلی استفاده کنید. سیاست‌های Apigee مقاوم‌سازی، بهینه‌سازی و پشتیبانی می‌شوند. برای مثال، در صورت امکان، از سیاست‌های استاندارد AssignMessage و ExtractVariables به جای جاوا اسکریپت برای ایجاد پیلودها، استخراج اطلاعات از پیلودها (XPath، JSONPath) و غیره استفاده کنید.
  • جاوا اسکریپت نسبت به پایتون و جاوا ارجحیت دارد. با این حال، اگر عملکرد مورد نیاز اصلی باشد، جاوا باید به جاوا اسکریپت ترجیح داده شود.

جاوا اسکریپت

  • اگر جاوا اسکریپت نسبت به سیاست‌های Apigee شهودی‌تر است، از آن استفاده کنید (برای مثال، هنگام تنظیم target.url برای ترکیب‌های مختلف URI).
  • تجزیه‌ی پیچیده‌ی بار داده مانند پیمایش در یک شیء JSON و رمزگذاری/رمزگشایی Base64.
  • سیاست جاوا اسکریپت محدودیت زمانی دارد، بنابراین حلقه‌های بی‌نهایت مسدود می‌شوند.
  • همیشه از مراحل جاوا اسکریپت استفاده کنید و فایل‌ها را در پوشه منابع jsc قرار دهید. نوع سیاست جاوا اسکریپت، کد را در زمان استقرار از قبل کامپایل می‌کند.

به برنامه‌نویسی پروکسی‌های API با جاوا اسکریپت مراجعه کنید.

جاوا

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

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

پایتون

  • از پایتون استفاده نکنید، مگر اینکه کاملاً ضروری باشد. اسکریپت‌های پایتون می‌توانند برای اجراهای ساده، گلوگاه‌های عملکردی ایجاد کنند، زیرا در زمان اجرا تفسیر می‌شوند.

فراخوانی‌های اسکریپت (جاوا، جاوا اسکریپت، پایتون)

  • از یک try/catch سراسری یا معادل آن استفاده کنید.
  • استثنائات معنی‌دار را ارسال کنید و آنها را به درستی برای استفاده در پاسخ‌های خطا دریافت کنید.
  • خطاها را زودتر پرتاب کنید و بگیرید. از try/catch سراسری برای مدیریت همه خطاها استفاده نکنید.
  • در صورت لزوم، بررسی‌های null و undefined را انجام دهید. نمونه‌ای از زمان انجام این کار، هنگام بازیابی متغیرهای جریان اختیاری است.
  • از ایجاد درخواست‌های HTTP/S درون فراخوانی اسکریپت خودداری کنید. در عوض، از سیاست Apigee ServiceCallout استفاده کنید زیرا این سیاست اتصالات را به خوبی مدیریت می‌کند.

جاوا اسکریپت

  • جاوا اسکریپت در پلتفرم API از طریق E4X از XML پشتیبانی می‌کند.

به مدل شیء جاوا اسکریپت مراجعه کنید.

جاوا

  • هنگام دسترسی به payloadهای پیام، سعی کنید از context.getMessage() به جای context.getResponseMessage یا context.getRequestMessage استفاده کنید. این تضمین می‌کند که کد می‌تواند payload را در هر دو جریان درخواست و پاسخ بازیابی کند.
  • کتابخانه‌ها را به سازمان یا محیط Apigee Edge وارد کنید و آنها را در فایل JAR قرار ندهید. این کار اندازه بسته را کاهش می‌دهد و به سایر فایل‌های JAR اجازه می‌دهد به همان مخزن کتابخانه دسترسی داشته باشند.
  • فایل‌های JAR را با استفاده از API منابع Apigee وارد کنید، نه اینکه آنها را در پوشه منابع پروکسی API قرار دهید. این کار زمان استقرار را کاهش می‌دهد و به فایل‌های JAR مشابه اجازه می‌دهد تا توسط چندین پروکسی API ارجاع داده شوند. مزیت دیگر، جداسازی بارگذار کلاس است.
  • از جاوا برای مدیریت منابع (مثلاً ایجاد و مدیریت thread pools) استفاده نکنید.

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

پایتون

  • استثنائات معنی‌دار را پرتاب کنید و آنها را به درستی برای استفاده در پاسخ‌های خطای Apigee دریافت کنید.

به سیاست اسکریپت پایتون مراجعه کنید.

فراخوان‌های سرویس

  • موارد استفاده معتبر زیادی برای استفاده از زنجیره‌سازی پروکسی وجود دارد، که در آن از فراخوانی سرویس در یک پروکسی API برای فراخوانی پروکسی API دیگر استفاده می‌کنید. اگر از زنجیره‌سازی پروکسی استفاده می‌کنید، حتماً از فراخوانی‌های بازگشتی "حلقه بی‌نهایت" به همان پروکسی API خودداری کنید.

    اگر بین پروکسی‌هایی که در یک سازمان و محیط هستند ارتباط برقرار می‌کنید، حتماً برای اطلاعات بیشتر در مورد پیاده‌سازی یک اتصال محلی که از سربار شبکه غیرضروری جلوگیری می‌کند، به بخش Chaining API proxies together مراجعه کنید.

  • با استفاده از سیاست AssignMessage، یک پیام درخواست ServiceCallout بسازید و شیء درخواست را در یک متغیر پیام قرار دهید. (این شامل تنظیم بار درخواست، مسیر و متد آن می‌شود.)
  • URL که در داخل این سیاست پیکربندی می‌شود، نیاز به مشخصات پروتکل دارد، به این معنی که بخش پروتکل URL، برای مثال https:// ، نمی‌تواند توسط یک متغیر مشخص شود. همچنین، شما باید از متغیرهای جداگانه برای بخش دامنه URL و برای بقیه URL استفاده کنید. به عنوان مثال: https://{domain}/{path}
  • شیء پاسخ برای ServiceCallout را در یک متغیر پیام جداگانه ذخیره کنید. سپس می‌توانید متغیر پیام را تجزیه کرده و محتوای پیام اصلی را برای استفاده توسط سایر سیاست‌ها دست نخورده نگه دارید.

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

دسترسی به موجودیت‌ها

سیاست AccessEntity

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

به سیاست نهاد دسترسی مراجعه کنید.

ثبت وقایع

  • از یک سیاست syslog مشترک در بین بسته‌ها و درون همان بسته استفاده کنید. این کار باعث می‌شود فرمت گزارش‌گیری ثابتی حفظ شود.

به سیاست ثبت پیام‌ها مراجعه کنید.

نظارت

مشتریان ابری ملزم به بررسی تک تک اجزای Apigee Edge (روترها، پردازنده‌های پیام و غیره) نیستند. تیم عملیات جهانی Apigee با توجه به درخواست‌های بررسی سلامت مشتری، تمام اجزا را به همراه بررسی‌های سلامت API به طور کامل رصد می‌کند.

تحلیل‌های آپیجی

ابزارهای تحلیلی می‌توانند با اندازه‌گیری درصد خطا، نظارت غیر بحرانی بر API را فراهم کنند.

به داشبوردهای آنالیتیکس مراجعه کنید.

ردیابی

ابزار ردیابی در رابط کاربری مدیریت API Edge برای اشکال‌زدایی مشکلات API در زمان اجرا، در طول توسعه یا عملیات تولید یک API مفید است.

به استفاده از ابزار ردیابی مراجعه کنید.

امنیت