enoch
0c908b128c
Some checks failed
CI/CD Pipeline / Run Tests (push) Failing after 11m9s
CI/CD Pipeline / Security Scan (push) Has been skipped
CI/CD Pipeline / Build Docker Image (push) Has been skipped
CI/CD Pipeline / Deploy to Staging (push) Has been skipped
CI/CD Pipeline / Deploy to Production (push) Has been skipped
CI/CD Pipeline / Notify Results (push) Successful in 31s
197 lines
3.9 KiB
Markdown
197 lines
3.9 KiB
Markdown
# 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 |