Cet article présente les meilleures pratiques pour que Spring Boot développe des interfaces de repos et les partage avec vous, comme suit:
Les verbes http correspondent aux commandes SQL
OBTENIR
Obtenez des ressources du serveur, vous pouvez obtenir une ou plusieurs ressources et obtenir toutes les informations utilisateur sur le serveur, obtenir / utilisateurs / ID, l'ID spécifié et obtenir des informations utilisateur de l'ID spécifié.
POSTE
Créez une nouvelle ressource sur le serveur, correspondant à CreatePost / Users dans la commande SQL pour créer un nouvel utilisateur
METTRE
Mettez à jour une ressource sur le serveur et le client fournit la ressource complète modifiée, correspondant à la mise à jour / utilisateurs / ID dans la commande SQL pour mettre à jour toutes les informations de l'utilisateur avec l'ID spécifié
SUPPRIMER
Supprimez une ressource du serveur et supprimez les informations utilisateur de l'ID spécifié correspondant à DeleteDelete / Users / ID dans la commande SQL
CORRECTIF
Mettez à jour certains attributs d'une ressource sur le serveur, correspondant à UpdatePatch / Users / ID dans la commande SQL pour mettre à jour un certain attribut de l'utilisateur avec l'ID spécifié
Conventions dans les URL
Les noms dans les URL utilisent des formes plurielles
La question de savoir si le nom d'une URL utilise un singulier ou un pluriel a été controversé. Les noms de l'URL correspondent généralement aux tableaux de la base de données, et les tableaux stockent des données similaires. En pratique, je force l'utilisation de formes plurielles, qui semblent plus confortables.
/ utilisateurs / utilisateurs / 1 / rôles / rôles / rôles / 1
Quant à certains noms irréguliers et innombrables, cela dépend de votre opinion.
/ Heroes / Heroes / 1 / personnes / personnes / 1 / pied / pied / 1 / pieds / pieds / 1 / pieds / pieds / 1
Version
Parlez des numéros de version à ajouter à l'URL pour gérer les changements incompatibles et destructeurs. Lors de la publication d'une nouvelle API, le client peut passer librement vers la nouvelle API et ne sera pas en difficulté en raison de l'appel d'une nouvelle API complètement différente. Utilisez un préfixe "V" intuitif pour indiquer que le numéro suivant est le numéro de version, aucun numéro de version secondaire n'est requis et que les versions API ne doivent pas être publiées fréquemment.
/ edu / v1 / utilisateurs / edu / v1 / rôles
Utilisez des chaînes de requête pour des paramètres complexes en option
Afin de rendre l'URL plus petite et plus concise, définissez une URL de base pour la ressource, et les paramètres facultatifs et complexes sont représentés par des chaînes de requête.
/ edu / v1 / utilisateurs? ENabled = 1 & roleId = 1
Fournir des informations de pagination
Ce n'est pas une bonne idée de retourner toutes les ressources dans la base de données à la fois, donc un mécanisme de radication est requis. Habituellement, les paramètres bien connus de la base de données sont utilisés pour compenser et limiter
/ edu / v1 / utilisateurs? Activé = 1 & offset = 1 & limite = 15
Si le client ne transmet pas ces paramètres, la valeur par défaut doit être utilisée, généralement offset = 0, limit = 10.
Utilisez des verbes pour les demandes de non-ressources
Parfois, les appels API n'impliquent pas de ressources, auquel cas le serveur effectue une opération et renvoie le résultat au client.
/ edu / v1 / calc? p = 100
Envisagez des ressources spécifiques et des recherches de ressources croisées
Il est facile de fournir une recherche d'une fin de séjour spécifique. Il vous suffit d'utiliser la collection de ressources correspondante et d'ajouter la chaîne de recherche aux paramètres de requête.
/ edu / v1 / utilisateurs? username = li qinghai
Si vous devez fournir une recherche globale pour toutes les ressources, vous devez utiliser une autre méthode.
/ edu / v1 / search? key = li qinghai
Résultats de la réponse
Utilisez la petite nomenclature de chameaux comme identifiant d'attribut
En règle générale, les services Web RESTful seront utilisés par des clients écrits en JavaScript. Le client convertit la réponse JSON à un objet JavaScript, puis appelle ses propriétés. Par conséquent, il est préférable de suivre la spécification commune du code JavaScript.
personne.year_of_birth // non recommandé, violant le code javascript spécification générale personne
Fournir des informations de pagination
Lorsqu'il y a de nombreux résultats renvoyés, des informations de pagination doivent être fournies.
{"page": 0, "taille": 10, "total": 3465, "obj": []}Interface de repos de développement de printemps
Annotations communes
@RestController
@RestController est une annotation combinée de @ResponseBody et @Controller.
@Requestmapping
Cette annotation peut être appliquée à une méthode du contrôleur ou à cette classe de contrôleur. Lorsque le contrôleur ajoute l'annotation @Requestmapping au niveau de la classe, cette annotation est appliquée à toutes les méthodes de processeur du contrôleur. L'annotation @RequestMapping sur la méthode du processeur complétera la déclaration de @RequestMapping au niveau de la classe.
@Postmapping
L'annotation combinée est l'abréviation de @RequestMapping (méthode = requestMethod.post).
@Putmapping
L'annotation combinée est l'abréviation de @RequestMapping (méthode = requestMethod.put).
@Patchmapping
L'annotation combinée est l'abréviation de @RequestMapping (méthode = requestMethod.patch).
@Deletemapping
L'annotation combinée est l'abréviation de @RequestMapping (méthode = requestMethod.delete).
@Getmapping
L'annotation combinée est l'abréviation de @RequestMapping (méthode = requestMethod.get).
@Pathvariable
Obtenez les données dans l'URL.
@RequestParam
Obtient la valeur du paramètre demandé.
Exemple de documentation de l'API de l'interface de repos et de fanfaronnade
Pour l'utilisation de Swagger, veuillez vous référer à l'utilisation de Swagger2 dans le projet Spring Boot. Le code dans le corps de la méthode n'est pas important, ce qui est important, c'est la signature de la méthode et le mappage avec les verbes http.
import java.util.date; import javax.persistence.entityNotFoundException; import org.springframework.beans.factory.annotation.autowired; import org.springframework.data.domain.page; import org.springframework.wat.bind.annotation.getmapping; import; org.springframework.web.bind.annotation.patchmapping; import org.springframework.web.bind.annotation.pathvariable; import org.springframework.web.bind.annotation.postmapping org.springframework.web.bind.annotation.requestmapping; import org.springframework.web.bind.annotation.requestParam; import org.springframework.web.bind.annotation.restController; import CN.com.infcn.jianshu.servce.Service.USSERSSERVICE; IMPORT cn.com.infcn.jianshu.exception.bizexception; import cn.com.infcn.jianshu.exception.loginnameorpassworderrorexception; import cn.com.infcn.jianshu.exception.resourceExistSexception; Importer cn.com.infcn.jianshu.model.usère; import; cn.com.infcn.jianshu.util.jsonresult; import io.swagger.annotations.api; import io.swagger.annotations.apiparam; / ** * Contrôleur d'utilisateur système * * @author li Qinghai * * / @ api (value = "System User Interface", Tags = "System Management") @ restController classe UserController {@Autowired Private UserService UserService; / ** * Ajouter l'utilisateur, le registre * * @Param LoginName * Compte de connexion * @param nom d'utilisateur * Nom d'utilisateur * @param mot de passe * Mot de passe de connexion * @param roleId * Rôle utilisateur * @return * @throws ResourceExistSException * / @apioperation (@APIpAram (Name = "LOGINNAG compte ", obligatoire = true) @RequestParam (obligatoire = true) @Requestbody String LoginName, @apiparam (name =" username ", value =" username ", obligé = true) @RequestParam (obligé = true) @requestbody String username, @APiparam (name =" mot de passe "," log dans le mot de passe ", obligatoire = true) @requestParam (nécessaire = true) @reque Mot de passe, @APiparam (name = "roleId", value = "Numéro de rôle utilisateur", requis = true) @RequestParam (requis = true) @Requestbody String RoleID) lève ResourceExistSException {boolean exists = this.userservice.exists (loginname); if (existant) {lancer un nouveau ressourceExistSException (loginname); } Utilisateur utilisateur = userService.Create (LoginName, Mot de passe, nom d'utilisateur, RoleID); return jsonResult.success (utilisateur); } / ** * Connexion de l'utilisateur avec compte de connexion et mot de passe de connexion * * @Param LoginName * Compte de connexion * @param mot de passe * Mot de passe de connexion * @throws EntityNotFoundException * / @APIOperation (Value = "Informations utilisateur de requête basée sur le numéro d'utilisateur") @getMapping ("/ Login") public JSONResult Login (@APiParam (nom = "Loginname", "Value =" LOCIN @RequestParam (required = true) String LoginName, @APiparam (name = "mot de passe", value = "Login Motword", requis = true) @RequestParam (required = true) String Password) lève LoginNameorPassWorderRorexception {user user = this.userservice.login (LoginName, mot de passe); if (null == user) {lancer un nouveau LoginNameorPassWorderRorexception (); } return JSONRESULT.SUCCESS (utilisateur); } / ** * Informations d'utilisateur de requête en fonction du numéro d'utilisateur * * @param id * numéro d'utilisateur * @throws entityNotFoundException * / @apioperation (value = "Informations utilisateur basées sur le numéro d'utilisateur") @getMapping ("/ {id}") public JSonResult Read (@APIPARAM (name = "id", user) lève entityNotFoundException {user user = this.userservice.getOne (id); return jsonResult.success (utilisateur); } / ** * Le compte est annulé et les données de l'utilisateur ne sont pas supprimées * * @param userId * numéro d'utilisateur * @return * / @apioperation (value = "cardée hors du compte") @PatchMapping ("/ {id}") public jsonResult annule (@APiparam (name = "id", value) EntityNotFoundException {this.userservice.cancel (id); retourner JSONRESULT.SUCCESS (); } / ** * réinitialiser le mot de passe * * @param id * numéro d'utilisateur * @param mot de passe * nouveau mot de passe de connexion * @return * / @apioperation (value = "réinitialiser le mot de passe") @PatchMapping ("/") public jsonResult updatePassword (@apiparam (name = "id", value = "numéro d'utilisation, @APIPAraCa "mot de passe", valeur = "nouveau mot de passe de connexion", obligatoire = true) @RequestParam (requis = true) mot de passe de chaîne) {this.userservice.updatepassword (id, mot de passe); retourner JSONRESULT.SUCCESS (); } / ** * Query de combinaison multi-conditions * * @param nom d'utilisateur * Nom d'utilisateur * @param roleId * Rôle de l'utilisateur * @param start * start Date * @param end * fin date * @param page * @return * @throws bizexectm * / @apiOperation (value = "information") ")") "/"). JSONRESULT QUERY (@APIPARAM (name = "username", value = "Nom d'utilisateur, mot-clé de requête", obligé = false) @RequestParam (obligatoire = false) Nom d'utilisateur de chaîne, @apiparam (name = "roleId", valeur = @apiparam " @RequestParam (obligatoire = false) date de démarrage, @apiparam (name = "end", valeur = "numéro de rôle utilisateur", obligatoire = false) @RequestParam (obligatoire = false) fin fin, @apiparam (name = "page", value = "pagination, quelle page, à partir de 1", defaultValue = "1", requise = true) @requestParam (DefaultValue = "1", obligatoire = Page) @requestParam (DefaultValue = "1", obligatoire = Page) @requestParam (DefaultValue = "1", obligat @Apiparam (name = "size", value = "nombre de lignes par page, entier positif", defaultValue = "10", requise = true) @RequestParam (defaultValue = "10", requis = true) int size) lève Bizexception {page <user> datas = this.UserService.FinDatas (nom d'utilisateur, rôled, début, fin, page, taille); if (null == dataS || null == datas.getContent () || dataS.getContent (). IsEmpty ()) {throw new Bizexception ("l'utilisateur n'existe pas"); } return jsonResult.success (datas); }}Rendu de document d'interface Swagger2
Ce qui précède est tout le contenu de cet article. J'espère que cela sera utile à l'apprentissage de tous et j'espère que tout le monde soutiendra davantage Wulin.com.