HaHafeng
3634933ece
- feat: Create ASLLayout component with 7-module left navigation - feat: Implement Title Screening Settings page with optimized PICOS layout - feat: Add placeholder pages for Workbench and Results - fix: Fix nested routing structure for React Router v6 - fix: Resolve Spin component warning in MainLayout - fix: Add QueryClientProvider to App.tsx - style: Optimize PICOS form layout (P+I left, C+O+S right) - style: Align Inclusion/Exclusion criteria side-by-side - docs: Add architecture refactoring and routing fix reports Ref: Week 2 Frontend Development Scope: ASL module MVP - Title Abstract Screening
480 lines
8.5 KiB
Markdown
480 lines
8.5 KiB
Markdown
# [模块名称] - API设计
|
||
|
||
> **基础路径：** `/api/v1/模块名`
|
||
> **端点数量：** X个
|
||
> **认证要求：** JWT Token
|
||
> **最后更新：** YYYY-MM-DD
|
||
|
||
---
|
||
|
||
## 📋 API概览
|
||
|
||
| 端点 | 方法 | 说明 | 认证 |
|
||
|------|------|------|------|
|
||
| `/api/v1/xxx/resources` | GET | 获取资源列表 | ✅ |
|
||
| `/api/v1/xxx/resources/:id` | GET | 获取资源详情 | ✅ |
|
||
| `/api/v1/xxx/resources` | POST | 创建资源 | ✅ |
|
||
| `/api/v1/xxx/resources/:id` | PUT | 更新资源 | ✅ |
|
||
| `/api/v1/xxx/resources/:id` | DELETE | 删除资源 | ✅ |
|
||
|
||
---
|
||
|
||
## 📚 API详细设计
|
||
|
||
### 1. 获取资源列表
|
||
|
||
**端点：** `GET /api/v1/xxx/resources`
|
||
|
||
**用途：** 获取当前用户的资源列表（分页）
|
||
|
||
**请求参数：**
|
||
|
||
**Query参数：**
|
||
```typescript
|
||
{
|
||
page?: number; // 页码，默认1
|
||
pageSize?: number; // 每页数量，默认10，最大100
|
||
status?: string; // 筛选：状态（active/inactive）
|
||
keyword?: string; // 搜索关键词
|
||
sortBy?: string; // 排序字段（createdAt/updatedAt）
|
||
sortOrder?: 'asc' | 'desc'; // 排序方向，默认desc
|
||
}
|
||
```
|
||
|
||
**请求示例：**
|
||
```bash
|
||
GET /api/v1/xxx/resources?page=1&pageSize=10&status=active
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
**成功响应：** `200 OK`
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"id": 1,
|
||
"userId": 123,
|
||
"fieldName": "示例",
|
||
"description": "描述",
|
||
"status": "active",
|
||
"createdAt": "2025-11-06T10:00:00.000Z",
|
||
"updatedAt": "2025-11-06T10:00:00.000Z"
|
||
}
|
||
],
|
||
"pagination": {
|
||
"page": 1,
|
||
"pageSize": 10,
|
||
"total": 100,
|
||
"totalPages": 10
|
||
}
|
||
},
|
||
"message": "获取成功"
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
```json
|
||
// 401 Unauthorized
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "UNAUTHORIZED",
|
||
"message": "未授权，请先登录"
|
||
}
|
||
}
|
||
|
||
// 400 Bad Request
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "INVALID_PARAMS",
|
||
"message": "参数错误",
|
||
"details": [
|
||
{ "field": "pageSize", "message": "最大不能超过100" }
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 获取资源详情
|
||
|
||
**端点：** `GET /api/v1/xxx/resources/:id`
|
||
|
||
**用途：** 获取指定资源的详细信息
|
||
|
||
**路径参数：**
|
||
- `id` (必填): 资源ID
|
||
|
||
**请求示例：**
|
||
```bash
|
||
GET /api/v1/xxx/resources/123
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
**成功响应：** `200 OK`
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": 123,
|
||
"userId": 456,
|
||
"fieldName": "示例",
|
||
"description": "详细描述",
|
||
"status": "active",
|
||
"createdAt": "2025-11-06T10:00:00.000Z",
|
||
"updatedAt": "2025-11-06T10:00:00.000Z",
|
||
// 额外的关联数据
|
||
"user": {
|
||
"id": 456,
|
||
"name": "用户名"
|
||
}
|
||
},
|
||
"message": "获取成功"
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
```json
|
||
// 404 Not Found
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "NOT_FOUND",
|
||
"message": "资源不存在"
|
||
}
|
||
}
|
||
|
||
// 403 Forbidden
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "FORBIDDEN",
|
||
"message": "无权访问此资源"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 创建资源
|
||
|
||
**端点：** `POST /api/v1/xxx/resources`
|
||
|
||
**用途：** 创建新资源
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"fieldName": "资源名称", // 必填，长度2-200
|
||
"description": "描述", // 可选，最大5000字
|
||
"status": "active" // 可选，默认active
|
||
}
|
||
```
|
||
|
||
**验证规则：**
|
||
- `fieldName`: 必填，2-200字符，不能包含特殊字符
|
||
- `description`: 可选，最大5000字符
|
||
- `status`: 可选，有效值：active, inactive
|
||
|
||
**请求示例：**
|
||
```bash
|
||
POST /api/v1/xxx/resources
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"fieldName": "新资源",
|
||
"description": "这是一个新资源"
|
||
}
|
||
```
|
||
|
||
**成功响应：** `201 Created`
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": 124,
|
||
"userId": 456,
|
||
"fieldName": "新资源",
|
||
"description": "这是一个新资源",
|
||
"status": "active",
|
||
"createdAt": "2025-11-06T10:00:00.000Z",
|
||
"updatedAt": "2025-11-06T10:00:00.000Z"
|
||
},
|
||
"message": "创建成功"
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
```json
|
||
// 422 Unprocessable Entity
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "VALIDATION_ERROR",
|
||
"message": "参数验证失败",
|
||
"details": [
|
||
{ "field": "fieldName", "message": "字段名称不能为空" },
|
||
{ "field": "fieldName", "message": "字段名称长度必须在2-200之间" }
|
||
]
|
||
}
|
||
}
|
||
|
||
// 409 Conflict
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "ALREADY_EXISTS",
|
||
"message": "该资源已存在"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 更新资源
|
||
|
||
**端点：** `PUT /api/v1/xxx/resources/:id`
|
||
|
||
**用途：** 更新指定资源（完整更新）
|
||
|
||
**路径参数：**
|
||
- `id` (必填): 资源ID
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"fieldName": "更新后的名称",
|
||
"description": "更新后的描述",
|
||
"status": "inactive"
|
||
}
|
||
```
|
||
|
||
**请求示例：**
|
||
```bash
|
||
PUT /api/v1/xxx/resources/123
|
||
Authorization: Bearer <token>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"fieldName": "更新后的名称",
|
||
"description": "更新后的描述"
|
||
}
|
||
```
|
||
|
||
**成功响应：** `200 OK`
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": 123,
|
||
"fieldName": "更新后的名称",
|
||
"description": "更新后的描述",
|
||
"updatedAt": "2025-11-06T11:00:00.000Z"
|
||
},
|
||
"message": "更新成功"
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
```json
|
||
// 404 Not Found
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "NOT_FOUND",
|
||
"message": "资源不存在"
|
||
}
|
||
}
|
||
|
||
// 403 Forbidden
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "FORBIDDEN",
|
||
"message": "无权修改此资源"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 删除资源
|
||
|
||
**端点：** `DELETE /api/v1/xxx/resources/:id`
|
||
|
||
**用途：** 删除指定资源（软删除）
|
||
|
||
**路径参数：**
|
||
- `id` (必填): 资源ID
|
||
|
||
**请求示例：**
|
||
```bash
|
||
DELETE /api/v1/xxx/resources/123
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
**成功响应：** `200 OK`
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": null,
|
||
"message": "删除成功"
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
```json
|
||
// 404 Not Found
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "NOT_FOUND",
|
||
"message": "资源不存在"
|
||
}
|
||
}
|
||
|
||
// 403 Forbidden
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "FORBIDDEN",
|
||
"message": "无权删除此资源"
|
||
}
|
||
}
|
||
|
||
// 409 Conflict
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": "CANNOT_DELETE",
|
||
"message": "该资源有关联数据，无法删除"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔐 认证与权限
|
||
|
||
### 认证方式
|
||
所有API都需要JWT Token认证：
|
||
```
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
### 权限检查
|
||
- 用户只能访问自己的资源
|
||
- ADMIN角色可以访问所有资源
|
||
|
||
---
|
||
|
||
## 📊 错误码汇总
|
||
|
||
| 错误码 | HTTP状态 | 说明 |
|
||
|--------|---------|------|
|
||
| UNAUTHORIZED | 401 | 未授权 |
|
||
| FORBIDDEN | 403 | 无权限 |
|
||
| NOT_FOUND | 404 | 资源不存在 |
|
||
| VALIDATION_ERROR | 422 | 参数验证失败 |
|
||
| ALREADY_EXISTS | 409 | 资源已存在 |
|
||
| INTERNAL_ERROR | 500 | 服务器错误 |
|
||
|
||
---
|
||
|
||
## 🚀 使用示例
|
||
|
||
### JavaScript/TypeScript
|
||
```typescript
|
||
// 获取资源列表
|
||
const response = await fetch('/api/v1/xxx/resources?page=1&pageSize=10', {
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`,
|
||
},
|
||
});
|
||
const data = await response.json();
|
||
|
||
// 创建资源
|
||
const response = await fetch('/api/v1/xxx/resources', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Authorization': `Bearer ${token}`,
|
||
'Content-Type': 'application/json',
|
||
},
|
||
body: JSON.stringify({
|
||
fieldName: '新资源',
|
||
description: '描述',
|
||
}),
|
||
});
|
||
```
|
||
|
||
### cURL
|
||
```bash
|
||
# 获取列表
|
||
curl -X GET "http://localhost:3001/api/v1/xxx/resources?page=1&pageSize=10" \
|
||
-H "Authorization: Bearer <token>"
|
||
|
||
# 创建资源
|
||
curl -X POST "http://localhost:3001/api/v1/xxx/resources" \
|
||
-H "Authorization: Bearer <token>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"fieldName":"新资源","description":"描述"}'
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
**性能优化：**
|
||
- 列表接口必须支持分页，默认pageSize=10，最大100
|
||
- 避免返回过多关联数据，按需加载
|
||
- 大量数据导出使用异步任务
|
||
|
||
**安全性：**
|
||
- 所有接口必须验证JWT Token
|
||
- 必须检查资源归属（用户只能操作自己的资源）
|
||
- 敏感字段不要返回（如密码）
|
||
|
||
**向后兼容：**
|
||
- API变更使用版本号（/api/v2）
|
||
- 不要删除已有字段，只能标记为deprecated
|
||
- 新增字段必须有默认值
|
||
|
||
---
|
||
|
||
## 🔗 相关文档
|
||
|
||
**规范：**
|
||
- [API设计规范](../../04-开发规范/02-API设计规范.md)
|
||
- [API路由总览](../../04-开发规范/04-API路由总览.md)
|
||
|
||
**数据库：**
|
||
- [本模块数据库设计](./01-数据库设计.md)
|
||
|
||
---
|
||
|
||
**最后更新：** YYYY-MM-DD
|
||
**维护人：** 技术架构师
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|