spring----RESTful API
RESTful API
REST 是一种很笼统的概念,它代表一种架构风格。
加上版本号
http://localhost:8080/api/v1/list
http://localhost:8080/api/v2/list 升级后的处理逻辑
如果发现v2处理异常,可以不需要做任何处理,直接请求v1就可以了
资源路径
URI 不能包含动词,只能是名词。注意的是,形容词也是可以使用的,但是尽量少用。一般来说,不论资源是单个还是多个,API 的名词要以复数进行命名。此外,命名名词的时候,要使用小写、数字及下划线来区分多个单词。这样的设计是为了与 json 对象及属性的命名方案保持一致
【GET】 /v1/tags/{tag_id}
有的时候,当一个资源变化难以使用标准的 RESTful API 来命名,可以考虑使用一些特殊的 actions 命名。
【PUT】 /v1/users/{user_id}/password/actions/modify // 密码修改
请求方式
可以通过 GET、 POST、 PUT、 PATCH、 DELETE 等方式对服务端的资源进行操作。其中:
- GET:用于查询资源
- POST:用于创建资源
- PUT:用于更新服务端的资源的全部信息
- PATCH:用于更新服务端的资源的部分信息
- DELETE:用于删除服务端的资源。
响应参数
如果是单条数据,则返回一个对象的 JSON 字符串。
{ "id" : "01234567-89ab-cdef-0123-456789abcdef", "name" : "example", "created_time": 1496676420000, "updated_time": 1496676420000, ... }
如果是列表数据,则返回一个封装的结构体
{ "count":100, "items":[ { "id" : "01234567-89ab-cdef-0123-456789abcdef", "name" : "example", "created_time": 1496676420000, "updated_time": 1496676420000, ... }, ... ] }
Rest 风格 URL
左边是传统的api,右边是Rest风格的api /get?id=1 ---->/order/1 get /add ---->/order post /delete?id=1 --->/order/1 delete /update?id=1 --->/order/2 put
SpringMVC处理Put或Delete
1、首先在web.xml中配置过滤器
<filter> <filter-name>HiddenHttpMethodFilter</filter-name> <filter-class>org.springframework.web.filter.HiddenHttpMethodFilter</filter-class> </filter> <filter-mapping> <filter-name>HiddenHttpMethodFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping>
2、form表单配置隐藏域,注意表单中method必须为post,隐藏域中name和value属性如下所示
<form action="/delete" method="post"> <input name="_method" value="DELETE" type="hidden"> <input type="submit" value="提交"> </form>
3、处理请求
需要加上@ResponseBody注解,否则报错,加上该注解后,就不能返回视图了
@RequestMapping(value = "/delete",method = RequestMethod.DELETE) @ResponseBody public String delete() throws IOException { return "delete"; }
SpringBoot处理Put或Delete
1、配置 HiddenHttpMethodFilter(不需要了,SpringBoot已经配置好了)
2、form表单配置隐藏域
<form action="/delete" method="post"> <input name="_method" value="DELETE" type="hidden"> <input type="submit" value="提交"> </form>
接口开发规范
Api请求及响应规范
- 1、get 请求时,采用key/value格式请求,SpringMVC可采用基本类型的变量接收,也可以采用对象接收。
- 2、Post请求时,可以提交form表单数据(application/x-www-form-urlencoded)和Json数据(Content-Type=application/json),文件等多部件类型(multipart/form-data)三种数据格式,SpringMVC接收Json数据使用@RequestBody注解解析请求的json数据。
- 4、响应结果统一信息为:是否成功、操作代码、提示信息及自定义数据。
- 5、响应结果统一格式为json。
@Data @ToString public class QueryResponseResult extends ResponseResult { QueryResult queryResult; public QueryResponseResult(ResultCode resultCode, QueryResult queryResult) { super(resultCode); this.queryResult = queryResult; } }
@Data @ToString @NoArgsConstructor public class ResponseResult implements Response { //操作是否成功 boolean success = SUCCESS; //操作代码 int code = SUCCESS_CODE; //提示信息 String message; public ResponseResult(ResultCode resultCode){ this.success = resultCode.success(); this.code = resultCode.code(); this.message = resultCode.message(); } public static ResponseResult SUCCESS(){ return new ResponseResult(CommonCode.SUCCESS); } public static ResponseResult FAIL(){ return new ResponseResult(CommonCode.FAIL); } }
public interface Response { public static final boolean SUCCESS = true; public static final int SUCCESS_CODE = 10000; }
Swagger
Swagger常用注解(给前端测试用户提示信息的)
- @Api:修饰整个类,描述Controller的作用
- @ApiOperation:描述一个类的一个方法,或者说一个接口
- @ApiParam:单个参数描述
- @ApiModel:用对象来接收参数
- @ApiModelProperty:用对象接收参数时,描述对象的一个字段 @ApiResponse:HTTP响应其中1个描述 @ApiResponses:HTTP响应整体描述 @ApiIgnore:使用该注解忽略这个API @ApiError :发生错误返回的信息 @ApiImplicitParam:一个请求参数
- @ApiImplicitParams:多个请求参数
解释
@Api:用在请求的类上,表示对类的说明 tags="说明该类的作用,可以在UI界面上看到的注解" value="该参数没什么意义,在UI界面上也看到,所以不需要配置" @ApiOperation:用在请求的方法上,说明方法的用途、作用 value="说明方法的用途、作用" notes="方法的备注说明" @ApiImplicitParams:用在请求的方法上,表示一组参数说明 @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面 name:参数名 value:参数的汉字说明、解释 required:参数是否必须传 paramType:参数放在哪个地方 · header --> 请求参数的获取:@RequestHeader · query --> 请求参数的获取:@RequestParam · path(用于restful接口)--> 请求参数的获取:@PathVariable · body(不常用) · form(不常用) dataType:参数类型,默认String,其它值dataType="Integer" defaultValue:参数的默认值 @ApiResponses:用在请求的方法上,表示一组响应 @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息 code:数字,例如400 message:信息,例如"请求参数没填好" response:抛出异常的类 @ApiModel:用于响应类上,表示一个返回响应数据的信息 (这种一般用在post创建的时候,使用@RequestBody这样的场景, 请求参数无法使用@ApiImplicitParam注解进行描述的时候) @ApiModelProperty:用在属性上,描述响应类的属性
spring boot配置使用
@Configuration @EnableSwagger2 //注解表示会去com.xuecheng包下找到所有添加了@RestController注解的类,为这个类中的每一个方法生成接口文档 public class Swagger2Configuration { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.xuecheng")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("学成网api文档") .description("学成网api文档") // .termsOfServiceUrl("/") .version("1.0") .build(); } }
给接口文档添加注释信息
@Api(value="cms页面管理接口",description = "cms页面管理接口,提供页面的增、删、改、查") public interface CmsPageControllerApi { //页面查询 @ApiOperation("分页查询页面列表") @ApiImplicitParams({@ApiImplicitParam(name="page",value = "页码",required=true,paramType="path",dataType="int"), @ApiImplicitParam(name="size",value = "每页记录数",required=true,paramType="path",dataType="int")}) public QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest); }
测试:启动spring boot,访问:http://localhost:31001/swagger-ui.html,效果如图
RESTful API