Inicio Explorar Axuda
Rexistro Iniciar sesión
AI_LA
/
ai_la
3
0
Fork 0
Ficheiros Incidencias 0 Pull Requests 0 Wiki
Rama: master
Ramas Etiquetas
ai_la
/
base
/
server
/
API接口使用说明.md

API接口使用说明.md 8.3 KB
Permalink Histórico Raw

中小学学习搭子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: 服务器内部错误

测试数据

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

  1. 管理员账户

    • 用户名: admin
    • 密码: 123456
    • 年级: 高三
    • 头像: https://example.com/avatar/admin.jpg

  2. 测试用户1

    • 用户名: xiaoming
    • 密码: 123456
    • 年级: 初三
    • 头像: https://example.com/avatar/xiaoming.jpg

  3. 测试用户2

    • 用户名: xiaohong
    • 密码: 123456
    • 年级: 高二
    • 头像: https://example.com/avatar/xiaohong.jpg

  4. 测试用户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

注意事项

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

联系方式

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