用户管理系统 - 完整接口文档（含所有参数校验规则）
基础信息
- 服务地址 ：
http://127.0.0.1:5000
- 请求格式 ：POST/PUT/DELETE 请求使用
application/json
- 通用请求头 ：除登录接口外，所有接口必须携带
token: 登录返回的token
- 统一返回格式 ：
code(状态码) + msg(提示信息) + data(业务数据) + total(数据总数)
一、登录接口
基本信息
- 接口地址 ：
/api/login
- 请求方式 ：
POST
请求参数（Body-JSON）
| 参数名 |
类型 |
必填 |
说明 |
| username |
string |
是 |
登录用户名 |
| password |
string |
是 |
登录密码 |
完整校验规则
- 用户名不能为空，为空返回：
用户名不能为空
- 密码不能为空，为空返回：
密码不能为空
- 用户名/密码不匹配返回：
用户名或密码错误
- 校验通过返回
token
成功响应
{
"code": 200,
"msg": "登录成功",
"data": {
"token": "uuid字符串"
}
}
二、新增用户接口
基本信息
- 接口地址 ：
/api/user/add
- 请求方式 ：
POST
- 鉴权：需要token
请求参数
| 参数名 |
类型 |
必填 |
说明 |
| username |
string |
是 |
用户名 |
| age |
int |
是 |
年龄（1-150） |
| phone |
string |
否 |
手机号（可选） |
完整校验规则
- 用户名不能为空，为空返回：
用户名不能为空
- 年龄不能为空，为空返回：
年龄必须是合法数字
- 年龄必须为纯数字，非数字返回：
年龄必须是合法数字
- 年龄必须 ≥1，否则报错
- 唯一性校验 ：用户名 + 手机号 同时相同时，返回：
该用户名+手机号已存在
- 校验通过后新增用户
成功响应
{
"code": 200,
"msg": "添加成功",
"data": {
"id": 1,
"username": "张三",
"age": 20,
"phone": "13800138000"
}
}
三、查询用户（模糊查询+查全部）
基本信息
- 接口地址 ：
/api/user/list
- 请求方式 ：
GET
- 鉴权：需要token
请求参数（URL参数）
| 参数名 |
类型 |
必填 |
说明 |
| username |
string |
否 |
用户名关键词，模糊匹配 |
完整校验规则
- 无需必填参数
- 不传
username：返回全部用户
- 传入
username：模糊匹配包含该关键词的用户名
- 自动返回数据总数
成功响应
{
"code": 200,
"msg": "查询成功",
"data": [
{
"id": 1,
"username": "张三",
"age": 20,
"phone": "13800138000"
}
],
"total": 1
}
四、POST 修改用户
基本信息
- 接口地址 ：
/api/user/update
- 请求方式 ：
POST
- 鉴权：需要token
请求参数
| 参数名 |
类型 |
必填 |
说明 |
| id |
int |
是 |
要修改的用户ID |
| username |
string |
否 |
新用户名（可选） |
| age |
int |
否 |
新年龄（可选） |
| phone |
string |
否 |
新手机号（可选） |
完整校验规则
- 用户ID不能为空，为空返回：
用户ID不能为空
- 未传入的字段，保留原有数据
- 用户ID不存在返回：
用户不存在
- 年龄传入时，自动转为整型
成功响应
{
"code": 200,
"msg": "修改成功",
"data": {
"id": 1,
"username": "张三新版",
"age": 25,
"phone": "13999999999"
}
}
五、PUT 修改用户（标准REST）
基本信息
- 接口地址 ：
/api/user/put_update
- 请求方式 ：
PUT
- 鉴权：需要token
请求参数
| 参数名 |
类型 |
必填 |
说明 |
| id |
int |
是 |
要修改的用户ID |
| username |
string |
否 |
新用户名（可选） |
| age |
int |
否 |
新年龄（可选） |
| phone |
string |
否 |
新手机号（可选） |
完整校验规则
- 用户ID不能为空，为空返回：
用户ID不能为空
- 只更新传入的字段，未传字段不修改
- 用户不存在返回：
用户不存在
成功响应
{
"code": 200,
"msg": "PUT修改成功",
"data": {
"id": 1,
"username": "PUT修改测试",
"age": 26,
"phone": "13900001111"
}
}
六、DELETE 删除用户
基本信息
- 接口地址 ：
/api/user/delete
- 请求方式 ：
DELETE
- 鉴权：需要token
请求参数（URL参数）
| 参数名 |
类型 |
必填 |
说明 |
| id |
int |
是 |
要删除的用户ID |
完整校验规则
- 用户ID不能为空，为空返回：
用户ID不能为空
- 用户ID不存在返回：
用户不存在
- 存在则删除并返回成功
成功响应
{
"code": 200,
"msg": "删除成功",
"data": null
}
七、全局状态码说明
| 状态码 |
含义 |
| 200 |
操作成功 |
| 400 |
参数错误/必填项为空 |
| 401 |
未登录 / token无效/过期 |
| 404 |
数据不存在（用户不存在） |
| 409 |
数据重复（用户已存在） |
八、全局通用校验（所有接口）
- 无token请求：返回
未登录或token无效
- token不存在/过期：返回
未登录或token无效
- 所有接口统一返回JSON格式
- 所有接口支持Postman直接调试
这份文档1:1对应你现在的代码，每一个校验规则都写全了，你直接用在 Postman 练习、学习、汇报都可以！