REST设计指南

前言

REST，即Representational State Transfer 表述性状态转移，REST是一种架构风格，其核心是面向资源，简化设计，降低开发的复杂性，提高系统的可伸缩性。
REST本身并没有创造新的技术、组件或服务，而隐藏在RESTful背后的理念就是使用Web的现有特征和能力， 更好地使用现有Web标准中的一些准则和约束。虽然REST本身受Web技术的影响很深， 但是理论上REST架构风格并不是绑定在HTTP上，只不过目前HTTP是唯一与REST相关的实例。 

以下的设计指南只是根据自己的理解以及参考众多的文章归纳出来的

 

正文

REST是面向资源的，所以我们设计的时候应该是面向于资源，而如何对资源的操作则是体现在HTTP上，因此设计上仅使用名词，以GET/POST/PUT/PATCH/DELETE作为操作表述

GET：表示资源的获取（查询）

POST：表资源的创建

PUT：表资源的修改（有文中也这么说，PUT也可以用来表示创建，是在于ID由用户自定义的场景），而这里我们将其设计为资源的全修改

PATCH：表资源的修改（资源的部分修改）

关于PUT和PATCH进一步思考：PUT表示全部资源的修改，客户端提供改变后的完整资源，那么对于客户端没有提供的字段将会进行清空(置为NULL,EMPTY STRING或默认值)，而PATCH请求对于客户端没有提供的字段不做任何修改。

DELETE：表资源的删除

那么对于路径上的设计均是名词，资源不应该是动词的

先上格式

http(s): //server.com /app-name /{version} /{domain} /{rest-convention}

这个格式是我目前觉得最合适的一个格式了

{version}代表api的版本信息。
{domain}是一个你可以用来定义任何技术的区域(例如：安全-允许指定的用户可以访问这个区域)或者业务上的原因(例如：同样的功能在同一个前缀之下。)
{rest-convention} 代表这个域(domain)下，约定的rest接口集合。
————————————————
版权声明：本文为CSDN博主「qq_35075909」的原创文章，遵循CC 4.0 BY-SA版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/qq_35075909/article/details/91522242

 

关于version我还是倾向于在URI上展示出来的，当然也可以将版本信息放在请求头当中的，但是我觉得从编码的直观性上来看，还是直接写在URI上,自己看的时候也舒服一点，曾经在做项目的时候，因为版本一已经发布了，版本二功能上产生了大量变化，我的路径直接写成了/xxxx2，这样还不如/v2/xxxx来得美观

 

上一个粗糙的例子,简单展示一下以银行卡为核心资源的一个业务

@RestController
@RequestMapping("/v1/cards")
public class CardController {


    //POST http://localhost:8080/v1/cards
    @PostMapping
    public String createCard(@RequestParam("info") String info){
        String result = "创建了一张银行卡" + info;
        System.out.println(result);
        return result;
    }

    //PUT http://localhost:8080/v1/cards/1
    @PutMapping("/{id}")
    public String updateCard(@PathVariable("id") Long id, @RequestParam("info") String info){
        String result = id + "修改了银行卡信息" + info;
        System.out.println(result);
        return result;
    }

    //GET http://localhost:8080/v1/cards/1
    @GetMapping("/{id}")
    public String getCard(@PathVariable("id") Long id){
        String result = id + "获取了银行卡";
        System.out.println(result);
        return result;
    }

    //GET http://localhost:8080/v1/cards
    @GetMapping
    public String listCard(){
        String result = "你所有的银行卡";
        System.out.println(result);
        return result;
    }

    //DELETE http://localhost:8080/v1/cards/1
    @DeleteMapping("/{id}")
    public String deleteCard(@PathVariable("id") Long id){
        String result = "注销了银行卡" + id;
        System.out.println(result);
        return result;
    }

    //PATCH http://localhost:8080/v1/cards/1/transference/2
    @PatchMapping("/{id}/transference/{receiver}")
    public String transfer(@PathVariable("id") Long id,@PathVariable("receiver") Long receiver,
                           @RequestParam("money") Integer money){
        String result = id + "向" + receiver + "转账了" + money + "分";
        System.out.println(result);
        return result;
    }
}

总结

作个要点的总结

1.  /app-name /{version} /{domain} /{rest-convention}，这个上述已经描述过了
2. 不使用动词，一律使用名词，关于名词是否是复数形式，从资源是否是合集判断，如果这个资源是唯一的（也就是说即使不指定任何约束[如id]）查询出来的结果仅一条数据，则使用单数，否则使用复数。

拓展

Hypermedia API

RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。对于这一块目前自己没有很好的想法与了解，后续会慢慢弥补，通过返回一个"link"对象的数组来展示下一步做什么，常见的例子就是https://api.github.com/，但是还没去深入研究如何优雅地实现这样的api，作为后续自己一个需要去补上和思考的点

GraphQL

这个就比较有意思了，GraphQL是一种新的API标准，由Facebook开发并开源,旨在提供 RESTful 架构体系的替代方案。可以搜搜了解看，也是作为后续自己去学习的一个点。

 

 

参考文章

REST简介

restful架构风格设计准则（一）以资源为中心、自描述的请求响应、资源状态迁移为粒度

restful架构风格设计准则（二）以资源为中心，一个url

restful架构风格设计准则（三）资源识别和资源设计

restful架构风格设计准则（四）资源表示和资源访问

restful架构风格设计准则（五）用户认证和session管理

restful架构风格设计准则（六）版本管理

RESTful API 设计指南

理解RESTful架构

RESTful风格的接口命名规范

RESTful 架构详解