Node.js后端开发笔记（二）：RESTful API

前后端分离开发必须要用到 API，而 RESTful API 就是一套目前比较成熟且应用广泛的 API 设计规范。我将以当前正在开发的项目为例，介绍一些设计时需要注意的细节。

请求路径

通常应把 API 部署在一个统一的域名下，比如：

https://api.fuckwall.cc

或者也可以选择部署在一个统一的路径下，比如：

https://wp.fuckwall.cc/api

出于版本控制的考虑，一般还可以在路径中加入版本号，比如：

https://wp.fuckwall.cc/api/v1

在 RESTful 理念中，每一个路径对应一种资源，所以路径名应为名词，比如：

https://wp.fuckwall.cc/api/v1/articles
https://wp.fuckwall.cc/api/v1/images

有时服务端返回给客户端的数据数量比较大，就需要 API 提供参数，过滤返回结果，比如：

?limit=10 指定返回记录的数量
?offset=5 指定返回记录的开始位置
?page=2&per_page=20 指定第几页，以及每页的记录数
?sortby=date&order=desc 指定返回结果按照哪个属性排序，以及排序顺序
?column_id=1 指定筛选条件

HTTP 方法

在 RESTful 理念中， 一个客户端发出的请求都是类似“动词+名词”的结构，比如：

?limit=10 指定返回记录的数量
?offset=5 指定返回记录的开始位置
?page=2&per_page=20 指定第几页，以及每页的记录数
?sortby=date&order=desc 指定返回结果按照哪个属性排序，以及排序顺序
?column_id=1 指定筛选条件

HTTP/1.1 协议中共定义了八种方法，详情可以在这个页面中查看。一般常用的方法有四种， 对应数据库的增删改查操作：

GET 获取指定资源的数据
POST 向指定资源提交数据
PUT 更新指定资源的数据
DELETE 删除指定资源的数据

虽然在一些实践中会用到 PUT、DELETE 等方法，但我建议只使用 GET 和 POST 方法，前者用于查询类的操作，后者用于修改类的操作。

响应信息

服务器收到客户端的请求时，会给出相应的响应。响应内容应包括 HTTP 状态码和响应数据两部分。

HTTP 状态码由是 3 位数字组成的状态代码，一共分为五类：

1xx 消息：请求已被服务器接收，继续处理
2xx 成功：请求已成功被服务器接收、理解、并接受
3xx 重定向：需要后续操作才能完成这一请求
4xx 请求错误：请求含有词法错误或者无法被执行
5xx 服务器错误：服务器在处理某个正确请求时发生错误

关于每一类的详细介绍以及所有状态码的详细介绍，可以在这个页面中查看。

服务器返回的数据格式不应为纯文本，而应该是 JSON 格式，同时最好避免返回 XML 格式。