rust-user-api/docs/api.md

Rust User API 文档

概述

这是一个使用 Rust 和 Axum 框架构建的用户管理 REST API。提供完整的用户 CRUD 操作和 JWT 身份认证功能。

基础信息

• Base URL: http://localhost:3000
• Content-Type: application/json
• 认证方式: JWT Bearer Token

端点列表

基础端点

GET /

获取 API 欢迎信息

响应示例:

{
  "message": "欢迎使用 Rust User API",
  "version": "0.1.0"
}

GET /health

健康检查端点

响应示例:

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00Z"
}

用户管理

POST /api/users

创建新用户

请求体:

{
  "username": "string (3-50字符)",
  "email": "string (有效邮箱)",
  "password": "string (至少8字符)"
}

成功响应 (201 Created):

{
  "id": "uuid",
  "username": "testuser",
  "email": "test@example.com",
  "created_at": "2024-01-01T12:00:00Z"
}

错误响应:

• 400 Bad Request: 验证失败
• 409 Conflict: 用户名已存在

GET /api/users

获取所有用户列表

成功响应 (200 OK):

[
  {
    "id": "uuid",
    "username": "testuser",
    "email": "test@example.com",
    "created_at": "2024-01-01T12:00:00Z"
  }
]

GET /api/users/{id}

根据 ID 获取特定用户

路径参数:

• id: 用户 UUID

成功响应 (200 OK):

{
  "id": "uuid",
  "username": "testuser",
  "email": "test@example.com",
  "created_at": "2024-01-01T12:00:00Z"
}

错误响应:

• 404 Not Found: 用户不存在

PUT /api/users/{id}

更新用户信息

路径参数:

• id: 用户 UUID

请求体:

{
  "username": "string (可选, 3-50字符)",
  "email": "string (可选, 有效邮箱)"
}

成功响应 (200 OK):

{
  "id": "uuid",
  "username": "newusername",
  "email": "newemail@example.com",
  "created_at": "2024-01-01T12:00:00Z"
}

错误响应:

• 400 Bad Request: 验证失败
• 404 Not Found: 用户不存在

DELETE /api/users/{id}

删除用户

路径参数:

• id: 用户 UUID

成功响应 (204 No Content): 无响应体

错误响应:

• 404 Not Found: 用户不存在

身份认证

POST /api/auth/login

用户登录

请求体:

{
  "username": "string",
  "password": "string"
}

成功响应 (200 OK):

{
  "token": "jwt_token_string",
  "user": {
    "id": "uuid",
    "username": "testuser",
    "email": "test@example.com",
    "created_at": "2024-01-01T12:00:00Z"
  }
}

错误响应:

• 401 Unauthorized: 用户名或密码错误
• 404 Not Found: 用户不存在

错误响应格式

所有错误响应都遵循统一格式：

{
  "error": "错误描述信息",
  "status": 400
}

常见错误码

• 400 Bad Request: 请求参数验证失败
• 401 Unauthorized: 认证失败或未提供认证信息
• 404 Not Found: 请求的资源不存在
• 409 Conflict: 资源冲突（如用户名已存在）
• 500 Internal Server Error: 服务器内部错误

认证机制

API 使用 JWT (JSON Web Token) 进行身份认证。

获取 Token

通过 POST /api/auth/login 端点登录获取 JWT token。

使用 Token

在需要认证的请求中，在 Header 中添加：

Authorization: Bearer <your_jwt_token>

Token 有效期

JWT token 有效期为 24 小时。

数据验证规则

用户名 (username)

• 长度：3-50 字符
• 必须唯一

邮箱 (email)

• 必须是有效的邮箱格式
• 例如：user@example.com

密码 (password)

• 最少 8 个字符
• 使用 bcrypt 进行哈希存储

使用示例

创建用户并登录

# 1. 创建用户
curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123"
  }'

# 2. 登录获取 token
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "password123"
  }'

# 3. 使用 token 访问受保护的端点（未来功能）
curl -H "Authorization: Bearer <your_token>" \
  http://localhost:3000/api/protected-endpoint

开发和测试

运行服务器

cargo run

运行测试

# 运行单元测试
cargo test

# 运行 API 集成测试
./test_api.sh

环境配置

复制 .env.example 到 .env 并修改配置：

cp .env.example .env

技术实现

• Web 框架: Axum 0.7
• 异步运行时: Tokio
• 序列化: Serde
• 密码哈希: bcrypt
• JWT: jsonwebtoken
• 验证: validator
• 日志: tracing

后续计划

• 数据库持久化 (SQLite)
• API 分页支持
• 用户搜索和过滤
• 角色和权限管理
• API 限流
• OpenAPI/Swagger 文档