接口设计【开发实践】

一、API设计

1.1 请求地址

请求地址也被称为端点（Endpoint）或URL，组成为：协议、域名（或IP）、端口号（可选）、路径（Path，可能包含路径参数）、查询参数（可选）。

1.2 请求方式

请求方式
GET：用于从服务器检索资源。
POST：用于向服务器提交数据，创建新资源。
PUT：用于更新已有资源，提供全部或完整的资源数据。
DELETE：用于删除指定资源。
其他（不常用）：HEAD、OPTIONS、PATCH、TRACE。

需要注意，上述请求方式对应的功能不是强制性的，只是规范。实际上，你也可以使用GET方法实现插入操作，或使用POST方法实现查询操作，不过不建议这样做。

幂等性
幂等性操作指多次操作的结果是一致的。
规范的情况下，GET满足幂等性，而POST、PUT、DELETE不满足幂等性。

1.3 请求参数

参数传递方式
路径参数（Path Parameters）：直接在URL路径中定义的参数，用来唯一标识资源或作为资源的一部分。例如，https://api.example.com/companies/{companyId}/employees/{employeeId}，其中{companyId}和{employeeId}是路径参数。
查询字符串（Query Parameters）：附加在URL后面的参数，以?开始，多个参数之间用&分隔。例如：https://api.example.com/data?param1=value1&param2=value2。
请求头（Request Header）：通过请求头可以传递元数据，如认证信息（Authorization）、内容类型（Content-Type）、Cookie等，也可用于传递特定的API参数。
请求体（Request Body）：较大量的数据或复杂结构的数据通常放在请求体中传递。数据格式常为JSON或XML。
表单数据（Form Data）：上传文件或提交表单时，可以使用multipart/form-data或application/x-www-form-urlencoded格式的表单数据传递参数。
参数传递规范
一般来说，GET和DELETE请求会使用路径参数和查询字符串，而POST和PUT会用请求体。但是不是绝对的，如GET也能使用请求体，POST也能带路径参数。

路径参数和查询字符串只适合在GET和DELETE操作时、传递参数很少（不要超过三个）、传递的参数数据不敏感（如用户密码）时使用。这两种参数传递方式会直接在请求URL中看到具体的数据，要避免URL太长和暴露用户数据。

非业务相关的参数放在header里。

1.4 响应的结构与示例

响应的结构
API响应通常遵循一定的结构，包括状态码（如200表示成功，404表示未找到等）、响应头（可能包含服务器信息、内容类型等）和响应体（包含请求的结果数据，通常是JSON或XML格式）。

响应的示例
提供API时，应该一起提供响应的示例，包括请求成功的示例和请求失败的示例，其中请求失败的示例应该覆盖主要的异常情况，并给出对应的提示信息。

二、安全设计

2.1 认证，鉴权，数据隔离（保证请求的合法性）

认证
简单来说，认证是为了禁止非系统用户访问系统。常见的认证方案为账号密码登录、手机号短信验证码登录等。登录需要维持登录状态，常用方案有cookie、session和token。
鉴权（接口层面的权限管理）
对于通过认证的用户，有时还需要进行鉴权操作。鉴权即判断某已认证的用户可以访问哪些资源或执行哪些操作。
数据隔离（数据层面的权限管理）
数据隔离是指在多用户或多进程环境下，通过技术手段确保不同的用户或进程只能访问到其被授权的数据，从而防止数据泄露、篡改或不适当的访问。

2.2 加密与解密（防止敏感信息泄露）

加密与解密
加密指使用特定的加密算法和密钥，将原始的、可读的明文信息（plain text）转换成不可读的密文（cipher text）的过程。
解密指使用一样的加密算法和对应的密钥，将密文还原为明文的过程。
在信息传输或存储过程中，即使第三方拿到了密文、也知道使用的加密算法，只要没有解密的秘钥，也无法解密出正确的明文信息。
对称加密和非对称加密
加密算法可以分为两类，一类使用对称加密，另一类使用非对称加密。
对称加密：加密和解密都是用相同的密钥，该密钥也被称为共享密钥。
非对称加密：使用一对被称为公钥（public Key）和私钥（private Key）的密钥。使用公钥加密时需要使用私钥解密，对应保密传输的情形。使用私钥加密时需要使用公钥解密，对应使用数字签名的情形。
密钥（key 或 secret）
不管共享密钥，还是公私密钥，本质都是随机字符串。
非对称加密中公私钥的生成
用于数据加密传输时，公私钥由信息接收者生成，并将公钥发送给发送者。用于数字签名时，公私钥由信息发送者生成，并将公钥发送给信息接收者。记住公钥加密、私钥签名、私钥持有者生成公私钥即可。

2.3 数字签名（防止数据篡改和验证发送者身份）

数字摘要（digest）
将任意长度的数据映射为一个紧凑的、长度固定的字符串，该字符串即摘要，也被称为散列值或哈希值。

摘要具有唯一性和不可逆性。唯一性指数据稍微变化，计算出的摘要就会不同，该特性常用于数据的完整性校验。不可逆性指无法从摘要还原出原始的数据，该特性可用于密码存储，数据库中存储密码的摘要，泄露摘要也不会导致密码泄露，此外摘要紧凑且长度固定的特点也便于存储。

需要注意的是，摘要能保证数据的完整性，但是不能防止数据被篡改，只要知道使用的是哪个摘要算法，任何人都能计算摘要。

常见的数字摘要算法有MD5、SHA-1、SHA-256等，摘要算法是输出字符串长度固定的哈希算法，并不是加密算法。加密要用到密钥，且可以通过解密过程还原数据，而摘要不使用密钥，也无法还原数据。
数字签名（signature）概述
数字签名是一种确保数字信息完整性和验证信息发送者身份的技术手段
极简版数字签名的实现（摘要 + 密钥）
可以通过摘要算法和共享密钥来实现简易版的数字签名，以Sender向Receiver发送data为例：

1. Sender和Receiver先商量好摘要算法和密钥secret
2. Sender将data和secret拼接在一起，生成摘要digest，然后将data和digest一起发送给Receiver
3. Receiver接收到数据后，取出data和自己的密钥secret拼接在一起，使用相同的摘要算法计算出摘要字符串，使用该字符串和接收数据中的digest比较，仅相同时采认为数据是从Sender发送的且没有被篡改

进阶版数字签名的实现（摘要 + 非对称加密）

1. Sender和Receiver先商量好摘要算法和加密算法
2. Sender先生成data的摘要digest，再使用私钥对摘要进行加密，得到的密文就是签名signature，然后将data和signature一起发送给Receiver
3. Receiver接收到数据后，取出data和signature，使用摘要算法计算出data的摘要字符串，使用加密算法和公钥将signature解密得到digest，再使用字符串和digest进行比较，仅相同时采认为数据是从Sender发送的且没有被篡改

2.4 数字证书（防止公钥伪造）

信息伪造问题
信息伪造，即第三方模拟信息发生者向信息接收者发送信息。
伪造问题是通过数字签名解决的，数字签名可以保证信息发送方的身份。
公钥伪造问题
防止信息伪造时，需要用到信息发送方的公钥，此时存在公钥伪造问题。
若在公钥的发布或存储过程中，被第三方替换掉为了他的公钥，此时信息接收者会认为原本的信息发送者是第三方，而把第三方视为正确的信息发送者。
公钥伪造问题通过数字证书解决。
申请数字证书的主要步骤

1. 生成密钥对：信息发送者自己生成公私钥，私钥自己保存。
2. 创建CSR（Certificate Signing Request）：使用密钥对创建CSR文件。
3. 提交申请：将CSR发送给SSL证书颁发机构（CA机构）申请数字证书。
4. 证书签发：CA使用其私钥对申请者的信息和公钥进行签名，生成数字证书。

提供证书（公钥就在证书中）
客户端验证服务器身份：客户端通过HTTPS连接到服务器时，服务器会自动发送其数字证书给客户端（证书是和域名绑定的，可以安装多个证书，一个证书可以关联多个域名）。
双向认证：双向认证，即客户端也需要向服务器证明自己的身份，那么服务器也需要客户端的证书，这个证书文件需要提前放到服务器中。

2.5 防重复提交

经典的例子是防止订单重复提交，经典的方案是分布式锁。
在防止订单重复提交的场景中，通过锁单号即可防止相同订单的重复提交。
尽管使用了分布式锁来防止重复提交，在代码中一般也要进行重复提交校验，如搜索该单号的订单是否已经提交，已经提交时反馈重复提交的提示。

三、调用外部接口

3.1 超时设置

需要根据业务需求设置合适的超时时间，且一般设置分层超时时间：

• 连接超时（Connect Timeout）：指定建立连接的最大等待时间。如果在这个时间内无法建立连接，应立即返回错误。
• 读取超时（Read Timeout）：即使连接成功建立，也应设定一个读取数据的超时时间，以防止服务端无响应或响应过慢导致客户端长时间等待。

3.2 重试与回退机制

当请求因超时失败时，可以设计自动重试机制，但需谨慎使用，避免对目标系统造成雪崩效应。重试次数、重试间隔也应合理设定，通常重试间隔会逐渐增加（指数退避）。

在多次重试失败后，应有相应的回退逻辑，比如提供默认数据、使用缓存数据或告知用户系统暂时不可用等。

3.3 监控，记录，报警

对接口调用的成功率、响应时间和超时次数进行监控，并设置报警机制，以便及时发现并解决问题。

详细记录超时及重试的信息，包括请求参数、超时时间、重试次数等，便于问题排查。