Maas-Model-platform/docs/inside/API/MD003_用户中心/MD003_用户中心后端API_V0.1.md

用户中心后端API文档 V0.1

更新日志

版本	日期	更新内容
V0.1	2024-12-29	初始版本，包含认证和用户信息管理

基础信息

• Base URL: http://localhost:8000
• 认证方式: Bearer Token (JWT)

统一响应格式

成功响应直接返回数据对象，错误响应格式：

{
  "detail": "错误信息"
}

---

认证接口

1. 用户注册

POST /api/auth/register

请求体

{
  "username": "testuser",
  "password": "password123",
  "nickname": "测试用户",
  "email": "test@example.com"
}

字段	类型	必填	说明
username	string	是	用户名，3-50字符
password	string	是	密码，8-100字符
nickname	string	是	昵称，1-100字符
email	string	否	邮箱地址

响应示例

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "testuser",
  "nickname": "测试用户",
  "phone": null,
  "email": "test@example.com",
  "avatar": null,
  "registration_date": "2024-12-29",
  "created_at": "2024-12-29T10:00:00",
  "updated_at": "2024-12-29T10:00:00"
}

错误响应

状态码	说明
409	Username already exists / Email already exists
422	参数验证失败

---

2. 用户登录

POST /api/auth/login

请求体

Content-Type: application/x-www-form-urlencoded

字段	类型	必填	说明
username	string	是	用户名
password	string	是	密码

响应示例

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "testuser",
    "nickname": "测试用户",
    "phone": null,
    "email": "test@example.com",
    "avatar": null,
    "registration_date": "2024-12-29",
    "created_at": "2024-12-29T10:00:00",
    "updated_at": "2024-12-29T10:00:00"
  }
}

错误响应

状态码	说明
401	Invalid username or password

---

用户接口

以下接口需要在请求头中携带 Authorization: Bearer {token}

3. 获取当前用户信息

GET /api/users/me

请求头

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

响应示例

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "testuser",
  "nickname": "测试用户",
  "phone": "13800138000",
  "email": "test@example.com",
  "avatar": "https://example.com/avatar.jpg",
  "registration_date": "2024-12-29",
  "created_at": "2024-12-29T10:00:00",
  "updated_at": "2024-12-29T10:00:00"
}

错误响应

状态码	说明
401	Invalid credentials / Token expired

---

4. 更新当前用户信息

PUT /api/users/me

请求头

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

请求体

{
  "nickname": "新昵称",
  "phone": "13800138000",
  "email": "newemail@example.com",
  "avatar": "https://example.com/new-avatar.jpg",
  "apikey": "sk-xxxxxxxxxxxxxxxx"
}

字段	类型	必填	说明
nickname	string	否	昵称，1-100字符
phone	string	否	手机号，最大20字符
email	string	否	邮箱地址
avatar	string	否	头像URL
apikey	string	否	API密钥，最大255字符

注意：id、username、password 字段不可通过此接口修改

响应示例

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "testuser",
  "nickname": "新昵称",
  "phone": "13800138000",
  "email": "newemail@example.com",
  "avatar": "https://example.com/new-avatar.jpg",
  "registration_date": "2024-12-29",
  "created_at": "2024-12-29T10:00:00",
  "updated_at": "2024-12-29T12:00:00"
}

错误响应

状态码	说明
401	Invalid credentials
409	Email already exists

---

数据字段说明

用户响应字段

字段	类型	说明
id	string	用户ID (UUID)
username	string	用户名
nickname	string	昵称
phone	string	手机号
email	string	邮箱
avatar	string	头像URL
registration_date	date	注册日期
created_at	datetime	创建时间
updated_at	datetime	更新时间

Token响应字段

字段	类型	说明
access_token	string	JWT访问令牌
token_type	string	令牌类型，固定为bearer
user	object	用户信息

---

JWT令牌说明

• 算法: HS256
• 有效期: 24小时（可配置）
• Payload: 包含 user_id 和 exp

令牌使用方式

curl -H "Authorization: Bearer {access_token}" http://localhost:8000/api/users/me

---

默认管理员账户

系统启动时自动创建：

字段	值
username	admin
password	admin123
email	wxcz@wxcz.com
apikey	sk-db36651a5e

---

在线文档

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc