# Rust User API

一个使用 Rust 和 Axum 框架构建的 REST API 服务器，用于用户管理系统的学习和演示。

## 功能特性

- ✅ 用户 CRUD 操作（创建、读取、更新、删除）
- ✅ 内存存储（HashMap）
- ✅ 请求验证和错误处理
- ✅ JWT 身份认证
- ✅ 结构化日志记录
- ✅ CI/CD 流水线（GitHub Actions、Gitea Actions、GitLab CI）
- ✅ Docker 容器化部署
- ✅ 安全扫描和代码质量检查
- 🔄 SQLite 数据库集成（计划中）
- 🔄 API 文档和测试（计划中）

## 技术栈

- **Web 框架**: Axum 0.7
- **异步运行时**: Tokio
- **序列化**: Serde
- **身份认证**: JWT (jsonwebtoken)
- **验证**: Validator
- **日志**: Tracing

## 快速开始

### 1. 克隆项目

```bash
git clone <repository-url>
cd rust-user-api
```

### 2. 配置环境

```bash
cp .env.example .env
# 编辑 .env 文件，修改配置参数
```

### 3. 运行项目

```bash
cargo run
```

服务器将在 `http://127.0.0.1:3000` 启动。

### 4. Docker 部署（可选）

```bash
# 构建镜像
docker build -t rust-user-api .

# 运行容器
docker run -p 3000:3000 rust-user-api
```

或使用 Docker Compose：

```bash
docker-compose up -d
```

## API 端点

### 基础端点

- `GET /` - 欢迎信息
- `GET /health` - 健康检查

### 用户管理

- `GET /api/users` - 获取所有用户
- `GET /api/users/{id}` - 获取特定用户
- `POST /api/users` - 创建新用户
- `PUT /api/users/{id}` - 更新用户信息
- `DELETE /api/users/{id}` - 删除用户

### 请求示例

#### 创建用户

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

#### 获取所有用户

```bash
curl http://localhost:3000/api/users
```

## 项目结构

```
src/
├── main.rs              # 应用入口点
├── lib.rs               # 库入口
├── config/              # 配置管理
├── models/              # 数据模型
├── handlers/            # HTTP 处理器
├── routes/              # 路由配置
├── services/            # 业务逻辑
├── storage/             # 数据存储
├── middleware/          # 中间件
└── utils/               # 工具函数
```

## 开发

### 运行测试

```bash
cargo test
```

### 检查代码

```bash
cargo clippy
```

### 格式化代码

```bash
cargo fmt
```

## CI/CD 部署

本项目支持在多个平台上进行自动化部署：

### 支持的平台
- ✅ **GitHub Actions** - 完整支持
- ✅ **Gitea Actions** - 兼容支持
- ✅ **GitLab CI/CD** - 原生支持

### 配置文件
- `.github/workflows/deploy.yml` - GitHub/Gitea Actions 配置
- `.gitlab-ci.yml` - GitLab CI/CD 配置

### 部署流程
1. **测试阶段** - 代码格式检查、Clippy 检查、单元测试
2. **安全扫描** - 依赖漏洞扫描
3. **构建阶段** - Docker 镜像构建和推送
4. **部署阶段** - 自动部署到测试/生产环境

### 快速配置
详细的配置说明请参考：[CI/CD 配置指南](docs/ci-cd-setup.md)

## Docker 支持

### 本地构建
```bash
docker build -t rust-user-api .
docker run -p 3000:3000 rust-user-api
```

### Docker Compose
```bash
docker-compose up -d
```

### 生产部署
```bash
docker-compose -f docker-compose.prod.yml up -d
```

## 学习路径

这个项目按照以下阶段设计，适合渐进式学习：

1. **基础搭建** - 项目初始化和 HTTP 服务器
2. **数据模型** - 用户模型和内存存储
3. **CRUD 操作** - 完整的用户管理 API
4. **错误处理** - 统一的错误处理机制
5. **身份认证** - JWT 认证系统
6. **测试文档** - 测试用例和 API 文档
7. **数据库集成** - SQLite 数据库支持
8. **高级功能** - 分页、搜索、过滤等

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT License