SpringBoot Getting Started Practice (4) — Лучший дизайн RESTful API

Spring Boot

мой блог:Ланьлин Сяосяошэн, добро пожаловать в блог!

 Предыдущая главаПрактика входа в SpringBoot (3) — инженерная структура и общие аннотацииСреди них мы представили структуру проекта SpringBoot и некоторые часто используемые аннотации. В этой главе кратко рассказывается о дизайне API.

 В Интернете есть много вводных статей о разработке API.Содержание этой главы кратко знакомит с тем, как лучше проектировать API, исходя из моего собственного практического опыта.

Каковы ключевые требования API

1 Любой клиент может звонить, и для согласования клиента и сервера требуется стандарт, который должен быть простым

2 API не зависит от клиента, развитие API, существующий клиент может продолжать работать без изменений.

RESTful URLS

REST API разработан вокруг этого ресурса, который имеет уникальный идентификатор и использует JSON.

Определение операций над ресурсами с использованием HTTP

  1. GET Проверить, чтобы получить ресурс
  2. POST создает ресурс, конечно, POST также можно использовать для запуска действий, которые на самом деле не создают ресурс.
  3. PUT создать или обновить
  4. УДАЛИТЬ удалить

SpringBoot и RESTful

  В SpringBoot предусмотрено множество аннотаций, и с помощью этих аннотаций легко реализовать RESTful API.

@RequestMapping:

 Аннотация имеет 6 параметров:

  • значение/путь : имя пути
  • params : параметры запроса
  • метод: тип метода GET, POST, PUT, DELETE и т. д.
  • заголовки: запрос должен содержать определенные указанные значения заголовков, чтобы этот метод мог обработать запрос.
  • потребляет: (Content-Type), например, application/json, text/html;

Например, запрос представляет запрос GET:

@RequestMapping(path = "/list",method = RequestMethod.GET, consumes ="application/json")
public HttpResponse list() { 
    List<User> user = new ArrayList<>(userMap.values());   
    return HttpResponse.ok().setData(user);
}

@PostMapping

  Эквивалент @RequestMapping (путь = "/**", метод = RequestMethod.POST)

@GetMapping

  Эквивалентно @RequestMapping(путь = "/**", метод = RequestMethod.GET)

@DeleteMapping

  Эквивалент @RequestMapping(path = "/**", method = RequestMethod.DELETE)

@PutMapping

  Эквивалент @RequestMapping(путь = "/**", метод = RequestMethod.PUT)

особый дизайн

 Определение URL-адреса отличается в каждой компании, вот краткое описание моего собственного фактического опыта, определение пути URL-адреса:

1 URL легко понять

2 API имеют контроль версий, контроль версий может быстро повторяться и избегать недействительных запросов на доступ к обновленным точкам доступа

http://www.example.com/api/v{версия}/имя_модуля/имя_действия

Получить одного пользователя

GET /api/v1/user/get/1

или

GET /api/v1/user/1

Разбиение на страницы или полный запрос, входной параметр — JSON

POST /api/v1/user/list

Это дополнение и обновление, как правило, API, конечно, PUT также может быть использован

POST /api/v1/user/save

удалить пользовательский ресурс

DELETE /api/v1/user/delete/12

или

DELETE /api/v1/user/12

public class User {  
    private Long id; 
    private String userName; 
    private Long age;
    
    ...
        
}

Настройте унифицированные результаты возврата

package com.miroservice.chapter2.common;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.io.Serializable;
import java.util.*;


@JsonInclude(JsonInclude.Include.NON_NULL)
public class HttpResponse implements Serializable { 
    
    private long code;  
    private String message; 
    private Long total;  
    private Object data;  
    private List<Object> table;  
    private String requestid;  
    public static final long CODE_SUCCESS = 200;  
    public static final long CODE_ERROR = 500;  
    public static final long CODE_VALIDATE_FAILED = 404;  
    public static final long CODE_UNAUTHORIZED = 401;  
    public static final long CODE_FORBIDDEN = 403;    
    public HttpResponse() {    
        this(200, (String) null);    } 
    public HttpResponse(long code, String message) {    
        this.code = CODE_SUCCESS;     
        this.code = code;      
        this.message = message;      
        this.requestid = UUID.randomUUID().toString().replaceAll("-", "");  
    }   
    public static HttpResponse error(String message) {   
        return new HttpResponse(500, message);  
    }  
    public HttpResponse setData(Object data) {       
        this.data = data;    
        return this;  
    }  
    public HttpResponse data(Object data) {  
        return this.setData(data);  
    }
    public HttpResponse addListItem(Object item) {   
        if (this.table == null) {       
            this.table = new ArrayList();     
        }     
        this.table.add(item);       
        
        return this;  
    }  
    public HttpResponse setTotal(Long total) {    
        this.total = total;    
        return this;   
    }    
    public HttpResponse setTotal(Integer total) {    
        this.total = (long) total;      
        return this; 
    }   
    public static HttpResponse ok() {  
        return new HttpResponse();  
    }  
    public HttpResponse set(String field, String value) {  
        if (this.data == null || !(this.data instanceof Map)) {    
            this.data = new HashMap();    
        }      
        ((Map) this.data).put(field, value); 
        return this;
    }   
    public long getCode() {   
        return this.code;   
    }   
    public HttpResponse setCode(long code) {    
        this.code = code;      
        return this; 
    }    public String getMessage() {       
        return this.message;  
    }   
    public HttpResponse setMessage(String message) {     
        this.message = message;       
        return this;   
                                               
    }   
    public Long getTotal() {     
        return this.total == null && this.table != null ?     Long.valueOf(String.valueOf(this.table.size())) : this.total;   
    }   
    public Object getData() {  
        return this.data;   
                                 }  
    public List<Object> getTable() {      
        return this.table; 
    }  
    public HttpResponse setTable(List table) {    
        this.table = table;   
        return this;  
    }   
    public HttpResponse table(List table) {    
        return this.setTable(table); 
    }  
    public String getRequestid() {     
        return this.requestid; 
    }  
    public HttpResponse setRequestid(String requestid) {     
        this.requestid = requestid;    
        return this;    }
}

 Слой контроллера

/** 
* 1 api 的设计 一眼明了
* 2 有版本
* 3 控制层统一返回自定义的结果 
*/
@RestController
@RequestMapping("/api/v1/user")
public class UserController { 
    static Map<Long, User> userMap = new HashMap<Long, User>();   
    /**   
    * 列表请求 
    * @return 
    */   
   @RequestMapping(method = RequestMethod.GET, consumes = "application/json")                @GetMapping(consumes = "application/json")    
    public HttpResponse list() {     
        List<User> user = new ArrayList<>(userMap.values());     
        return HttpResponse.ok().setData(user);  
    }  
    /**   
    * 保存  
    * @param user   
    * @return  
    */  
    @PostMapping("/save")   
    public HttpResponse save(@RequestBody User user) {      
        userMap.put(user.getId(), user);      
        return HttpResponse.ok();    }  
    /**     
    * 获取单个用户  
    * @param id   
    * @return   
    */  
    @GetMapping("/get/{id}") 
    public HttpResponse get(@PathVariable Long id) {   
        final User user = userMap.get(id);    
        return HttpResponse.ok().setData(user);    } 
    /**   
    * 删除  
    * @param id   
    * @return  
    */  
    @DeleteMapping("/delete/{id}")   
    public HttpResponse delete(@PathVariable Long id) {  
        userMap.remove(id);     
        return HttpResponse.ok(); 
    }
    
}

 Выше показано, как поделиться этой проблемой, вы также можете следить за этим блогом #Вводная серия упражнений по Spring Boot!#

Ссылаться на: #Практика Microsoft API#     #Spring REST DOC#

Эта статья опубликована в блогеOpenWriteвыпуск!

Категории