feat: [阶段7] 完善 API 文档和测试用例

- 创建详细的 API 文档（docs/api.md），包含所有端点说明和示例 - 实现完整的单元测试套件，覆盖所有核心功能： * 内存存储操作测试 * 用户请求验证测试 * 数据模型转换测试 * 错误处理测试 * 配置管理测试 * 用户认证服务测试 - 添加集成测试框架（tests/integration_tests.rs） - 修复 OpenSSL 依赖问题，使用 rustls-tls - 增强测试脚本，包含更多验证场景 - 所有测试通过，确保代码质量和稳定性
2025-08-04 17:58:47 +08:00
parent 038b6e6140
commit bb539e5cba
5 changed files with 769 additions and 3 deletions
--- a/docs/api.md
+++ b/docs/api.md
@@ -0,0 +1,293 @@
+# 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 文档