Mempertahankan dokumentasi untuk layanan-layanan microsoft mutakhir masih membutuhkan disiplin penuh dalam pengembangan, dan biaya tenaga kerja yang besar. Sebagai contoh, GraphQL menawarkan pendekatan yang sangat masuk akal untuk membuat dokumentasi, di mana dokumentasi terkait erat dengan kode program dan ini menjamin kepatuhan 100% dari dokumentasi dan layanan yang didokumentasikan. Namun, pendekatan yang tidak biasa dari GraphQL untuk pengembang yang terbiasa dengan REST-API, masih membuatnya sulit untuk mempromosikan teknologi ini dalam pengembangan aplikasi praktis. Di sini Anda dapat mengingat SOAP, yang telah lama memecahkan masalah kesesuaian dokumentasi dan layanan, tetapi karena terlalu rumit, ia tidak berakar di antara massa pengembang yang luas.
Saya ingin menemukan setumpuk teknologi untuk mengembangkan layanan-layanan microser yang menyediakan kemampuan mendokumentasikan diri yang sama dari kode program ketika mengembangkan layanan-layanan REST-API "tradisional". Dan dia, ternyata, sudah ada.
Kami mendefinisikan aktor dan pemain yang akan terlibat dalam contoh kecil kami.
ArangoDB adalah basis data hybrid + dokumen-berorientasi.
UPD Kenalan lebih rinci dengan database ini adalah alasan untuk kekecewaan lain. Ternyata, setelah database melebihi batas tidak terbatas, yang dibatasi oleh RAM gratis, database mulai melambat - hanya berhenti bersama dengan server. Pada saat yang sama, asumsi malu-malu diungkapkan bahwa transisi ke mesin penyimpanan baru akan bekerja lebih baik, yang belum dikonfirmasi.
Foxx adalah kerangka kerja layanan mikro yang dibangun ke dalam basis data ArangoDB. Ini berjalan pada mesin JavaScript, yang (tidak seperti nodejs) dapat secara bersamaan dieksekusi dalam jumlah paralel thread yang tidak terbatas (tidak saling menghalangi), sebagai akibatnya tidak ada kebutuhan untuk konstruksi janji / daripada / canch dan async / menunggu. Tidak seperti mongodb, di mana tidak disarankan untuk menyalahgunakan prosedur server, dan basis data relasional di mana prosedur tersimpan juga digunakan dengan hati-hati dan tentu saja tidak berinteraksi dengan klien (browser, aplikasi seluler, dll.) Melalui REST-API, ini adalah kerangka kerja layanan mikro Foxx dirancang khusus untuk pengembangan layanan mikro yang berkomunikasi langsung dengan protokol http dengan klien.
Swagger adalah lingkungan perangkat lunak sumber terbuka yang didukung oleh ekosistem besar alat yang membantu pengembang mengembangkan, membuat, mendokumentasikan, dan mengonsumsi layanan web RESTful. Meskipun sebagian besar pengguna mengidentifikasi Swagger dengan UI Swagger, toolkit Swagger mencakup dukungan untuk dokumentasi otomatis, pembuatan kode, dan pembuatan kasus uji.
Fakta bahwa Swagger menyertakan dukungan untuk pembuatan kode adalah situasi yang berlawanan dengan yang ingin kami dapatkan - ketika kode mendukung pembuatan dokumentasi. Apa yang ditawarkan ArangoDB + Foxx hanya mencakup opsi yang berlawanan. Ketika kode microservice menghasilkan sirkuit untuk Swagger. Namun, sekarang Anda dapat memverifikasi ini sendiri setelah melakukan pekerjaan minimum.
Anda harus menginstal ArangoDB untuk melakukan tindakan lebih lanjut.
- Kami masuk ke panel admin dan memilih item untuk membuat Layanan microservice baru-> Tambah layanan-> Baru.
- Kami mengisi formulir yang diperlukan dalam formulir yang dibuka. Di bidang "Koleksi Dokumen", tambahkan nama koleksi dokumen yang akan dibuat ketika layanan Microsoft digunakan. Misalnya, kucing.
- Kami klik pada tombol install, masukkan di bidang url di mana microservice akan dipasang.
Saat memasang layanan mikro, untuk setiap koleksi dari bidang "Koleksi Dokumen" (lihat klausa 2), rute akan dibuat yang mengimplementasikan operasi CRUD menggunakan metode POST, GET, PUT, dan HAPUS. Namun, ini hanya konsep metode yang dapat Anda ubah, hapus, tambahkan yang baru. Kami memilih satu koleksi saat membuat microservice (kucing), meskipun kami mungkin tidak melakukannya, tetapi menambahkan semuanya secara manual nanti.
Sekarang, koleksi kucing kami memiliki rute untuk operasi CRUD, dan kami dapat mulai memanggil rute ini dari panel admin database dengan memilih tab API (Layanan -> [Nama Layanan Mikro] -> API). Tab ini berisi antarmuka Swagger yang familier. Dimungkinkan juga untuk menerbitkan antarmuka Swagger pada rute eksternal, diakses tidak hanya melalui panel admin, tetapi sebagai URL biasa.
Jika kami mencoba menambahkan dokumen ke koleksi kucing menggunakan metode POST {"name": "Tom"}, kami mendapatkan status dengan kesalahan. Karena bidang nama yang belum kami definisikan. Karenanya, kami akan terus bekerja dengan panel admin ArangoDB.
4. Untuk pengembangan yang lebih mudah, ArangoDB menyediakan mode Pengembangan, yang diaktifkan pada tab Pengaturan (Layanan -> [Nama Layanan Mikro] -> Pengembangan Pengaturan-Pengaturan)
Sekarang Anda dapat mengubah kode layanan dunia dan segera mengamati hasilnya (tanpa penyebaran tambahan). Direktori tempat kode program layanan mikro dapat ditemukan di panel admin pada tab Info (Layanan -> [Nama Layanan Mikro] -> Info).
Mari kita lihat seperti apa definisi dari rute POST.
'use strict'; const dd = require('dedent'); const joi = require('joi'); const httpError = require('http-errors'); const status = require('statuses'); const errors = require('@arangodb').errors; const createRouter = require('@arangodb/foxx/router'); const Cat = require('../models/cat'); const cats = module.context.collection('cats'); const keySchema = joi.string().required() .description('The key of the cat'); const ARANGO_NOT_FOUND = errors.ERROR_ARANGO_DOCUMENT_NOT_FOUND.code; const ARANGO_DUPLICATE = errors.ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED.code; const ARANGO_CONFLICT = errors.ERROR_ARANGO_CONFLICT.code; const HTTP_NOT_FOUND = status('not found'); const HTTP_CONFLICT = status('conflict'); const router = createRouter(); module.exports = router; router.tag('cat'); router.post(function (req, res) { const cat = req.body; let meta; try { meta = cats.save(cat); } catch (e) { if (e.isArangoError && e.errorNum === ARANGO_DUPLICATE) { throw httpError(HTTP_CONFLICT, e.message); } throw e; } Object.assign(cat, meta); res.status(201); res.set('location', req.makeAbsolute( req.reverse('detail', {key: cat._key}) )); res.send(cat); }, 'create') .body(Cat, 'The cat to create.') .response(201, Cat, 'The created cat.') .error(HTTP_CONFLICT, 'The cat already exists.') .summary('Create a new cat') .description(dd` Creates a new cat from the request body and returns the saved document. `);
Baik validasi dan dokumentasi didasarkan pada penggunaan skema objek. Kami akan melakukan sedikit perubahan dengan menambahkan bidang nama:
'use strict'; const _ = require('lodash'); const joi = require('joi'); module.exports = { schema: {
Dengan pergi ke bookmark API, Anda dapat memastikan bahwa skema telah berubah dan sekarang objek dengan bidang nama dapat ditambahkan ke koleksi kucing.
apapacy@gmail.com
12 November 2018.