feat: 项目的增删改查
This commit is contained in:
239
apps/server/README-RESTful-API.md
Normal file
239
apps/server/README-RESTful-API.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# 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，保留数据历史。
|
||||
Reference in New Issue
Block a user