31条接口设计规范

编号	规范	描述	案例
1	使用HTTP动词	使用HTTP动词来描述操作，例如GET获取资源，POST创建资源，PUT更新资源，DELETE删除资源。	GET /users - 获取用户列表 POST /users - 创建新用户 PUT /users/123 - 更新用户123 DELETE /users/123 - 删除用户123
2	RESTful URL设计	资源命名使用名词，URL中避免使用动词，保持简洁。	GET /products - 获取产品列表 POST /products - 创建新产品 GET /products/123 - 获取产品123的详细信息
3	统一响应格式	统一返回格式，包含状态码、消息和数据，便于客户端解析。	`{ "status": "success", "message": "Operation completed", "data": {...} }`
4	使用状态码	使用标准HTTP状态码表示请求结果，200表示成功，4xx表示客户端错误，5xx表示服务器错误。	200 OK - 请求成功 400 Bad Request - 请求参数错误 404 Not Found - 资源不存在 500 Internal Server Error - 服务器内部错误
5	接口版本控制	在URL中包含版本号，便于接口升级和兼容。	GET /v1/users - 获取用户列表（版本1） GET /v2/users - 获取用户列表（版本2）
6	请求参数校验	对请求参数进行严格校验，确保数据完整性和合法性。	`{ "name": "John", "email": "john@example.com" }` - POST请求的用户数据，校验name和email字段
7	分页和过滤	对大量数据提供分页和过滤功能，减少一次性返回的数据量。	GET /products?page=1&limit=10 - 获取第一页的10个产品 GET /products?category=electronics - 按类别过滤产品
8	安全性考虑	使用HTTPS加密传输，确保数据安全。	`https://api.example.com/users` - 使用HTTPS协议传输数据
9	错误处理	返回详细的错误信息，包含错误码和错误描述，便于调试。	`{ "status": "error", "code": "400", "message": "Invalid request parameter: email" }`
10	使用幂等操作	确保对同一资源的多次相同请求具有相同的副作用，避免重复提交导致的数据不一致。	POST /orders - 创建订单 PUT /orders/123 - 更新订单123，操作幂等
11	提供完整文档	为API提供详细的文档，描述每个接口的功能、请求参数、响应格式和示例。	使用Swagger生成API文档提供在线文档链接，便于开发者查看和测试
12	避免深层级嵌套	避免URL路径过长和嵌套层级过多，保持简洁易读。	/users/123/orders/456 - 合理的URL设计 /users/123/orders/456/items/789 - URL层级过深
13	使用规范的命名	使用一致且有意义的命名，便于理解和维护。	GET /users/{user_id}/orders - 获取指定用户的订单 GET /products/{product_id}/reviews - 获取指定产品的评论
14	缓存控制	使用HTTP缓存头控制缓存，提高接口响应速度。	`Cache-Control: no-cache` - 禁止缓存 `Cache-Control: max-age=3600` - 缓存1小时
15	支持批量操作	提供批量操作接口，减少请求次数，提高效率。	POST /users/batch - 批量创建用户 DELETE /users/batch - 批量删除用户
16	国际化支持	提供多语言支持，返回符合客户端语言偏好的数据。	`Accept-Language: en-US` - 请求英文数据 `Accept-Language: zh-CN` - 请求中文数据
17	提供适当的元数据	返回结果中包含总记录数、分页信息等元数据，便于客户端处理。	`{ "status": "success", "data": [...], "meta": { "total": 100, "page": 1, "limit": 10 } }`
18	避免敏感信息泄露	返回结果中避免包含敏感信息，确保数据安全。	`{ "status": "success", "data": { "user_id": 123, "name": "John" } }` - 避免返回密码、身份证号等敏感信息
19	支持异步操作	对耗时操作提供异步接口，返回任务状态，避免阻塞客户端。	POST /tasks - 创建任务，返回任务ID GET /tasks/{task_id} - 获取任务状态
20	使用JSON Web Token	使用JWT进行身份认证和授权，确保接口安全性。	`Authorization: Bearer <token>` - 使用JWT进行认证
21	记录请求日志	对每个请求进行日志记录，便于问题排查和性能分析。	记录请求URL、参数、响应状态码和时间等信息
22	提供健康检查接口	提供健康检查接口，便于监控和运维。	GET /health - 返回服务健康状态
23	提供限流和熔断机制	对接口进行限流和熔断，保护系统稳定性。	使用RateLimiter进行限流实现熔断机制，避免服务雪崩
24	使用统一的时间格式	统一使用ISO 8601格式表示时间，避免时区问题。	`2023-01-01T12:00:00Z` - ISO 8601格式时间
25	版本弃用策略	对旧版本接口提供弃用策略，给出合理的过渡期。	在文档中标注旧版本弃用日期，并提供新版本接口
26	接口签名	对接口请求进行签名验证，确保数据完整性和防止请求被篡改。	`Signature: <签名>` - 在请求头中包含签名信息
27	数据加密	对敏感数据进行加密传输，确保数据在传输过程中的安全性。	`Encrypt: <加密数据>` - 在请求头或请求体中包含加密后的数据
28	IP白名单	仅允许特定IP地址访问接口，增强安全性。	配置服务器或网关，只允许特定IP范围的请求通过
29	压力测试	定期进行压力测试，评估接口在高并发情况下的性能。	使用工具如JMeter、LoadRunner进行压测，记录接口响应时间、吞吐量等性能指标
30	异步处理	对耗时操作进行异步处理，提升接口响应速度和系统性能。	使用消息队列（如RabbitMQ、Kafka）处理异步任务，接口返回任务ID
31	数据脱敏	对返回结果中的敏感信息进行脱敏处理，保护用户隐私。	`{ "status": "success", "data": { "user_id": 123, "name": "J* D" } }` - 对姓名进行脱敏处理

案例：接口签名

问题描述：未对接口请求进行签名验证，可能导致请求被篡改。

解决方案：对接口请求进行签名验证，确保数据完整性和防止请求被篡改。

示例：

// 示例代码：签名生成
String secretKey = "your_secret_key";
String data = "param1=value1¶m2=value2"; // 请求参数拼接
String signature = HMACSHA256(data, secretKey); // 使用HMAC-SHA256生成签名

// 请求头中包含签名信息
HttpHeaders headers = new HttpHeaders();
headers.add("Signature", signature);

案例：数据加密

问题描述：接口请求和响应的数据未加密，可能导致敏感信息泄露。

解决方案：对敏感数据

进行加密传输，确保数据在传输过程中的安全性。

示例：

// 示例代码：数据加密
String secretKey = "your_secret_key";
String plainText = "sensitive_data";
String encryptedData = AES256Encrypt(plainText, secretKey); // 使用AES-256加密

// 请求体中包含加密后的数据
HttpEntity<String> request = new HttpEntity<>(encryptedData);

案例：IP白名单

问题描述：接口未限制访问IP，可能被恶意访问。

解决方案：仅允许特定IP地址访问接口，增强安全性。

示例：

# Nginx配置示例：IP白名单
server {
    listen 80;
    server_name api.example.com;

    location / {
        allow 192.168.1.0/24; # 允许的IP范围
        deny all; # 其他IP拒绝访问
        proxy_pass http://backend;
    }
}

案例：异步处理

问题描述：接口直接处理耗时操作，导致响应时间过长。

解决方案：对耗时操作进行异步处理，提升接口响应速度和系统性能。

示例：

// 示例代码：异步处理
@RestController
public class TaskController {
    
    @PostMapping("/tasks")
    public ResponseEntity<String> createTask(@RequestBody Task task) {
        // 异步处理任务
        CompletableFuture.runAsync(() -> {
            taskService.processTask(task);
        });

        // 返回任务ID
        return ResponseEntity.ok("Task created successfully");
    }
}

这些规范和案例有助于设计安全性高、性能优越、用户友好的API接口，提高系统稳定性和用户体验。

本文来自公众号：多课网

原文阅读