API文档
用户认证
用户认证相关 API
注册
POST
/auth/sign-up/email使用邮箱、密码和用户名注册新用户。
请求参数：
email
string required
用户邮箱地址
name
string required
用户名
password
string required
用户密码
响应状态码：
| 状态码 | 说明 |
|---|---|
| 201 | 注册成功 |
| 400 | 输入参数无效（如邮箱格式错误、密码太短、用户名格式错误等） |
| 409 | 邮箱已被注册 |
邮箱登录
POST
/auth/sign-in/email使用邮箱和密码登录，获取访问令牌和刷新令牌。
请求参数：
email
string required
用户邮箱地址
password
string required
用户密码
响应数据：
{
"success": true,
"message": "登录成功",
"data": {
"user": {
"userId": "8ebc8550-6d4b-4dd0-967b-3e1367a4abf1",
"email": "[email protected]",
"username": "Alice",
"avatar": null,
"isEmailVerified": true,
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
},
"tokens": {
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "eyJhbGciOiJIUzI1NiIs...",
"accessTokenExpiredIn": 1771325631,
"refreshTokenExpiredIn": 1771930431,
"tokenType": "Bearer"
}
},
"timestamp": "2026-01-01T00:00:00Z"
}
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 登录成功 |
| 400 | 输入参数无效 |
| 401 | 用户名或密码错误 |
| 403 | 账号状态不可登录（如未验证、被封禁） |
刷新 Token
POST
/auth/refresh使用刷新令牌获取新的访问令牌。
请求参数：
refreshToken
string required
当前有效的 Refresh Token
响应数据：
{
"success": true,
"message": "令牌刷新成功",
"data": {
"user": {
"userId": "8ebc8550-6d4b-4dd0-967b-3e1367a4abf1",
"email": "[email protected]",
"username": "Alice",
"avatar": null,
"isEmailVerified": true,
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
},
"tokens": {
"accessToken": "eyJhbGciOiJIUzI1NiIs...",
"refreshToken": "eyJhbGciOiJIUzI1NiIs...",
"accessTokenExpiredIn": 1771325631,
"refreshTokenExpiredIn": 1771930431,
"tokenType": "Bearer"
}
},
"timestamp": "2026-01-01T00:00:00Z"
}
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 刷新成功 |
| 401 | 刷新令牌无效或已过期 |
退出登录
POST
/auth/sign-out注销当前会话，使刷新令牌失效。
请求参数：
refreshToken
string
需要注销的 Refresh Token（可选）
响应状态码：
| 状态码 | 说明 |
|---|---|
| 204 | 退出成功 |
发送 OTP
POST
/auth/email-otp/send向指定邮箱发送验证码，用于验证邮箱或重置密码。
请求参数：
email
string required
目标邮箱地址
type
string required
OTP 类型：
reset_password、verify_email、sign_in响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 验证码发送成功 |
| 400 | 邮箱格式错误或类型不支持 |
| 429 | 请求频率超限 |
验证邮箱
POST
/auth/email-otp/verify-email使用收到的验证码验证用户邮箱。
请求参数：
email
string required
用户邮箱地址
otp
string required
收到的验证码
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 邮箱验证成功 |
| 400 | 邮箱格式无效 |
| 401 | 验证码错误或已过期 |
| 404 | 用户不存在 |
重置密码
POST
/auth/email-otp/reset-password使用验证码重置用户密码。
请求参数：
email
string required
用户邮箱地址
otp
string required
验证码
password
string required
新密码
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 密码重置成功 |
| 400 | 邮箱或密码格式不符 |
| 401 | 验证码错误或已过期 |
| 404 | 用户不存在 |
获取当前用户
GET
/auth/me Auth 获取当前登录用户的详细信息。
响应数据：
{
"success": true,
"message": "操作成功",
"data": {
"userId": "8ebc8550-6d4b-4dd0-967b-3e1367a4abf1",
"email": "[email protected]",
"username": "Alice",
"avatar": null,
"isEmailVerified": true,
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-15T08:30:00Z"
},
"timestamp": "2026-01-15T08:30:00Z"
}
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 获取成功 |
| 401 | 未登录或令牌无效 |
| 404 | 用户不存在 |
更新个人信息
PUT
/auth/me Auth 更新当前登录用户的用户名与头像 URL。
请求参数：
username
string required
新的用户名
avatar
string
新的头像 URL
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 更新成功 |
| 400 | 用户名或头像 URL 格式无效 |
| 401 | 未登录或令牌无效 |
| 404 | 用户不存在 |
上传头像
POST
/auth/me/avatar Auth 上传用户头像。使用 multipart/form-data 格式。
请求参数：
file
binary required
头像图片文件
响应数据：
{
"success": true,
"message": "头像上传成功",
"data": {
"avatar": "https://cdn-momohub.hanasaki.tech/avatars/8ebc8550-6d4b-4dd0-967b-3e1367a4abf1.jpg"
},
"timestamp": "2026-01-15T08:30:00Z"
}
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 上传成功 |
| 400 | 未上传文件或文件格式无效 |
| 401 | 未登录或令牌无效 |
修改密码
POST
/auth/password/change Auth 已登录用户修改自己的密码。
请求参数：
oldPassword
string required
当前密码
newPassword
string required
新密码
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 密码修改成功 |
| 400 | oldPassword/newPassword 格式不符 |
| 401 | 旧密码错误或未登录 |
注销账号
DELETE
/auth/account Auth 永久删除当前用户账号。
响应状态码：
| 状态码 | 说明 |
|---|---|
| 204 | 账号已删除 |
| 401 | 未登录或令牌无效 |