## 一、API规范 ### 1.1 基础信息 - **基础URL**: `http://localhost:8080`(本地测试) - **接口格式**: RESTful API - **数据格式**: JSON - **字符编码**: UTF-8 - **认证方式**: JWT (JSON Web Token) - **GET**: 获取资源 - **POST**: 创建资源 - **PUT**: 更新资源（全量更新） - **PATCH**: 部分更新资源 - **DELETE**: 删除资源 ### 1.2 响应规范 #### 响应状态码 - **200**: 成功 - **400**: 请求参数错误 - **401**: 未授权 - **403**: 禁止访问 - **404**: 资源不存在 - **500**: 服务器内部错误 #### 后端相应格式 成功响应: ```json { "code": 200, // 200表示成功 "message": "success", "data": { // 实际返回数据 // ... } } ``` 错误相应: ```json { "code": 400, "message": "参数错误", // 错误信息 "data": null } ``` ## 二、 数据库设计 ### 2.1用户表设计 (users) | 字段名 | 类型 | 约束 | 说明 | | ----------- | ------------ | ----------------------------------------------------- | ------------------------------------ | | id | BIGINT | PRIMARY KEY, AUTO_INCREMENT | 用户ID | | username | VARCHAR(50) | NOT NULL, UNIQUE | 用户名 | | email | VARCHAR(100) | NOT NULL, UNIQUE | 邮箱地址（学校邮箱） | | password | VARCHAR(255) | NOT NULL | 密码（加密存储） | | nickname | VARCHAR(50) | NOT NULL | 昵称 | | avatar | VARCHAR(255) | | 头像URL | | bio | TEXT | | 个人简介 | | gender | TINYINT | | 性别（0-未知, 1-男, 2-女） | | student_id | VARCHAR(20) | UNIQUE | 学号 | | department | VARCHAR(100) | | 院系 | | major | VARCHAR(100) | | 专业 | | grade | VARCHAR(20) | | 年级 | | points | INT | DEFAULT 0 | 积分 | | role | TINYINT | DEFAULT 0 | 角色（0-普通用户, 1-版主, 2-管理员） | | status | TINYINT | DEFAULT 1 | 状态（0-禁用, 1-启用） | | is_verified | TINYINT | DEFAULT 0 | 是否验证（0-未验证, 1-已验证） | | login_ip | VARCHAR(50) | | 最近登录IP | | login_time | DATETIME | | 最近登录时间 | | created_at | DATETIME | DEFAULT CURRENT_TIMESTAMP | 创建时间 | | updated_at | DATETIME | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 | #### 建表语句 ```sql CREATE TABLE `users` ( `id` BIGINT PRIMARY KEY AUTO_INCREMENT COMMENT '用户ID', `username` VARCHAR(50) NOT NULL UNIQUE COMMENT '用户名', `email` VARCHAR(100) NOT NULL UNIQUE COMMENT '邮箱地址（学校邮箱）', `password` VARCHAR(255) NOT NULL COMMENT '密码（加密存储）', `nickname` VARCHAR(50) NOT NULL COMMENT '昵称', `avatar` VARCHAR(255) DEFAULT NULL COMMENT '头像URL', `bio` TEXT DEFAULT NULL COMMENT '个人简介', `gender` TINYINT DEFAULT 0 COMMENT '性别（0-未知, 1-男, 2-女）', `student_id` VARCHAR(20) UNIQUE DEFAULT NULL COMMENT '学号', `department` VARCHAR(100) DEFAULT NULL COMMENT '院系', `major` VARCHAR(100) DEFAULT NULL COMMENT '专业', `grade` VARCHAR(20) DEFAULT NULL COMMENT '年级', `points` INT DEFAULT 0 COMMENT '积分', `role` TINYINT DEFAULT 0 COMMENT '角色（0-普通用户, 1-版主, 2-管理员）', `status` TINYINT DEFAULT 1 COMMENT '状态（0-禁用, 1-启用）', `is_verified` TINYINT DEFAULT 0 COMMENT '是否验证（0-未验证, 1-已验证）', `login_ip` VARCHAR(50) DEFAULT NULL COMMENT '最近登录IP', `login_time` DATETIME DEFAULT NULL COMMENT '最近登录时间', `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `updated_at` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', INDEX `idx_email` (`email`), INDEX `idx_username` (`username`), INDEX `idx_student_id` (`student_id`), INDEX `idx_role` (`role`), INDEX `idx_status` (`status`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户表'; ``` ## 三、Api功能实现 ### 3.1用户认证模块 #### 3.1.1 用户注册 - **URL**: `/users/register` - **方法**: POST - **描述**: 创建新用户账号 请求参数： ```json { "username": "student123", "email": "student@school.edu", "password": "Secure@Password123", "nickname": "学生昵称", "studentId": "20220101001", "department": "计算机学院", "major": "软件工程", "grade": "2023级" } ``` 响应结果： ```json { "code": 200, "message": "注册成功", "data": { "userId": 12345, "username": "student123", "nickname": "学生昵称" } } ``` #### 3.1.2 用户密码登录 - **URL**: `/users/login` - **方法**: POST - **描述**: 用户登录 请求参数： ```json { "username": "student123", // 用户名或邮箱 "password": "Secure@Password123" } ``` 响应结果： ```json { "code": 200, "message": "登录成功", "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "userInfo": { "userId": 12345, "username": "student123", "nickname": "学生昵称", "avatar": "https://example.com/avatar.jpg", "role": 0, "isVerified": true, "status": 1 } } } ``` #### 3.1.3 获取邮箱验证码 - **URL**: `/users/code` - **方法**: POST - **描述**: 向指定邮箱发送登录验证码 请求参数 ```json { "email": "student@school.edu" } ``` 响应结果: ```json { "code": 200, "message": "验证码已发送", "data": null } ``` #### 3.1.4 邮箱验证码登录 - **URL**: `/users/login/code` - **方法**: POST - **描述**: 使用邮箱和验证码进行登录 请求参数 ```json { "email": "student@school.edu", "code": "123456" } ``` 成功响应: ```json { "code": 200, "message": "登录成功", "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "userInfo": { "userId": 12345, "username": "student123", "nickname": "学生昵称", "avatar": "https://example.com/avatar.jpg", "role": 0 } } } ```