跳到主要内容

接口案例

介绍​

realworld 案例。

RESTful 接口设计规范​

  • 协议：API 与 用户的通信协议，尽量使用 HTTPS 协议。
  • 域名：应该尽量将API部署在专用域名之下https://api.example.com，如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下：https://example.com/api/。
  • 版本：https://api.example.com/v1
  • 路径：又称为“终点（endpoint）”，表示 API 的具体网址。

在 REATful 架构中，每一个网址代表一种资源（resource），所有网址中不能有动词，只能是名词，而且所用的名词往往和数据库的表格名对应。一般来说，数据库中的表都是同种记录的“集合(collection)”，所以API中的名词也应该使用复数：

  • https://api.example.com/v1/zoos

  • https://api.example.com/v1/animals

  • https://api.example.com/v1/employees

  • HTTP 动词

对于资源的具体操作类型，由 HTTP 动词表示。

常用的 HTTP 动词有下面五个：

  • GET(读取)：从服务器获取资源

  • POST(创建)：在服务器新建一个资源

  • PUT(完整更新)：在服务器更新资源（客户端提供改变后的完整资源）

  • PATCH(部分更新)：在服务器更新资源（客户端提供改变的属性）

  • DELETE(删除)：从服务器删除资源 还有俩个不常见的 HTTP 动词：

  • HEAD：获取资源的元数据

  • OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

  • 过滤信息

如果记录数量很多，服务器不可能豆浆它们返回给用户。API 应该提供参数，过滤返回一下结果：

  • ?limit=10：指定返回记录的数量；

  • ?offset=10：指定返回记录的开始位置；

  • ?sortly=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

  • ?animal_type_id=10：指定筛选条件

  • 状态码

创建项目​

const express = require('express');

const app = express();

const port = process.env.PORT || 3000;

app.get('/', function (req, res) {
  res.send('hello world!');
});
app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`);
});

// PORT=5000 nodemon app.js

配置中间件​

express.json()
express.urlencoded()
morgan('dev')
cors()

路由设计​

RealWorld API Spec

代码实现​

B站视频地址：P29-P55

我的代码：realworld-api-express