spring boot开发接口api

在上一次教了大家怎么去搭建一个自己的后端模板之后，现在和大家分享讨论一下如何开发RestfulApi接口。
首先开发api之前要考虑到后端是需要写api文档的，这里可以提两个比较好的在线自动生成api文档的工具：swagger和showdoc。当然还有其他好的工具，大家可以去自己探索，但是希望在开发接口之前就确定好使用哪一种工具，使用之后就不要再去考虑其他的工具了，不然会耽误开发。在这里我个人比较喜欢showdoc生成的文档格式，清晰明了，但是用它生成的文档代码量比较大，swagger相对来说代码量比showdoc少一点，但是生成的文档没有showdoc那么好看。showdoc基本上不需要什么配置，swagger需要的配置比较麻烦。萝卜青菜各有所爱，看自己喜欢哪一个吧。

在这里我只讲开发接口api而已.

定义一个统一的响应模板

开发出来的接口返回的响应结果应该尽可能的规范统一，可以去看restful规范来开发自己的接口。一个比较好的响应规范应该要有状态码（code）、信息描述（msg）、数据（data）。

下面我展示一下自己的开发模板：

package org.csu.backdemo.utils;import lombok.Data;import java.io.Serializable;//统一响应数据格式
@Data
public class Result implements Serializable {private int code;//200表示正常，非200表示异常private String msg;//结果返回的信息private Object data;//结果返回的数据//请求成功的响应public static Result success(Object data){return success(200,"请求成功",data);}//自定义成功相应的信息内容public static Result success(int code,String msg,Object data){Result result=new Result();result.setCode(code);result.setMsg(msg);result.setData(data);return result;}//请求失败public static Result fail(int code,String msg){return fail(code,msg,null);}//自定义失败相应的信息内容public static Result fail(int code,String msg,Object data){Result result=new Result();result.setCode(code);result.setMsg(msg);result.setData(data);return result;}

这里提醒一下，使用@Data注解需要使用到Lombok，大家可以自行去了解。

开发接口controller

1.接口类的编写

要知道写一个controller的一个方法（带有@***Mapping）就是一个api接口，可以自己去创建一个controller类，对应的某个模块的接口。

注意编写这个controller这个类，需要在类的前面加上注解@RestController，或者在每个方法前面加上@ResponseBody。我建议使用@RestController。

2.请求方式

请求方式的注解有：

@RequestMapping //一般用于全局设置，对应一个模块/** rest请求方式主要有以下几种：* get：主要用来获取资源，对应的注解：@GetMapping* post：用来建立新的资源，对应的注解：@PostMapping* put：用来更新资源，对应的注解：@PutMapping* delete:用来删除资源，对应的注解：@DeleteMapping* */

3.参数的传递

第一类：请求路径参数
1、@PathVariable
获取路径参数。即url/{id}这种形式。

2、@RequestParam
获取查询参数。即url?name=这种形式

注意：@GetMapping是没有请求体的，也就是说它大部分都是采用上面的两种方式

@GetMapping("/demo/{id}")
public void demo(@PathVariable(name = "id") String id, @RequestParam(name = "name") String name) {System.out.println("id="+id);
System.out.println("name="+name);
}

那么当get方法的参数过于复杂的时候怎么处理？

public List<String> getName(@RequestParam String queryDtoStr) {QueryDto queryDto = new Gson().fromJson(queryDtoStr, QueryDto .class);// ....return new ArrayList<>();
}

前端的请求就变成了：

http://localhost:8080/app/names?queryDtoStr={"query1":12,"query2":2,"query3":2}

第二类：Body参数

@RequestBody

这个就是请求体参数，前端一般是用json串来传递给后端的。后端可以采用一个实体bean来接受参数。

public void doInsert(@RequestBody ApiUser apiUser) {AfaUser user = BeanUtils.copyBean(apiUser, AfaUser.class);userService.addAfaUser(user);}

也可以是这样的

@PostMapping(path = "/demo1")
public void demo1(@RequestBody Map<String, String> person) {System.out.println(person.get("name"));
}

这些就是基本上传递参数的用法了。可能还会有@RequestHead这些注解等等，有些是比较少用的，我就不说了。

状态码

状态码必须精确

客户端的每一次请求，服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。

HTTP 状态码就是一个三位数，分成五个类别。

# 1xx：相关信息
# 2xx：操作成功
# 3xx：重定向
# 4xx：客户端错误
# 5xx：服务器错误

这五大类总共包含100多种状态码，覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的（或者约定的）解释，客户端只需查看状态码，就可以判断出发生了什么情况，所以服务器应该返回尽可能精确的状态码。

API 不需要1xx状态码，下面介绍其他四类状态码的精确含义。

2XX状态码

200状态码表示操作成功，但是不同的方法可以返回更精确的状态码。

# GET: 200 OK
# POST: 201 Created
# PUT: 200 OK
# PATCH: 200 OK
# DELETE: 204 No Content

上面代码中，POST返回201状态码，表示生成了新的资源；DELETE返回204状态码，表示资源已经不存在。

此外，202 Accepted状态码表示服务器已经收到请求，但还未进行处理，会在未来再处理，通常用于异步操作。下面是一个例子。

HTTP/1.1 202 Accepted
{  "task": {    "href": "/api/company/job-management/jobs/2130040",    "id": "2130040"  }}

3xx 状态码

API 用不到301状态码（永久重定向）和302状态码（暂时重定向，307也是这个含义），因为它们可以由应用级别返回，浏览器会直接跳转，API 级别可以不考虑这两种情况。

API 用到的3xx状态码，主要是303 See Other，表示参考另一个 URL。它与302和307的含义一样，也是"暂时重定向"，区别在于302和307用于GET请求，而303用于POST、PUT和DELETE请求。收到303以后，浏览器不会自动跳转，而会让用户自己决定下一步怎么办。下面是一个例子。

HTTP/1.1 303 See OtherLocation: /api/orders/12345

4xx 状态码

4xx状态码表示客户端错误，主要有下面几种。

400 Bad Request：服务器不理解客户端的请求，未做任何处理。

401 Unauthorized：用户未提供身份验证凭据，或者没有通过身份验证。

403 Forbidden：用户通过了身份验证，但是不具有访问资源所需的权限。

404 Not Found：所请求的资源不存在，或不可用。

405 Method Not Allowed：用户已经通过身份验证，但是所用的 HTTP 方法不在他的权限之内。

410 Gone：所请求的资源已从这个地址转移，不再可用。

415 Unsupported Media Type：客户端要求的返回格式不支持。比如，API 只能返回 JSON 格式，但是客户端要求返回 XML 格式。

422 Unprocessable Entity ：客户端上传的附件无法处理，导致请求失败。

429 Too Many Requests：客户端的请求次数超过限额。

5xx 状态码

5xx状态码表示服务端错误。一般来说，API 不会向用户透露服务器的详细信息，所以只要两个状态码就够了。

500 Internal Server Error：客户端请求有效，服务器处理时发生了意外。

503 Service Unavailable：服务器无法处理请求，一般用于网站维护状态。