Java开发中RestFul服务接口规范

REST介绍

representational State Transfer (REST) 是一种架构原则,其中将 web 服务视为资源,可以由其 URL 唯一标识。RESTful Web 服务的关键特点是明确使用 HTTP 方法来表示不同的操作的调用。

REST 的基本设计原则对典型 CRUD 操作使用 HTTP 协议方法:

POST - 创建资源

GET - 检索资源

PUT – 更新资源

DELETE - 删除资源

REST 服务的主要优势在于:

它们是跨平台 (Java、.net、PHP 等)高度可重用的,因为它们都依赖基本 HTTP 协议。

它们使用基本的 XML,而不是复杂的 SOAP XML,使用非常方便。

基于 REST 的 web 服务日益成为后端企业服务集成的首选方法。与基于 SOAP 的 web 服务相比,它的编程模型简单,而本机 XML(而不是 SOAP )的使用减少了序列化和反序列化过程的复杂性,并且不再需要其他作用相同的第三方库。

​​​​​​​编写目的

编写本文的目的是为了规范项目系统功能进行模块化、服务化,将用户的操作以服务的方式提供。系统与系统之间遵循服务规范,将系统与系统之间的交互转为定制化服务交互,以实现系统与系统之间的集成。

​​​​​​​编写原则

  1. 可寻址性(Addressability)REST 中的所有东西都基于资源 的概念。资源与 OOP 中的对象或其他名词不同,它是一种抽象,必须可以通过 URI 寻址或访问。
  2. 接口一致性(Interface uniformity)与 SOAP 或其他标准不同,REST 要求用来操纵资源的方法或动词不是任意的。这意味着 RESTful 服务的开发人员只能使用 HTTP 支持的方法,比如 GET、PUT、POST、DELETE 等等。因此不需要使用 WSDL 等服务描述语言。
  3. 无状态(Statelessness)为了增强可伸缩性,服务器端不存储客户机的状态信息。这使服务器不与特定的客户机相绑定,负载平衡变得简单多了。这还让服务器更容易监视、更可靠。
  4. 具象(Representational)客户机总是与资源的某种具象交互,绝不会直接与资源本身交互。同一资源还可以有多个具象。理论上说,持有资源的具象的任何客户机应该有操纵底层资源的足够信息。
  5. 连通性(Connectedness)任何基于 REST 的系统都应该预见到客户机需要访问相关的资源,应该在返回的资源具象中包含这些资源。例如,可以以超链接的形式包含特定 RESTful 服务的操作序列中的相关步骤,让客户机可以根据需要访问它们。基于 REST 的 Web 服务日益成为后端企业服务集成的

GET,DELETE,PUT和POST的典型用法

GET用法

​​​​​​​

安全且幂等

获取表示

变更时获取表示(缓存)

200(OK) - 表示已在响应中发出

204(无内容) - 资源有空表示

301(Moved Permanently) - 资源的URI已被更新

303(See Other) - 其他(如,负载均衡)

304(not modified)- 资源未更改(缓存)

400 (bad request)- 指代坏请求(如,参数错误)

404 (not found)- 资源不存在

406 (not acceptable)- 服务端不支持所需表示

500 (internal server error)- 通用错误响应

503 (Service Unavailable)- 服务端当前无法处理

POST用法

不安全且不幂等

使用服务端管理的(自动产生)的实例号创建资源

创建子资源

部分更新资源

如果没有被修改,则不过更新资源(乐观锁)

200(OK)- 如果现有资源已被更改

201(created)- 如果新资源被创建

202(accepted)- 已接受处理请求但尚未完成(异步处理)

301(Moved Permanently)- 资源的URI被更新

303(See Other)- 其他(如,负载均衡)

400(bad request)- 指代坏请求

404 (not found)- 资源不存在

406 (not acceptable)- 服务端不支持所需表示

409 (conflict)- 通用冲突

412 (Precondition Failed)- 前置条件失败(如执行条件更新时的冲突)

415 (unsupported media type)- 接受到的表示不受支持

500 (internal server error)- 通用错误响应

503 (Service Unavailable)- 服务当前无法处理请求

PUT用法

不安全但幂等

用客户端管理的实例号创建一个资源

通过替换的方式更新资源

如果未被修改,则更新资源(乐观锁)

200 (OK)- 如果已存在资源被更改

201 (created)- 如果新资源被创建

301(Moved Permanently)- 资源的URI已更改

303 (See Other)- 其他(如,负载均衡)

400 (bad request)- 指代坏请求

404 (not found)- 资源不存在

406 (not acceptable)- 服务端不支持所需表示

409 (conflict)- 通用冲突

412 (Precondition Failed)- 前置条件失败(如执行条件更新时的冲突)

415 (unsupported media type)- 接受到的表示不受支持

500 (internal server error)- 通用错误响应

503 (Service Unavailable)- 服务当前无法处理请求

DELETE用法

不安全但幂等

删除资源

200 (OK)- 资源已被删除

301 (Moved Permanently)- 资源的URI已更改

303 (See Other)- 其他,如负载均衡

400 (bad request)- 指代坏请求

404 (not found)- 资源不存在

409 (conflict)- 通用冲突

500 (internal server error)- 通用错误响应

503 (Service Unavailable)- 服务端当前无法处理请求

 

Java开发中RestFul用法举例

//@RestController 代替 @Controller,省略以后的 @ResponseBody
@RestController
@RequestMapping("/student")
public class StudentController {
    @Autowired
    private StudentService studentservice;
    /**
     * 显示所有
     * url:"http://localhost/student/findall"
     * 
     * @return
     */
    @RequestMapping(value = "/findall")
    public List<Student> findAllStudent() {
        return studentservice.findAllStudent();
    }

    /**
     * 查找 restful 风格 
     * url:"http://localhost/student/findone/1"
     * 
     * @param id
     * @return
     */

    // == @RequestMapping(value = "/findone/{id}", method = RequestMethod.GET)
    @GetMapping("/findone/{id}")
    public Student findStudentRestful(@PathVariable("id") Integer id) {
        return studentservice.findStudent(id);
    }

    /**
     * 删除 restful 风格
     * url:"http://localhost/student/deleteone/4"
     * 注意无法通过浏览器的链接来模拟检验,可以通过 jquery的 $.ajax方法,并type="delete"
     * 
     * @param id
     */
    // == @RequestMapping(value = "/deleteone/{id}", method = RequestMethod.DELETE)
    @DeleteMapping("/deleteone/{id}")
    public void deleteStudentRestful(@PathVariable("id") Integer id) {
        studentservice.deleteStudent(id);
    }


    /**
     * 增加 restful 风格
     * url:"http://localhost/student/addone"
     * 通过<form>表单模拟验证
     * 
     * @param student
     */
    // == @RequestMapping(value="/addone",method=RequestMethod.POST)
    @PostMapping("/addone")
    public void addStudentRestful(Student student) {
        studentservice.addStudent(student);
    }


    /**
     * 修改 restful 风格
     * url:"http://localhost/student/updateone"
     * 验证:可以通过 jquery的 $.ajax方法,并type="put",同时注意data形式——A=a&B=b&C=c
     * 
     * @param student
     */
    // == @RequestMapping(value="/addone",method=RequestMethod.PUT)
    @PutMapping("/updateone")
    public void updateStudentRestful(Student student) {
        studentservice.updateStudent(student);
    }
}

 

已标记关键词 清除标记
©️2020 CSDN 皮肤主题: 创作都市 设计师:CSDN官方博客 返回首页