API 架构（RPC风格、RESTful风格）

news2024/9/16 9:53:43

API 架构风格笔记

RPC风格的接口案例
RESTful风格的接口案例
两者比对

RPC风格的接口案例

RPC（Remote Procedure Call，远程过程调用）风格的接口设计主要关注于远程服务调用的过程，而不强调资源的表述。以下是RPC风格接口的一个案例：

接口定义：
- 假设我们有一个远程服务，用于处理用户信息的查询和修改。
- 接口方法可能包括：getUserInfo(userId: int) -> User 和 updateUserInfo(userId: int, userInfo: User) -> bool。
调用方式：
- 客户端通过RPC框架（如Dubbo、gRPC等）调用远程服务的方法。
- 调用时，客户端无需关心底层网络通信的细节，只需按照接口定义传递参数和接收返回值。
数据格式：
- RPC请求和响应的数据格式通常使用二进制或自定义的序列化协议，以实现高效的数据传输和解析。
示例请求：
- 客户端通过RPC框架发送一个请求，请求中包含方法名getUserInfo和参数userId=123。
示例响应：
- 远程服务处理请求后，返回一个包含用户信息的User对象给客户端。

RESTful风格的接口案例

RESTful（Representational State Transfer，表述性状态转移）风格的接口设计以资源为核心，强调资源的表述和状态转移。以下是RESTful风格接口的一个案例：

资源定义：
- 假设我们有一个Web服务，用于管理用户信息。
- 资源可以是“用户”（User），对应的URI可能是/users/{userId}。
HTTP方法：
- 使用HTTP的GET、POST、PUT、DELETE等方法来表示对资源的不同操作。
- 例如，GET /users/{userId} 用于获取用户信息，POST /users 用于创建新用户，PUT /users/{userId} 用于更新用户信息，DELETE /users/{userId} 用于删除用户。
数据格式：
- 请求和响应的数据格式通常使用JSON或XML，以易于人类阅读和机器解析。
示例请求（GET /users/123）：
- 客户端发送一个HTTP GET请求到/users/123。
- 请求头中可能包含认证信息（如Bearer Token）。
- 请求体为空（因为GET请求通常没有请求体）。
示例响应（HTTP 200 OK）：
- 服务器返回一个HTTP 200 OK响应，表示请求成功。
- 响应头中包含一些元数据，如Content-Type: application/json。
- 响应体中包含用户信息的JSON表示，如{"id": 123, "name": "John Doe", "email": "johndoe@example.com"}。

两者比对

从接口名称来看：
- RESTful风格的接口名称通常使用名词来表示资源，遵循资源的层次结构。
  例如，对于获取用户信息的接口，可能会命名为/users或/users/{userId}，这样的命名方式更侧重于资源的访问，而不是具体的操作。
- RPC风格的接口名称则通常包含动词，直接描述了服务的操作或动作。
  例如，getUserInfo、addUser等，这样的命名方式更侧重于服务的行为或功能。
从HTTP请求方法来看：
- RESTful风格严格遵循HTTP协议中定义的请求方法（GET、POST、PUT、DELETE等），每种方法都有明确的操作语义。
  例如，GET用于请求资源，POST用于创建新资源，PUT用于更新资源，DELETE用于删除资源。
- RPC风格的接口在HTTP请求方法的使用上可能更加灵活或受限。
  有些RPC实现可能只使用POST或GET方法作为远程调用的载体，而不严格区分请求方法的具体语义。
从返回数据格式来看：
- RESTful风格通常使用JSON格式作为返回数据的标准格式，因为JSON具有轻量级、易于阅读和编写的特点，同时也易于机器解析和生成。RESTful风格的返回数据结构往往遵循一定的规范，便于客户端处理。
- RPC风格的返回数据格式则可能更加多样化，它取决于具体的RPC框架和协议。虽然JSON也是一种常见的返回数据格式，但RPC也可能支持其他格式，如XML、Protobuf等。RPC风格的返回数据结构可能更加灵活，以适应不同的服务需求和传输场景。