aijianhua/docs/Java后端API接口文档.md

爱鉴花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. 公共响应格式

成功响应

{
  "code": 200,
  "message": "成功",
  "data": {}
}

分页响应

{
  "code": 200,
  "message": "成功",
  "data": {
    "list": [],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 0,
      "pages": 0
    }
  }
}

错误响应

{
  "code": 400,
  "message": "参数错误",
  "data": null
}

4. 认证接口

用户登录

POST /api/v1/auth/login

请求参数:

参数名	类型	必填	说明
username	string	是	用户名
password	string	是	密码

请求示例:

{
  "username": "admin",
  "password": "admin123"
}

响应示例:

{
  "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"

请求示例:

{
  "username": "newuser",
  "password": "password123",
  "phone": "13800138001",
  "email": "newuser@example.com"
}

响应示例:

{
  "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>

响应示例:

{
  "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>

响应示例:

{
  "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	否	昵称

响应示例:

{
  "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等)

请求示例:

curl -X POST "http://localhost:3200/api/v1/upload" \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/image.jpg" \
  -F "type=image"

响应示例:

{
  "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	否	文件类型筛选

请求示例:

curl -X GET "http://localhost:3200/api/v1/upload?page=1&size=10&type=image" \
  -H "Authorization: Bearer <token>"

响应示例:

{
  "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

请求示例:

curl -X DELETE "http://localhost:3200/api/v1/upload/1" \
  -H "Authorization: Bearer <token>"

响应示例:

{
  "code": 200,
  "message": "删除成功"
}

7. 健康检查接口

服务健康检查

GET /health

响应示例:

{
  "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