Mòdul de comunitat impressionant

fib-app

marc d'api bàsic de l'aplicació fibjs

Instal·la

1
npm install fib-app [--save]

Prova

1
npm test

Construeix un script bàsic

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
const http = require('http'); const util = require('util') const Session = require('fib-session') const App = require('../'); var app = new App('sqlite:test.db', { uuid: true }); app.db.use(require('./defs/person')); var session = new Session(new util.LruCache(20000), { timeout: 60 * 1000 }); var svr = new http.Server(8080, [ session.cookie_filter, { '/1.0': app } ]); svr.run();

On persones troba el mòdul de definició del model, de la següent manera:

1 2 3 4 5 6 7
module.exports = db => { db.define('person', { name: String, sex: ["male", "female"], age: Number }); };

Aquesta és una definició estàndard d’ORM i també es poden utilitzar altres funcions d’ORM, com ara comprovació de tipus, esdeveniments, etc.

Format de dades API

Per a les sol·licituds POST i PUT, el cos de la sol·licitud ha d'estar en format JSON i el tipus de contingut de la capçalera HTTP s'ha d'establir a application / json.

1 2 3 4
curl -X PUT \ -H "Content-Type: application/json" \ -d '{"name": "tom","sex":"male","age":23}' \ http://localhost/1.0/person/57fbbdb0a2400000

Per a totes les sol·licituds, el format de resposta és un objecte JSON.

L’èxit d’una sol·licitud s’indica amb el codi d’estat HTTP. Un codi d'estat 2XX indica l'èxit i un 4XX indica la fallida de la sol·licitud. Quan una sol·licitud falla, el cos de la resposta continua sent un objecte JSON, però sempre contindrà els dos camps de codi i missatge, que podeu utilitzar per a la depuració. Per exemple, si falla la sol·licitud d'autenticació de permisos, es retornarà la informació següent:

1 2 3 4
{ "code": 4030501, "message": "The operation isn’t allowed for clients due to class-level permissions." }

El codi es divideix en tres parts: els primers tres dígits 403 indiquen el tipus d'error, 05 indiquen el número de la taula de dades i 01 indiquen el codi d'error detallat.

Per a una sol·licitud GET, normalment es retornen les dades de l'objecte. Segons l'adreça de la sol·licitud GET, es pot retornar un objecte o una matriu. per exemple:

1 2 3 4 5
{ "name": "tom", "sex": "male", "age": 23 }

o:

1 2 3 4 5 6 7 8 9 10 11 12
[ { "name": "tom", "sex": "male", "age": 23 }, { "name": "lily", "sex": "female", "age": 22 } ]

Camp especial

A les dades de l'objecte, hi ha quatre camps amb significats especials, que no es poden canviar mitjançant l'API. Respectivament id, updatedAt, createdAt, createdBy.

On id, updatedAt, createdAtcamps individuals es poden crear i modificar de forma automàtica. createdByHeu d’especificar el tipus vosaltres mateixos.

API bàsica d'accés a objectes

Després de completar aquesta definició de dades, tindreu directament un conjunt complet de trucades a la interfície que s’ajusten a l’especificació de l’API REST:

url mètode acció
/1.0/:className POST Crea un objecte nou
/1.0/:className/:id ACONSEGUIR Llegiu l’objecte
/1.0/:className/:id POSA Modifiqueu l'objecte
/1.0/:className/:id ESBORRAR Suprimeix l'objecte
/1.0/:className ACONSEGUIR Llista d'objectes de consulta

Crea un objecte nou

Per crear un objecte nou, s’ha d’enviar una sol·licitud POST a l’URL de la classe, que hauria de contenir l’objecte mateix. Per exemple, per crear l'objecte tal com s'ha esmentat anteriorment:

1 2 3 4
curl -X POST \ -H "Content-Type: application/json" \ -d '{"name": "tom","sex":"male","age":23}' \ http://localhost/1.0/person

Quan la creació té èxit, la resposta HTTP es crea 201 i el cos de la resposta és un objecte JSON, inclòs objectId i createdAt timestamp del nou objecte:

1 2 3 4
{ "createdAt": "2017-11-25T01:39:35.931Z", "id": "57fbbdb0a2400000" }

Llegiu l’objecte

Quan creeu un objecte, podeu obtenir-ne el contingut enviant una sol·licitud GET a la ubicació de la capçalera retornada. Per exemple, per obtenir l'objecte que hem creat més amunt:

1
curl -X GET http://localhost/1.0/person/57fbbdb0a2400000

El cos retorna un objecte JSON conté totes les juntes amb el camp subministrats per l'usuari createdAt, updatedAti idcamps:

1 2 3 4 5 6 7 8
{ "name": "tom", "sex": "male", "age": 23, "createdAt": "2017-11-25T01:39:35.931Z", "updatedAt": "2017-11-25T01:39:35.931Z", "id": "57fbbdb0a2400000" }

Torna el camp proporcionant keyscontingut personalitzat que es pot retornar, el keyscontingut es troba en una ,cadena de noms de camp dividida:

1
curl -X GET http://localhost/1.0/person/57fbbdb0a2400000?keys=name%2Csex

Tornarà:

1 2 3 4
{ "name": "tom", "sex": "male" }

Modifiqueu l'objecte

Per canviar les dades existents d'un objecte, podeu enviar una sol·licitud PUT a l'URL corresponent de l'objecte. Qualsevol clau que no hàgiu especificat no es canviarà, de manera que només podeu actualitzar un subconjunt de dades de l'objecte. Per exemple, canviem un camp d'edat del nostre objecte:

1 2 3 4
curl -X PUT \ -H "Content-Type: application/json" \ -d '{"age": 25}' \ http://localhost/1.0/person/57fbbdb0a2400000

L'objecte retornat JSON contindrà updatedAti un idcamp que indiquen que l'actualització s'ha produït alhora:

1 2 3 4
{ "updatedAt": "2017-11-25T01:39:35.931Z", "id": "57fbbdb0a2400000" }

Suprimeix l'objecte

Per suprimir un objecte, podeu enviar una sol·licitud SUPRIMIR a l'URL de l'objecte especificat, com ara:

1
curl -X DELETE http://localhost/1.0/person/57fbbdb0a2400000

Llista d'objectes de consulta

En enviar una sol·licitud GET a l’URL de la classe, podeu obtenir diversos objectes alhora sense cap paràmetre d’URL. El següent és simplement aconseguir que tots els usuaris:

1
curl -X GET http://localhost/1.0/person

El valor retornat és un objecte JSON que conté el camp de resultats i el seu valor és una llista d’objectes:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
[ { "name": "tom", "sex": "male", "age": 23, "createdAt": "2017-11-25T01:39:35.931Z", "updatedAt": "2017-11-25T01:39:35.931Z", "id": "57fbbdb0a2400000" }, { "name": "lily", "sex": "female", "age": 22, "createdAt": "2017-11-25T01:39:35.931Z", "updatedAt": "2017-11-25T01:39:35.931Z", "id": "57fbbdb0a2400001" } ]

personalització del camp de claus

Igual que amb la consulta d'objectes, podeu definir que el keyscamp personalitzat de la llista de consultes retorni el resultat que contindrà. keysEl contingut es troba en una ,cadena de noms de camp dividida, per exemple:

1
curl -X GET http://localhost/1.0/person?keys=name%2Cage

Només el retorn especificat namei agedos camps.

on es troba l'estat del filtre

By wherepot fer restriccions a l'objecte de consulta com a paràmetre.

whereEl valor del paràmetre ha de ser codificat per JSON. Dit d’una altra manera, si mireu la sol·licitud d’URL realment enviada, primer hauria d’estar codificada per JSON i, després, codificada per URL. El més fàcil d'utilitzar wherecom a arguments és incloure la clau i el valor adequats. Per exemple, si volem cercar usuaris que es diuen tom, hauríem de construir la consulta així:

1
curl -X GET http://localhost/1.0/person?where=%7B%22name%22%3A%22tom%22%7D

where El valor és una cadena JSON després del codi d’URL, el contingut és:{"name":"tom"}

A més de coincidir exactament amb un valor determinat, wheretambé s’admeten mètodes de comparació com la inclusió. whereEls paràmetres admeten les opcions següents:

clau operació mostra
eq igual {"name": {"eq": "tom"}} o {"name": "tom"}
ne no igual a {"name": {"ne": "tom"}}
gt més que el {"age": {"gt": "24"}}
gte major o igual a {"age": {"gte": "24"}}
lt Menys que {"age": {"lt": "24"}}
lte Menys o igual a {"age": {"lte": "24"}}
M'agrada Consulta difusa {"name": {"like": "% m"}}
no_com Consulta difusa {"name": {"not_like": "% m"}}
entre Comparació d'intervals {"age": {"between": [22,25]}}
no_entre Comparació d'intervals {"age": {"not_between": [22,25]}}
dins enumerar {"name": {"in": ["tom", "lily"]}}
no_in enumerar {"name": {"not_in": ["tom", "lily"]}}
o bé O operació {"or": [{"name": "tom"}, {"age": 24}]}

saltar saltar registres

Per skipopció, podeu especificar el nombre de registres que voleu ometre per aconseguir un efecte de capgirament.

1
curl -X GET http://localhost/1.0/person?skip=100

límit retorna el límit de registre

Per limitopció, podeu limitar el nombre de registres retornats, limitels dígits significatius d'1 a 1000 i els valors predeterminats a 100.

1
curl -X GET http://localhost/1.0/person?limit=100

ordre especifica el mètode d'ordenació

Per orderopció establerta per tornar a ordenar el conjunt de resultats, abans que el nom del camp contingui -com a temps invers.

1
curl -X GET http://localhost/1.0/person?order=-id

count retorna el nombre total de resultats

Quan se us demani que augmenteu countel nombre total, podeu tornar un conjunt de resultats del contingut especificat al mateix temps.

1
curl -X GET http://localhost/1.0/person?count=1&limit=1

En aquest moment, els resultats de retorn que contenen counti resultsque comprèn dos camps, i cadascun un nombre total de resultats:

1 2 3 4 5 6 7 8 9 10 11 12 13
{ "count": 2, "results": [ { "name": "tom", "sex": "male", "age": 23, "createdAt": "2017-11-25T01:39:35.931Z", "updatedAt": "2017-11-25T01:39:35.931Z", "id": "57fbbdb0a2400000" } ] }

Creeu un objecte d'extensió

En definir hasOne i hasMany mitjançant orm, la relació d’associació entre objectes es pot definir i reflectir a l’API, per exemple:

1 2 3 4 5 6 7 8 9
module.exports = db => { var Person = db.models.person; var Pet = db.define('pet', { name: String }); Person.hasMany('pets', Pet); };

API d'accés a objectes ampliada

A continuació es defineix l'API de l'objecte d'extensió:

url mètode acció
/1.0/:className/:id/:extendName POSA Estableix l'objecte d'extensió
/1.0/:className/:id/:extendName POST Creeu un objecte d'extensió
/1.0/:className/:id/:extendName/:rid ACONSEGUIR Llegiu l'objecte ampliat
/1.0/:className/:id/:extendName/:rid POSA Modifiqueu l'objecte d'extensió
/1.0/:className/:id/:extendName/:rid ESBORRAR Suprimeix l'objecte de l'extensió
/1.0/:className/:id/:extendName ACONSEGUIR Consulteu la llista d'objectes ampliats

Estableix l'objecte d'extensió

Establir un objecte ampliat és establir una connexió entre dos objectes independents. Per exemple, Tom ha adoptat una mascota anomenada gat, que es pot aconseguir amb les següents operacions:

1 2 3 4
curl -X PUT \ -H "Content-Type: application/json" \ -d '{"id": "57fbbdb0a2400007"}' \ http://localhost/1.0/person/57fbbdb0a2400000/pets

A la trucada, cal especificar l’identificador de gat al cos.

Creeu un objecte d'extensió

En crear directament objectes ampliats, podeu establir connexions entre objectes mentre creeu objectes. per exemple:

1 2 3 4
curl -X POST \ -H "Content-Type: application/json" \ -d '{"name": "cat"}' \ http://localhost/1.0/person/57fbbdb0a2400000/pets

Es crearà una mascota anomenada gat i s’establirà una relació d’associació amb Tom.

Llegiu l'objecte ampliat

La lectura d'objectes ampliats és molt similar a la lectura d'objectes base i també admet l'opció de tecles:

1
curl -X GET http://localhost/1.0/person/57fbbdb0a2400000/pets/57fbbdb0a2400007

Modifiqueu l'objecte d'extensió

La lectura d'objectes ampliats és molt similar a la lectura d'objectes base:

1 2 3 4
curl -X PUT \ -H "Content-Type: application/json" \ -d '{"name": "cat 1"}' \ http://localhost/1.0/person/57fbbdb0a2400000/pets/57fbbdb0a2400007

Suprimeix l'objecte de l'extensió

Si suprimiu un objecte ampliat, no se suprimeix l'objecte en si, sinó que només s'elimina la relació entre els objectes:

1
curl -X DETELE http://localhost/1.0/person/57fbbdb0a2400000/pets/57fbbdb0a2400007

Consulteu la llista d'objectes ampliats

La consulta de la llista d’objectes ampliada és molt similar a la consulta de la llista d’objectes bàsics i també admet opcions com ara tecles i filtratge condicional:

1
curl -X GET http://localhost/1.0/person/57fbbdb0a2400000/pets

ACL

Els permisos de dades es poden controlar definint l'ACL del model. per exemple:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
const orm = require('fib-orm'); module.exports = db => { db.define('blog', { title: String, detail: Stringnote: String }, { ACL: function(session) { return { "*": { "*": false }, "57fbbdb0a2400000": { "*": true }, "roles": { "user": { "read": true } } }; } }); };

Si no s’especifica cap ACL quan es defineix el model, equival a definir els permisos per defecte:

1 2 3 4 5
{ "*": { "*": true } }

cos principal

Hi ha tres descripcions principals de l’ACL, usuari id, usuari rolei *, que idrepresenten un usuari específic, roleque indiquen que l’usuari té un paper, *significa que tots els usuaris:

cos principal descriure prioritat
identificador Identificador de l'usuari concret 1
paper Nom del grup d'usuaris 2
* Tots 3

En comprovar els privilegis, el primer coincidirà amb idels drets corresponents, si no s’especifica, els rolepermisos d’ usuari coincidents corresponen encara si s’especifica, per veure si l’ *autoritat designada , si *no s’especifica, no té permís.

Per exemple, la configuració de permisos anterior especifica el usergrup d’usuaris que pot llegir, l’usuari 57fbbdb0a2400000té drets complets, mentre que la resta d’usuaris no tenen permís.

Autoritat

L'ACL classifica cinc tipus de permisos en funció del comportament de l'API:

Autoritat descriure Tipus permès
crear Crea un objecte true / false / array
llegir Llegiu l’objecte true / false / array
escriure Modifiqueu l'objecte true / false / array
esborrar Suprimeix l'objecte veritable / fals
trobar Llista d'objectes de consulta veritable / fals
* Coincideix amb tots els permisos true / false / array

Permisos desenvolupats trueper permetre l'accés, per falseprohibir l'accés per arraypermetre només els camps d'accés especificats. deleteI findno accepta array, si s'estableix, arrayllavors es considera com true. Si el permís especificat no existeix, el següent coincideix amb l' *autoritat principal . Si no n'hi ha cap, torneu a consultar l'assumpte de la següent prioritat.

Exemples de l'exemple anterior, si es requereix per establir usernomés permet llegir titlei detailes poden llegir altres title, es pot configurar de manera que:

1 2 3 4 5 6 7 8 9 10 11 12 13 14
{ "*": { "*": false, "read": ['title'] }, "57fbbdb0a2400000": { "*": true }, "roles": { "user": { "read": ['title', 'detail'] } } }

Permisos d'objectes

Els permisos de tota la classe es defineixen al model. Si heu d'establir permisos per a objectes específics, podeu configurar OACL per aconseguir:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
module.exports = db => { db.define('person', { name: String, sex: ["male", "female"], age: Number }, { ACL: function(session) { return { "*": { "*": false } } }, OACL: function(session) { var _acl = {}; if(this.id === session.id) _acl[session.id] = { "*": true }; return _acl; } }); };

En aquest exemple, quan el visitant és el tema, es permetran totes les operacions, en cas contrari es prohibiran totes les visites. Els permisos es comprovaran segons els passos següents:

  • person[57fbbdb0a2400000] => OACL
  • person => ACL

Permisos d'objectes ampliats

El control de permisos d'accés de l'objecte ampliat és similar al permís d'objecte bàsic, l'única diferència és que cal especificar-lo per separat a l'ACL:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
module.exports = db => { var Person = db.define('person', { name: String, sex: ["male", "female"], age: Number },{ ACL: function(session) { return { "*": { "read": ['name', 'sex'], "extends": { "pets": { "read": true, "find": true } } } } }, OACL: function(session) { var _acl = {}; if(this.id === session.id) _acl[session.id] = { "*": true, "extends": { "pets": { "*": true } } }; return _acl; } }); var Pet = db.define('pet', { name: String }); Person.hasMany('pets', Pet); };

En aquesta definició, tothom pot accedir a informació personal namei sex, i d’accedir-hi gratuïtament i buscar-lo pets, sóc l’usuari que pot operar totes les seves dades i tots els drets de tenir la seva pròpia informació sobre mascotes.

En comprovar l'autorització d'accés de l'objecte ampliat, l'autorització d'objectes i l'autoritat d'objectes ampliada es comproven per separat. Per exemple, la sol·licitud següent:

1
curl -X GET http://localhost/1.0/person/57fbbdb0a2400000/pets/57fbbdb0a2400007

Els permisos es comprovaran segons els passos següents:

  • pets[57fbbdb0a2400007] => OACL
  • person[57fbbdb0a2400000]=> OACL=> extends=>pets
  • person=> ACL=> extends=>pets
  • pets => ACL

Funció

Es poden definir API per al model i es poden completar operacions de dades complexes personalitzant la funció.

ACL pot controlar la gran majoria de permisos i no es requereix cap funció per completar els permisos basats en objectes. La funció es pot utilitzar per completar permisos basats en dades, com ara concedir permisos a diferents grups d'usuaris en funció de l'estat d'aprovació. I diverses modificacions, com ara la necessitat de modificar diversos registres de bases de dades.

Dibuixa el model de dades

Un cop finalitzada la definició de dades, es pot utilitzar app.diagram()per dibuixar svgun diagrama de classes de format de model de dades , els fitxers es guardaran en una imatge similar a la següent: diagrama