240 lines
4.8 KiB
Markdown
240 lines
4.8 KiB
Markdown
# RESTful API 设计规范
|
||
|
||
## 概述
|
||
|
||
本项目采用 RESTful API 设计规范，提供统一、直观的 HTTP 接口设计。
|
||
|
||
## API 设计原则
|
||
|
||
### 1. 资源命名规范
|
||
- 使用名词复数形式作为资源名称
|
||
- 示例：`/api/projects`、`/api/users`
|
||
|
||
### 2. HTTP 方法语义
|
||
- `GET`: 获取资源
|
||
- `POST`: 创建资源
|
||
- `PUT`: 更新整个资源
|
||
- `PATCH`: 部分更新资源
|
||
- `DELETE`: 删除资源
|
||
|
||
### 3. 状态码规范
|
||
- `200 OK`: 成功获取或更新资源
|
||
- `201 Created`: 成功创建资源
|
||
- `204 No Content`: 成功删除资源
|
||
- `400 Bad Request`: 请求参数错误
|
||
- `404 Not Found`: 资源不存在
|
||
- `500 Internal Server Error`: 服务器内部错误
|
||
|
||
## 项目 API 接口
|
||
|
||
### 项目资源 (Projects)
|
||
|
||
#### 1. 获取项目列表
|
||
```
|
||
GET /api/projects
|
||
```
|
||
|
||
**查询参数:**
|
||
- `page` (可选): 页码，默认为 1
|
||
- `limit` (可选): 每页数量，默认为 10，最大 100
|
||
- `name` (可选): 项目名称搜索
|
||
|
||
**响应格式:**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取列表成功，共N条记录",
|
||
"data": {
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"name": "项目名称",
|
||
"description": "项目描述",
|
||
"repository": "https://github.com/user/repo",
|
||
"valid": 1,
|
||
"createdAt": "2024-01-01T00:00:00Z",
|
||
"updatedAt": "2024-01-01T00:00:00Z",
|
||
"createdBy": "system",
|
||
"updatedBy": "system"
|
||
}
|
||
],
|
||
"pagination": {
|
||
"page": 1,
|
||
"limit": 10,
|
||
"total": 100,
|
||
"totalPages": 10
|
||
}
|
||
},
|
||
"timestamp": 1700000000000
|
||
}
|
||
```
|
||
|
||
#### 2. 获取单个项目
|
||
```
|
||
GET /api/projects/:id
|
||
```
|
||
|
||
**路径参数:**
|
||
- `id`: 项目ID（整数）
|
||
|
||
**响应格式:**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取数据成功",
|
||
"data": {
|
||
"id": 1,
|
||
"name": "项目名称",
|
||
"description": "项目描述",
|
||
"repository": "https://github.com/user/repo",
|
||
"valid": 1,
|
||
"createdAt": "2024-01-01T00:00:00Z",
|
||
"updatedAt": "2024-01-01T00:00:00Z",
|
||
"createdBy": "system",
|
||
"updatedBy": "system"
|
||
},
|
||
"timestamp": 1700000000000
|
||
}
|
||
```
|
||
|
||
#### 3. 创建项目
|
||
```
|
||
POST /api/projects
|
||
```
|
||
|
||
**请求体:**
|
||
```json
|
||
{
|
||
"name": "项目名称",
|
||
"description": "项目描述（可选）",
|
||
"repository": "https://github.com/user/repo"
|
||
}
|
||
```
|
||
|
||
**验证规则:**
|
||
- `name`: 必填，2-50个字符
|
||
- `description`: 可选，最多200个字符
|
||
- `repository`: 必填，有效的URL格式
|
||
|
||
**响应格式:**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取数据成功",
|
||
"data": {
|
||
"id": 1,
|
||
"name": "项目名称",
|
||
"description": "项目描述",
|
||
"repository": "https://github.com/user/repo",
|
||
"valid": 1,
|
||
"createdAt": "2024-01-01T00:00:00Z",
|
||
"updatedAt": "2024-01-01T00:00:00Z",
|
||
"createdBy": "system",
|
||
"updatedBy": "system"
|
||
},
|
||
"timestamp": 1700000000000
|
||
}
|
||
```
|
||
|
||
#### 4. 更新项目
|
||
```
|
||
PUT /api/projects/:id
|
||
```
|
||
|
||
**路径参数:**
|
||
- `id`: 项目ID（整数）
|
||
|
||
**请求体:**
|
||
```json
|
||
{
|
||
"name": "新项目名称（可选）",
|
||
"description": "新项目描述（可选）",
|
||
"repository": "https://github.com/user/newrepo（可选）"
|
||
}
|
||
```
|
||
|
||
**验证规则:**
|
||
- `name`: 可选，2-50个字符
|
||
- `description`: 可选，最多200个字符
|
||
- `repository`: 可选，有效的URL格式
|
||
|
||
**响应格式:**
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "获取数据成功",
|
||
"data": {
|
||
"id": 1,
|
||
"name": "新项目名称",
|
||
"description": "新项目描述",
|
||
"repository": "https://github.com/user/newrepo",
|
||
"valid": 1,
|
||
"createdAt": "2024-01-01T00:00:00Z",
|
||
"updatedAt": "2024-01-01T12:00:00Z",
|
||
"createdBy": "system",
|
||
"updatedBy": "system"
|
||
},
|
||
"timestamp": 1700000000000
|
||
}
|
||
```
|
||
|
||
#### 5. 删除项目
|
||
```
|
||
DELETE /api/projects/:id
|
||
```
|
||
|
||
**路径参数:**
|
||
- `id`: 项目ID（整数）
|
||
|
||
**响应:**
|
||
- HTTP 状态码: 204 No Content
|
||
- 响应体: 空
|
||
|
||
## 错误处理
|
||
|
||
### 验证错误 (400 Bad Request)
|
||
```json
|
||
{
|
||
"code": 1003,
|
||
"message": "项目名称至少2个字符",
|
||
"data": {
|
||
"field": "name",
|
||
"validationErrors": [
|
||
{
|
||
"field": "name",
|
||
"message": "项目名称至少2个字符",
|
||
"code": "too_small"
|
||
}
|
||
]
|
||
},
|
||
"timestamp": 1700000000000
|
||
}
|
||
```
|
||
|
||
### 资源不存在 (404 Not Found)
|
||
```json
|
||
{
|
||
"code": 1002,
|
||
"message": "项目不存在",
|
||
"data": null,
|
||
"timestamp": 1700000000000
|
||
}
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 统一响应格式
|
||
所有 API 都使用统一的响应格式，包含 `code`、`message`、`data`、`timestamp` 字段。
|
||
|
||
### 2. 参数验证
|
||
使用 Zod 进行严格的参数验证，确保数据的完整性和安全性。
|
||
|
||
### 3. 错误处理
|
||
全局异常处理中间件统一处理各种错误，提供一致的错误响应格式。
|
||
|
||
### 4. 分页支持
|
||
列表接口支持分页功能，返回分页信息方便前端处理。
|
||
|
||
### 5. 软删除
|
||
删除操作采用软删除方式，将 `valid` 字段设置为 0，保留数据历史。
|