【测开】接口路由分类与技巧，GraphQL，WebSocket，RESTFUL方法（PUT、PATCH、OPTIONS、HEAD、TRACE）

【测开】接口路由分类与技巧，GraphQL，WebSocket，RESTFUL方法（PUT、PATCH、OPTIONS、HEAD、TRACE）

1、接口路由分类（RESTful，GraphQL，WebSocket）

接口路由规则通常用于定义如何在系统中路由请求，以确保不同的服务、模块或组件之间能够正确地交流。

RESTful API 路由规则

• 资源表示：每个资源（如用户、产品等）对应一个 URL。
• HTTP 方法：
  GET：获取资源
  POST：创建资源
  PUT：更新资源
  DELETE：删除资源
• 路由示例：
  GET /api/users — 获取用户列表
  POST /api/users — 创建新用户
  GET /api/users/{id} — 获取特定用户信息
  PUT /api/users/{id} — 更新特定用户信息
  DELETE /api/users/{id} — 删除特定用户

GraphQL 路由规则

• 所有请求通过一个端点（如 /graphql）处理，使用查询语句指定所需的数据。 引用：1, 2, 3
• GraphQL 将 API 请求分为查询（query）和变更（mutation）。查询用于获取数据，变更用于修改数据。
• GraphQL 强制使用类型系统定义请求和响应的数据类型，这使得接口更加可预测。基本类型：String、Int、Float、Boolean、ID。
• GraphQL 支持嵌套查询，可以在一个请求中获取相关联的多个资源。
• GraphQL 支持实时更新，通过subscription来处理。这适用于需要实时数据的情况，比如聊天应用或通知系统。

query {
  users {
    id
    name
  }
}
mutation {
  addUser(name: "Alice") {
    id
    name
  }
}

WebSocket 路由规则

• WebSocket 是一种网络通信协议，提供全双工通信通道，常用于需要实时数据传输的应用（如聊天、游戏、实时通知等）。与传统的 HTTP 请求-响应模型不同，WebSocket 允许客户端和服务器之间的持久连接与即时消息传递。
• WebSocket 可以定义不同的路由以处理各种事件。1, 2，3
• 示例：
  ws://example.com/chat — 聊天消息
  ws://example.com/notifications — 实时通知
• WebSocket 具有一系列事件，可以处理连接打开、消息接收、错误和连接关闭等情况。
  常见事件：
  onopen: 连接建立时触发
  onmessage: 接收到消息时触发
  onerror: 发生错误时触发
  onclose: 连接关闭时触发
• WebSocket 的“路由”通常是通过消息内容来实现的，而不是 URL 路由。可以在消息中包含一个操作类型或命令，根据此来处理不同的事件。

{
  "type": "CHAT_MESSAGE",
  "data": {
    "user": "Alice",
    "message": "Hello, World!"
  }
}
switch (msg.type) {
    case 'CHAT_MESSAGE':
        // 处理聊天消息
        break;
    case 'USER_JOINED':
        // 处理用户加入
        break;
}

2、接口路由设计与技巧

版本控制

• 路由中包含版本号，以便于接口的升级和维护。
• 示例：
  /api/v1/users
  /api/v2/users

中间件

• 中间件用于处理请求的预处理和后处理，比如身份验证、日志记录和数据格式化等。
• 示例：
  // 身份验证中间件示例
  function authMiddleware(req, res, next) {
  const token = req.headers[‘authorization’];
  if (isValidToken(token)) {
  next();
  } else {
  res.status(401).json({ error: ‘Unauthorized’ });
  }
  }
  app.use(‘/api/’, authMiddleware);

动态路由

• 支持在 URL 中使用动态参数，用于捕获变量。
• 示例：
  /api/products/{category} — 根据分类获取产品
  // 用户信息的动态路由
  app.get(‘/api/users/:id’, (req, res) => {
  const userId = req.params.id;
  // 根据 userId 获取用户信息
  });

错误处理

• 统一的错误处理机制有助于返回一致的错误响应并提高用户体验。
• 例子：
  app.use((err, req, res, next) => {
  console.error(err.stack);
  res.status(500).json({ error: ‘Something went wrong!’ });
  });

资源嵌套

• 为相关资源嵌套路由，使得 API 更加直观。
  app.get(‘/api/users/:userId/posts’, (req, res) => {
  const userId = req.params.userId;
  // 获取 userId 下的所有文章
  });

过滤、排序和分页

• 支持查询参数以便客户端能够过滤、排序和分页。
  app.get(‘/api/users’, (req, res) => {
  const { page = 1, limit = 10, sort = ‘name’ } = req.query;
  // 根据 page、limit 和 sort 获取用户信息
  });

使用缓存

• 对于较少变动的数据，可以使用缓存机制以提高 API 的性能。
• 示例：
  利用 HTTP 缓存头：
  app.get(‘/api/users’, (req, res) => {
  res.set(‘Cache-Control’, ‘public, max-age=300’);
  // 返回用户数据
  });

3、RESTFUL方法介绍

方法：GET、POST、DELETE、PUT、PATCH、OPTIONS、HEAD、TRACE
安全与幂等

• 根据RFC2616第九章说明，http方法的定义有两点：safe and Idempotent，即安全性和幂等性，可以结合这两点对以上方法进行说明
• 安全：安全方法是指不修改资源的 HTTP 方法，是那些可以被缓存、对资源无损预加载的方法。一般只用于查询。
• 幂等：幂等方法是指无论调用多少次都不会有不同结果，它无论是调用一次，还是十次都无关紧要，结果仍应相同。比如a = 4幂等; a++不幂等;

方法说明：

• 1，GET
  安全、幂等；
  用于获取资源；

• 2，HEAD
  安全、幂等；
  与get方法类似，但不返回message body内容，仅仅是获得获取资源的部分信息（content-type、content-length）；
  restful框架中较少使用

• 3，POST
  非安全、非幂等；
  用于创建子资源

• 4，PUT
  非安全、幂等；
  用于创建、更新资源；

• 5，DELETE
  非安全、幂等；
  删除资源；

• 6，OPTIONS
  安全、幂等；
  用于url验证，验证接口服务是否正常；

• 7，TEACE
  安全、幂等；
  维基百科“回显服务器收到的请求，这样客户端可以看到（如果有）哪一些改变或者添加已经被中间服务器实现。”
  restful框架中较少使用

• 8，PATCH
  非安全、幂等；
  用于创建、更新资源，与PUT类似，区别在于PATCH代表部分更新；
  后来提出的接口方法，使用时可能去要验证客户端和服务端是否支持；

日常中的使用：

• post和put的区别：
  在于uri，或者说post用于创建子资源，比如接口：POST /api/person/ 会创建一个资源比如 /api/person/1或者/api/person/2 … 或者/api/person/n，创建了新的uri，
  而put方法创建资源的uri是 PUT /api/person/1，这样就创建了一个资源，如果1已经存在那么就是更新，所以put并不是只是更新操作。
  再有post是非幂等的。通常情况下，我们都会将post、get、put、delete对应到CRUD操作上，但实际上put并不是只能更新。

• patch的使用：
  patch是2010后成为的正式http方法，它是对put的补充，在没有patch之前，我们都是用put进行更新操作，这时候我们的接口中通常会有一个逻辑规则，如：如果对象的的一个字符属性为NULL，那么就是不更新该属性（字段）值，如果对象的字符属性是“”，那么就更新该属性（字段）的值，通过这种方式来避免全部覆盖的操作。现在有了patch就解决了这种判断，在put接口中不管属性是不是null，都进行更新，在patch接口中就对非null的进行更新。

• uri的使用规范：
  uri即代表资源的，通过不同的方法来区分操作，那么像如下的接口就已经违反了restful规范：
  GET /api/getPerson/1
  DELETE /api/delPerson/1
  GET /api/person/get/1
  DELETE /api/person/delete/1
  在符合规范的前提下，uri的定义应该也是实际使用中应该考虑的，比如uri包涵那些信息？如版本、资源分类、资源名称、表述格式等：
  /api/1.0/person/man/1.xml
  /api/2.0/person/man/1.json

参考资料：1, 2 ，3