57 lines
2.4 KiB
Markdown
57 lines
2.4 KiB
Markdown
|
## RESTful架构简要开发指导
|
|||
|
|
|
|||
|
|
1. 遵循RESTful设计原则
|
|||
|
|
|
|||
|
|
资源导向：将API视为对资源（如用户、订单、文章等）的操作，每个资源都有唯一的URI（Uniform Resource Identifier）。
|
|||
|
|
|
|||
|
|
无状态：服务器不保留客户端会话状态，每次请求都应包含完成该操作所需的所有信息。
|
|||
|
|
|
|||
|
|
统一接口：使用标准的HTTP方法（GET、POST、PUT、PATCH、DELETE等）来表达对资源的操作意图。
|
|||
|
|
|
|||
|
|
2. HTTP方法映射到CRUD操作
|
|||
|
|
|
|||
|
|
GET：检索资源（单个或集合）。如GET /users（获取所有用户）、GET /users/123（获取ID为123的用户）。
|
|||
|
|
|
|||
|
|
POST：创建新资源。如POST /users，请求体携带新用户信息。
|
|||
|
|
|
|||
|
|
PUT：替换整个资源。如PUT /users/123，请求体携带完整更新后的用户信息。
|
|||
|
|
|
|||
|
|
PATCH：部分更新资源。如PATCH /users/123，请求体只包含需要更改的属性。
|
|||
|
|
|
|||
|
|
DELETE：删除资源。如DELETE /users/123。
|
|||
|
|
|
|||
|
|
3. 资源标识与URL结构
|
|||
|
|
|
|||
|
|
使用名词复数表示资源集合：如/users、/orders。
|
|||
|
|
|
|||
|
|
使用唯一标识符访问单个资源：如/users/123、/orders/456。
|
|||
|
|
|
|||
|
|
嵌套资源表示关联关系：如/users/123/orders表示用户ID为123的订单列表。
|
|||
|
|
4. 数据交换格式
|
|||
|
|
|
|||
|
|
使用JSON作为默认数据格式，设置Content-Type和Accept头为application/json。
|
|||
|
|
|
|||
|
|
定义清晰的数据模型，包括属性名称、数据类型、嵌套结构等。
|
|||
|
|
|
|||
|
|
5. 版本控制
|
|||
|
|
|
|||
|
|
在URL中包含版本号：如/v1/users、/v2/orders。
|
|||
|
|
|
|||
|
|
使用Accept头区分版本：如Accept: application/vnd.yourapp.v1+json。
|
|||
|
|
|
|||
|
|
6. 安全性与认证授权
|
|||
|
|
|
|||
|
|
实现用户认证：如使用JWT（JSON Web Tokens）或OAuth。客户端在请求头中携带Authorization字段。
|
|||
|
|
|
|||
|
|
实施授权：如使用RBAC（Role-Based Access Control）或其他权限模型。返回401（Unauthorized）、403（Forbidden）等状态码处理未授权访问。
|
|||
|
|
|
|||
|
|
7. 错误处理与文档
|
|||
|
|
|
|||
|
|
使用合适的HTTP状态码传达操作结果（如200 OK、400 Bad Request、404 Not Found、500 Internal Server Error等）。
|
|||
|
|
|
|||
|
|
提供详细的错误信息：在响应体中包含错误代码、描述和可能的解决方案。
|
|||
|
|
|
|||
|
|
编写或生成API文档：如使用OpenAPI/Swagger规范，提供接口描述、参数说明、请求示例、响应示例等信息。
|
|||
|
|
|
|||
|
|
### 更多参考
|
|||
|
|
[【RESTful】RESTful API 接口设计规范 | 示例](https://developer.aliyun.com/article/940518)
|