# Reading

**Repository Path**: tleke/reading

## Basic Information

- **Project Name**: Reading
- **Description**: 毕业设计基于springBoot后端开发
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-11
- **Last Updated**: 2025-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## **📌 RESTful API 设计规范全指南**
REST（Representational State Transfer）是一种基于 HTTP 的架构风格，适用于 Web 服务。以下是 **RESTful 设计规范**的完整建议，包括资源 URL 设计、HTTP 方法选择、状态码、分页、安全性等。

---

## **🔹 1. 资源 URL 设计**
### **✅ 规则**
1. **使用名词，不用动词**
    - ❌ `/getBooks` ✅ `/books`
    - ❌ `/createUser` ✅ `/users`
2. **使用复数形式**
    - ❌ `/book` ✅ `/books`
3. **使用层级结构表达关系**
    - `/users/{userId}/orders`（获取某个用户的订单）
4. **避免使用动词**
    - 资源本身是名词，操作由 HTTP 方法表达
    - ❌ `/deleteBook/1`
    - ✅ `DELETE /books/1`

---

## **🔹 2. HTTP 方法的正确使用**
| **操作** | **HTTP 方法** | **示例** | **说明** |
|----------|-------------|---------|---------|
| **创建资源** | `POST` | `POST /books` | 服务器创建新资源（自动分配 ID） |
| **获取资源（单个或多个）** | `GET` | `GET /books` | 获取资源（可分页） |
| **更新资源（完整更新）** | `PUT` | `PUT /books/{id}` | 需要提供完整的资源数据 |
| **部分更新资源** | `PATCH` | `PATCH /books/{id}` | 仅修改部分字段 |
| **删除资源** | `DELETE` | `DELETE /books/{id}` | 删除指定 ID 的资源 |

🔹 **注意**
- `PUT` **幂等**（多次调用，结果不变）
- `POST` **非幂等**（多次调用会创建多个资源）
- `DELETE` **幂等**（删除同一资源多次，结果不变）
- `PATCH` **非幂等**（取决于更新逻辑）

---

## **🔹 3. 状态码使用**
| **状态码** | **含义** | **适用场景** |
|-----------|---------|-------------|
| **200 OK** | 请求成功 | `GET /books/1` 返回书籍详情 |
| **201 Created** | 资源创建成功 | `POST /books` 创建书籍成功 |
| **204 No Content** | 请求成功，无返回内容 | `DELETE /books/1` 删除成功 |
| **400 Bad Request** | 请求参数错误 | `POST /books` 缺少必填字段 |
| **401 Unauthorized** | 认证失败 | 访问需要身份验证的接口 |
| **403 Forbidden** | 权限不足 | 普通用户访问管理员接口 |
| **404 Not Found** | 资源不存在 | `GET /books/999` 书籍 ID 不存在 |
| **409 Conflict** | 资源冲突 | `POST /users` 用户已存在 |
| **500 Internal Server Error** | 服务器错误 | 代码异常 |

---

## **🔹 4. 查询参数（筛选、排序、分页）**
✅ **查询参数用于过滤数据**
```http
GET /books?author=张三&category=技术
```

✅ **分页**
```http
GET /books?page=2&size=10
```
- `page=2`：请求第 2 页
- `size=10`：每页 10 条数据

✅ **排序**
```http
GET /books?sort=price,desc
```
- `sort=price,desc`：按价格降序

---

## **🔹 5. 请求和响应规范**
### **✅ 统一 JSON 格式**
所有 API 返回 JSON，结构一致：
```json
{
  "code": 200,
  "message": "Success",
  "data": {
    "id": 1,
    "title": "Spring Boot实战",
    "author": "张三"
  }
}
```
- `code`：状态码
- `message`：响应消息
- `data`：具体数据

**错误响应示例**
```json
{
  "code": 400,
  "message": "缺少必填字段：title",
  "errors": ["title 不能为空"]
}
```

---

## **🔹 6. 安全性**
✅ **使用 HTTPS**
- 保护数据传输安全，防止窃听

✅ **身份认证（JWT）**
- 使用 `Authorization: Bearer <token>` 进行身份验证

✅ **权限控制**
- 通过角色（如 `ROLE_ADMIN`）控制访问权限

✅ **防止 SQL 注入**
- 使用 `@Query` 或 JPA 进行参数绑定，避免拼接 SQL

✅ **API 速率限制**
- 通过 Redis + 限流算法（如令牌桶）防止滥用

---

## **🔹 7. RESTful API 设计示例**
### **📌 书籍管理系统 API**
| **操作** | **方法** | **URL** | **说明** |
|----------|---------|---------|---------|
| 获取所有书籍 | `GET` | `/books` | 可分页、筛选 |
| 获取书籍详情 | `GET` | `/books/{id}` | 获取单本书 |
| 添加新书籍 | `POST` | `/books` | 服务器生成 ID |
| 更新书籍（完整） | `PUT` | `/books/{id}` | 需要提供完整数据 |
| 更新书籍（部分） | `PATCH` | `/books/{id}` | 仅更新部分字段 |
| 删除书籍 | `DELETE` | `/books/{id}` | 删除指定书籍 |

---

## **🔹 8. 版本管理**
✅ **URL 版本**
```http
GET /api/v1/books
```
✅ **Header 版本**
```http
GET /books
Accept: application/vnd.myapi.v1+json
```
✅ **推荐**
- **小项目**：使用 URL 版本（`/api/v1`）
- **大项目**：使用 Header 版本（更灵活）

---

## **🔹 9. HATEOAS（可选）**
✅ **RESTful 允许返回关联链接**
```json
{
  "id": 1,
  "title": "Spring Boot实战",
  "author": "张三",
  "_links": {
    "self": { "href": "/books/1" },
    "author": { "href": "/authors/张三" }
  }
}
```
- 方便前端导航

---

## **🔹 10. API 文档**
✅ **推荐使用 Swagger / OpenAPI**
- `springdoc-openapi`（适用于 Spring Boot 3.x）
- `Swagger UI` 生成可交互 API 文档

📌 **示例**
```java
@Operation(summary = "获取所有书籍", description = "分页获取书籍列表")
@GetMapping("/books")
public List<Book> getBooks(@RequestParam int page, @RequestParam int size) {
    return bookService.getBooks(page, size);
}
```

---

## **🎯 总结**
| **类别** | **最佳实践** |
|----------|------------|
| **URL 设计** | 资源名用**名词**，使用**复数** |
| **HTTP 方法** | `GET` 查询、`POST` 添加、`PUT` 更新、`PATCH` 部分更新、`DELETE` 删除 |
| **状态码** | 200（成功）、201（创建成功）、400（参数错误）、404（资源不存在） |
| **分页** | `GET /books?page=1&size=10` |
| **安全** | HTTPS + JWT 认证 + 角色权限 |
| **API 版本** | `GET /api/v1/books` |
| **文档** | 使用 Swagger/OpenAPI |

---

## **🔹 附录**
### **🔸 常见问题**
1. **RESTful API 与 SOAP 区别**
    - RESTful API 基于 HTTP 协议，基于资源的 URL 设计，使用 HTTP 方法表示操作，状态码表示结果，使用 JSON 格式数据交换。
    - SOAP 基于 XML 格式，基于 RPC 远程过程调用，使用 WSDL 描述服务，使用 SOAPAction 头指定操作。

2. **RESTful API 设计原则**
    - 客户端-服务器分离：RESTful API 应该是客户端和服务器之间交互的唯一接口。
    - 无状态：RESTful API 应该是无状态的，所有数据都应该通过请求参数传递。
    - 统一接口：RESTful API 应该使用统一的接口，不应该有多个 API 版本。
    - 缓存：RESTful API 应该支持缓存，减少网络传输。
    - 统一接口：RESTful API 应该使用统一的接口，不应该有多个 API 版本。
    - 接口文档：RESTful API 应该有接口文档，方便开发者使用。

3. **RESTful API 设计规范**
    - 资源 URL 设计：资源名用名词，使用复数；使用层级结构表达关系；避免使用动词。
    - HTTP 方法的正确使用：GET 查询、POST 添加、PUT 更新、PATCH 部分更新、DELETE 删除。
    - 状态码使用：200（成功）、201（创建成功）、400（参数错误）、404（资源不存在）。
    - 查询参数（筛选、排序、分页）：查询参数用于过滤数据，分页、排序参数用于分页和排序。
    - 请求和响应规范：统一 JSON 格式、错误响应示例。
    - 安全性：使用 HTTPS + JWT 认证 + 角色权限。
    - API 速率限制：通过 Redis + 限流算法（如令牌桶）防止滥用。
    - 版本管理：URL 版本、Header 版本。
    - HATEOAS（可选）：RESTful 允许返回关联链接。
    - API 文档：推荐使用 Swagger / OpenAPI。