SpringBoot入门实践(四)-RESTful API 最佳设计

时间 2020-02-01

标签 springboot 入门实践 restful api 最佳设计栏目 Spring 繁體版

原文原文链接

个人博客：兰陵笑笑生,欢迎浏览博客！html

上一章 SpringBoot入门实践(三)-工程结构与经常使用注解当中,咱们介绍了SpringBoot的项目的工程结构和一些经常使用的注解。本章简单的讲一讲API的设计。html5

网上有很是多的关于API设计的介绍，本章内容从本身的实际经验简单介绍如何更好的设计API。java

API的有什么关键的要求

1 任何客户端都可以调用，须要一个标准，使得客户端和服务端达成一致,必须简单spring

2 api独立于客户端，api的发展，现有的客户端能够继续运行，不须要修改。json

RESTful URLS

REST API 是围绕这资源设计的,资源有一个惟一的标识符，而且使用JSONapi

使用HTTP 定义资源的操做app

GET 检所获取资源
POST 建立资源，固然POST也能够用来触发实际上不建立资源的操做
PUT 建立或者更新
DELETE 移除

SpringBoot与RESTful

在springBoot当中提供了不少的注解，使用这些注解就很容易的实现RESTful的apidom

@RequestMapping:

该注解有6个参数：this

value/path ：路径名称
params ：请求的参数
method ：方法类型 GET、POST、PUT、DELETE 等
headers： request 中必须包含某些指定的 header 值，才能让该方法处理请求。
consumes : （Content-Type），例如application/json，text/html；

例如请求表示一個GET请求：url

@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(path = "/**",method = RequestMethod.POST)

@GetMapping

等价于@RequestMapping(path = "/**",method = RequestMethod.GET)

@DeleteMapping

等价于@RequestMapping(path = "/**",method = RequestMethod.DELETE)

@PutMapping

等价于@RequestMapping(path = "/**",method = RequestMethod.PUT)

具体的设计

URL的定义在每一个公司中都不同，这里简单给出一些我本身的实际经验，url路径定义：

1 url理解简单

2 api有版本控制，版本控制能够快速迭代并避免无效的请求访问已更新的接入点

http://www.example.com/api/v{version}/模块名称/操做名称

获取单个用户

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;    }
}

Controller层

/** 
* 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入门实践系列!#

参考： #微软的API实践# #Spring REST DOC#

本文由博客一文多发平台 OpenWrite 发布！

个人博客地址兰陵笑笑生,欢迎浏览！