认识RESTful API
-
概述
是一种 API 设计规范，规定了如何编写数据接口以及报文的格式、状态码等信息
-
核心特点
每一种 URL 代表一种资源
URL的设计（动宾结构）
-
HTTP动词 - 表示一个动作
GET 读取资源；POST 新增资源
PUT 全量资源更新；PATCH 部分资源更新
DELETE 删除资源
注意：根据 HTTP 规范，动词一律大写
-
宾语名词 - 表示动作的目标对象
GET /authors
推荐：宾语使用复数
-
避免多级
资源需要多级分类，因此很容易写出多级的 URL，比如获取某个作者的某一类文章
GET /authors/5/categories/2 （不推荐）不利于扩展，语义也不明确
GET /authors/5?categories=2 （推荐）除了第一级，其它级别都用查询字符串表达
-
API的演进
在 URL 中添加版本信息，如：GET /v1/authors
报文格式
-
不做多余的包装，直接返回结果数据
[ { "id": 1, "name": "安琪拉", "alias": "Angela" }, { "id": 2, "name": "老夫子", "alias": "OldMaster" } ] -
带有分页的数据
{ "paging": { "limit": 10, "offset": 1, "total": 500 }, "data": [ { "id": 1, "name": "安琪拉", "alias": "Angela" }, { "id": 2, "name": "老夫子", "alias": "OldMaster" } ] } -
不同请求的响应报文
GET 返回单个对象或集合
POST 返回新增成功的对象
PUT/PATCH 返回更新成功的对象
DELETE 返回空
错误处理
-
业务类异常
// 抛出正确的异常状态码和异常的文本描述 { "error": "不合法的参数", "detail": { "user_name": "用户名为必填项" } }例如：参数检验不通过，权限校验失败
-
非业务类异常
不在预期内的问题，通常由类库、框架抛出，或由于自己的代码逻辑错误导致
比如：数据库连接失败
-
统一处理错误
状态码
业务类异常，使用指定的 HTTP 状态码 非业务类异常，统一使用 500 状态码错误描述
业务类异常，使用指定的错误文本 非业务类异常，生产环境统一文案，如："服务端正忙，请稍后再试"
常用状态码
-
1XX表示相关信息
API 不使用 1XX 状态码
-
2XX表示操作成功
200 - 请求成功
201 - created 创建一个资源
204 - No Content 服务器处理了请求，但不返回任何实体内容
-
3XX表示重定向
301 - 永久重定向，搜索引擎在抓取新的内容的同时也将旧的网址替换为了重定向之后的网址
302 - 暂时的重定向，搜索引擎会抓取新的内容而保留旧的地址
304 - Not Modified 资源未修改，可以直接使用缓存资源（协商缓存）
注：服务端通过 Location 字段设置重定向
-
4XX表示客户端错误
400 - Bad Request 客户端请求有语法错误，常用于参数校验
401 - Unauthorized 请求未经授权，常用于未登录，如果经过验证后依然没权限，则使用 403
403 - Forbidden 服务器收到请求，但拒绝提供服务，无权限
404 - Not Found 请求的资源不存在
-
5XX表示服务端错误
500 - Internal Server Error 服务器内部错误，用于非业务类异常
一起学习，加群交流看 沸点
