توسعه افزایه‌های سفارشی

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

Edge Microgateway v. 3.0.x

مخاطبان

این موضوع برای توسعه‌دهندگانی درنظر گرفته شده است که می‌خواهند ویژگی‌های Edge Microgateway را با نوشتن افزایه‌های سفارشی گسترش دهند. اگر می‌خواهید افزایه جدیدی بنویسید، تجربه کار با جاوا اسکریپت و Node.js الزامی است.

افزایه سفارشی Edge Microgateway چیست؟

افزایه یک واحد Node.js است که عملکرد را به Edge Microgateway اضافه می‌کند. واحدهای افزایه از الگوی یکسانی پیروی می‌کنند و در مکانی که Edge Microgateway می‌شناسد ذخیره می‌شوند، که باعث می‌شود این واحدها به‌طور خودکار شناسایی و اجرا شوند. وقتی Edge Microgateway را نصب می‌کنید، چندین افزایه ازپیش تعریف‌شده ارائه می‌شود. این موارد شامل افزایه‌های اصالت‌سنجی، جلوگیری از افزایش ناگهانی، سهمیه، و تجزیه‌وتحلیل است. این افزونه‌های موجود در استفاده از افزونه‌ها توضیح داده شده است.

با نوشتن افزایه‌های سفارشی می‌توانید ویژگی‌ها و قابلیت‌های جدیدی به ریزدروازه اضافه کنید. به‌طور پیش‌فرض، Edge Microgateway اساساً یک پراکسی عبوری امن است که درخواست‌ها و پاسخ‌ها را بدون تغییر به و از سرویس‌های هدف منتقل می‌کند. با افزونه‌های سفارشی، می‌توانید به‌صورت برنامه‌ریزی‌شده با درخواست‌ها و پاسخ‌هایی که ازطریق ریزدرگاه جریان می‌یابند تعامل داشته باشید.

کد افزایه سفارشی را کجا قرار دهیم

پوشه‌ای برای افزایه‌های سفارشی به‌عنوان بخشی از نصب Edge Microgateway در اینجا گنجانده شده است:

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins

که در آن [prefix] پیشوند دایرکتوری npm است که در «Edge Microgateway کجا نصب می‌شود» در نصب Edge Microgateway توضیح داده شده است.

می‌توانید این فهرستگان افزایه پیش‌فرض را تغییر دهید. ببینید افزایه‌ها را کجا پیدا کنید.

درحال بررسی افزایه‌های ازپیش تعریف‌شده

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

[prefix]/lib/node_modules/edgemicro/node_modules/microgateway-plugins

که در آن [prefix] پیشوند دایرکتوری npm است. همچنین «Edge Microgateway در کجا نصب شده است» را در نصب Edge Microgateway ببینید.

برای جزئیات، افزایه‌های ازپیش‌تعریف‌شده ارائه‌شده با Edge Microgateway را نیز ببینید.

نوشتن افزایه ساده

در این بخش، مراحل لازم برای ایجاد یک افزایه ساده را مرور خواهیم کرد. این افزایه داده‌های پاسخ (هرچه که باشد) را با رشته «Hello, World!» ملغی می‌کند و آن را در پایانه چاپ می‌کند.

  1. اگر Edge Microgateway درحال اجرا است، آن را متوقف کنید:
    edgemicro stop
  2. ‫cd به دایرکتوری افزایه سفارشی:

    cd [prefix]/lib/node_modules/edgemicro/plugins

    که در آن [prefix] پیشوند npm دایرکتوری است همان‌طور که در «Edge Microgateway کجا نصب شده است» در نصب Edge Microgateway توضیح داده شده است.

  3. پروژه افزایه جدیدی به‌نام response-override ایجاد کنید و cd به آن اضافه کنید:
    mkdir response-override && cd response-override
  4. ایجاد پروژه جدید Node.js:
    npm init
    برای پذیرفتن پیش‌فرض‌ها، چند بار کلید «بازگشت» را فشار دهید.
  5. از ویرایشگر نوشتار برای ایجاد فایل جدیدی به‌نام index.js استفاده کنید.
  6. کد زیر را در index.js کپی کنید و فایل را ذخیره کنید.
    'use strict';
var debug = require('debug')

module.exports.init = function(config, logger, stats) {

  return {
   
    ondata_response: function(req, res, data, next) {
      debug('***** plugin ondata_response');
      next(null, null);
    },
    
    onend_response: function(req, res, data, next) {
      debug('***** plugin onend_response');
      next(null, "Hello, World!\n\n");
    }
  };
}
  7. اکنون افزایه‌ای ایجاد کرده‌اید و باید آن را به پیکربندی Edge Microgateway اضافه کنید. فایل $HOME/.edgemicro/[org]-[env]-config.yaml را باز کنید، که در آن org و env نام‌های سازمان و محیط Edge شما هستند.
  8. افزایه response-override را به عنصر plugins:sequence همان‌طور که در زیر نشان داده شده است اضافه کنید.
          ...
      
      plugins:
        dir: ../plugins
        sequence:
          - oauth
          - response-override
          
      ...
  9. ‫Edge Microgateway را بازراه‌اندازی کنید.
  10. میانای برنامه‌سازی کاربردی را ازطریق Edge Microgateway فراخوانی کنید. (این فراخوانی API فرض می‌کند که پیکربندی یکسانی را مانند آموزش گام‌به‌گام با امنیت کلید API راه‌اندازی کرده‌اید، همان‌طور که در راه‌اندازی و پیکربندی Edge Microgateway توضیح داده شده است:
    curl -H 'x-api-key: uAM4gBSb6YoMvTHfx5lXJizYIpr5Jd' http://localhost:8000/hello/echo
Hello, World!

ساختار افزایه

افزایه نمونه Edge Microgateway زیر الگویی را که باید هنگام توسعه افزایه‌های خودتان دنبال کنید نشان می‌دهد. کد منبع افزایه نمونه که در این بخش درباره آن بحث شده است در plugins/header-uppercase/index.js. قرار دارد

  • افزایه‌ها واحدهای استاندارد NPM با package.json و index.js در پوشه ریشه هستند.
  • افزایه باید تابع init()‎ را صادر کند.
  • تابع init()‎ سه آرگومان می‌گیرد: config، logger، و stats. این متغیرهای مستقل در متغیرهای مستقل تابع Plugin init() توضیح داده شده‌اند.
  • init() شیئی را با گردانندگان تابع نام‌گذاری‌شده برمی‌گرداند که وقتی رویدادهای خاصی درطول عمر درخواست رخ می‌دهد فراخوانی می‌شوند.

توابع مدیریت رویداد

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

درخواست مدیران رویداد جریان

این توابع در رویدادهای درخواست در Edge Microgateway فراخوانی می‌شوند.

  • onrequest
  • ondata_request
  • onend_request
  • onclose_request
  • onerror_request

onrequest تابع

در ابتدای درخواست مشتری فراخوانده می‌شود. این تابع زمانی اجرا می‌شود که اولین بایت درخواست توسط Edge Microgateway دریافت شود. این تابع به شما امکان می‌دهد به سرایندهای درخواست، نشانی وب، پارامترهای پُرسمان، و روش HTTP دسترسی داشته باشید. اگر با آرگومان اول درست (مثل نمونه‌ای از Error) با next تماس بگیرید، پردازش درخواست متوقف می‌شود و درخواست هدف شروع نمی‌شود.

مثال:

onrequest: function(req, res, next) {
      debug('plugin onrequest');
      req.headers['x-foo-request-start'] = Date.now();
      next();
    }

ondata_request تابع

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

مثال:

ondata_request: function(req, res, data, next) {
      debug('plugin ondata_request ' + data.length);
      var transformed = data.toString().toUpperCase();
      next(null, transformed);
    }

onend_request تابع

وقتی همه داده‌های درخواست از مشتری دریافت شده است، فراخوانی می‌شود.

مثال:

onend_request: function(req, res, data, next) {
      debug('plugin onend_request');
      next(null, data);
    }

تابع onclose_request

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

مثال:

onclose_request: function(req, res, next) {
      debug('plugin onclose_request');
      next();
    }

تابع onerror_request

اگر هنگام دریافت درخواست کارخواه خطایی رخ دهد، فراخوانده می‌شود.

مثال:

onerror_request: function(req, res, err, next) {
      debug('plugin onerror_request ' + err);
      next();
    }

مدیران رویداد جریان پاسخ

این توابع در رویدادهای پاسخ در Edge Microgateway فراخوانی می‌شوند.

  • onresponse
  • ondata_response
  • onend_response
  • onclose_response
  • onerror_response

تابع onresponse

در ابتدای پاسخ هدف فراخوانده شد. این تابع زمانی اجرا می‌شود که اولین بایت پاسخ توسط Edge Microgateway دریافت شود. این تابع به شما امکان می‌دهد به سرایندهای پاسخ و کد وضعیت دسترسی داشته باشید.

مثال:

onresponse: function(req, res, next) {      
    debug('plugin onresponse');     
    res.setHeader('x-foo-response-time', Date.now() - req.headers['x-foo-request-start'])    
    next();    
}


تابع ondata_response

وقتی تکه‌ای از داده از هدف دریافت می‌شود، فراخوانی می‌شود.

مثال:

ondata_response: function(req, res, data, next) {
      debug('plugin ondata_response ' + data.length);
      var transformed = data.toString().toUpperCase();
      next(null, transformed);
    }


تابع onend_response

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

مثال:

onend_response: function(req, res, data, next) {
      debug('plugin onend_response');
      next(null, data);
    }

تابع onclose_response

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

مثال:

onclose_response: function(req, res, next) {
      debug('plugin onclose_response');
      next();
    }


تابع onerror_response

اگر هنگام دریافت پاسخ هدف خطایی رخ دهد، فراخوانی می‌شود.

مثال:

onerror_response: function(req, res, err, next) {
      debug('plugin onerror_response ' + err);
      next();
    }

آنچه باید درباره توابع مدیریت‌کننده رویداد افزایه بدانید

توابع مدیریت‌کننده رویداد افزایه در پاسخ به رویدادهای خاصی که درحین پردازش درخواست API توسط Edge Microgateway رخ می‌دهد فراخوانده می‌شوند.

  • هریک از مدیریت‌کننده‌های تابع init()‎ (ondata_request، ondata_response، و غیره) باید پس‌از اتمام پردازش، با next()‎ تماس بگیرند. اگر next() را فراخوانی نکنید، پردازش متوقف می‌شود و درخواست معلقه می‌شود.
  • اولین آرگومان next() می‌تواند خطا باشد که باعث می‌شود پردازش درخواست متوقف شود.
  • دستورات مدیریت ondata_ و onend_ باید next() را با آرگومان دومی که حاوی داده‌های ارسالی به هدف یا مشتری است فراخوانی کنند. اگر افزایه درحال ذخیره کردن موقت باشد و درحال‌حاضر داده کافی برای تبدیل نداشته باشد، این آرگومان می‌تواند تهی باشد.
  • توجه داشته باشید که از یک نمونه واحد افزایه برای ارائه خدمات به همه درخواست‌ها و پاسخ‌ها استفاده می‌شود. اگر یک افزایه بخواهد وضعیت هر درخواست را بین تماس‌ها حفظ کند، می‌تواند آن وضعیت را در یک دارایی که به شیء درخواست ارائه‌شده (req) اضافه شده است ذخیره کند، که طول عمر آن مدت زمان تماس با API است.
  • مراقب باشید که همه خطاها را دریافت کنید و next() را با خطا فراخوانی کنید. عدم فراخوانی next() باعث می‌شود فراخوانی API معلقه شود.
  • مراقب باشید که نشت حافظه ایجاد نکنید زیرا این امر می‌تواند بر عملکرد کلی Edge Microgateway تأثیر بگذارد و درصورت تمام شدن حافظه باعث ازکارافتادن آن شود.
  • مراقب باشید که از مدل Node.js پیروی کنید و وظایف محاسباتی سنگین را در رشته اصلی انجام ندهید، زیرا این کار می‌تواند بر عملکرد Edge Microgateway تأثیر منفی بگذارد.

درباره تابع init() افزایه

این بخش متغیرهای مستقلی را که به تابع init() ارسال می‌شوند شرح می‌دهد: config، logger، و stats.

پیکربندی

شیء پیکربندی که پس‌از ادغام فایل پیکربندی Edge Microgateway با اطلاعات بارگیری‌شده از Apigee Edge، مثل محصولات و سهمیه‌ها، به‌دست می‌آید. می‌توانید پیکربندی ویژه افزایه را در این شیء پیدا کنید: config.<plugin-name>.

برای افزودن پارامتر پیکربندی به‌نام param با مقدار foo به افزایه‌ای به‌نام response-override، این را در فایل default.yaml قرار دهید:

response-override:
    param: foo

سپس، می‌توانید به پارامتر در کد افزایه خود دسترسی داشته باشید، مانند این:

// Called when response data is received
    ondata_response: function(req, res, data, next) {
      debug('***** plugin ondata_response');
      debug('***** plugin ondata_response: config.param: ' + config.param);
      next(null, data);
    },

در این مورد، foo را در برونداد اشکال‌زدایی افزایه خواهید دید:

Sun, 13 Dec 2015 21:25:08 GMT plugin:response-override ***** plugin ondata_response: config.param: foo

ثبت‌کننده

گزارشگر سیستم. گزارشگر فعلی این توابع را صادر می‌کند، که در آن شیء می‌تواند رشته، درخواست HTTP، پاسخ HTTP، یا نمونه «خطا» باشد.

  • info(object, message)
  • warn(object, message)
  • error(object, message)

آمار

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

  • treqErrors - تعداد درخواست‌های هدف با خطا.
  • treqErrors - تعداد پاسخ‌های هدف با خطا.
  • statusCodes - شیئی که حاوی تعداد کدهای پاسخ است:
{
  1: number of target responses with 1xx response codes
  2: number of target responses with 2xx response codes
  3: number of target responses with 3xx response codes
  4: number of target responses with 4xx response codes
  5: number of target responses with 5xx response codes
  }
  • درخواست‌ها - تعداد کل درخواست‌ها.
  • پاسخ‌ها - تعداد کل پاسخ‌ها.
  • اتصالات - تعداد اتصالات هدف فعال.

درباره تابع next()‎

همه روش‌های افزایه باید next() را فراخوانی کنند تا پردازش روش بعدی در مجموعه ادامه یابد (درغیراین‌صورت، فرایند افزایه معلقه خواهد شد). در چرخه حیات درخواست، اولین روش فراخوانده‌شده onrequest() است. روش بعدی که فراخوانده می‌شود روش ondata_request() است؛ بااین‌حال، ondata_request فقط درصورتی فراخوانده می‌شود که درخواست شامل داده باشد، مانند درخواست POST. روش بعدی که فراخوانده می‌شود onend_request() است که وقتی پردازش درخواست تکمیل می‌شود فراخوانده می‌شود. تابع‌های onerror_* فقط درصورت بروز خطا فراخوانده می‌شوند و به شما امکان می‌دهند درصورت تمایل خطاها را با کد سفارشی مدیریت کنید.

فرض کنیم داده‌ها در درخواست ارسال شده است و ondata_request() فراخوانی می‌شود. توجه داشته باشید که تابع next() را با دو پارامتر فراخوانی می‌کند:

next(null, data);

طبق قرارداد، از پارامتر اول برای انتقال اطلاعات خطا استفاده می‌شود، که سپس می‌توانید آن را در تابع بعدی در زنجیره مدیریت کنید. با تنظیم آن روی null، یک آرگومان نادرست، می‌گوییم که هیچ خطایی وجود ندارد و پردازش درخواست باید به‌طور معمول ادامه یابد. اگر این آرگومان درست باشد (مثل شیء «خطا»)، پردازش درخواست متوقف می‌شود و درخواست به هدف ارسال می‌شود.

پارامتر دوم داده‌های درخواست را به تابع بعدی در زنجیره منتقل می‌کند. اگر پردازش اضافی انجام ندهید، داده‌های درخواست بدون تغییر به هدف میانای برنامه‌سازی کاربردی ارسال می‌شود. بااین‌حال، در این روش فرصت دارید داده‌های درخواست را اصلاح کنید و درخواست اصلاح‌شده را به هدف ارسال کنید. برای مثال، اگر داده‌های درخواست XML باشد و هدف انتظار JSON داشته باشد، می‌توانید به روش ondata_request() کدی اضافه کنید که (الف) «نوع محتوا» سرایند درخواست را به application/json تغییر دهد و داده‌های درخواست را با هر روشی که می‌خواهید به JSON تبدیل کند (برای مثال، می‌توانید از تبدیل‌کننده xml2json در Node.js که از NPM دریافت شده است استفاده کنید).

بیایید ببینیم چگونه ممکن است به‌نظر برسد:

ondata_request: function(req, res, data, next) {
  debug('****** plugin ondata_request');
  var translated_data = parser.toJson(data);
  next(null, translated_data);
},

در این مورد، داده‌های درخواست (که فرض می‌شود XML باشد) به JSON تبدیل می‌شود و داده‌های تبدیل‌شده ازطریق next() به تابع بعدی در زنجیره درخواست منتقل می‌شود، قبل‌از اینکه به هدف زیرینه منتقل شود.

توجه داشته باشید که می‌توانید عبارت اشکال‌زدایی دیگری اضافه کنید تا داده‌های تبدیل‌شده را برای اهداف اشکال‌زدایی چاپ کنید. برای مثال:

ondata_request: function(req, res, data, next) {
  debug('****** plugin ondata_request');
  var translated_data = parser.toJson(data);
  debug('****** plugin ondata_response: translated_json: ' + translated_json);
  next(null, translated_data);
},

درباره ترتیب اجرای مدیریت افزایه

اگر افزایه‌هایی برای Edge Microgateway می‌نویسید، باید ترتیب اجرای کنترل‌کننده‌های رویداد افزایه را بدانید.

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

مثال زیر برای کمک به شما در درک این توالی اجرا طراحی شده است.

۱. سه افزایه ساده بسازید

افزایه زیر را درنظر بگیرید. تنها کاری که انجام می‌دهد این است که وقتی مدیریت‌کننده‌های رویداد آن فراخوانده می‌شوند، برونداد کنسول را چاپ می‌کند:

plugins/plugin-1/index.js

module.exports.init = function(config, logger, stats) {

  return {

    onrequest: function(req, res, next) {
      console.log('plugin-1: onrequest');
      next();
    },

    onend_request: function(req, res, data, next) {
      console.log('plugin-1: onend_request');
      next(null, data);
    },

    ondata_response: function(req, res, data, next) {
      console.log('plugin-1: ondata_response ' + data.length);
      next(null, data);
    },

    onend_response: function(req, res, data, next) {
      console.log('plugin-1: onend_response');
      next(null, data);
    }
  };
}

اکنون، افزایه‌های دیگری، plugin-2 و plugin-3، با همان کد (به‌جز اینکه دستورات console.log() را به plugin-2 و plugin-3 تغییر دهید) بسازید.

۲. کد افزایه را مرور کنید

توابع افزایه صادرشده در <microgateway-root-dir>/plugins/plugin-1/index.js کنترل‌کننده‌های رویدادی هستند که در زمان‌های خاصی درطول پردازش درخواست و پاسخ اجرا می‌شوند. برای مثال، onrequest اولین بایت از سرایندهای درخواست اجرا می‌شود. درحالی‌که، onend_response پس‌از دریافت آخرین بایت داده‌های پاسخ اجرا می‌شود.

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

۳. افزودن افزایه‌ها به توالی افزایه

با ادامه این مثال، افزایه‌ها را به ترتیب افزایه‌ها در فایل پیکربندی Edge Microgateway (~./edgemicro/config.yaml) به شرح زیر اضافه می‌کنیم. توالی مهم است. ترتیب اجرای کنترل‌کننده‌های افزایه را تعریف می‌کند.

  plugins:
    dir: ../plugins
    sequence:
      - plugin-1
      - plugin-2
      - plugin-3

۴. برونداد اشکال‌زدایی را بررسی کنید

اکنون، بیایید به بروندادی که هنگام فراخوانی این افزونه‌ها تولید می‌شود نگاهی بیندازیم. چند نکته مهم وجود دارد که باید به آن‌ها توجه کنید:

  • ترتیب افزایه فایل پیکربندی Edge Microgateway (~./edgemicro/config.yaml) ترتیب فراخوانی کنترل‌کننده‌های رویداد را مشخص می‌کند.
  • مدیران درخواست به ترتیب صعودی فراخوانده می‌شوند (ترتیبی که در توالی افزایه ظاهر می‌شوند -- ۱، ۲، ۳).
  • مدیران پاسخ در ترتیب نزولی فراخوانده می‌شوند -- ۳، ۲، ۱.
  • کارپرداز ondata_response یک‌بار برای هر بخش از داده‌هایی که می‌رسند فراخوانی می‌شود. در این مثال (برونداد در زیر نشان داده شده است)، دو تکه دریافت می‌شود.

در اینجا نمونه برونداد اشکال‌زدایی تولیدشده زمانی که این سه افزایه درحال استفاده هستند و درخواستی ازطریق Edge Microgateway ارسال می‌شود آورده شده است. فقط به ترتیب فراخوانی کنترل‌کننده‌ها توجه کنید:

  plugin-1: onrequest
  plugin-2: onrequest
  plugin-3: onrequest

  plugin-1: onend_request
  plugin-2: onend_request
  plugin-3: onend_request

  plugin-3: ondata_response 931
  plugin-2: ondata_response 931
  plugin-1: ondata_response 931

  plugin-3: ondata_response 1808
  plugin-3: onend_response

  plugin-2: ondata_response 1808
  plugin-2: onend_response

  plugin-1: ondata_response 1808
  plugin-1: onend_response

خلاصه

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

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

درباره استفاده از متغیرهای سراسری در افزونه‌ها

هر درخواست به Edge Microgateway به نمونه یکسانی از افزایه ارسال می‌شود؛ بنابراین، وضعیت درخواست دوم از مشتری دیگر، درخواست اول را ملغی می‌کند. تنها مکان امن برای ذخیره وضعیت افزایه، ذخیره کردن وضعیت در دارایی درخواستی یا پاسخ شیء است (که طول عمر آن به طول عمر درخواست محدود می‌شود).

بازنویسی نشانی‌های وب هدف در افزونه‌ها

اضافه‌شده در: v2.3.3

می‌توانید نشانی وب مقصد پیش‌فرض را در افزایه به‌صورت پویا با تغییر دادن این متغیرها در کد افزایه خود ملغی کنید: req.targetHostname و req.targetPath.

اضافه‌شده در: نسخه ۲.۴.x

همچنین می‌توانید درگاه نقطه پایانی مقصد را ملغی کنید و بین HTTP و HTTPS انتخاب کنید. این متغیرها را در کد افزایه خود اصلاح کنید: req.targetPort و req.targetSecure. برای انتخاب HTTPS، مقدار req.targetSecure را روی true تنظیم کنید؛ برای HTTP، آن را روی false تنظیم کنید. اگر req.targetSecure را روی true تنظیم کنید، برای اطلاعات بیشتر، این رشته گفتگو را ببینید.

افزونه نمونه‌ای به‌نام eurekaclient به Edge Microgateway اضافه شده است. این افزایه نشان می‌دهد چگونه از متغیرهای req.targetPort و req.targetSecure استفاده کنید و نشان می‌دهد که چگونه Edge Microgateway می‌تواند بااستفاده از Eureka به‌عنوان کاتالوگ نقطه پایانی سرویس، جستجوی نقطه پایانی پویا انجام دهد.

‫
افزایه‌های نمونه

این افزایه‌ها با نصب Edge Microgateway ارائه می‌شوند. می‌توانید آن‌ها را در نصب Edge Microgateway در اینجا پیدا کنید:

[prefix]/lib/node_modules/edgemicro/plugins

که در آن [prefix] پیشوند دایرکتوری npm است که در «Edge Microgateway کجا نصب می‌شود» در نصب Edge Microgateway توضیح داده شده است.

انباشت-درخواست

این افزایه تکه‌های داده را از مشتری در دارایی آرایه‌ای که به شیء درخواست پیوست شده است جمع‌آوری می‌کند. وقتی همه داده‌های درخواست دریافت شد، آرایه در یک «میان‌گیر» به‌هم می‌پیوندد و سپس به افزایه بعدی در توالی ارسال می‌شود. این افزایه باید اولین افزایه در توالی باشد تا افزایه‌های بعدی داده‌های درخواست انباشته‌شده را دریافت کنند.

module.exports.init = function(config, logger, stats) {

  function accumulate(req, data) {

    if (!req._chunks) req._chunks = [];
    req._chunks.push(data);

  }

  return {

    ondata_request: function(req, res, data, next) {

      if (data && data.length > 0) accumulate(req, data);

      next(null, null);

    },


    onend_request: function(req, res, data, next) {

      if (data && data.length > 0) accumulate(req, data);

      var content = null;

      if (req._chunks && req._chunks.length) {

        content = Buffer.concat(req._chunks);

      }

      delete req._chunks;

      next(null, content);

    }

  };

}

انباشت پاسخ

این افزایه تکه‌های داده را از هدف در دارایی آرایه‌ای که به شیء پاسخ پیوست شده است جمع‌آوری می‌کند. وقتی همه داده‌های پاسخ دریافت شد، آرایه به یک «میان‌گیر» پیوند داده می‌شود که سپس به افزایه بعدی در توالی ارسال می‌شود. ازآنجایی‌که این افزایه روی پاسخ‌ها عمل می‌کند، که به‌ترتیب معکوس پردازش می‌شوند، باید آن را به‌عنوان آخرین افزایه در توالی قرار دهید.

module.exports.init = function(config, logger, stats) {

  function accumulate(res, data) {
    if (!res._chunks) res._chunks = [];
    res._chunks.push(data);
  }

  return {

    ondata_response: function(req, res, data, next) {
      if (data && data.length > 0) accumulate(res, data);
      next(null, null);
    },

    onend_response: function(req, res, data, next) {
      if (data && data.length > 0) accumulate(res, data);
      var content = Buffer.concat(res._chunks);
      delete res._chunks;
      next(null, content);
    }

  };

}

افزایه header-uppercase

توزیع‌های Edge Microgateway شامل افزایه‌ای نمونه به‌نام <microgateway-root-dir>/plugins/header-uppercase است. نمونه شامل نظراتی است که هریک از مدیریت‌کننده‌های تابع را توصیف می‌کند. این نمونه مقداری تبدیل داده ساده روی پاسخ هدف انجام می‌دهد و سرایندهای سفارشی به درخواست مشتری و پاسخ هدف اضافه می‌کند.

کد منبع <microgateway-root-dir>/plugins/header-uppercase/index.js در اینجا است:

'use strict';

var debug = require('debug')('plugin:header-uppercase');

// required
module.exports.init = function(config, logger, stats) {

  var counter = 0;

  return {

    // indicates start of client request
    // request headers, url, query params, method should be available at this time
    // request processing stops (and a target request is not initiated) if
    // next is called with a truthy first argument (an instance of Error, for example)
    onrequest: function(req, res, next) {
      debug('plugin onrequest');
      req.headers['x-foo-request-id'] = counter++;
      req.headers['x-foo-request-start'] = Date.now();
      next();
    },

    // indicates start of target response
    // response headers and status code should be available at this time
    onresponse: function(req, res, next) {
      debug('plugin onresponse');
      res.setHeader('x-foo-response-id', req.headers['x-foo-request-id']);
      res.setHeader('x-foo-response-time', Date.now() - req.headers['x-foo-request-start']);
      next();
    },

    // chunk of request body data received from client
    // should return (potentially) transformed data for next plugin in chain
    // the returned value from the last plugin in the chain is written to the target
    ondata_request: function(req, res, data, next) {
      debug('plugin ondata_request ' + data.length);
      var transformed = data.toString().toUpperCase();
      next(null, transformed);
    },

    // chunk of response body data received from target
    // should return (potentially) transformed data for next plugin in chain
    // the returned value from the last plugin in the chain is written to the client
    ondata_response: function(req, res, data, next) {
      debug('plugin ondata_response ' + data.length);
      var transformed = data.toString().toUpperCase();
      next(null, transformed);
    },

    // indicates end of client request
    onend_request: function(req, res, data, next) {
      debug('plugin onend_request');
      next(null, data);
    },

    // indicates end of target response
    onend_response: function(req, res, data, next) {
      debug('plugin onend_response');
      next(null, data);
    },

    // error receiving client request
    onerror_request: function(req, res, err, next) {
      debug('plugin onerror_request ' + err);
      next();
    },

    // error receiving target response
    onerror_response: function(req, res, err, next) {
      debug('plugin onerror_response ' + err);
      next();
    },

    // indicates client connection closed
    onclose_request: function(req, res, next) {
      debug('plugin onclose_request');
      next();
    },

    // indicates target connection closed
    onclose_response: function(req, res, next) {
      debug('plugin onclose_response');
      next();
    }

  };

}

تبدیل به حروف بزرگ

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

 */
module.exports.init = function(config, logger, stats) {

  // perform content transformation here
  // the result of the transformation must be another Buffer
  function transform(data) {
    return new Buffer(data.toString().toUpperCase());
  }

  return {

    ondata_response: function(req, res, data, next) {
      // transform each chunk as it is received
      next(null, data ? transform(data) : null);
    },

    onend_response: function(req, res, data, next) {
      // transform accumulated data, if any
      next(null, data ? transform(data) : null);
    },

    ondata_request: function(req, res, data, next) {
      // transform each chunk as it is received
      next(null, data ? transform(data) : null);
    },

    onend_request: function(req, res, data, next) {
      // transform accumulated data, if any
      next(null, data ? transform(data) : null);
    }

  };

}