织梦模板更新网站,长沙网页设计公司,佛山网站建设网站制作公司,apple官网登录入口前言 RESTful 是 Representational State Transfer 的缩写#xff0c;是一种软件架构风格#xff0c;用于在网络上构建和整合应用程序。它基于 HTTP 协议#xff0c;并定义了一组约束和规范#xff0c;用于规范客户端和服务器之间的通信。
RESTful API 是遵循 REST 架构规…前言 RESTful 是 Representational State Transfer 的缩写是一种软件架构风格用于在网络上构建和整合应用程序。它基于 HTTP 协议并定义了一组约束和规范用于规范客户端和服务器之间的通信。
RESTful API 是遵循 REST 架构规范的 API它允许客户端以标准化的方式与服务器进行交互。RESTful API 通常用于构建 Web 服务并已被广泛应用于各种领域包括电子商务、社交媒体、物联网等。
Rest API设计风格原则
1.使用名词而不是动词
不要使用 如: /getAllUsers get /users get /users/002 /createNewUser post /users /deleteAllUser delete /users/001
2.Get方法和查询参数不应该涉及状态改变
使用PUT, POST 和DELETE 方法 而不是 GET 方法来改变状态不要使用GET 进行状态改变。
3.使用复数名词
不要混淆名词单数和复数为了保持简单只对所有资源使用复数。 如: /cars 而不是 /car /users 而不是 /user /products 而不是 /product /settings 而不是 /setting /orders 而不是 /order
4. 使用子资源表达关系
如果一个资源与另外一个资源有关系使用子资源 如: GET /cars/711/drivers/ 返回 car 711的所有司机 GET /cars/711/drivers/4 返回 car 711的4号司机 GET /users/11/pets 返回 user 11的所有宠物 GET /users/11/pets/2 返回 user 11的2号宠物
5.使用Http头声明序列化格式
在客户端和服务端双方都要知道通讯的格式格式在HTTP-Header中指定 如: Content-Type 定义请求格式 Accept 定义系列可接受的响应格式
6.为集合提供过滤 排序 选择和分页等功能 Filtering过滤:使用唯一的查询参数进行 GET /cars?colorred 返回红色的cars GET /cars?seats2 返回小于两座位的cars集合 Sorting排序:允许针对多个字段排序 GET /cars?sort-manufactorer,model 这是返回根据生产者降序和模型升序排列的car集合 Field selection 移动端能够显示其中一些字段它们其实不需要一个资源的所有字段给API消费者一个选择字段的能力这会降低网络流量提高API可用性。 GET /cars?fieldsmanufacturer,model,id,color Paging分页 使用 limit 和offset.实现分页缺省limit20 和offset0 GET /cars?offset10limit5 为了将总数发给客户端使用订制的HTTP头 X-Total-Count. 链接到下一页或上一页可以在HTTP头的link规定遵循Link规定: Link: https://blog.mwaysolutions.com/sample/api/v1/cars?offset15limit5; rel“next”,https://blog.mwaysolutions.com/sample/api/v1/cars?offset50limit3; rel“last”,https://blog.mwaysolutions.com/sample/api/v1/cars?offset0limit5; rel“first”,https://blog.mwaysolutions.com/sample/api/v1/cars?offset5limit5; rel“prev”,
7.版本化你的API 支付宝 v1 v2 v3
使得API版本变得强制性不要发布无版本的API使用简单数字避免小数点如2.5. 一般在Url后面使用?v /blog/api/v1
8. 使用Http状态码处理错误
如果你的API没有错误处理是很难的只是返回500和出错堆栈不一定有用Http状态码提供70个出错我们只要使用10个左右 200 – OK – 一切正常 201 – OK – 新的资源已经成功创建 204 – OK – 资源已经成功删除 304 – Not Modified – 客户端使用缓存数据 400 – Bad Request – 请求无效需要附加细节解释如 “JSON无效” 401 – Unauthorized – 请求需要用户验证 403 – Forbidden – 服务器已经理解了请求但是拒绝服务或这种请求的访问是不允许的。 404 – Not found – 没有发现该资源 422 – Unprocessable Entity – 只有服务器不能处理实体时使用比如图像不能被格式化或者重要字段丢失。 500 – Internal Server Error – API开发者应该避免这种错误。 使用详细的错误包装错误 状态码 数据 header头信息 { “errors”: [ { “userMessage”: “Sorry, the requested resource does not exist”, “internalMessage”: “No car found in the database”, “code”: 34, “more info”: “http://dev.mwaysolutions.com/blog/api/v1/errors/12345” } ] }
Rest API案例
没有使用RestFul的规范之前的设计
Controller
RequestMapping(user)
public class DemoController {private static final Logger log LoggerFactory.getLogger(DemoController.class);//查询一个RequestMapping(findUserById)public String findUserById(Integer id){log.info(查询用户id为:{},id);//存储到作用域return showOne;}//查询所有RequestMapping(findAll)public String findAll(){log.info(查询所有);ListUser userList new ArrayListUser();userList.add(new User(21,xiaochen,2300,new Date()));//存储到作用域return showAll;}//保存RequestMapping(saveUser)public String save(User user){log.info(user: {},user);return redirect:/user/findAll;}//修改RequestMapping(updateUser)public String update(User user){log.info(user: {},user);return redirect:/user/findAll;}RequestMapping(deleteUser)public String delete(User user){log.info(user: {},user);return redirect:/user/findAll;}}这里我们就完全没有按照我们前面所说的RestFul的架构去规范我们的API下面我们将采用RestFul的设计去规范。
使用了RestFul的设计
RestController
RequestMapping(/v1/users) //符合使用复数名词
public class UserController {private static final Logger log LoggerFactory.getLogger(UserController.class);// ResponeEntity: springmvc 封装一个专用于restful 响应类 这个类在响应时可以提供响应的状态码,同时还可以自定义响应头信息// HttpStatus: springmvc 封住一个枚举类型类 这个类中都是网络中状态码/*** 查询某个用户详细* param id* return*///RequestMapping(value /{id},method RequestMethod.GET)GetMapping(/{id}) //RequestMapping:子类注解 使用GETMapping代表只能使用GET方式访问到当前请求//注解: PathVariable:代表在路径中获取请求参数//ResponseBody //将控制器方法返回值转为jsonpublic ResponseEntityUser user(PathVariable(id) Integer id){log.info(本次id: {},id);User user null;try {user new User(id, 小陈, 2300.23, new Date());} catch (Exception e) {e.printStackTrace();return new ResponseEntityUser(user,HttpStatus.INTERNAL_SERVER_ERROR);}return new ResponseEntity(user,HttpStatus.OK);}/*** 用户列表* return*/GetMapping//ResponseBodypublic ResponseEntityListUser users(){ArrayListUser users new ArrayList();users.add(new User(21,小王,2300.23,new Date()));users.add(new User(24,小金豆,3400.23,new Date()));return new ResponseEntity(users,HttpStatus.OK);}/*** 添加用户*/PostMapping//ResponseBody //ResponseBody 将方法返回值转为json格式数据 并响应请求 RequestBody: 接收请求json格式数据 将json格式数据转为对象public ResponseEntityVoid save(RequestBody User user){log.info(name:{} salary:{} bir:{},user.getName(),user.getSalary(),user.getBir());//调用业务方法return new ResponseEntity(HttpStatus.NO_CONTENT);//没有内容}/*** 更新用户* param user*/PutMapping(/{id})//ResponseBodypublic ResponseEntityVoid update(PathVariable(id) Integer id,RequestBody User user){log.info(id:{} ,id);log.info(name:{} salary:{} bir:{},user.getName(),user.getSalary(),user.getBir());//调用业务方法return new ResponseEntity(HttpStatus.NO_CONTENT);//没有内容}/*** 删除用户信息* param id*/DeleteMapping(/{id})//ResponseBodypublic ResponseEntityVoid delete(PathVariable(id) Integer id){log.info(本次id: {},id);return new ResponseEntity(HttpStatus.NO_CONTENT);//没有内容}/*** 获取这个人所有宠物*/GetMapping(/{id}/pets)public ResponseEntityListPet pets(PathVariable(id) Integer id){log.info(查询那个人id: {},id);ListPet pets Arrays.asList(new Pet(21, 小红帽, 23), new Pet(22, 小猪, 22));return new ResponseEntity(pets, HttpStatus.OK);}/*** 获取这个人某个宠物*/GetMapping(/{id}/pets/{pid})public ResponseEntityPet pet(PathVariable(id) Integer id,PathVariable(pid) Integer petId){log.info(查询那个人id: {},id);Pet pet new Pet(21, 小红帽, 23);return new ResponseEntity(pet, HttpStatus.OK);}}
上述方法就
代码示例的设计特点总结 使用了 RestController 注解 RestController 注解表示该类是一个 RESTful 控制器它可以将方法返回值自动转换为 JSON 格式数据并响应请求。 使用了标准的 HTTP 方法 GetMapping用于处理 GET 请求 PostMapping用于处理 POST 请求 PutMapping用于处理 PUT 请求 DeleteMapping用于处理 DELETE 请求 使用了 PathVariable 注解 PathVariable 注解用于获取路径中的参数。 使用了 RequestBody 注解 RequestBody 注解用于接收请求中的 JSON 格式数据并将其转换为对象。 使用了 ResponseEntity 类 ResponseEntity 类用于封装响应数据包括响应状态码和响应体。
