中小学学习搭子APP - API接口使用说明文档

项目概述

本项目是一个基于Spring Boot + JPA的中小学学习搭子APP后端API，为中小学生提供寻找学习伙伴的平台功能。

服务地址: http://localhost:8080/api

API文档: http://localhost:8080/api/docs

🔄 数据持久化说明

数据存储方式: H2文件数据库（持久化存储）

✅ 数据持久化: 所有用户数据会永久保存到磁盘文件中
✅ 应用重启: 重启后数据不会丢失，用户信息依然存在
📁 数据文件位置: ./data/testdb.mv.db
🔍 数据库控制台: http://localhost:8080/api/h2-console
- JDBC URL: jdbc:h2:file:./data/testdb
- 用户名: sa
- 密码: (空)

接口列表

1. 学习搭子注册

接口地址: POST /api/users/register

功能描述: 创建新的学习搭子用户账户

请求参数:

{
  "username": "xiaoming",
  "password": "123456",
  "grade": "初三"
}

参数说明:

username (必填): 用户名，3-50个字符
password (必填): 密码，6个字符以上
grade (可选): 年级（如：小一、小二、小三、小四、小五、小六、初一、初二、初三、高一、高二、高三等）

成功响应:

{
  "code": 200,
  "message": "注册成功",
  "data": {
    "userId": 1,
    "username": "xiaoming",
    "grade": "初三",
    "avatarUrl": null,
    "createTime": "2024-01-01T10:00:00",
    "updateTime": "2024-01-01T10:00:00"
  },
  "timestamp": "2024-01-01T10:00:00"
}

错误响应:

{
  "code": 400,
  "message": "用户名已存在",
  "data": null,
  "timestamp": "2024-01-01T10:00:00"
}

2. 学习搭子登录

接口地址: POST /api/users/login

功能描述: 验证学习搭子用户凭据并返回用户信息

请求参数:

{
  "username": "xiaoming",
  "password": "123456"
}

参数说明:

username (必填): 用户名
password (必填): 密码

成功响应:

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "userId": 1,
    "username": "xiaoming",
    "grade": "初三",
    "avatarUrl": "https://example.com/avatar/xiaoming.jpg",
    "createTime": "2024-01-01T10:00:00",
    "updateTime": "2024-01-01T10:00:00"
  },
  "timestamp": "2024-01-01T10:00:00"
}

错误响应:

{
  "code": 401,
  "message": "用户名或密码错误",
  "data": null,
  "timestamp": "2024-01-01T10:00:00"
}

3. 获取学习搭子信息

接口地址: GET /api/users/{id}

功能描述: 根据用户ID获取学习搭子详细信息

请求参数:

id (路径参数): 用户ID

请求示例: GET /api/users/1

成功响应:

{
  "code": 200,
  "message": "success",
  "data": {
    "userId": 1,
    "username": "xiaoming",
    "grade": "初三",
    "avatarUrl": "https://example.com/avatar/xiaoming.jpg",
    "createTime": "2024-01-01T10:00:00",
    "updateTime": "2024-01-01T10:00:00"
  },
  "timestamp": "2024-01-01T10:00:00"
}

错误响应:

{
  "code": 404,
  "message": "用户不存在",
  "data": null,
  "timestamp": "2024-01-01T10:00:00"
}

4. 获取所有学习搭子

接口地址: GET /api/users

功能描述: 获取系统中所有学习搭子的列表

请求参数: 无

成功响应:

{
  "code": 200,
  "message": "获取中小学学习搭子列表成功",
  "data": [
    {
      "userId": 1,
      "username": "admin",
      "grade": "高三",
      "avatarUrl": "https://example.com/avatar/admin.jpg",
      "createTime": "2024-01-01T10:00:00",
      "updateTime": "2024-01-01T10:00:00"
    },
    {
      "userId": 2,
      "username": "xiaoming",
      "grade": "初三",
      "avatarUrl": "https://example.com/avatar/xiaoming.jpg",
      "createTime": "2024-01-01T10:00:00",
      "updateTime": "2024-01-01T10:00:00"
    }
  ],
  "timestamp": "2024-01-01T10:00:00"
}

5. 更新学习搭子信息

接口地址: PUT /api/users/{id}

功能描述: 更新指定学习搭子的信息

请求参数:

id (路径参数): 用户ID

请求体:

{
"grade": "高一",
"avatarUrl": "https://example.com/avatar/new.jpg"
}

参数说明:

grade (可选): 年级
avatarUrl (可选): 头像URL

成功响应:

{
  "code": 200,
  "message": "中小学学习搭子信息更新成功",
  "data": {
    "userId": 1,
    "username": "xiaoming",
    "grade": "高一",
    "avatarUrl": "https://example.com/avatar/new.jpg",
    "createTime": "2024-01-01T10:00:00",
    "updateTime": "2024-01-01T11:00:00"
  },
  "timestamp": "2024-01-01T11:00:00"
}

错误响应:

{
  "code": 400,
  "message": "参数格式不正确",
  "data": null,
  "timestamp": "2024-01-01T11:00:00"
}

6. 删除学习搭子

接口地址: DELETE /api/users/{id}

功能描述: 删除指定学习搭子

请求参数:

id (路径参数): 用户ID

请求示例: DELETE /api/users/1

成功响应:

{
  "code": 200,
  "message": "中小学学习搭子删除成功",
  "data": null,
  "timestamp": "2024-01-01T12:00:00"
}

错误响应:

{
  "code": 404,
  "message": "中小学学习搭子不存在",
  "data": null,
  "timestamp": "2024-01-01T12:00:00"
}

7. 修改密码

接口地址: POST /api/users/{id}/change-password

功能描述: 修改中小学学习搭子密码

请求参数:

id (路径参数): 用户ID

请求体:

{
"oldPassword": "123456",
"newPassword": "newpassword123"
}

参数说明:

oldPassword (必填): 原密码
newPassword (必填): 新密码，6个字符以上

成功响应:

{
  "code": 200,
  "message": "密码修改成功",
  "data": null,
  "timestamp": "2024-01-01T13:00:00"
}

错误响应:

{
  "code": 400,
  "message": "原密码错误",
  "data": null,
  "timestamp": "2024-01-01T13:00:00"
}

通用说明

响应格式

所有接口都使用统一的响应格式：

{
  "code": 200,
  "message": "操作结果描述",
  "data": "具体数据或null",
  "timestamp": "响应时间戳"
}

状态码说明

200: 操作成功
400: 请求参数错误
401: 未授权（用户名或密码错误）
404: 资源不存在
500: 服务器内部错误

测试数据

系统启动时会自动创建以下测试中小学学习搭子：

管理员账户
- 用户名: admin
- 密码: 123456
- 年级: 高三
- 头像: https://example.com/avatar/admin.jpg
测试用户1
- 用户名: xiaoming
- 密码: 123456
- 年级: 初三
- 头像: https://example.com/avatar/xiaoming.jpg
测试用户2
- 用户名: xiaohong
- 密码: 123456
- 年级: 高二
- 头像: https://example.com/avatar/xiaohong.jpg
测试用户3
- 用户名: xiaogang
- 密码: 123456
- 年级: 初二
- 头像: https://example.com/avatar/xiaogang.jpg

使用示例（curl命令）

中小学学习搭子注册

curl -X POST http://localhost:8080/api/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "123456",
    "grade": "初一",
    "avatarUrl": "https://example.com/avatar/newuser.jpg"
  }'

中小学学习搭子登录

curl -X POST http://localhost:8080/api/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "xiaoming",
    "password": "123456"
  }'

获取中小学学习搭子信息

curl -X GET http://localhost:8080/api/users/1

获取所有中小学学习搭子

curl -X GET http://localhost:8080/api/users

注意事项

跨域支持: 所有接口都支持跨域访问，方便前端调用
参数验证: 所有接口都有完整的参数验证
错误处理: 统一的错误处理和响应格式
日志记录: 所有操作都有详细的日志记录
数据库: 默认使用H2文件数据库，数据持久化存储
密码安全: 生产环境建议使用BCrypt加密（当前为演示用简单加密）
中小学学习搭子匹配: 可根据年级等信息进行学习伙伴匹配
个人资料: 支持头像展示，适合中小学生使用

联系方式

如有问题，请联系开发团队：dev@example.com

API接口使用说明.md 8.3 KB パーマリンク 履歴 Raw

中小学学习搭子APP - API接口使用说明文档

项目概述

🔄 数据持久化说明

接口列表

1. 学习搭子注册

2. 学习搭子登录

3. 获取学习搭子信息

4. 获取所有学习搭子

5. 更新学习搭子信息

6. 删除学习搭子

7. 修改密码

通用说明

响应格式

状态码说明

测试数据

使用示例（curl命令）

中小学学习搭子注册

中小学学习搭子登录

获取中小学学习搭子信息

获取所有中小学学习搭子

注意事项

联系方式

API接口使用说明.md 8.3 KB

パーマリンク履歴 Raw