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 欢迎信息

**响应示例**:
```json
{
  "message": "欢迎使用 Rust User API",
  "version": "0.1.0"
}
```

#### GET /health
健康检查端点

**响应示例**:
```json
{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00Z"
}
```

### 用户管理

#### POST /api/users
创建新用户

**请求体**:
```json
{
  "username": "string (3-50字符)",
  "email": "string (有效邮箱)",
  "password": "string (至少8字符)"
}
```

**成功响应** (201 Created):
```json
{
  "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):
```json
[
  {
    "id": "uuid",
    "username": "testuser",
    "email": "test@example.com",
    "created_at": "2024-01-01T12:00:00Z"
  }
]
```

#### GET /api/users/{id}
根据 ID 获取特定用户

**路径参数**:
- `id`: 用户 UUID

**成功响应** (200 OK):
```json
{
  "id": "uuid",
  "username": "testuser",
  "email": "test@example.com",
  "created_at": "2024-01-01T12:00:00Z"
}
```

**错误响应**:
- 404 Not Found: 用户不存在

#### PUT /api/users/{id}
更新用户信息

**路径参数**:
- `id`: 用户 UUID

**请求体**:
```json
{
  "username": "string (可选, 3-50字符)",
  "email": "string (可选, 有效邮箱)"
}
```

**成功响应** (200 OK):
```json
{
  "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
用户登录

**请求体**:
```json
{
  "username": "string",
  "password": "string"
}
```

**成功响应** (200 OK):
```json
{
  "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: 用户不存在

## 错误响应格式

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

```json
{
  "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 进行哈希存储

## 使用示例

### 创建用户并登录

```bash
# 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
```

## 开发和测试

### 运行服务器

```bash
cargo run
```

### 运行测试

```bash
# 运行单元测试
cargo test

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

### 环境配置

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

```bash
cp .env.example .env
```

## 技术实现

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

## 后续计划

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