🏂🏿 🧦 ✍🏻 هابي للصغار ✳️ 👔 🆗

Hapi.js هو إطار لبناء تطبيقات الويب. هذا المنشور يحتوي على جميع الأساسيات لبداية ساخنة. للأسف ، المؤلف ليس كاتباً على الإطلاق ، لذلك سيكون هناك الكثير من الشفرات والكلمات القليلة.

MVP

ضع مجموعة من التبعيات:

npm i @hapi/hapi @hapi/boom filepaths hapi-boom-decorators

hapi / hapi - في الواقع ، خادمنا
hapi / boom - وحدة لتوليد الإجابات القياسية
hapi-boom-decorators - مساعد لـ hapi / boom
filepaths - أداة مساعدة تقرأ المجلدات بشكل متكرر

إنشاء بنية مجلد ومجموعة من بدء الملفات:

في ./src/routes/ نضيف وصفًا لنقاط النهاية api ، ملف واحد - نقطة نهاية واحدة:

 // ./src/routes/home.js async function response() { // content-type            return { result: 'ok', message: 'Hello World!' }; } module.exports = { method: 'GET', //  path: '/', //  options: { handler: response // ,  ,  hapi > 17    } };

./src/server.js - الوحدة النمطية التي تصدر الخادم نفسه.

 // ./src/server.js 'use strict'; const Hapi = require('@hapi/hapi'); const filepaths = require('filepaths'); const hapiBoomDecorators = require('hapi-boom-decorators'); const config = require('../config'); async function createServer() { //   const server = await new Hapi.Server(config.server); //   await server.register([ hapiBoomDecorators ]); //      ./src/routes/ let routes = filepaths.getSync(__dirname + '/routes/'); for(let route of routes) server.route( require(route) ); //   try { await server.start(); console.log(`Server running at: ${server.info.uri}`); } catch(err) { //    ,   console.log(JSON.stringify(err)); } //      return server; } module.exports = createServer;

في ./server.js كل ما نقوم به هو استدعاء createServer ()

 #!/usr/bin/env node const createServer = require('./src/server'); createServer();

نطلق

 node server.js

وتحقق:

 curl http://127.0.0.1:3030/ {"result":"ok","message":"Hello World!"} curl http://127.0.0.1:3030/test {"statusCode":404,"error":"Not Found","message":"Not Found"}

في البرية

في مشروع حقيقي ، على الأقل ، نحتاج إلى قاعدة بيانات ومسجل وترخيص ومعالجة الأخطاء والمزيد.

إضافة تسلسل

ORM sequelize متصل كوحدة نمطية:

 ... const Sequelize = require('sequelize'); ... await server.register([ ... { plugin: require('hapi-sequelizejs'), options: [ { name: config.db.database, // identifier models: [__dirname + '/models/*.js'], //    //ignoredModels: [__dirname + '/server/models/**/*.js'], //  -     sequelize: new Sequelize(config.db), //  sync: true, // default false forceSync: false, // force sync (drops tables) - default false }, ] } ... ]);

تصبح قاعدة البيانات متاحة داخل المسار من خلال مكالمة:

 async function response(request) { const model = request.getModel('_', '_'); }

حقن وحدات إضافية في الطلب

من الضروري اعتراض حدث "onRequest" ، والذي بداخله سنحقن التكوين والمسجل في كائن الطلب:

 ... const Logger = require('./libs/Logger'); ... async function createServer(logLVL=config.logLVL) { ... const logger = new Logger(logLVL, 'my-hapi-app'); ... server.ext({ type: 'onRequest', method: async function (request, h) { request.server.config = Object.assign({}, config); request.server.logger = logger; return h.continue; } }); ... }

بعد ذلك ، داخل معالج الطلب ، سنتمكن من الوصول إلى التكوين والمسجل وقاعدة البيانات ، دون الحاجة إلى إضافة شيء ما في نص الوحدة النمطية:

 // ./src/routes/home.js async function response(request) { //  request.server.logger.error('request error', 'something went wrong'); //  console.log(request.server.config); //   const messages = request.getModel(request.server.config.db.database, '_'); return { result: 'ok', message: 'Hello World!' }; } module.exports = { method: 'GET', //  path: '/', //  options: { handler: response // ,  ,  hapi > 17    } };

وبالتالي ، سيتلقى معالج الطلب عند الإدخال كل ما هو ضروري للمعالجة ، ولن يكون من الضروري تضمين الوحدات النمطية نفسها في كل مرة من وقت لآخر.

ترخيص

يتم اعتماد في hapi في شكل وحدات.

 ... const AuthBearer = require('hapi-auth-bearer-token'); ... async function createServer(logLVL=config.logLVL) { ... await server.register([ AuthBearer, ... ]); server.auth.strategy('token', 'bearer-access-token', {// 'token' -   ,  allowQueryToken: false, unauthorized: function() { //  ,  validate  isValid=false throw Boom.unauthorized(); }, validate: function(request, token) { if( token == 'asd' ) { return { //    isValid: true, credentials: {} }; } else { return { //   isValid: false, credentials: {} }; } } }); server.auth.default('token'); //    ... }

وأيضًا داخل المسار ، يلزمك تحديد نوع التفويض المطلوب استخدامه:

 module.exports = { method: 'GET', path: '/', auth: 'token', //  false,     options: { handler: response } };

إذا تم استخدام عدة أنواع من التراخيص:

 auth: { strategies: ['token1', 'token2', 'something_else'] },

خطأ في التعامل

افتراضيًا ، يولد ذراع التطوّر الأخطاء بطريقة معيارية ، غالبًا ما تكون هذه الإجابات بحاجة إلى التفاف بتنسيقها الخاص.

 server.ext('onPreResponse', function (request, h) { //      Boom,     if ( !request.response.isBoom ) { return h.continue; } //  -     let responseObj = { message: request.response.output.statusCode === 401 ? 'AuthError' : 'ServerError', status: request.response.message } //     logger.error('code: ' + request.response.output.statusCode, request.response.message); return h.response(responseObj).code(request.response.output.statusCode); });

مخططات البيانات

هذا موضوع صغير ولكنه مهم جدا. تسمح لك مخططات البيانات بالتحقق من صحة الطلب وصحة الاستجابة. إلى أي مدى تصف هذه المخططات جيدًا ، فستكون المبادلات والاختبارات الذاتية ذات جودة عالية.

يتم وصف جميع مخططات البيانات من خلال joi. فلنقدم مثالًا لترخيص المستخدم:

 const Joi = require('@hapi/joi'); const Boom = require('boom'); async function response(request) { //   const accessTokens = request.getModel(request.server.config.db.database, 'access_tokens'); const users = request.getModel(request.server.config.db.database, 'users'); //     let userRecord = await users.findOne({ where: { email: request.query.login } }); //   ,     if ( !userRecord ) { throw Boom.unauthorized(); } // ,    if ( !userRecord.verifyPassword(request.query.password) ) { throw Boom.unauthorized();//  ,    ,    } // ,    let token = await accessTokens.createAccessToken(userRecord); //    return { meta: { total: 1 }, data: [ token.dataValues ] }; } //   ,      const tokenScheme = Joi.object({ id: Joi.number().integer().example(1), user_id: Joi.number().integer().example(2), expires_at: Joi.date().example('2019-02-16T15:38:48.243Z'), token: Joi.string().example('4443655c28b42a4349809accb3f5bc71'), updatedAt: Joi.date().example('2019-02-16T15:38:48.243Z'), createdAt: Joi.date().example('2019-02-16T15:38:48.243Z') }); //   const responseScheme = Joi.object({ meta: Joi.object({ total: Joi.number().integer().example(3) }), data: Joi.array().items(tokenScheme) }); //   const requestScheme =Joi.object({ login: Joi.string().email().required().example('pupkin@gmail.com'), password: Joi.string().required().example('12345') }); module.exports = { method: 'GET', path: '/auth', options: { handler: response, validate: { query: requestScheme }, response: { schema: responseScheme } } };

الاختبار:

 curl -X GET "http://localhost:3030/auth?login=pupkin@gmail.com&password=12345"

أرسل الآن بدلاً من البريد ، فقط تسجيل الدخول:

 curl -X GET "http://localhost:3030/auth?login=pupkin&password=12345"

إذا لم تتطابق الإجابة مع مخطط الاستجابة ، فسيقع الخادم أيضًا في خطأ 500.

إذا بدأ المشروع بمعالجة أكثر من طلب واحد في الساعة ، فقد يكون من الضروري الحد من التحقق من الردود ، كما هو التحقق عملية كثيفة الاستخدام للموارد. هناك معلمة لهذا: "عينة"

 module.exports = { method: 'GET', path: '/auth', options: { handler: response, validate: { query: requestScheme }, response: { sample: 50, schema: responseScheme } } };

على هذا النحو ، سيتم التحقق من صحة 50 ٪ فقط من الطلبات.

من المهم للغاية وصف القيم الافتراضية والأمثلة ، في المستقبل سوف يتم استخدامها لإنشاء الوثائق و autotests.

اختيال / OpenAPI

نحتاج إلى مجموعة من الوحدات الإضافية:

 npm i hapi-swagger @hapi/inert @hapi/vision

نحن ربطها إلى server.js

 ... const Inert = require('@hapi/inert'); const Vision = require('@hapi/vision'); const HapiSwagger = require('hapi-swagger'); const Package = require('../package'); ... const swaggerOptions = { info: { title: Package.name + ' API Documentation', description: Package.description }, jsonPath: '/documentation.json', documentationPath: '/documentation', schemes: ['https', 'http'], host: config.swaggerHost, debug: true }; ... async function createServer(logLVL=config.logLVL) { ... await server.register([ ... Inert, Vision, { plugin: HapiSwagger, options: swaggerOptions }, ... ]); ... });

وفي كل مسار تحتاج إلى وضع علامة "api":

 module.exports = { method: 'GET', path: '/auth', options: { handler: response, tags: [ 'api' ], //    swagger'     validate: { query: requestScheme }, response: { sample: 50, schema: responseScheme } } };

الآن على الموقع http: // localhost: 3030 / وثائق ، ستكون هناك واجهة ويب مع الوثائق متاحة ، وعلى الموقع http: // localhost: 3030 / documentation.json .json.

اختبار السيارات جيل

إذا وصفنا نوعيًا خطط الطلب والاستجابة ، فقمنا بإعداد قاعدة بيانات أولية تتوافق مع الأمثلة الموضحة في أمثلة الطلب ، ثم ، وفقًا للمخططات المعروفة ، يمكنك إنشاء الطلبات تلقائيًا والتحقق من رموز استجابة الخادم.

على سبيل المثال ، في GET: / auth معلمات تسجيل الدخول وكلمة المرور متوقعة ، سنأخذها من الأمثلة التي حددناها في الرسم البياني:

 const requestScheme =Joi.object({ login: Joi.string().email().required().example('pupkin@gmail.com'), password: Joi.string().required().example('12345') });

وإذا كان الخادم يستجيب بـ HTTP-200-OK ، فسنفترض أن الاختبار قد مر.

لسوء الحظ ، لم يكن هناك وحدة مناسبة جاهزة ؛ عليك التحدث قليلاً:

 // ./test/autogenerate.js const assert = require('assert'); const rp = require('request-promise'); const filepaths = require('filepaths'); const rsync = require('sync-request'); const config = require('./../config'); const createServer = require('../src/server'); const API_URL = 'http://0.0.0.0:3030'; const AUTH_USER = { login: 'pupkin@gmail.com', pass: '12345' }; const customExamples = { 'string': 'abc', 'number': 2, 'boolean': true, 'any': null, 'date': new Date() }; const allowedStatusCodes = { 200: true, 404: true }; function getExampleValue(joiObj) { if( joiObj == null ) // if joi is null return joiObj; if( typeof(joiObj) != 'object' ) //If it's not joi object return joiObj; if( typeof(joiObj._examples) == 'undefined' ) return customExamples[ joiObj._type ]; if( joiObj._examples.length <= 0 ) return customExamples[ joiObj._type ]; return joiObj._examples[ 0 ].value; } function generateJOIObject(schema) { if( schema._type == 'object' ) return generateJOIObject(schema._inner.children); if( schema._type == 'string' ) return getExampleValue(schema); let result = {}; let _schema; if( Array.isArray(schema) ) { _schema = {}; for(let item of schema) { _schema[ item.key ] = item.schema; } } else { _schema = schema; } for(let fieldName in _schema) { if( _schema[ fieldName ]._type == 'array' ) { result[ fieldName ] = [ generateJOIObject(_schema[ fieldName ]._inner.items[ 0 ]) ]; } else { if( Array.isArray(_schema[ fieldName ]) ) { result[ fieldName ] = getExampleValue(_schema[ fieldName ][ 0 ]); } else if( _schema[ fieldName ]._type == 'object' ) { result[ fieldName ] = generateJOIObject(_schema[ fieldName ]._inner); } else { result[ fieldName ] = getExampleValue(_schema[ fieldName ]); } } } return result } function generateQuiryParams(queryObject) { let queryArray = []; for(let name in queryObject) queryArray.push(`${name}=${queryObject[name]}`); return queryArray.join('&'); } function generatePath(basicPath, paramsScheme) { let result = basicPath; if( !paramsScheme ) return result; let replaces = generateJOIObject(paramsScheme); for(let key in replaces) result = result.replace(`{${key}}`, replaces[ key ]); return result; } function genAuthHeaders() { let result = {}; let respToken = rsync('GET', API_URL + `/auth?login=${AUTH_USER.login}&password=${AUTH_USER.pass}`); let respTokenBody = JSON.parse(respToken.getBody('utf8')); result[ 'token' ] = { Authorization: 'Bearer ' + respTokenBody.data[ 0 ].token }; return result; } function generateRequest(route, authKeys) { if( !route.options.validate ) { return false; } let options = { method: route.method, url: API_URL + generatePath(route.path, route.options.validate.params) + '?' + generateQuiryParams( generateJOIObject(route.options.validate.query || {}) ), headers: authKeys[ route.options.auth ] ? authKeys[ route.options.auth ] : {}, body: generateJOIObject(route.options.validate.payload || {}), json: true, timeout: 15000 } return options; } let authKeys = genAuthHeaders(); let testSec = [ 'POST', 'PUT', 'GET', 'DELETE' ]; let routeList = []; for(let route of filepaths.getSync(__dirname + '/../src/routes/')) routeList.push(require(route)); describe('Autogenerate Hapi Routes TEST', async () => { for(let metod of testSec) for(let testRoute of routeList) { if( testRoute.method != metod ) { continue; } it(`TESTING: ${testRoute.method} ${testRoute.path}`, async function () { let options = generateRequest(testRoute, authKeys); if( !options ) return false; let statusCode = 0; try { let result = await rp( options ); statusCode = 200; } catch(err) { statusCode = err.statusCode; } if( !allowedStatusCodes[ statusCode ] ) { console.log('*** TEST STACK FOR:', `${testRoute.method} ${testRoute.path}`); console.log('options:', options); console.log('StatusCode:', statusCode); } return assert.ok(allowedStatusCodes[ statusCode ]); }); } });

لا تنسى التبعيات:

 npm i request-promise mocha sync-request

وحول package.json

 ... "scripts": { "test": "mocha", "dbinit": "node ./scripts/dbInit.js" }, ...

نتحقق من:

 npm test

وإذا كان القفل عبارة عن نظام بيانات ما ، أو إذا كانت الإجابة غير متطابقة مع المخطط:

ولا تنسَ أن الاختبارات ستصبح عاجلاً أم آجلاً حساسة للبيانات الموجودة في قاعدة البيانات. قبل إجراء الاختبارات ، تحتاج إلى مسح قاعدة البيانات على الأقل.

مصادر كاملة

هابي للصغار

MVP