RESTFUL如何指导WEB API设计？

Posted 2021-12-02 time-read

　　博主刚刚接触web开发的时候，写了一个接口 /get_article_info/1 获取id为1的这篇文章的内容，被前辈们看见了，前辈给我说我这个接口设计的不太好啊，不符合RESTFUL规范，当前辈们说出这些话的时候，我很迷惑，我写的接口不能够好好工作吗？能够正常返回内容啊，对于不存在的文章也能够在返回的内容体中提示不存在，而且接口的意思很明确，一看就能明白，这还有什么不好的地方吗？

一、RESTFUL是什么？

　　RESTFUL是英文单词Representational State Transfer的缩写，翻译成中文就是表现层状态转化，什么是表现层？什么是状态？什么是转化？

　　表现层可以理解为一种资源，可以是一篇文章，一张图片，一个订单...... 所有网络上的一个实体，都可以说是一个资源，而URL就是这个唯一资源的定位符，状态和转化应该连在一起理解，这是一个动作，即状态变化，可以是新建，删除，更新，获取，比如新建一篇文章，删除一篇文章，更新文章内容，获取文章内容。HTTP协议应当如何表示这种变化？HTTP协议中有四个操作方法，可以用来表示，GET表示获取，POST表示新建，DELETE表示删除，PUT表示更新。

　　综上，RESTFUL可以通俗的理解通过HTTP协议的动词和URL对一个资源进行各种操作，实现表现层状态转化。

二、 RESTFUL如何指导我们设计API？

核心思想就是HTTP动词 + URL资源，比如获取文章信息 GET /articles, GET是动词，/articles 是名词

1. 动词通常是HTTP的方法

GET：    获取信息
POST：   新建信息
DELETE： 删除信息
PUT：    更新信息

2. 资源必须是名词

已经有了HTTP的方法的动词，URL中，我们就没有必要使用动词了

POST /create_articles   
POST /delete_articles   
POST /update_articles   

上面都是不好的用法，我们应当使用下面这种用法

POST    /articles
DELETE  /articles/2
PUT     /articles/2

3. 资源最好使用名词的复数，任何情况下都能够适用

/airticles/1  获取id为1的文章内容
/airticles    获取所有文章内容

# 使用单数
/article  获取一篇文章内容？还是所有的文章内容？

4. 避免多级URL

/authors/5/airticles  获取作者id为5的所有文章

上面换成这种形式更好，也利于扩展
/airticles?author_id=5

5. 利用querystring来过滤和筛选

一般情况下一个url很难满足复杂多变的情况，比如分页，过滤，这时候我们应当如何设计？

/airticles/published  这种形式？

不不不，published不是一个资源，而且这种url不宜于扩展

最佳实践应当是下面这种形式

/articles?page=1          获取第一页的文章
/articles?published=true  获取已经发布的文章

6. 返回有意义的状态码

HTTP有很多状态码，表示不同的意义，我们应当充分利用这些状态码

尤其是出现错误时，不要返回200，意义很不明确

一般成功请求后返回的状态码

GET：200 OK
POST：201 Created
PUT：200 OK
DELETE：204 No Content

其他状态码信息

1xx：相关信息

2xx：请求成功

3xx：重定向

4xx：客户端错误

5xx：服务器端错误

2xx状态码表示成功

200 OK 请求成功

201 Created 请求成功，并创建了资源

202 Accepted 请求接受，但未处理完成，一般用于异步处理

204 No Content 请求处理成功，但未返回内容，一般用于DELETE请求成功

3xx状态码表示重定向

301 Moved Permanently 永久重定向

302 Found 暂时重定向

4xx状态码表示客户端错误

400 Bad Request 错误请求，服务器不理解请求，没做任何处理

401 Unauthorized 未认证

403 Forbidden 用户通过了认证，但是没有权限

404 Not Found 没有发现请求的内容

405 Method Not Allowed 不允许的请求方法

5xx状态码表示服务端错误

500 Internal Server Error 服务器内部错误，无法完成请求

503 Service Unavailable 服务不可用

三、总结

　　RESTFUL就是一种规范，我们不遵循这种规范也能够写出可用的代码，但是遵循这种规范却能给我们带来更多的好处，API设计更加可读，与其他人交流也能够很方便。现在让我看看我刚刚接触web接口开发时的设计，真的是不太好啊，URL信息太重复，错误的返回状态不明确，全是200。

参考文章：https://blog.florimond.dev/restful-api-design-13-best-practices-to-make-your-users-happy

rear