用户接口文档

用户相关的所有API接口文档。

基础信息

• Base URL: /api/v1/users
• 认证要求: 部分接口需要认证
• 版本: v1.0.0

用户注册

接口信息

• 接口名称: 用户注册
• 请求方式: POST
• 请求地址: /api/v1/users/register
• 接口描述: 创建新用户账号

请求参数

参数名	类型	必填	说明	示例
username	string	是	用户名，3-20个字符	"john_doe"
email	string	是	邮箱地址	"user@example.com"
password	string	是	密码，至少8位	"password123"
phone	string	否	手机号码	"13800138000"

请求示例

{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "securePassword123",
  "phone": "13800138000"
}

返回参数

参数名	类型	说明	示例
userId	string	用户唯一标识	"usr_123456789"
username	string	用户名	"john_doe"
email	string	邮箱地址	"john@example.com"
createdAt	string	创建时间	"2024-01-15T10:30:00Z"

成功响应示例

{
  "code": 200,
  "message": "用户注册成功",
  "data": {
    "userId": "usr_123456789",
    "username": "john_doe",
    "email": "john@example.com",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "timestamp": 1705315800000
}

错误响应示例

{
  "code": 400,
  "message": "用户名已存在",
  "data": null,
  "timestamp": 1705315800000
}

注意事项

• 用户名不能包含特殊字符，只能包含字母、数字和下划线
• 邮箱地址必须唯一
• 密码需要包含至少一个大写字母、一个小写字母和一个数字

---

用户登录

接口信息

• 接口名称: 用户登录
• 请求方式: POST
• 请求地址: /api/v1/users/login
• 接口描述: 用户账号登录获取访问令牌

请求参数

参数名	类型	必填	说明	示例
email	string	是	注册邮箱	"user@example.com"
password	string	是	用户密码	"password123"

请求示例

{
  "email": "john@example.com",
  "password": "securePassword123"
}

返回参数

参数名	类型	说明	示例
accessToken	string	访问令牌	"eyJhbGciOiJIUzI1NiIs..."
refreshToken	string	刷新令牌	"eyJhbGciOiJIUzI1NiIs..."
expiresIn	number	令牌有效期（秒）	3600
userInfo	object	用户信息

成功响应示例

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600,
    "userInfo": {
      "userId": "usr_123456789",
      "username": "john_doe",
      "email": "john@example.com",
      "avatar": "https://example.com/avatar.jpg"
    }
  },
  "timestamp": 1705315800000
}

注意事项

• accessToken有效期为1小时
• refreshToken有效期为7天，可用于刷新accessToken
• 连续登录失败5次将锁定账号30分钟

---

获取用户信息

接口信息

• 接口名称: 获取用户信息
• 请求方式: GET
• 请求地址: /api/v1/users/profile
• 接口描述: 获取当前登录用户的详细信息
• 认证要求: 需要Bearer Token

请求参数

无（通过请求头传递认证信息）

请求头示例

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

返回参数

参数名	类型	说明	示例
userId	string	用户唯一标识	"usr_123456789"
username	string	用户名	"john_doe"
email	string	邮箱地址	"john@example.com"
phone	string	手机号码	"13800138000"
avatar	string	头像URL	"https://example.com/avatar.jpg"
createdAt	string	创建时间	"2024-01-15T10:30:00Z"
updatedAt	string	更新时间	"2024-01-15T10:30:00Z"

成功响应示例

{
  "code": 200,
  "message": "获取用户信息成功",
  "data": {
    "userId": "usr_123456789",
    "username": "john_doe",
    "email": "john@example.com",
    "phone": "13800138000",
    "avatar": "https://example.com/avatar.jpg",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "timestamp": 1705315800000
}

---

更新用户信息

接口信息

• 接口名称: 更新用户信息
• 请求方式: PUT
• 请求地址: /api/v1/users/profile
• 接口描述: 更新当前登录用户的信息
• 认证要求: 需要Bearer Token

请求参数

参数名	类型	必填	说明	示例
username	string	否	用户名	"new_username"
phone	string	否	手机号码	"13900139000"
avatar	string	否	头像URL	"https://example.com/new-avatar.jpg"

请求示例

{
  "username": "new_username",
  "phone": "13900139000",
  "avatar": "https://example.com/new-avatar.jpg"
}

返回参数

与获取用户信息接口相同

注意事项

• 用户名修改后，原用户名将释放可供他人使用
• 手机号码需要验证格式正确性
• 头像URL需要是有效的图片链接