docs: 更新项目文档，完善需求和技术细节
This commit is contained in:
ylweng
380
docs/Java后端API接口文档.md
Normal file
380
docs/Java后端API接口文档.md
Normal file
@@ -0,0 +1,380 @@
|
||||
# 爱鉴花Java后端API接口文档
|
||||
|
||||
## 1. 概述
|
||||
本文档定义了爱鉴花项目Java后端的所有API接口规范，包括请求方式、参数、响应格式和错误处理等。
|
||||
|
||||
## 2. 基础信息
|
||||
|
||||
- **Base URL**: `http://localhost:3200`
|
||||
- **认证方式**: Bearer Token (JWT)
|
||||
- **响应格式**: JSON
|
||||
- **字符编码**: UTF-8
|
||||
|
||||
## 3. 公共请求头
|
||||
|
||||
| 头部名称 | 是否必须 | 说明 |
|
||||
|---------|---------|------|
|
||||
| Authorization | 是 | Bearer Token，格式为 `Bearer <token>` |
|
||||
| Content-Type | 否 | 请求体类型，上传文件时为 `multipart/form-data` |
|
||||
|
||||
## 4. 公共响应格式
|
||||
|
||||
## 3. 公共响应格式
|
||||
|
||||
### 成功响应
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
### 分页响应
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"list": [],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 10,
|
||||
"total": 0,
|
||||
"pages": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
```json
|
||||
{
|
||||
"code": 400,
|
||||
"message": "参数错误",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 认证接口
|
||||
|
||||
### 用户登录
|
||||
**POST** `/api/v1/auth/login`
|
||||
|
||||
**请求参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| username | string | 是 | 用户名 |
|
||||
| password | string | 是 | 密码 |
|
||||
|
||||
**请求示例**:
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "admin123"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "登录成功",
|
||||
"data": {
|
||||
"user_id": 1,
|
||||
"username": "admin",
|
||||
"phone": "13800138000",
|
||||
"email": "admin@example.com",
|
||||
"user_type": "admin",
|
||||
"avatar_url": "/uploads/avatar.jpg",
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 用户注册
|
||||
**POST** `/api/v1/auth/register`
|
||||
|
||||
**请求参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| username | string | 是 | 用户名 |
|
||||
| password | string | 是 | 密码 |
|
||||
| phone | string | 是 | 手机号 |
|
||||
| email | string | 否 | 邮箱 |
|
||||
| user_type | string | 否 | 用户类型，默认为"user" |
|
||||
|
||||
**请求示例**:
|
||||
```json
|
||||
{
|
||||
"username": "newuser",
|
||||
"password": "password123",
|
||||
"phone": "13800138001",
|
||||
"email": "newuser@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 201,
|
||||
"message": "注册成功",
|
||||
"data": {
|
||||
"user_id": 2,
|
||||
"username": "newuser",
|
||||
"phone": "13800138001",
|
||||
"email": "newuser@example.com",
|
||||
"user_type": "user",
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 获取当前用户信息
|
||||
**GET** `/api/v1/auth/me`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"user_id": 1,
|
||||
"username": "admin",
|
||||
"phone": "13800138000",
|
||||
"email": "admin@example.com",
|
||||
"user_type": "admin",
|
||||
"avatar_url": "/uploads/avatar.jpg",
|
||||
"created_at": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 用户接口
|
||||
|
||||
### 获取当前用户信息
|
||||
**GET** `/users/me`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"username": "admin",
|
||||
"email": "admin@example.com",
|
||||
"createdAt": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 更新用户信息
|
||||
**PUT** `/users/me`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**请求参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| email | string | 否 | 邮箱 |
|
||||
| nickname | string | 否 | 昵称 |
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "更新成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"username": "admin",
|
||||
"email": "newemail@example.com",
|
||||
"nickname": "管理员"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 6. 文件上传接口
|
||||
|
||||
### 上传文件
|
||||
**POST** `/api/v1/upload`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: multipart/form-data
|
||||
```
|
||||
|
||||
**请求参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| file | file | 是 | 文件 |
|
||||
| type | string | 是 | 文件类型(image, document等) |
|
||||
|
||||
**请求示例**:
|
||||
```bash
|
||||
curl -X POST "http://localhost:3200/api/v1/upload" \
|
||||
-H "Authorization: Bearer <token>" \
|
||||
-F "file=@/path/to/image.jpg" \
|
||||
-F "type=image"
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "上传成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"url": "/uploads/2024/01/15/abc123.jpg",
|
||||
"filename": "abc123.jpg",
|
||||
"original_name": "image.jpg",
|
||||
"type": "image",
|
||||
"size": 102400,
|
||||
"created_at": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 获取上传文件列表
|
||||
**GET** `/api/v1/upload`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**查询参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| page | int | 否 | 页码，默认1 |
|
||||
| size | int | 否 | 每页数量，默认10 |
|
||||
| type | string | 否 | 文件类型筛选 |
|
||||
|
||||
**请求示例**:
|
||||
```bash
|
||||
curl -X GET "http://localhost:3200/api/v1/upload?page=1&size=10&type=image" \
|
||||
-H "Authorization: Bearer <token>"
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"list": [
|
||||
{
|
||||
"id": 1,
|
||||
"url": "/uploads/2024/01/15/abc123.jpg",
|
||||
"filename": "abc123.jpg",
|
||||
"original_name": "image.jpg",
|
||||
"type": "image",
|
||||
"size": 102400,
|
||||
"created_at": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"size": 10,
|
||||
"total": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 删除上传文件
|
||||
**DELETE** `/api/v1/upload/{id}`
|
||||
|
||||
**请求头**:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**路径参数**:
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| id | int | 是 | 文件ID |
|
||||
|
||||
**请求示例**:
|
||||
```bash
|
||||
curl -X DELETE "http://localhost:3200/api/v1/upload/1" \
|
||||
-H "Authorization: Bearer <token>"
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "删除成功"
|
||||
}
|
||||
```
|
||||
|
||||
## 7. 健康检查接口
|
||||
|
||||
### 服务健康检查
|
||||
**GET** `/health`
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"status": "UP",
|
||||
"timestamp": "2024-01-15T10:30:00Z",
|
||||
"service": "aijianhua-backend"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 8. 错误码规范
|
||||
|
||||
| 错误码 | 错误信息 | 说明 |
|
||||
|--------|----------|------|
|
||||
| 200 | 成功 | 请求成功 |
|
||||
| 201 | 创建成功 | 资源创建成功 |
|
||||
| 400 | 参数错误 | 请求参数验证失败 |
|
||||
| 401 | 未授权 | 需要登录认证 |
|
||||
| 403 | 禁止访问 | 权限不足 |
|
||||
| 404 | 资源不存在 | 请求的资源不存在 |
|
||||
| 409 | 资源冲突 | 资源已存在或状态冲突 |
|
||||
| 422 | 数据验证失败 | 请求数据格式正确但业务验证失败 |
|
||||
| 500 | 服务器内部错误 | 服务器内部处理错误 |
|
||||
| 503 | 服务不可用 | 服务暂时不可用 |
|
||||
|
||||
## 9. 安全要求
|
||||
|
||||
1. 所有敏感接口必须使用HTTPS
|
||||
2. JWT token有效期7天
|
||||
3. 密码使用bcrypt加密存储
|
||||
4. 文件上传限制10MB
|
||||
5. 支持CORS跨域访问
|
||||
6. 请求频率限制（每分钟最多100次）
|
||||
7. 敏感操作需要二次验证
|
||||
|
||||
## 10. 版本历史
|
||||
|
||||
- v1.0.0 (2024-03-15): 初始版本发布
|
||||
- v1.1.0 (2024-03-16):
|
||||
- 完善认证接口文档
|
||||
- 完善文件上传接口文档
|
||||
- 添加健康检查接口文档
|
||||
- 补充错误码规范
|
||||
- 增强安全要求说明
|
||||
|
||||
---
|
||||
*本文档最后更新: 2024-03-15*
|
||||
Reference in New Issue
Block a user