Este artículo presenta las mejores prácticas para Spring Boot para desarrollar interfaces de descanso y las comparte con usted, de la siguiente manera:
Los verbos HTTP corresponden a los comandos SQL
CONSEGUIR
Obtenga recursos del servidor, puede obtener uno o más recursos y obtener toda la información del usuario en el servidor, Get /Users /ID, la ID especificada y obtener información del usuario de la ID especificada.
CORREO
Cree un nuevo recurso en el servidor, correspondiente a CreatePost /Usuarios en el comando SQL para crear un nuevo usuario
PONER
Actualizar un recurso en el servidor, y el cliente proporciona el recurso completo cambiado, correspondiente al updateput /users /id en el comando sql para actualizar toda la información del usuario con la identificación especificada
BORRAR
Eliminar un recurso del servidor y eliminar la información del usuario de la ID especificada correspondiente al DeletedElete /Uss /ID en el comando SQL
PARCHE
Actualice algunos atributos de un recurso en el servidor, correspondiente a UpdatePatch /Users /ID en el comando SQL para actualizar un cierto atributo del usuario con la ID especificada
Convenciones en URLS
Sustantivos en las URL usan formas plurales
La cuestión de si el nombre en una URL usa un singular o un plural ha sido controvertida. Los sustantivos en la URL generalmente corresponden a tablas en la base de datos, y las tablas almacenan datos similares. En la práctica, forgo el uso de formas plurales, que se ve más cómoda.
/usuarios/usuarios/1/roles/roles/roles/1
En cuanto a algunos sustantivos irregulares e incontables, depende de su opinión.
/héroes/héroes/1/personas/personas/1/pies/pies/1/pies/pies/1/pies/pies/1
Versión
Hable los números de versión que se agregarán a la URL para lidiar con cambios incompatibles y destructivos. Al lanzar una nueva API, el cliente puede pasar a la nueva API libremente y no estará en problemas debido a que llama a una nueva API completamente diferente. Use un prefijo intuitivo "V" para indicar que el siguiente número es el número de versión, no se requiere un número de versión secundario y las versiones de API no deben lanzarse con frecuencia.
/edu/v1/users/edu/v1/roles
Use cadenas de consulta para parámetros opcionales y complejos
Para que la URL sea más pequeña y más concisa, establezca una URL básica para el recurso, y los parámetros opcionales y complejos están representados por cadenas de consulta.
/edu/v1/ussers? habilitado = 1 & rolyid = 1
Proporcionar información de paginación
No es una buena idea devolver todos los recursos en la base de datos a la vez, por lo que se requiere un mecanismo de paginación. Por lo general, los parámetros bien conocidos en la base de datos se utilizan para compensar y limitar
/edu/v1/ussers? habilitado = 1 & offset = 1 & limit = 15
Si el cliente no pasa estos parámetros, se debe usar el valor predeterminado, generalmente compensado = 0, límite = 10.
Use verbos para solicitudes de no recursos
A veces, las llamadas API no involucran recursos, en cuyo caso el servidor realiza una operación y devuelve el resultado al cliente.
/edu/v1/calc? P = 100
Considere recursos específicos y búsquedas de recursos cruzados
Es fácil proporcionar una búsqueda para un fin de estadía específico. Solo necesita utilizar la colección de recursos correspondiente y agregar la cadena de búsqueda a los parámetros de consulta.
/edu/v1/ussers? UserName = Li Qinghai
Si necesita proporcionar una búsqueda global de todos los recursos, debe usar otro método.
/edu/v1/search? Key = Li Qinghai
Resultados de la respuesta
Use la nomenclatura de camello pequeño como identificador de atributos
Por lo general, los clientes RESTFUL serán utilizados por clientes escritos en JavaScript. El cliente convierte la respuesta JSON a un objeto JavaScript y luego llama a sus propiedades. Por lo tanto, es mejor seguir la especificación común del código JavaScript.
Person.year_of_birth // no recomendado, violando el código JavaScript Especificación general Person.yearofbirth // No recomendado, constructor de JavaScript llamado Person.YearofBirth // Recomendado
Proporcionar información de paginación
Cuando se devuelven muchos resultados, se debe proporcionar información de paginación.
{"página": 0, "tamaño": 10, "total": 3465, "obj": []}Interfaz REST de desarrollo MVC de primavera
Anotaciones comunes
@RestController
@RestController es una anotación combinada de @ResponseBody y @Controller.
@RequestMapping
Esta anotación se puede aplicar a un método del controlador o a esta clase de controlador. Cuando el controlador agrega la anotación @RequestMapping a nivel de clase, esta anotación se aplica a todos los métodos del procesador del controlador. La anotación @RequestMapping en el método del procesador complementará la declaración de @RequestMapping a nivel de clase.
@PostMapping
La anotación de combinación es la abreviatura de @RequestMapping (método = requestmethod.post).
@Putmapping
La anotación de combinación es la abreviatura de @RequestMapping (método = requestmethod.put).
@Patchmapping
La anotación de combinación es la abreviatura de @RequestMapping (método = requestmethod.patch).
@DeletEmapping
La anotación de combinación es la abreviatura de @RequestMapping (método = requestmethod.delete).
@Getmapping
La anotación de combinación es la abreviatura de @RequestMapping (método = requestmethod.get).
@PathVariable
Obtenga los datos en la URL.
@RequestParam
Obtiene el valor del parámetro solicitado.
Interfaz de descanso y ejemplo de documentación de la API de Swagger
Para el uso de Swagger, consulte el uso de Swagger2 en el proyecto Spring Boot. El código en el cuerpo del método no es importante, lo importante es la firma del método y la asignación con verbos HTTP.
import java.util.date; import javax.persistence.entitynotFoundException; import org.springframework.beans.factory.annotation.aUtowired; import org.springframework.data.domain.page; import og.springframework.web.bind.annotation.getMapping; import org.springframework.web.bind.annotation.patchmapping; import org.springframework.web.bind.annotation.pathvariable; import org.springframework.web.bind.annotation.postmapping; import og.springframework.web.bind.annotation 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.service.userservice; import cn.com.infcn.jiansshu.exception.bizexception; import cn.com.infcn.jiansshu.exception.loginnameorpassworderRorException; import cn.com.infcn.jianshu.exception.reseurceexistsexception; import cn.com.infcn.jianshu.model.user; import; cn.com.infcn.jiansshu.util.jsonresult; import io.swagger.annotations.api; import io.swagger.annotations.apiparam;/** * Controlador de usuario del sistema * * @author li qinghai * */ @api (valor = "interfaz de usuario del sistema", etiquetas = "sistema sistema Administración ")@RestController@requestMapping ("/v3/edu/users ") clase pública UserController {@autewired private UserService UserService; /** * Add user, register * * @param loginName * Login account* @param userName * User name* @param password * Login password* @param roleId * User role* @return * @throws ResourceExistsException */ @ApiOperation(value = "Add user") @PostMapping("/") public JsonResult create( @ApiParam(name = "loginName", value = "Login cuenta ", requirir = true) @RequestParam (requirir = true) @RequestBody String LoginName, @apiparam (name =" username ", value =" username ", requerido = true) @requestparam (requerido = true) @requestbody string username, @apiparam (name =" contraseña ", valor =" log en contraseña ", requerido) @request lo requerido (requerido) contraseña, @apiparam (name = "rolyid", value = "Número de rol de usuario", requerido = true) @RequestParam (requerido = true) @RequestBody String rolyId) lanza ResourceExistSeXception {boolean exists = this.userservice.Exists (loginName); if (existe) {lanzar nueva recursosexistsexception (LoginName); } User user = Userservice.create (LoginName, Password, UserName, RoleId); return jsonResult.success (usuario); } /** * User login with login account and login password* * @param loginName * Login account* @param password * Login password* @throws EntityNotFoundException */ @ApiOperation(value = "Query user information based on user number") @GetMapping("/login") public JsonResult login( @ApiParam(name = "loginName", value = "Login account", required = true) @RequestParam (requerido = true) String LoginName, @Apiparam (name = "Passwase", valor = "Password de inicio de sesión", requerido = True) @RequestParam (requerido = True) String Password) lanza LoginNameorPassworderRorException {user User = this.UserService.login (loginName, contraseña); if (null == user) {lanzar nueva loginnameOrpasswOrderRorException (); } return jsonResult.success (usuario); }/** * Consulta información del usuario basada en el número de usuario * * @param ID * Número de usuario * @throws entityNotFoundException */@apioperation (valor = "Información de usuario de consulta basada en el número de usuario") @getmapping ("/{id}") public jSesult Read (@apiparam (nombre = "id", valor de usuario = "Número de usuario, primaria", requerido = verdadero) @verdadero) @Path) lanza EntityNotFoundException {user user = this.userservice.getone (id); return jsonResult.success (usuario); } /** * Account is cancelled, and the user's data is not deleted* * @param userId * User number* @return */ @ApiOperation(value = "Carded out of account") @PatchMapping("/{id}") public JsonResult cancel( @ApiParam(name = "id", value = "User number, primary key", required = true) @PathVariable(required = true) String id) throws EntityNotFoundException {this.userservice.cancel (id); return jsonResult.success (); }/** * Restablecer contraseña * * @param ID * Número de usuario * @param contraseña * nueva contraseña de inicio de sesión * @return */@apioperation (valor = "restablecer contraseña") @patchmapping ("/") public jsonResult updatePassword (@apiparam (name = "id", value = "número de usuario, clave primaria", requería = verdadero) @Requestparam (verdadero = verdadero). "Password", Value = "nueva contraseña de inicio de sesión", requerido = true) @RequestParam (requerido = verdadero) String Password) {this.userservice.updatePassword (id, contraseña); return jsonResult.success (); }/** * Consulta de combinación de múltiples acondicionamiento * * @param nombre de usuario * nombre de usuario * @param rolyid * rol de usuario * @param inicio * fecha de inicio * @param final * fin final * @param página * pagination, comenzando desde 0 * @param tamaño * número de filas por página, predeterminado 10 * @return * @throws bizexception */@apiOperation (valor = "query de información") @getmappi (")") ")") JSONRESULT QUERY (@APIPARAM (name = "username", value = "nombre de usuario, palabra clave de consulta", requerido = false) @RequestParam (requerido = false) String username, @apiparam (name = "rolyId", valor = "número de usuario", requerido = false) @requestparam (requerido = falso) string stryID, @apiparam (name = "start", value ",", requerido ", requerido, requerido, requerido, requerido, requerido) @RequestParam (requerido = falso) Fecha Inicio, @apiparam (name = "end", value = "Número de rol de usuario", requerido = false) @RequestParam (requerido = falso) Fecha final, @apiparam (name = "página", valor = "paginación, qué página, comenzando desde 1", defaultalue = "1", requerido = verdadero) @Requestparam (defaultValue = "1, se requiere desde 1", predeterminado). @Apiparam (name = "size", value = "número de filas por página, entero positivo", defaultValue = "10", requerido = true) @RequestParam (defaultValue = "10", requerido = true) int tize) lanza bizexception {página <serve> dataS = this.userservice.finddatas (username, rolid, start, fin, fin, página, tamaño); if (null == DataS || null == dataS.getContent () || dataS.getContent (). isEtimty ()) {tire nueva bizexception ("El usuario no existe"); } return jsonResult.success (datos); }}Representación de documentos de la interfaz Swagger2
Lo anterior es todo el contenido de este artículo. Espero que sea útil para el aprendizaje de todos y espero que todos apoyen más a Wulin.com.